citeproc-py

0.9.2 verified Mon Apr 27 auth: no python

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.

pip install citeproc-py

Common errors

error AttributeError: module 'citeproc' has no attribute 'CitationStylesStyle' ↓

cause Import path is wrong; common mistake is importing citeproc and expecting submodules to be accessible directly.

fix

Use: from citeproc import CitationStylesStyle

error citeproc.source.json.CiteProcJSON - TypeError: the JSON object must be str, bytes or bytearray, not 'list' ↓

cause Passing a Python list/dict directly to CiteProcJSON instead of a JSON-encoded string.

fix

Use: CiteProcJSON(json.dumps(your_list))

Warnings

gotcha The CiteProcJSON source requires JSON input as a string, not a list of dicts directly. Always pass a JSON-encoded string to the constructor. ↓

fix Use CiteProcJSON(json.dumps(your_data)) or pass a JSON string directly.

breaking 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. ↓

fix Install citeproc-py-styles and use CitationStylesStyle('apa') or load from a file with an absolute path.

deprecated The formatter module may be removed in future versions. The current recommended formatter is formatter.html. ↓

fix Use from citeproc import formatter and pass formatter.html to CitationStylesBibliography.

Install

pip install citeproc-py-styles

Imports

CitationStylesStyle
```
from citeproc import CitationStylesStyle
```
Standard import path; never import from citeproc.source or citeproc.etc.

CitationStylesBibliography

from citeproc import CitationStylesBibliography

Standard import path.

Citation
```
from citeproc import Citation
```
Standard import path.

Quickstart

Basic usage: load a style, create a bibliography from JSON data, register citations, and render.

import os
from citeproc import CitationStylesStyle, CitationStylesBibliography, Citation, CitationItem
from citeproc import formatter
from citeproc.source.json import CiteProcJSON

# Ensure a style file is available; either install citeproc-py-styles or download one
# For this example we use a built-in style path
style_path = os.path.join(os.path.dirname(__file__), 'style.csl')  # replace with actual path
if not os.path.exists(style_path):
    # Fallback: use a minimal style string
    style_str = '''<?xml version="1.0" encoding="utf-8"?>
<style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" version="1.0">
  <info><title>Test Style</title><id>http://example.com/test</id></info>
  <citation><layout><text variable="title"/></layout></citation>
</style>'''
    style = CitationStylesStyle(style_str, validate=False)
else:
    style = CitationStylesStyle(style)

bib_source = CiteProcJSON('[
  {"id": "ITEM-1", "type": "book", "title": "The Example Book", "author": [{"family": "Doe", "given": "John"}], "issued": {"date-parts": [[2024]]}}
]')
bibliography = CitationStylesBibliography(style, bib_source, formatter.html)
citation = Citation([CitationItem('ITEM-1')])
bibliography.register(citation)

# Render citation
print(bibliography.cite(citation))
# Render bibliography
print(bibliography.bibliography()[0])