mddj API¶

mddjs API is based around a single object as the point of entry, the DJ, which helps you read, write, and remix your metadata.

Quickstart¶

Create a DJ and use it to read some metadata:

from mddj.api import DJ

dj = DJ()
print("project version:", dj.read.version())
print("lowest support Python:", dj.read.requires_python(lower_bound=True))
print("dependencies:")
for dep in dj.read.dependencies():
    print("  -", dep)

Or use it to write metadata:

from mddj.api import DJ

dj = DJ()
new_version = "0.99.0"
old_version = dj.write.version(new_version)
print(f"updated version from {old_version} to {new_version}")

Caching¶

Every DJ instance will aggressively cache loaded TOML data and built distribution metadata to make operations performant. If you want to edit metadata and ensure that the caches are cleared, instantiate a new DJ object, which will always use its own, fresh cache.

Note

The caching behavior of a DJ after writes may be improved in the future to do more cache invalidations. Currently, the TOML data cache is shared between writers and readers, and therefore writes and reads to that data will appear to be synchronized within a given DJ.

Configuration¶

A DJ can be configured by means of a DJConfig. This is the primary interface for programmatically controlling the behavior of a DJ.

Additionally, configuration will be read from the project’s pyproject.toml file if possible, looking for the [tool.mddj] table. See the config docs for details on the TOML configuration.

Reference¶

class mddj.api.DJ(config: DJConfig | None = None)¶

An MDDJ DJ object is the top level access point for the library API.

It provides programmatic access to the capabilities of MDDJ.

Note that DJs and their components aggressively cache data so that it can be read many times quickly. In order to refresh state, instantiate a new DJ.

property project_directory: Path¶

The directory where project metadata can be found.

By default, this is automatically discovered on first access, but it can also be explicitly set via config.

property pyproject_path: Path¶: The path to the pyproject.toml file which will be used to read and write metadata. The file may not actually exist, and this will not raise errors.

property read: Reader¶: A Reader configured via this DJ.

property write: Writer¶: A Writer configured via this DJ.

class mddj.api.DJConfig(discovery_start_dir: ~pathlib._local.Path = <factory>, project_dir: ~pathlib._local.Path | None = None, isolated_builds: bool = <factory>, capture_build_output: bool = <factory>)¶

Configuration for a DJ object.

Some values support having their defaults set via environment variables:

isolated_builds: MDDJ_ISOLATED_BUILDS
capture_build_output: MDDJ_CAPTURE_BUILD_OUTPUT

capture_build_output: bool¶: Whether or not to use “quiet mode” for builds when they are invoked. Defaults to True.

discovery_start_dir: Path¶: The starting directory for project dir discovery. Defaults to cwd.

isolated_builds: bool¶: Whether or not to use isolated builds when getting metadata from build backends. Defaults to True.

project_dir: Path | None = None¶: The project directory. By default, it is discovered from the start directory.

Readers¶

class mddj.api.reader.Reader(config: ReaderConfig, document_cache: TomlDocumentCache | None = None)¶

A Reader is an interface for data reading capabilities.

Typically, users should simply create a DJ and then access the reader built by it, as in:

>>> from mddj.api import DJ
>>> dj = DJ()
>>> dj.read.version()
'0.1.0'

Variables:: tox – a ToxReader provided by this reader

dependencies() → tuple[str, ...]¶: Get the dependencies for the project.

requires_python(*, lower_bound: bool = False) → str¶

Get the Requires-Python bound for the project.

Parameters:: lower_bound – When true, only get the lower bound of a >= expression. Only >= is supported. Any other comparator will produce a ValueError if lower_bound is set.

version() → str¶: Get the version of the project.

class mddj.api.tox_reader.ToxReader¶

A ToxReader is a specialized data reader for tox data.

Typically, users should simply create a DJ and then access the tox reader built by it, as in:

>>> from mddj.api import DJ
>>> dj = DJ()
>>> dj.read.tox.list_versions()
['3.8', '3.9', '3.10', '3.11', '3.12', '3.13']

list_python_versions() → tuple[str, ...]¶: List the Python versions which appear in the list of tox environments.

min_python_version() → str¶

Get the minimum Python version which appears in the environment list.

Raises a LookupError if the list appears to be empty.

class mddj.api.tox_reader.ToxReaderError¶: The class of errors which can be raised if tox data discovery fails.

Writers¶

class mddj.api.writer.Writer(config: WriterConfig, document_cache: TomlDocumentCache | None = None)¶

A Writer is an interface for data writing capabilities.

Typically, users should simply create a DJ and then access the writer built by it, as in:

>>> from mddj.api import DJ
>>> dj = DJ()
>>> dj.write.version("0.2.0")
'0.1.0'

version(new_version: str) → str¶

Write a new version into the project metadata, returning the old version.

If no previous version can be found, a LookupError is raised, on the presumption that this means that the writer is not correctly configured for the project.