Metadata-Version: 2.2
Name: citeproc-py
Version: 0.7.0
Summary: Citations and bibliography formatter
Home-page: https://github.com/brechtm/citeproc-py
Author: Brecht Machiels
Author-email: brecht@mos6581.org
License: 2-clause BSD License
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
License-File: LICENSE
Requires-Dist: lxml
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: provides
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

===========
citeproc-py
===========

.. image:: http://img.shields.io/pypi/v/citeproc-py.svg
   :target: https://pypi.python.org/pypi/citeproc-py
   :alt: PyPI

.. image:: https://github.com/brechtm/citeproc-py/actions/workflows/test.yml/badge.svg
   :target: https://github.com/brechtm/citeproc-py/actions/workflows/test.yml
   :alt: Build status

.. image:: https://coveralls.io/repos/brechtm/citeproc-py/badge.svg?branch=master&service=github
   :target: https://coveralls.io/github/brechtm/citeproc-py?branch=master
   :alt: Code coverage

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.

.. _CSL: http://citationstyles.org/
.. _CSL 1.0.1 specification: https://docs.citationstyles.org/en/1.0.1/specification.html
.. _semantic versioning: http://semver.org/


Requirements
------------

citeproc-py supports Python 3.9 and up. It depends on `lxml`_ for parsing and
navigating the CSL style and locale files.

.. _lxml: http://lxml.de/


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.

.. _pip: https://pip.pypa.io/en/latest/

If you insist, you can manually install citeproc-py from distribution packages
hosted at `PyPI`_. Please ignore the release archives offered by GitHub.

.. _PyPI: https://pypi.python.org/pypi/citeproc-py/


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

.. _citeproc-test suite: https://github.com/citation-style-language/test-suite
.. _citeproc-js: https://github.com/juris-m/citeproc-js



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.rst <https://github.com/citeproc-py/citeproc-py/blob/master/CONTRIBUTING.rst>`_ file.


Local Install and Running the Tests
-----------------------------------

First clone the `citeproc-py`_ repository and install the submodules with ``git
submodule update --init``. Then install with ``pip install -e .``. Then move to 
the ``tests`` directory and run ``python citeproc-test.py``. 

Run ``citeproc-test.py --help`` to see its usage information. The first time
you run the script it will clone the `citeproc-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 ``git update-index
--assume-unchanged citeproc/data/schema``


Changelog
---------

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
