citeproc-py

library0.9.3pypypi✓ verified 86d ago

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.

serialization data

pip install citeproc-py

github ↗package ↗

INSTALL

IMPORT

SIG · CITEPROC-PY

citeproc-py

serializationpythonv0.9.3

Install

3.0s avg

Import

97ms

Disk

29MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.9.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.098s · 30.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 3.0s · import 0.096s · 31MB

29MB installed

● package 29MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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])

Debug

Known issues

gotchaThe 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.

affects: >=0.8

breakingIn 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.

affects: >=0.9.0

deprecatedThe 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.

affects: >=0.8

Errors

Common errors & fixes

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

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

fix

Use: from citeproc import CitationStylesStyle

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

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

fix

Use: CiteProcJSON(json.dumps(your_list))

Upgrade

Version history

0.9.3latest on PyPI · released Apr 30, 2026

Audit

Dependencies

citeproc-py-stylesoptionalProvides a collection of CSL styles for easy use; optional but recommended.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/brechtm/citeproc-py ↗

packagehttps://pypi.org/project/citeproc-py/ ↗