Discoverers

feu.compat.discoverers

Contain a registry-based system of per-package compatibility target discoverers.

Discovering compatibility targets from PyPI wheel metadata is generally computed the same way for every package (CompatDiscoverer), but some packages need a different strategy (e.g. because their wheel tags or requires_python metadata don't reflect their real compatibility). CompatDiscovererRegistry allows registering a package-specific BaseCompatDiscoverer that takes precedence over the default one.

Example

>>> from feu.compat.discoverers import discover_compat_targets
>>> compat = discover_compat_targets("numpy")  # doctest: +SKIP

feu.compat.discoverers.BaseCompatDiscoverer

Bases: ABC

Define the base class for package compatibility target discoverers.

Example

>>> from feu.compat.discoverers import CompatDiscoverer
>>> from feu.compat.target import Target
>>> discoverer = CompatDiscoverer()
>>> compat = discoverer.discover(
...     "numpy", targets=(Target(python_version="3.11", os="linux", arch="x86_64"),)
... )  # doctest: +SKIP

feu.compat.discoverers.BaseCompatDiscoverer.discover abstractmethod

discover(
    pkg_name: str, targets: Sequence[Target]
) -> dict[Target, list[VersionRange]]

Discover the version range compatible with each target.

Parameters:

Name	Type	Description	Default
pkg_name	str	The package name to inspect (e.g., "numpy").	required
targets	Sequence[Target]	The compatibility targets to compute constraints for. Each target must have concrete (non-None) os and arch.	required

Returns:

Type	Description
dict[Target, list[VersionRange]]	A mapping of Target to a list of VersionRange, in the same shape expected by CompatRegistry.register_many.

feu.compat.discoverers.CompatDiscoverer

Bases: BaseCompatDiscoverer

Implement the default compatibility target discoverer, using actual wheel filenames published on PyPI.

Unlike an approach that only inspects the requires_python metadata, this discoverer parses each release's wheel filenames to determine whether it shipped a build matching a target's free-threaded/OS/arch axes, not just its Python version. For pure-Python wheels (which carry no OS/arch information, and sometimes no Python-version information either), it falls back to the requires_python metadata.

Example

>>> from feu.compat.discoverers import CompatDiscoverer
>>> from feu.compat.target import Target
>>> discoverer = CompatDiscoverer()
>>> compat = discoverer.discover(
...     "numpy", targets=(Target(python_version="3.11", os="linux", arch="x86_64"),)
... )  # doctest: +SKIP

feu.compat.discoverers.CompatDiscovererRegistry

Implement a registry that manages and dispatches compatibility discoverers based on package name.

Parameters:

Name	Type	Description	Default
initial_state	dict[str, BaseCompatDiscoverer] | None	Optional initial mapping of package name to discoverer. If provided, the state is copied to prevent external mutations.	None

Example

>>> from feu.compat.discoverers import CompatDiscovererRegistry, CompatDiscoverer
>>> registry = CompatDiscovererRegistry()
>>> registry.register("my_package", CompatDiscoverer())
>>> registry.has_discoverer("my_package")
True

feu.compat.discoverers.CompatDiscovererRegistry.find_discoverer

find_discoverer(pkg_name: str) -> BaseCompatDiscoverer

Find the relevant compatibility discoverer for the given package.

Parameters:

Name	Type	Description	Default
pkg_name	str	The package name.	required

Returns:

Type	Description
BaseCompatDiscoverer	The compatibility discoverer for the package, or a CompatDiscoverer if none is registered.

Example

>>> from feu.compat.discoverers import CompatDiscovererRegistry
>>> registry = CompatDiscovererRegistry()
>>> discoverer = registry.find_discoverer("pydantic")
>>> discoverer
CompatDiscoverer()

feu.compat.discoverers.CompatDiscovererRegistry.has_discoverer

has_discoverer(pkg_name: str) -> bool

Indicate if a compatibility discoverer is registered for the given package name.

Parameters:

Name	Type	Description	Default
pkg_name	str	The package name.	required

Returns:

Type	Description
bool	True if a discoverer is registered, otherwise False.

Example

>>> from feu.compat.discoverers import CompatDiscovererRegistry
>>> registry = CompatDiscovererRegistry()
>>> registry.has_discoverer("pydantic")
False

feu.compat.discoverers.CompatDiscovererRegistry.register

register(
    pkg_name: str,
    discoverer: BaseCompatDiscoverer,
    exist_ok: bool = False,
) -> None

Register a compatibility discoverer for a given package.

Parameters:

Name	Type	Description	Default
pkg_name	str	The package name.	required
discoverer	BaseCompatDiscoverer	The discoverer used for the given package.	required
exist_ok	bool	If False, RuntimeError is raised if the package already exists. This parameter should be set to True to overwrite the discoverer for a package.	False

Raises:

Type	Description
RuntimeError	if a discoverer is already registered for the package name and exist_ok=False.

Example

>>> from feu.compat.discoverers import CompatDiscovererRegistry, CompatDiscoverer
>>> registry = CompatDiscovererRegistry()
>>> registry.register("my_package", CompatDiscoverer())
>>> registry.has_discoverer("my_package")
True

feu.compat.discoverers.CompatDiscovererRegistry.register_many

register_many(
    mapping: Mapping[str, BaseCompatDiscoverer],
    exist_ok: bool = False,
) -> None

Register multiple compatibility discoverers at once.

Parameters:

Name	Type	Description	Default
mapping	Mapping[str, BaseCompatDiscoverer]	Mapping of package name to discoverer.	required
exist_ok	bool	If False, RuntimeError is raised if any package already exists. This parameter should be set to True to overwrite the discoverer for a package.	False

Raises:

Type	Description
RuntimeError	if a discoverer is already registered for any of the package names and exist_ok=False.

Example

>>> from feu.compat.discoverers import CompatDiscovererRegistry, CompatDiscoverer
>>> registry = CompatDiscovererRegistry()
>>> registry.register_many({"my_package": CompatDiscoverer()})
>>> registry.has_discoverer("my_package")
True

feu.compat.discoverers.DuckdbCompatDiscoverer

Bases: BaseCompatDiscoverer

Implement a specialized compatibility discoverer for duckdb.

duckdb has a spurious 0.0.0 release published on PyPI in 2023. It is not a real release, and including it in version ordering only creates confusion in the computed compatibility ranges. This discoverer behaves exactly like the default CompatDiscoverer but ignores that version.

Example

>>> from feu.compat.discoverers.duckdb import DuckdbCompatDiscoverer
>>> from feu.compat.target import Target
>>> discoverer = DuckdbCompatDiscoverer()
>>> compat = discoverer.discover(
...     "duckdb", targets=(Target(python_version="3.11", os="linux", arch="x86_64"),)
... )  # doctest: +SKIP

feu.compat.discoverers.JaxCompatDiscoverer

Bases: BaseCompatDiscoverer

Implement a specialized compatibility discoverer for jax.

jax itself ships pure-Python wheels, so its own wheel filenames carry no OS/arch/Python-version information: the default CompatDiscoverer would (incorrectly) consider every jax release compatible with every target. In practice, jax requires jaxlib, whose wheels are platform-specific and are released in lockstep with matching jax version numbers. This discoverer therefore only considers a jax release compatible with a target if the jaxlib release with the same version number shipped a wheel matching that target's Python version/free-threaded/OS/arch axes.

Example

>>> from feu.compat.discoverers.jax import JaxCompatDiscoverer
>>> from feu.compat.target import Target
>>> discoverer = JaxCompatDiscoverer()
>>> compat = discoverer.discover(
...     "jax", targets=(Target(python_version="3.11", os="linux", arch="x86_64"),)
... )  # doctest: +SKIP

feu.compat.discoverers.PolarsCompatDiscoverer

Bases: BaseCompatDiscoverer

Implement a specialized compatibility discoverer for polars.

Older polars releases ship platform-specific compiled wheels directly, so the default CompatDiscoverer logic (matching wheel tags exactly) works fine for those. Starting with polars 1.34, however, the polars wheel itself became pure-Python and delegates the compiled, platform-specific parts to the separate polars-runtime-32 package, pinned to an exact version per release. The default discoverer cannot see this indirection: it falls back to the requires_python metadata for pure-Python wheels and (incorrectly) considers every such polars release compatible with every OS/arch/free-threaded combination.

This discoverer handles both eras correctly: it matches wheel tags directly for releases that ship platform-specific wheels, and for pure-Python releases it resolves the pinned polars-runtime-32 version and matches against that release's wheel tags instead.

Example

>>> from feu.compat.discoverers.polars import PolarsCompatDiscoverer
>>> from feu.compat.target import Target
>>> discoverer = PolarsCompatDiscoverer()
>>> compat = discoverer.discover(
...     "polars", targets=(Target(python_version="3.11", os="linux", arch="x86_64"),)
... )  # doctest: +SKIP

feu.compat.discoverers.PydanticCompatDiscoverer

Bases: BaseCompatDiscoverer

Implement a specialized compatibility discoverer for pydantic.

pydantic 1.x ships platform-specific compiled wheels directly, so the default CompatDiscoverer logic (matching wheel tags exactly) works fine for those releases. pydantic 2.x, however, ships a pure-Python wheel and delegates the compiled, platform- specific parts to the separate pydantic-core package, pinned to an exact version per release. The default discoverer cannot see this indirection: it falls back to the requires_python metadata for pure-Python wheels and (incorrectly) considers every pydantic 2.x release compatible with every OS/arch/free- threaded combination.

This discoverer handles both eras correctly: it matches wheel tags directly for releases that ship platform-specific wheels, and for pure-Python releases it resolves the pinned pydantic-core version and matches against that release's wheel tags instead.

Example

>>> from feu.compat.discoverers.pydantic import PydanticCompatDiscoverer
>>> from feu.compat.target import Target
>>> discoverer = PydanticCompatDiscoverer()
>>> compat = discoverer.discover(
...     "pydantic", targets=(Target(python_version="3.11", os="linux", arch="x86_64"),)
... )  # doctest: +SKIP

feu.compat.discoverers.discover_compat_targets

discover_compat_targets(
    pkg_name: str,
    targets: Sequence[Target] = DEFAULT_TARGETS,
) -> dict[Target, list[VersionRange]]

Discover the version range compatible with each target.

Uses the compatibility discoverer registered for pkg_name in the default global registry if one exists, otherwise falls back to the default CompatDiscoverer.

Parameters:

Name	Type	Description	Default
pkg_name	str	The package name to inspect (e.g., "numpy").	required
targets	Sequence[Target]	The compatibility targets to compute constraints for. Each target must have concrete (non-None) os and arch. Defaults to DEFAULT_TARGETS.	DEFAULT_TARGETS

Returns:

Type	Description
dict[Target, list[VersionRange]]	A mapping of Target to a list of VersionRange, in the same shape expected by CompatRegistry.register_many.

Example

>>> from feu.compat import discover_compat_targets
>>> compat = discover_compat_targets("numpy")  # doctest: +SKIP

feu.compat.discoverers.get_default_registry

get_default_registry() -> CompatDiscovererRegistry

Return the default global compatibility discoverer registry.

The registry is created on the first call and reused on all subsequent calls (singleton pattern).

Returns:

Type	Description
CompatDiscovererRegistry	A singleton CompatDiscovererRegistry.

Example

>>> from feu.compat.discoverers import get_default_registry
>>> registry = get_default_registry()

feu.compat.discoverers.register_discoverers

register_discoverers(
    mapping: Mapping[str, BaseCompatDiscoverer],
    exist_ok: bool = False,
) -> None

Register custom compatibility discoverers into the default global registry.

Parameters:

Name	Type	Description	Default
mapping	Mapping[str, BaseCompatDiscoverer]	Mapping of package name to discoverer.	required
exist_ok	bool	If False, RuntimeError is raised if any package already exists. This parameter should be set to True to overwrite the discoverer for a package.	False

Example

>>> from feu.compat.discoverers import CompatDiscoverer, register_discoverers
>>> register_discoverers({"my_package": CompatDiscoverer()})