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.Path = <factory>, project_dir: ~pathlib.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.

By default, the reader will prefer to use static metadata and will failover to dynamic data (which requires a build). Use static or dynamic to explicitly choose one or the other.

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
static – a StaticPyprojectReader provided by this reader
dynamic – a DynamicPackageReader provided by this reader

classifiers(*, python_versions: bool = False) → tuple[str, ...]¶

Get the classifiers for the project.

Parameters:: python_versions – Set python_versions=True to extract MAJOR.MINOR Python versions from classifiers.

Note that python_versions skips major-version-only classifiers.

dependencies() → tuple[str, ...]¶

Get the dependencies for the project.

Because extras use some of the same metadata fields, when dynamic metadata is used this listing is filtered to remove the values which are associated with optional-dependencies.

optional_dependencies(*, exact_wheel_metadata: bool = False) → MappingProxyType¶

Retrieve the optional dependencies for the current project.

When wheel dynamic metadata is used, and wheel metadata is therefore produced, the fields in metadata must be interpreted in order to find optional dependencies based on marker. mddj checks dependencies which start or end with an extra marker to find the optional dependencies. This heuristic is correct for typical cases but could be inaccurate with very unusual package builds.

Parameters:: exact_wheel_metadata – Only applies to dynamic metadata builds. After finding optional dependencies, mddj will attempt to remove the markers which associate a dependency with an extra. Set this flag to True to retrieve the original data without this modification.

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

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.reader.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.reader.tox_reader.ToxReaderError¶: The class of errors which can be raised if tox data discovery fails.

class mddj.api.reader.readthedocs_reader.ReadthedocsReader(config: ReadthedocsConfig)¶

A ReadthedocsReader is a data reader for readthedocs configuration.

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.readthedocs.python_version()
'3.11'

python_version() → str¶: Read the Python version out of ReadTheDocs configuration, using the configured read method.

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.