Metadata-Version: 2.4
Name: citeproc-py
Version: 0.9.0
Summary: Citations and bibliography formatter
Home-page: https://github.com/brechtm/citeproc-py
Author: Brecht Machiels
Author-email: brecht@mos6581.org
License: BSD-2-Clause-Views
Keywords: csl citation html rst bibtex xml
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Other Environment
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Legal Industry
Classifier: Intended Audience :: Other Audience
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Printing
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides: citeproc
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml
Provides-Extra: full
Requires-Dist: citeproc-py-styles; extra == "full"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# citeproc-py

[![PyPI - Version](https://img.shields.io/pypi/v/citeproc-py)](https://pypi.org/project/citeproc-py/)
[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/citeproc-py/citeproc-py/test.yml)](https://github.com/citeproc-py/citeproc-py/actions?query=branch%3Amaster+workflow%3ATest)
[![Coveralls](https://img.shields.io/coverallsCoverage/github/citeproc-py/citeproc-py)](https://coveralls.io/github/citeproc-py/citeproc-py)


citeproc-py is a [CSL](https://citationstyles.org/) processor for Python. It aims to implement the
[CSL 1.0.1 specification](https://docs.citationstyles.org/en/1.0.1/specification.html).
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](https://semver.org/). 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.9 and up. It depends on [lxml](https://lxml.de/) for parsing and
navigating the CSL style and locale files.

# Installation

The recommended way of installing citeproc-py is by using
[pip](https://pip.pypa.io/en/latest/):
```bash
   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](https://pypi.python.org/pypi/citeproc-py/). 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](https://github.com/citation-style-language/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](https://github.com/juris-m/citeproc-js)
functionality that is not part of the CSL spec is not (yet) supported:

-  raw dates
-  static-ordering
-  literal names

## Contributing

citeproc-py is 100% volunteer maintained, and new contributions are always welcome.
If you would like to contribute, please follow the guidelines in the
[CONTRIBUTING.md](https://github.com/citeproc-py/citeproc-py/blob/master/CONTRIBUTING.md) file.

## Local Install and Running the Tests

First clone the `citeproc-py` repository and install the submodules with
```bash
git submodule update --init
```

Then install with
```bash
pip install --editable .
```

Then move to the `tests` directory and run
```bash
python citeproc-test.py
```

Run
```bash
citeproc-test.py --help
```
to see its usage information. The first time
you run the script it will clone the
[citeproc-test suite](https://github.com/citation-style-language/test-suite) repository into the
`tests` directory and checkout the last tested version. By default failed tests are
automatically added into the `failing_tests.txt` file and aren't shown when
running the test suite again.

If you want git to fully ignore the submodule, you can type
```bash
git update-index --assume-unchanged citeproc/data/schema
```


# v0.9.0 (Mon Aug 25 2025)

#### 🚀 Enhancement

- Feature/flexible style loading [#180](https://github.com/citeproc-py/citeproc-py/pull/180) ([@yarikoptic](https://github.com/yarikoptic))

#### Authors: 1

- Yaroslav Halchenko ([@yarikoptic](https://github.com/yarikoptic))

---

# v0.8.3 (Mon Aug 18 2025)

#### 🐛 Bug Fix

- setup: match license label with actual text [#175](https://github.com/citeproc-py/citeproc-py/pull/175) ([@tmorrell](https://github.com/tmorrell))
- Fix Non-existent Terms [#156](https://github.com/citeproc-py/citeproc-py/pull/156) ([@JVickery-TBS](https://github.com/JVickery-TBS))

#### 🏠 Internal

- Remove hardcoded option for auto to onlyPublishWithReleaseLabel [#178](https://github.com/citeproc-py/citeproc-py/pull/178) ([@yarikoptic](https://github.com/yarikoptic))
- release action: missing semicolon [#177](https://github.com/citeproc-py/citeproc-py/pull/177) ([@tmorrell](https://github.com/tmorrell))
- release action: missing quotes [#176](https://github.com/citeproc-py/citeproc-py/pull/176) ([@tmorrell](https://github.com/tmorrell))
- coveralls: try to reenable [#163](https://github.com/citeproc-py/citeproc-py/pull/163) ([@tmorrell](https://github.com/tmorrell))

#### 📝 Documentation

- Fix some formatting issues in README [#164](https://github.com/citeproc-py/citeproc-py/pull/164) ([@alexfikl](https://github.com/alexfikl))

#### Authors: 4

- Alex Fikl ([@alexfikl](https://github.com/alexfikl))
- Jesse Vickery ([@JVickery-TBS](https://github.com/JVickery-TBS))
- Tom Morrell ([@tmorrell](https://github.com/tmorrell))
- Yaroslav Halchenko ([@yarikoptic](https://github.com/yarikoptic))

---

# v0.8.2 (Wed Mar 12 2025)

#### 🏠 Internal

- Explicitly specify utf-8 encoding while reading top level .md files for description [#162](https://github.com/citeproc-py/citeproc-py/pull/162) ([@yarikoptic](https://github.com/yarikoptic))
- Instruct that long description is in markdown and not ReST [#160](https://github.com/citeproc-py/citeproc-py/pull/160) ([@yarikoptic](https://github.com/yarikoptic))

#### Authors: 1

- Yaroslav Halchenko ([@yarikoptic](https://github.com/yarikoptic))

---

# v0.8.1 (Wed Mar 12 2025)

#### 🏠 Internal

- release: checkout with submodules [#159](https://github.com/citeproc-py/citeproc-py/pull/159) ([@yarikoptic](https://github.com/yarikoptic))

#### Authors: 1

- Yaroslav Halchenko ([@yarikoptic](https://github.com/yarikoptic))

---

# v0.8.0 (Wed Mar 12 2025)

#### 🚀 Enhancement

- release: use GitHUb App token for checkout and push [#158](https://github.com/citeproc-py/citeproc-py/pull/158) ([@tmorrell](https://github.com/tmorrell))

#### ⚠️ Pushed to `master`

- Rename CHANGES to CHANGELOG ([@yarikoptic](https://github.com/yarikoptic))

#### 🏠 Internal

- release: switch to using GitHub App to overcome branch protection [#157](https://github.com/citeproc-py/citeproc-py/pull/157) ([@tmorrell](https://github.com/tmorrell))
- Set up `auto` to automate releases [#153](https://github.com/citeproc-py/citeproc-py/pull/153) ([@jwodder](https://github.com/jwodder) [@yarikoptic](https://github.com/yarikoptic))

#### 📝 Documentation

- Convert CHANGES.rst, CONTRIBUTING.rst, and README.md to markdown [#154](https://github.com/citeproc-py/citeproc-py/pull/154) ([@tmorrell](https://github.com/tmorrell))

#### Authors: 3

- John T. Wodder II ([@jwodder](https://github.com/jwodder))
- Tom Morrell ([@tmorrell](https://github.com/tmorrell))
- Yaroslav Halchenko ([@yarikoptic](https://github.com/yarikoptic))

---


# Release 0.7.0 (2025-02-19)

Just to get a release out after long period.

#### Bug fixes

* Better handling of ordinals
* Fix locator conditions (resolves #142)
* Make family name optional
* Allow date parts to not be integers
* Support space macros
* Fix multiple capitals
* Fix parsing BibTex integer values

#### Other changes:

* Removed support for Python 3.6, 3.7, 3.8 and added for 3.10 - 3.13
* Switch versioning to versioneer


# 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
