API

Versions are passed to & returned from methods as strings in the form "X" (a major version), "X.Y" (a minor version), or "X.Y.Z" (a micro version).

All dates are returned as datetime.date objects.

class pyversion_info.VersionDatabase[source]

Added in version 1.0.0.

A database of CPython and PyPy version information. Instances are constructed from JSON objects following this JSON Schema.

classmethod fetch(url: str = DATA_URL, cache_dir: str | pathlib.Path | None = CACHE_DIR) → pyversion_info.VersionDatabase[source]

Fetches the latest version information from the JSON document at url and returns a new VersionDatabase instance

Parameters:

url (str) – The URL from which to fetch the data
cache_dir (str | Path | None) – The directory to use for caching HTTP requests. May be None to disable caching.

Return type:

VersionDatabase

cpython: CPythonVersionInfo: A database of CPython version information

last_modified: datetime: The date & time when the database was last updated

classmethod parse_file(filepath: str | Path) → VersionDatabase[source]: Parses a version database from a JSON file and returns a new VersionDatabase instance

classmethod parse_obj(data: dict) → VersionDatabase[source]: Parses a version database from a dict deserialized from a JSON document and returns a new VersionDatabase instance

pypy: PyPyVersionInfo: A database of PyPy version information

class pyversion_info.VersionInfo[source]

Added in version 1.0.0.

A base class for storing & querying versions and their release dates

is_released(version: str) → bool[source]

Returns whether the given version has been released yet. For a major or minor version, this is the whether the first (in version order) micro version has been released.

Parameters:

version (str) – the version to query the release status of

Return type:

bool

Raises:

UnknownVersionError – if there is no micro version corresponding to version in the database
ValueError – if version is not a valid version string

major_versions() → list[str][source]: Returns a list in version order of all known major versions (as strings).

Changed in version 1.0.0: Now returns all known versions, released & unreleased

micro_versions() → list[str][source]: Returns a list in version order of all known micro versions

Changed in version 1.0.0: Now returns all known versions, released & unreleased

minor_versions() → list[str][source]: Returns a list in version order of all known minor versions

Changed in version 1.0.0: Now returns all known versions, released & unreleased

release_date(version: str) → date | None[source]

Returns the release date of the given version. For a major or minor version, this is the release date of its first (in version order) micro version. The return value may be None, indicating that, though the version is known to the database, its release date is not; use is_released() to determine whether such a version has been released yet.

Changed in version 1.0.0: Unknown release dates are now always returned as None

Parameters:

version (str) – the version to fetch the release date of

Return type:

Optional[datetime.date]

Raises:

UnknownVersionError – if there is no micro version corresponding to version in the database
ValueError – if version is not a valid version string

release_dates: dict[MicroVersion, date | bool]

subversions(version: str) → list[str][source]

Returns a list in version order of all known subversions of the given version. If version is a major version, this is all of its minor versions. If version is a minor version, this is all of its micro versions.

Changed in version 1.0.0: Now returns all known subversions, released & unreleased

Parameters:

version (str) – a major or minor version

Raises:

UnknownVersionError – if there is no entry for version in the database
ValueError – if version is not a valid major or minor version string

version_trie: dict[int, dict[int, list[int]]]

class pyversion_info.CPythonVersionInfo[source]

Bases: VersionInfo

A class for storing & querying CPython versions, their release dates, and series EOL dates

Changed in version 1.0.0: This class was previously named PyVersionInfo

eol_date(version: str) → date | None[source]

Returns the end-of-life date of the given CPython version. The return value may be None, indicating that, though the version is known to the database, its EOL date is not; use is_eol() to determine whether such a version has reached end-of-life yet.

For a major version, this method returns the EOL date of the last subversion if every subversion is already end-of-life; otherwise, it returns None. For a micro version, this returns the EOL date of the corresponding minor version.

Changed in version 1.0.0: Unknown end-of-life dates are now always returned as None

Changed in version 1.1.0: Major and micro versions are now accepted

Parameters:

version (str) – the version to fetch the end-of-life date of

Return type:

Optional[datetime.date]

Raises:

UnknownVersionError – if there is no entry for version in the end-of-life table
ValueError – if version is not a valid version string

eol_dates: dict[MinorVersion, date | bool]

is_eol(series: str) → bool[source]

Returns whether the given version has reached end-of-life yet. For a major version, this is whether every subversion has reached end-of-life. For a micro version, this is whether the corresponding minor version has reached end-of-life.

Changed in version 1.1.0: Major and micro versions are now accepted

Parameters:

series (str) – a Python version number

Return type:

bool

Raises:

UnknownVersionError – if there is no entry for version in the end-of-life table
ValueError – if version is not a valid version string

is_supported(version: str) → bool[source]

Returns whether the given version is currently supported. For a micro version, this is whether it has been released and the corresponding minor version is not yet end-of-life. For a major or minor version, this is whether at least one subversion is supported.

Parameters:: version (str) – the version to query the support status of
Return type:: bool
Raises:: UnknownVersionError – if there is no entry for version in the database

supported_series() → list[str][source]: Returns a list in version order of all CPython version series (i.e., minor versions like 3.5) that are currently supported (i.e., that have at least one release made and are not yet end-of-life)

class pyversion_info.PyPyVersionInfo[source]

Bases: VersionInfo

Added in version 1.0.0.

A class for storing & querying PyPy versions, their release dates, and their corresponding CPython versions

cpython_versions: dict[MicroVersion, list[MicroVersion]]

supported_cpython(version: str) → list[str][source]

Given a PyPy micro version, returns a list of the corresponding CPython micro versions in version order.

Raises:

UnknownVersionError – if there is no entry for version in the database
ValueError – if version is not a valid micro version string

supported_cpython_series(version: str, released: bool = False) → list[str][source]

Given a PyPy version, returns a list of all CPython series supported by that version or its subversions in version order. If released is true, only released versions are considered.

>>> db.supported_cpython_series("7.3.5")
['2.7', '3.7']
>>> db.supported_cpython_series("7.3")
['2.7', '3.6', '3.7', '3.8']
>>> db.supported_cpython_series("7")
['2.7', '3.5', '3.6', '3.7', '3.8']

Raises:

UnknownVersionError – if there is no entry for version in the database
ValueError – if version is not a valid version string

exception pyversion_info.UnknownVersionError(version: str)[source]

Bases: ValueError

Subclass of ValueError raised when a VersionInfo instance is asked for information about a version that does not appear in its database. Operations that result in an UnknownVersionError may succeed later as more Python versions are announced & released.

version: The unknown version the caller asked about

pyversion_info.DATA_URL: The default URL from which the version database is downloaded

pyversion_info.CACHE_DIR: The default directory in which the downloaded version database is cached