Metadata-Version: 2.3
Name: acl-anthology
Version: 0.5.3
Summary: A library for accessing the ACL Anthology
License: Apache-2.0
Author: Marcel Bollmann
Author-email: marcel@bollmann.me
Requires-Python: >=3.10, !=3.11.0, <3.14
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: PyYAML (>=6.0,<7.0)
Requires-Dist: app-paths (>=0.0.7,<0.1.0)
Requires-Dist: attrs (>=24.1,<25.0)
Requires-Dist: citeproc-py (>=0.6.0,<0.7.0)
Requires-Dist: diskcache (>=5.6.1)
Requires-Dist: docopt (>=0.6.2)
Requires-Dist: gitpython (>=3.1.37)
Requires-Dist: langcodes[data] (>=3.5.0)
Requires-Dist: lxml (>=5.3.1,<5.4.0)
Requires-Dist: numpy (>=1.26.0)
Requires-Dist: omegaconf (>=2.3.0,<2.4.0)
Requires-Dist: platformdirs (>=3.11.0,<3.12.0)
Requires-Dist: pylatexenc (>=2.10,<3.0)
Requires-Dist: python-slugify[unidecode] (>=8.0.1,<8.1.0)
Requires-Dist: rich (>=13.3.5)
Requires-Dist: rnc2rng (>=2.6.6)
Requires-Dist: scipy (>=1.6.0)
Requires-Dist: stop-words (>=2018.7.23)
Requires-Dist: texsoup (>=0.3.1,<0.4.0)
Requires-Dist: typing-extensions (>=4.6.0) ; python_version < "3.11"
Description-Content-Type: text/markdown

# acl-anthology

[![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)](https://acl-anthology.readthedocs.io/)
[![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)
![Development Status](https://img.shields.io/pypi/status/acl-anthology)
[![Package on PyPI](https://img.shields.io/pypi/v/acl-anthology)](https://pypi.org/project/acl-anthology/)

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

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

## How to use

Install via `pip`:

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

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.readthedocs.io/).

## 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).

