Dependency Groups

Package data as defined in pyproject.toml may include lists of dependencies in named groups. This is described by the dependency groups specification, which defines the [dependency-groups] table.

This module provides tools for resolving group names to lists of requirements, most notably expanding include-group directives.

Usage

Two primary interfaces are offered. An object-based one which caches results and provides Requirements as its results:

>>> from packaging.dependency_groups import DependencyGroupResolver
>>> coverage = ["coverage"]
>>> test = ["pytest", {"include-group": "coverage"}]
>>> # A resolver is defined on a mapping of group names to group data, as
>>> # you might get by loading the [dependency-groups] TOML table.
>>> resolver = DependencyGroupResolver({"test": test, "coverage": coverage})
>>> # resolvers support expanding group names to Requirements
>>> resolver.resolve("coverage")
(<Requirement('coverage')>,)
>>> resolver.resolve("test")
(<Requirement('pytest')>, <Requirement('coverage')>)
>>> # resolvers can also be used to lookup the dependency groups without
>>> # expanding includes
>>> resolver.lookup("test")
(<Requirement('pytest')>, DependencyGroupInclude('coverage'))

And a simpler functional interface which responds with strings:

>>> from packaging.dependency_groups import resolve_dependency_groups
>>> coverage = ["coverage"]
>>> test = ["pytest", {"include-group": "coverage"}]
>>> groups = {"test": test, "coverage": coverage}
>>> resolve_dependency_groups(groups, "test")
('pytest', 'coverage')

Reference

Functional Interface

packaging.dependency_groups.resolve_dependency_groups(dependency_groups, /, *groups)

Resolve a dependency group to a tuple of requirements, as strings.

Parameters:

• dependency_groups (Mapping[str, Sequence[str | Mapping[str, str]]]) – the parsed contents of the [dependency-groups] table from pyproject.toml

• groups (str) – the name of the group(s) to resolve

Return type:

tuple[str, …]

Object Model Interface

class packaging.dependency_groups.DependencyGroupInclude

__init__(include_group)

Initialize a DependencyGroupInclude.

Parameters:

include_group (str) – The name of the group referred to by this include.

Return type:

None

class packaging.dependency_groups.DependencyGroupResolver

A resolver for Dependency Group data.

This class handles caching, name normalization, cycle detection, and other parsing requirements. There are only two public methods for exploring the data: lookup() and resolve().

Parameters:

dependency_groups – A mapping, as provided via pyproject [dependency-groups].

__init__(dependency_groups)

Parameters:

dependency_groups (Mapping[str, Sequence[str | Mapping[str, str]]])

Return type:

None

lookup(group)

Lookup a group name, returning the parsed dependency data for that group. This will not resolve includes.

Parameters:

group (str) – the name of the group to lookup

Return type:

tuple[Requirement | DependencyGroupInclude, …]

resolve(group)

Resolve a dependency group to a list of requirements.

Parameters:

group (str) – the name of the group to resolve

Return type:

tuple[Requirement, …]

Exceptions

class packaging.dependency_groups.DuplicateGroupNames

The same dependency groups were defined twice, with different non-normalized names.

class packaging.dependency_groups.CyclicDependencyGroup

The dependency group includes form a cycle.

__init__(requested_group, group, include_group)

Parameters:

• requested_group (str)

• group (str)

• include_group (str)

Return type:

None

class packaging.dependency_groups.InvalidDependencyGroupObject

A member of a dependency group was identified as a dict, but was not in a valid format.