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]
New 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 newVersionDatabase
instance- Parameters:
- Return type:
- cpython: CPythonVersionInfo
A database of CPython version information
- 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 newVersionDatabase
instance
- pypy: PyPyVersionInfo
A database of PyPy version information
- class pyversion_info.VersionInfo[source]
New 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:
- Raises:
UnknownVersionError – if there is no micro version corresponding to
version
in the databaseValueError – 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; useis_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 databaseValueError – if
version
is not a valid version string
- 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. Ifversion
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 databaseValueError – if
version
is not a valid major or minor version string
- 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; useis_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 tableValueError – if
version
is not a valid version string
- 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:
- Raises:
UnknownVersionError – if there is no entry for
version
in the end-of-life tableValueError – 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:
- Raises:
UnknownVersionError – if there is no entry for
version
in the database
- class pyversion_info.PyPyVersionInfo[source]
Bases:
VersionInfo
New in version 1.0.0.
A class for storing & querying PyPy versions, their release dates, and their corresponding CPython versions
- 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 databaseValueError – 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 databaseValueError – if
version
is not a valid version string
- exception pyversion_info.UnknownVersionError(version: str)[source]
Bases:
ValueError
Subclass of
ValueError
raised when aVersionInfo
instance is asked for information about a version that does not appear in its database. Operations that result in anUnknownVersionError
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