Pure Python, no dependencies. Requires Python >= 3.11.

Citations are constructed directly in Python source. Required fields are positional-or-keyword constructor arguments; optional fields are keyword-only with None defaults. key is always optional at construction -- it will be auto-generated if omitted (see Key generation below).

from citeable import Article, Software

cite = Article(
    author=["Huttley, Gavin", "Caley, Katherine", "McArthur, Robert"],
    title="diverse-seq: an application for alignment-free selecting and clustering biological sequences",
    journal="Journal of Open Source Software",
    year=2025,
    volume=10,
    number=110,
    pages="7765",
    doi="10.21105/joss.07765",
)
# cite.key == "Huttley.2025"

tool_cite = Software(
    author=["Smith, Jane"],
    title="my-cogent3-plugin",
    year=2024,
    version="1.0.0",
    url="https://github.com/jsmith/my-cogent3-plugin",
)
# tool_cite.key == "Smith.2024"

Validation is performed at construction time. A missing required field raises ValueError with a message identifying the field and entry type:

ValueError: Article requires 'volume'; received None

from_bibtex_string accepts a raw BibTeX string containing a single record and returns the corresponding citeable object. This is the intended path for developers who already have a .bib entry in a reference manager -- paste the raw BibTeX string directly into Python source.

from citeable import from_bibtex_string

cite = from_bibtex_string("""
@article{Huttley.2025,
  doi       = {10.21105/joss.07765},
  url       = {https://doi.org/10.21105/joss.07765},
  year      = {2025},
  volume    = {10},
  number    = {110},
  pages     = {7765},
  author    = {Huttley, Gavin and Caley, Katherine and McArthur, Robert},
  title     = {diverse-seq: an application for alignment-free selecting and clustering biological sequences},
  journal   = {Journal of Open Source Software},
}
""")

The cite key from the BibTeX string is preserved as the key value. Author names in "First Last" format are normalised to "Last, First" on parse.

Round-trip scaffolding: use from_bibtex_string + repr() to convert a BibTeX record into a clean Python constructor call, then paste that into your source:

print(repr(cite))

Article(
    author=['Huttley, Gavin', 'Caley, Katherine', 'McArthur, Robert'],
    title='diverse-seq: an application for alignment-free selecting and clustering biological sequences',
    year=2025,
    journal='Journal of Open Source Software',
    volume=10,
    pages='7765',
    number=110,
    doi='10.21105/joss.07765',
    url='https://doi.org/10.21105/joss.07765',
)

Fields common to all entry types

Article

Book

InProceedings

TechReport

Thesis

Software

Misc

No additional required fields beyond the common set.

Because citations come from multiple independent plugin developers, key collisions are expected. The function assign_unique_keys resolves collisions in-place across a deduplicated list:

from citeable import assign_unique_keys

unique = assign_unique_keys(citations)

• Deduplication by value is performed first: if two objects compare as equal, only the first is retained
• Keys already unique in the deduplicated collection are left unchanged
• Collisions between distinct citations sharing a base key get a letter suffix: "Smith.2024" becomes "Smith.2024.a", "Smith.2024.b", etc.
• The function mutates surviving objects in-place and returns the deduplicated list

cogent3 calls assign_unique_keys when assembling a bibliography from a composed app, so plugin developers do not need to call it themselves.

write_bibtex takes a list of citations and a file path, deduplicates the list, assigns unique keys, then writes the result as a valid .bib file:

from citeable import write_bibtex

write_bibtex(citations, "bibliography.bib")

For cases where only the string is needed:

unique = assign_unique_keys(citations)
bib_string = "\n\n".join(str(c) for c in unique)

This project uses uv for dependency management.

Initial setup

uv sync

This creates a .venv and installs the package in editable mode with all dev dependencies.

Running tests

uv run pytest

Running nox (multi-version test matrix)

uv run nox

Nox is configured to use uv as its virtualenv backend, so it will use uv to create per-session environments.

Formatting

uv run nox -s fmt

This runs ruff check --fix-only followed by ruff format.

Other common commands

uv run mypy src/citeable --strict   # type checking
uv run ruff check .                 # linting
uv run cog -r README.md             # regenerate cog blocks