Metadata-Version: 2.1
Name: acl-anthology-py
Version: 0.5.0
Summary: A library for accessing the ACL Anthology
Home-page: https://github.com/acl-org/acl-anthology
License: Apache-2.0
Author: Marcel Bollmann
Author-email: marcel@bollmann.me
Requires-Python: >=3.10, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*, !=3.8.*, !=3.9.*
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: PyYAML (>=6.0,<7.0)
Requires-Dist: app-paths (>=0.0.7,<0.0.8)
Requires-Dist: attrs (>=23.2.0,<24.0.0)
Requires-Dist: citeproc-py (>=0.6.0,<0.7.0)
Requires-Dist: diskcache (>=5.6.1,<6.0.0)
Requires-Dist: docopt (>=0.6.2,<0.7.0)
Requires-Dist: gitpython (>=3.1.37,<4.0.0)
Requires-Dist: langcodes[data] (>=3.5.0,<4.0.0)
Requires-Dist: latexcodec (>=2.0.1,<3.0.0)
Requires-Dist: lxml (>=4.9.2,<5.0.0)
Requires-Dist: numpy (>=1.26.0,<2.0.0)
Requires-Dist: omegaconf (>=2.3.0,<3.0.0)
Requires-Dist: platformdirs (>=3.11.0,<4.0.0)
Requires-Dist: python-slugify[unidecode] (>=8.0.1,<9.0.0)
Requires-Dist: rich (>=13.3.5,<14.0.0)
Requires-Dist: rnc2rng (>=2.6.6,<3.0.0)
Requires-Dist: scipy (>=1.6.0,<2.0.0)
Requires-Dist: texsoup (>=0.3.1,<0.4.0)
Requires-Dist: typing-extensions (>=4.6.0,<5.0.0) ; python_version < "3.11"
Project-URL: Repository, https://github.com/acl-org/acl-anthology
Description-Content-Type: text/markdown

# acl-anthology-py

[![License](https://img.shields.io/github/license/acl-org/acl-anthology)](LICENSE)
[![Build Status](https://img.shields.io/github/actions/workflow/status/acl-org/acl-anthology/code-quality.yml)](https://github.com/acl-org/acl-anthology/actions/workflows/code-quality.yml)
[![Documentation](https://img.shields.io/readthedocs/acl-anthology-py)](https://acl-anthology-py.readthedocs.io/en/latest/)
[![Code Coverage](https://img.shields.io/codecov/c/gh/acl-org/acl-anthology)](https://codecov.io/gh/acl-org/acl-anthology)
![Supported Python Versions](https://img.shields.io/pypi/pyversions/acl-anthology-py)
![Development Status](https://img.shields.io/pypi/status/acl-anthology-py)
[![Package on PyPI](https://img.shields.io/pypi/v/acl-anthology-py)](https://pypi.org/project/acl-anthology-py/)

This package accesses data from the [ACL
Anthology](https://aclanthology.org).

- [**Documentation**](https://acl-anthology-py.readthedocs.io/en/latest/)
- [**Package on PyPI**](https://pypi.org/project/acl-anthology-py/)

## How to use

Install via `pip`:

```bash
$ pip install acl-anthology-py
```

Instantiate the library, automatically fetching data files from the [ACL
Anthology repo](https://github.com/acl-org/acl-anthology) (requires `git` to be
installed on your system):

```python
from acl_anthology import Anthology
anthology = Anthology.from_repo()
```

Some brief usage examples:

```pycon
>>> paper = anthology.get("C92-1025")
>>> str(paper.title)
Two-Level Morphology with Composition
>>> [author.name for author in paper.authors]
[
    Name(first='Lauri', last='Karttunen'),
    Name(first='Ronald M.', last='Kaplan'),
    Name(first='Annie', last='Zaenen')
]
>>> anthology.find_people("Karttunen, Lauri")
[
    Person(
        id='lauri-karttunen', names=[Name(first='Lauri', last='Karttunen')],
        item_ids=<set of 30 AnthologyIDTuple objects>, comment=None
    )
]
```

Find more examples and details on the API in the [**official
documentation**](https://acl-anthology-py.readthedocs.io/en/latest/).

## Developing

This package uses the [**Poetry**](https://python-poetry.org/) packaging system.
Development is easiest with the [**just**](https://github.com/casey/just)
command runner; running `just -l` will list all available recipes, while `just
-n <recipe>` will print the commands that the recipe would run.

### Running checks, pre-commit hooks, and tests

- `just check` will run [**black**](https://github.com/psf/black),
   [**ruff**](https://github.com/charliermarsh/ruff),
   [**mypy**](https://mypy.readthedocs.io), and some other pre-commit hooks on all
   files in the repo.

    - `just install-hooks` will install pre-commit hooks so they run on every
      attempted commit.

- `just test-all` will run all tests _except_ for tests that run on the full
  Anthology data.

    - `just test NAME` will only run test functions with `NAME` in them.
    - `just test-integration` will run tests on the full Anthology data.

- `just fix-and-test` (or `just ft` for short) will run all checks and tests,
  additionally re-running the checks on failure, so that the checking and
  testing will continue even if some hooks have modified files.

- The justfile defines several more useful recipes; list them with `just -l`!

### Running benchmarks

There are some benchmark scripts intended to be run with
[richbench](https://github.com/tonybaloney/rich-bench):

```bash
poetry run richbench benchmarks/
```

### Generating and writing documentation

- `just docs` generates the documentation in the `site/` folder.
- `just docs-serve` serves the documentation for local browsing.

Docstrings are written in [Google
style](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings)
as this [supports the most
features](https://mkdocstrings.github.io/griffe/docstrings/#parsers-features)
with the mkdocstrings handler (particularly compared to Sphinx/reST).

