Package

feu.package ¶

Provide package version compatibility checking functionality.

This module provides a registry-based system for managing package version constraints across different Python versions. It allows you to:

Define minimum and maximum package version constraints for each Python version
Validate if a package version is compatible with a specific Python version
Find the closest valid package version when a requested version is out of range
Maintain a centralized registry of version constraints for common packages

The main class PackageConfig provides both class methods for direct use and a registry that can be extended with custom package configurations.

feu.package.PackageConfig ¶

Manage package version compatibility across different Python versions.

This class maintains a registry of package version constraints indexed by package name and Python version. Each entry specifies the minimum and maximum compatible versions for a package on a specific Python version.

The registry is structured as a nested dictionary

{ package_name: { python_version: { "min": minimum_version_string or None, "max": maximum_version_string or None, }, ... }, ... }

Use cases

Check if a package version is valid for a Python version
Find the closest valid version for a package
Add custom package configurations
Query version constraints for package/Python version combinations

Example

>>> from feu.package import PackageConfig
>>> # Check if numpy 2.0.2 is valid for Python 3.11
>>> PackageConfig.is_valid_version("numpy", "2.0.2", "3.11")
True
>>> # Get version constraints
>>> PackageConfig.get_config("numpy", "3.11")
{'min': '1.23.2', 'max': None}
>>> # Find closest valid version
>>> PackageConfig.find_closest_version("numpy", "1.0.0", "3.11")
'1.23.2'

Attributes:

Name	Type	Description
`registry`	`dict[str, dict[str, dict[str, str \| None]]]`	Class-level registry storing package version constraints. The structure is a three-level nested dictionary mapping package names to Python versions to version constraints.

feu.package.PackageConfig.add_config `classmethod` ¶

add_config(
    pkg_name: str,
    pkg_version_min: str | None,
    pkg_version_max: str | None,
    python_version: str,
    exist_ok: bool = False,
) -> None

Add a new package configuration to the registry.

This method registers version constraints for a package on a specific Python version. If a configuration already exists for the package and Python version, exist_ok must be True to allow overwriting.

Parameters:

Name	Type	Description	Default
`pkg_name`	`str`	The package name to register (e.g., `"numpy"`).	required
`pkg_version_min`	`str \| None`	The minimum valid package version for this Python version. Use `None` if there is no minimum version constraint.	required
`pkg_version_max`	`str \| None`	The maximum valid package version for this Python version. Use `None` if there is no maximum version constraint.	required
`python_version`	`str`	The Python version (e.g., `"3.11"`).	required
`exist_ok`	`bool`	If `False`, a `RuntimeError` is raised when a package configuration already exists for this package and Python version. Set to `True` to overwrite the existing configuration. Defaults to `False`.	`False`

Raises:

Type	Description
`RuntimeError`	If a package configuration already exists for the given package name and Python version, and `exist_ok` is `False`.

Example

>>> from feu.package import PackageConfig
>>> # Add a new package configuration
>>> PackageConfig.add_config(
...     pkg_name="my_package",
...     python_version="3.11",
...     pkg_version_min="1.2.0",
...     pkg_version_max="2.0.2",
... )
>>> # Overwrite existing configuration
>>> PackageConfig.add_config(
...     pkg_name="my_package",
...     python_version="3.11",
...     pkg_version_min="1.3.0",
...     pkg_version_max="2.1.0",
...     exist_ok=True,
... )

feu.package.PackageConfig.find_closest_version `classmethod` ¶

find_closest_version(
    pkg_name: str, pkg_version: str, python_version: str
) -> str

Find the closest valid version for a package.

Given a requested package version, this method returns the closest valid version based on the configured constraints for the package and Python version. The logic is:

If the requested version is below the minimum, return the minimum version
If the requested version is above the maximum, return the maximum version
Otherwise, return the requested version unchanged

If no configuration exists for the package or Python version, the requested version is returned unchanged.

Parameters:

Name	Type	Description	Default
`pkg_name`	`str`	The package name to check (e.g., `"numpy"`).	required
`pkg_version`	`str`	The requested package version to validate.	required
`python_version`	`str`	The Python version (e.g., `"3.11"`).	required

Returns:

Type	Description
`str`	The closest valid version as a string. This will be either the
`str`	requested version (if valid), the minimum version (if too low),
`str`	or the maximum version (if too high).

Example

>>> from feu.package import PackageConfig
>>> # Valid version is returned unchanged
>>> PackageConfig.find_closest_version(
...     pkg_name="numpy",
...     pkg_version="2.0.2",
...     python_version="3.11",
... )
'2.0.2'
>>> # Version too low, returns minimum
>>> PackageConfig.find_closest_version(
...     pkg_name="numpy",
...     pkg_version="1.0.2",
...     python_version="3.11",
... )
'1.23.2'

feu.package.PackageConfig.get_config `classmethod` ¶

get_config(
    pkg_name: str, python_version: str
) -> dict[str, str | None]

Get the package version configuration for a package and Python version.

Retrieves the minimum and maximum version constraints for a package on the specified Python version from the registry.

Parameters:

Name	Type	Description	Default
`pkg_name`	`str`	The package name to query (e.g., `"numpy"`).	required
`python_version`	`str`	The Python version (e.g., `"3.11"`).	required

Returns:

Type	Description
`dict[str, str \| None]`	A dictionary with `"min"` and `"max"` keys containing the
`dict[str, str \| None]`	version constraint strings, or `None` for no constraint. Returns
`dict[str, str \| None]`	an empty dictionary if no configuration exists for the package or
`dict[str, str \| None]`	Python version.

Example

>>> from feu.package import PackageConfig
>>> # Get configuration for an existing package
>>> PackageConfig.get_config(pkg_name="numpy", python_version="3.11")
{'min': '1.23.2', 'max': None}
>>> # Query a non-existent configuration
>>> PackageConfig.get_config(pkg_name="unknown_pkg", python_version="3.11")
{}

feu.package.PackageConfig.get_min_and_max_versions `classmethod` ¶

get_min_and_max_versions(
    pkg_name: str, python_version: str
) -> tuple[Version | None, Version | None]

Get the minimum and maximum versions as Version objects.

Retrieves the version constraints for a package and Python version, converting them from strings to packaging.version.Version objects for comparison operations.

Parameters:

Name	Type	Description	Default
`pkg_name`	`str`	The package name to query (e.g., `"numpy"`).	required
`python_version`	`str`	The Python version (e.g., `"3.11"`).	required

Returns:

Type	Description
`Version \| None`	A tuple `(min_version, max_version)` where each value is either
`Version \| None`	a `packaging.version.Version` object or `None`. Returns
`tuple[Version \| None, Version \| None]`	`(None, None)` if no configuration exists for the package or
`tuple[Version \| None, Version \| None]`	Python version.

Example

>>> from feu.package import PackageConfig
>>> PackageConfig.get_min_and_max_versions(
...     pkg_name="numpy",
...     python_version="3.11",
... )
(<Version('1.23.2')>, None)

feu.package.PackageConfig.is_valid_version `classmethod` ¶

is_valid_version(
    pkg_name: str, pkg_version: str, python_version: str
) -> bool

Check if a package version is valid for a Python version.

Validates whether the specified package version falls within the configured minimum and maximum version constraints for the given Python version.

If no configuration exists for the package or Python version, the version is considered valid (returns True).

Parameters:

Name	Type	Description	Default
`pkg_name`	`str`	The package name to check (e.g., `"numpy"`).	required
`pkg_version`	`str`	The package version to validate.	required
`python_version`	`str`	The Python version (e.g., `"3.11"`).	required

Returns:

Type	Description
`bool`	`True` if the package version is valid for the Python version
`bool`	(i.e., it meets the minimum and maximum version constraints),
`bool`	`False` otherwise. Returns `True` if no configuration exists.

Example

>>> from feu.package import PackageConfig
>>> # Valid version
>>> PackageConfig.is_valid_version(
...     pkg_name="numpy",
...     pkg_version="2.0.2",
...     python_version="3.11",
... )
True
>>> # Version too low
>>> PackageConfig.is_valid_version(
...     pkg_name="numpy",
...     pkg_version="1.0.2",
...     python_version="3.11",
... )
False

feu.package.find_closest_version ¶

find_closest_version(
    pkg_name: str, pkg_version: str, python_version: str
) -> str

Find the closest valid version for a package.

This is a convenience function that delegates to PackageConfig.find_closest_version. See that method for full documentation.

Given a requested package version, returns the closest valid version based on the configured constraints:

If the requested version is below the minimum, return the minimum version
If the requested version is above the maximum, return the maximum version
Otherwise, return the requested version unchanged

Parameters:

Name	Type	Description	Default
`pkg_name`	`str`	The package name to check (e.g., `"numpy"`).	required
`pkg_version`	`str`	The requested package version to validate.	required
`python_version`	`str`	The Python version (e.g., `"3.11"`).	required

Returns:

Type	Description
`str`	The closest valid version as a string.

Example

>>> from feu.package import find_closest_version
>>> # Valid version is returned unchanged
>>> find_closest_version(
...     pkg_name="numpy",
...     pkg_version="2.0.2",
...     python_version="3.11",
... )
'2.0.2'
>>> # Version too low, returns minimum
>>> find_closest_version(
...     pkg_name="numpy",
...     pkg_version="1.0.2",
...     python_version="3.11",
... )
'1.23.2'

feu.package.is_valid_version ¶

is_valid_version(
    pkg_name: str, pkg_version: str, python_version: str
) -> bool

Check if a package version is valid for a Python version.

This is a convenience function that delegates to PackageConfig.is_valid_version. See that method for full documentation.

Validates whether the specified package version falls within the configured minimum and maximum version constraints.

Parameters:

Name	Type	Description	Default
`pkg_name`	`str`	The package name to check (e.g., `"numpy"`).	required
`pkg_version`	`str`	The package version to validate.	required
`python_version`	`str`	The Python version (e.g., `"3.11"`).	required

Returns:

Type	Description
`bool`	`True` if the package version is valid for the Python version,
`bool`	`False` otherwise. Returns `True` if no configuration exists.

Example

>>> from feu.package import is_valid_version
>>> # Valid version
>>> is_valid_version(
...     pkg_name="numpy",
...     pkg_version="2.0.2",
...     python_version="3.11",
... )
True
>>> # Version too low
>>> is_valid_version(
...     pkg_name="numpy",
...     pkg_version="1.0.2",
...     python_version="3.11",
... )
False

Package

feu.package ¶

feu.package.PackageConfig ¶

feu.package.PackageConfig.add_config classmethod ¶

feu.package.PackageConfig.find_closest_version classmethod ¶

feu.package.PackageConfig.get_config classmethod ¶

feu.package.PackageConfig.get_min_and_max_versions classmethod ¶

feu.package.PackageConfig.is_valid_version classmethod ¶

feu.package.find_closest_version ¶

feu.package.is_valid_version ¶

feu.package.PackageConfig.add_config `classmethod` ¶

feu.package.PackageConfig.find_closest_version `classmethod` ¶

feu.package.PackageConfig.get_config `classmethod` ¶

feu.package.PackageConfig.get_min_and_max_versions `classmethod` ¶

feu.package.PackageConfig.is_valid_version `classmethod` ¶