{"id":21042,"library":"citeproc-py","title":"citeproc-py","description":"A citation and bibliography formatter for Python implementing the Citation Style Language (CSL). Current version 0.9.2 supports Python >=3.9 and provides flexible style loading from CSL files or the citeproc-py-styles collection. Released under BSD-2-Clause, with irregular maintenance cadence.","status":"active","version":"0.9.2","language":"python","source_language":"en","source_url":"https://github.com/brechtm/citeproc-py","tags":["citation","bibliography","csl","academic writing"],"install":[{"cmd":"pip install citeproc-py","lang":"bash","label":"Install from PyPI"},{"cmd":"pip install citeproc-py-styles","lang":"bash","label":"Install bundled CSL styles"}],"dependencies":[{"reason":"Provides a collection of CSL styles for easy use; optional but recommended.","package":"citeproc-py-styles","optional":true}],"imports":[{"note":"Standard import path; never import from citeproc.source or citeproc.etc.","symbol":"CitationStylesStyle","correct":"from citeproc import CitationStylesStyle"},{"note":"Standard import path.","symbol":"CitationStylesBibliography","correct":"from citeproc import CitationStylesBibliography"},{"note":"Standard import path.","symbol":"Citation","correct":"from citeproc import Citation"}],"quickstart":{"code":"import os\nfrom citeproc import CitationStylesStyle, CitationStylesBibliography, Citation, CitationItem\nfrom citeproc import formatter\nfrom citeproc.source.json import CiteProcJSON\n\n# Ensure a style file is available; either install citeproc-py-styles or download one\n# For this example we use a built-in style path\nstyle_path = os.path.join(os.path.dirname(__file__), 'style.csl')  # replace with actual path\nif not os.path.exists(style_path):\n    # Fallback: use a minimal style string\n    style_str = '''<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<style xmlns=\"http://purl.org/net/xbiblio/csl\" class=\"in-text\" version=\"1.0\">\n  <info><title>Test Style</title><id>http://example.com/test</id></info>\n  <citation><layout><text variable=\"title\"/></layout></citation>\n</style>'''\n    style = CitationStylesStyle(style_str, validate=False)\nelse:\n    style = CitationStylesStyle(style)\n\nbib_source = CiteProcJSON('[\n  {\"id\": \"ITEM-1\", \"type\": \"book\", \"title\": \"The Example Book\", \"author\": [{\"family\": \"Doe\", \"given\": \"John\"}], \"issued\": {\"date-parts\": [[2024]]}}\n]')\nbibliography = CitationStylesBibliography(style, bib_source, formatter.html)\ncitation = Citation([CitationItem('ITEM-1')])\nbibliography.register(citation)\n\n# Render citation\nprint(bibliography.cite(citation))\n# Render bibliography\nprint(bibliography.bibliography()[0])","lang":"python","description":"Basic usage: load a style, create a bibliography from JSON data, register citations, and render."},"warnings":[{"fix":"Use CiteProcJSON(json.dumps(your_data)) or pass a JSON string directly.","message":"The CiteProcJSON source requires JSON input as a string, not a list of dicts directly. Always pass a JSON-encoded string to the constructor.","severity":"gotcha","affected_versions":">=0.8"},{"fix":"Install citeproc-py-styles and use CitationStylesStyle('apa') or load from a file with an absolute path.","message":"In version 0.9.0, the style loading mechanism changed. The old direct file path support (e.g., CitationStylesStyle('style.csl')) may not work if the file is not found in the expected location. Use the citeproc-py-styles package or provide a full path.","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"Use from citeproc import formatter and pass formatter.html to CitationStylesBibliography.","message":"The formatter module may be removed in future versions. The current recommended formatter is formatter.html.","severity":"deprecated","affected_versions":">=0.8"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use: from citeproc import CitationStylesStyle","cause":"Import path is wrong; common mistake is importing citeproc and expecting submodules to be accessible directly.","error":"AttributeError: module 'citeproc' has no attribute 'CitationStylesStyle'"},{"fix":"Use: CiteProcJSON(json.dumps(your_list))","cause":"Passing a Python list/dict directly to CiteProcJSON instead of a JSON-encoded string.","error":"citeproc.source.json.CiteProcJSON - TypeError: the JSON object must be str, bytes or bytearray, not 'list'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}