acl-anthology

This package accesses data from the ACL Anthology.

• Documentation
• Package on PyPI

For end users

Install via pip:

$ pip install acl-anthology

Instantiate the library, automatically fetching data files from the ACL Anthology repo (requires git to be installed on your system):

from acl_anthology import Anthology
anthology = Anthology.from_repo()

Some brief usage examples:

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

For Anthology maintainers

If you want to instantiate the library from a script within the repo, e.g. in order to make modifications to the data and push them to a branch, instantiate the library like this:

anthology = Anthology.from_within_repo()

If you want to quickly check or try out something in a Python REPL, you can invoke just python repl (or simply just repl if you're within the python/ folder) to start a REPL with this anthology object already instantiated.

For developers

This package uses uv for project management. Development is easiest with the just command runner.

Running just -l will list all available recipes in the current directory, while just -n <recipe> will print the commands that the recipe would run.

Given below are example just commands that can be run inside the python/ folder (or with just python from the repository root).

Running checks, pre-commit hooks, and tests

• just check will run ruff (linter and formatter), mypy, 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!

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 as this supports the most features with the mkdocstrings handler (particularly compared to Sphinx/reST).