Citations and bibliography formatter
Project description
citeproc-py is a CSL processor for Python. It aims to implement the CSL 1.0.1 specification. citeproc-py can output styled citations and bibliographies in a number of different output formats. Currently supported are plain text, reStructuredText and HTML. Other formats can be added easily.
citeproc-py uses semantic versioning. Currently, its major version number is still at 0, meaning the API is not yet stable. However, you should not expect to see any major API changes soon.
Requirements
citeproc-py supports Python 3.6 and up. It depends on lxml for parsing and navigating the CSL style and locale files.
Installation
The recommended way of installing citeproc-py is by using pip:
pip install citeproc-py
If lxml isn’t installed, pip will try to install it for you.
If you insist, you can manually install citeproc-py from distribution packages hosted at PyPI. Please ignore the release archives offered by GitHub.
Getting Started
To get started with citeproc-py, take a look at the examples under examples/. Two examples are provided, one parsing references from a JSON representation of references as supported by citeproc-js, another parsing the references from a BibTeX file. Both show and explain how to cite references and render the bibliography.
CSL Compatibility
Currently, citeproc-py passes almost 60% of the (relevant) tests in the citeproc-test suite. However, it is more than 60% complete, as citeproc-py doesn’t take care of double spaces and repeated punctuation marks yet, making a good deal of the tests fail. In addition, the following features have not yet been implemented (there are probably some I forgot though):
disambiguation/year-suffix
et-al-subsequent-min/et-al-subsequent-use-first
collapsing
punctuation-in-quote
display
Also, some citeproc-js functionality that is not part of the CSL spec is not (yet) supported:
raw dates
static-ordering
literal names
Running the Tests
First clone the citeproc-test suite so that it sits next to the citeproc-py directory. Now you can run citeproc-test.py (in the tests directory). Run citeproc-test.py --help to see its usage information.
Changelog
Release 0.6.0 (2021-05-27)
Bug fixes
Various issues on Windows: testing, explicit utf-8 encoding
Strings with unescaped declared r”aw”
Other changes:
Removed support for Python 2.7, 3.5 and added for 3.9
Travis CI is removed in favor of GitHub actions testing across all 3 major OSes (MacOS, Windows, GNU/Linux Ubuntu)
CSL test-suite progressed from 5779a8c to c3db429
Release 0.5.1 (2020-03-06)
Bug fixed:
avoid rnc2rng 2.6.2 which breaks installation of citeproc-py
Release 0.5.0 (2020-02-09)
Enhancements:
handle commas and ampersands in a functional style
Number: handle commas and ampersands
added symbol for textquotesingle
specify fallback locales for fr-CA and es-CL
improved page number and ranges parsing
Bug fixed:
don’t fail on empty page ranges (#90) (bbm)
detect end of file while parsing incorrect bib (#59) (John Vandenberg)
Other changes:
Removed 3.2-3.4 and added 3.7, 3.8 to supported Pythons
Refactored locales handling
Release 0.4.0 (2017-06-23)
New features:
allow specifying the encoding of a BibTeX database file (#20 and #25)
BibTeX ‘month’ field: support integers and “<month> <day>” values
BibTeX ‘pages’ field: support “10”, “10+”, “10-12” and “10–12” formats
BibTeX entry types: map the non-standard ‘thesis’ and ‘report’ entries
update the CSL schema to version 1.0.1 (#5)
update the CSL locales to commit 49bf3fc0
Bug fixed:
avoid crash when there is nothing to affix (David Lesieur)
fix BibTeX month to CSL month mapping (#24)
strip leading/trailing whitespace from BibTeX values (#37)
Release 0.3.0 (2014-11-07)
Major improvements to the BibTeX parser:
split names into parts and assign them to the equivalent CSL name parts
fixed handling of accent macros and escaped characters
more compatible (La)TeX macro handling in general (but still basic)
handle standard Computer Modern ligatures such as –, —, and <<
added unit tests for the BibTeX and LaTeX parsers
Other changes:
disable RelaxNG validation of CSL styles by default (API change)
Release 0.2.0 (2014-10-25)
bad cite callback function can determine how a bad cite is displayed (hetsch)
added option to disable RelaxNG validation (Jasper Op de Coul)
distutils was replaced with setuptools (Joshua Carp)
bug fixes (Yaroslav Halchenko, David Lesieur)
CitationStylesBibliography.bibliography() now returns the list of entries
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file citeproc-py-0.6.0.tar.gz.
File metadata
- Download URL: citeproc-py-0.6.0.tar.gz
- Upload date:
- Size: 140.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.2.0 pkginfo/1.4.2 requests/2.25.1 setuptools/50.3.0 requests-toolbelt/0.8.0 tqdm/4.51.0 CPython/3.9.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | d9e3a224f936fe2e5033b5d9ffdacab769cedb61d96c4e0cf2f0b488f1d24b4e |
|
| MD5 | 8c3657ed005609a8d3d0de6cf552069f |
|
| BLAKE2b-256 | 246cd6b638e1cc64a0d99e42de524448da6f5d5972288e7f1557a22dbe9a0c42 |
File details
Details for the file citeproc_py-0.6.0-py3-none-any.whl.
File metadata
- Download URL: citeproc_py-0.6.0-py3-none-any.whl
- Upload date:
- Size: 179.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.2.0 pkginfo/1.4.2 requests/2.25.1 setuptools/50.3.0 requests-toolbelt/0.8.0 tqdm/4.51.0 CPython/3.9.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | ca4c7a5158d6f68cb00a89bb47d9aa0eec7b89b18e574eb08a061b011b602bbe |
|
| MD5 | dcc88f4b544e55797b5a1a0f4f792404 |
|
| BLAKE2b-256 | 23e85e42b253c40d1087a4ef341d78d88b7a9beb46e6ab9cec19c75e4e3cba78 |
