auto_intersphinx.catalog

This module contains instructions for documentation lookup.

Module Attributes

PackageDictionaryType	Type for the internal values of Catalog
BUILTIN_CATALOG	Base name for the catalog file distributed with this package.
PEP440_RE	Regular expression for matching PEP-440 version numbers.

Functions

docurls_from_environment(package)	Checks installed package metadata for documentation URLs.
docurls_from_pypi(package, max_entries)	Checks PyPI for documentation pointers for a given package.
docurls_from_rtd(package)	Checks readthedocs.org for documentation pointers for the package.

Classes

Catalog()	A type that can lookup and store information about Sphinx documents.
LookupCatalog(catalog)	A catalog that guarantees standardised version lookups.

auto_intersphinx.catalog.PackageDictionaryType

Type for the internal values of Catalog

alias of dict[str, dict[str, str]]

auto_intersphinx.catalog.BUILTIN_CATALOG = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/auto-intersphinx/envs/latest/lib/python3.11/site-packages/auto_intersphinx/catalog.json')

Base name for the catalog file distributed with this package.

auto_intersphinx.catalog.PEP440_RE = re.compile('^\\s*\n    v?\n    (?:\n        (?:(?P<epoch>[0-9]+)!)?                           # epoch\n        (?P<release>[0-9]+(?:\\.[0-9]+)*)                  # release segment\n        (?P<pre>              , re.IGNORECASE|re.VERBOSE)

Regular expression for matching PEP-440 version numbers.

auto_intersphinx.catalog.docurls_from_environment(package)

Checks installed package metadata for documentation URLs.

Parameters:

• package (str) – Name of the package you want to check

• version – A version such as “stable”, “latest” or a formal version number parsed by packaging.version.Version.

Return type:

dict[str, str]

Returns:

A dictionary, that maps the version of the documentation found on PyPI to the URL.

auto_intersphinx.catalog.docurls_from_rtd(package)

Checks readthedocs.org for documentation pointers for the package.

Parameters:

package (str) – Name of the package to check on rtd.org - this must be the name it is know at rtd.org and not necessarily the package name. Some packages do have different names on rtd.org.

Return type:

dict[str, str]

Returns:

A dictionary, which contains all versions of documentation available for the given package on RTD. If the package’s documentation is not available on RTD, returns an empty dictionary.

auto_intersphinx.catalog.docurls_from_pypi(package, max_entries)

Checks PyPI for documentation pointers for a given package.

This procedure first looks up the main repo JSON entry, and then figures out all available versions of the package. In a second step, and depending on the value of max_entries, this function will retrieve the latest max_entries available on that particular package.

Parameters:

• package (str) – Name of the PyPI package you want to check

• max_entries (int) – The maximum number of entries to lookup in PyPI. A value of zero will download only the main package information and will hit PyPI only once. A value bigger than zero will download at most the information from the last max_entries releases. Finally, a negative value will imply the download of all available releases.

Return type:

dict[str, str]

Returns:

A dictionary, that maps the version of the documentation found on PyPI to the URL.

class auto_intersphinx.catalog.Catalog

Bases: MutableMapping

A type that can lookup and store information about Sphinx documents.

The object is organised as a dictionary (mutable mapping type) with extra methods to handle information update from various sources. Information is organised as dictionary mapping Python package names to another dictionary containing the following entries:

• versions: A dictionary mapping version numbers to URLs. The keys have free form, albeit are mostly PEP440 version numbers. Keywords such as stable, latest, master, or main are typically found as well.

• sources: A dictionary mapping information sources for this particular entry. Keys are one of pypi, readthedocs or environment. Values correspond to specific names used for the lookup of the information on those sources.

_data

Internal dictionary containing the mapping between package names the user can refer to, versions and eventual sources of such information.

load(path)

Loads and replaces contents with those from the file.

Return type:

None

loads(contents)

Loads and replaces contents with those from the string.

Return type:

None

dump(path)

Loads and replaces contents with those from the file.

Return type:

None

dumps()

Loads and replaces contents with those from the string.

Return type:

str

reset()

Full resets internal catalog.

Return type:

None

update_versions_from_environment(pkg, name)

Replaces package documentation URLs using information from current Python environment.

Parameters:

• pkg (str) – Name of the package as one would find in pypi.org. This name can be different then that of the Python package itself.

• name (str | None) – This is the name of the package as installed on the current environment. Sometimes, this name can be different then that of the Python package itself. If this value is set to None, then we just use pkg as the name to lookup.

Return type:

bool

Returns:

True, if the update was successful (found versions), or False, otherwise.

update_versions_from_rtd(pkg, name)

Replaces package documentation URLs using information from readthedocs.org.

Parameters:

• pkg (str) – Name of the Python package to update versions for.

• name (str | None) – This is the name of the package on readthedocs.org. Often, this name is different then that of the Python package itself. If this value is set to None, then we just use pkg as the name to lookup.

Return type:

bool

Returns:

The dictionary of values for the current package, as obtained from readthedocs.org, and potentially merged with the existing one.

update_versions_from_pypi(pkg, name, max_entries)

Replaces package documentation URLs using information from pypi.org.

Parameters:

• pkg (str) – Name of the package as one would find in pypi.org. This name can be different then that of the Python package itself.

• name (str | None) – This is the name of the package on pypi.org. Sometimes, this name can be different then that of the Python package itself. If this value is set to None, then we just use pkg as the name to lookup.

• max_entries (int) – The maximum number of entries to lookup in PyPI. A value of zero will download only the main package information and will hit PyPI only once. A value bigger than zero will download at most the information from the last max_entries releases. Finally, a negative value will imply the download of all available releases.

Return type:

bool

Returns:

The dictionary of values for the current package, as obtained from pypi.org, and potentially merged with the existing one.

update_versions(pkgs, order=['environment', 'readthedocs', 'pypi'], names={}, pypi_max_entries=0, keep_going=False)

Updates versions for a list of packages in this catalog.

This method will add a list of packages defined by pkgs (list of names) into its own catalog. The order of look-ups by default is set by the order, and it is the following:

1. Current Python environment (environment)

2. readthedocs.org (readthedocs)

3. PyPI (pypi)

Parameters:

• pkgs (Iterable[str]) – List of packages that will have their versions updated

• order (Iterable[str]) – A list, containing the order in which lookup will happen. There are only 3 possible keys that can be used here: environment, which stands for finding package metadata from the currently installed Python environment, readthedocs, which will trigger readthedocs.org lookups, and pypi, which will trigger pypi.org lookups from uploaded packages.

• names (dict[str, dict[str, str]]) – A dictionary, that eventually maps source names (as in order) to another dictionary that maps package names to to their supposed names on readthedocs.org, pypi.org or the current environment. If keys for various packages are not available, then their package names are used. If the keys exist, but are set to None, then lookup for that particular source is skipped.

• pypi_max_entries (int) – The maximum number of entries to lookup in PyPI. A value of zero will download only the main package information and will hit PyPI only once. A value bigger than zero will download at most the information from the last max_entries releases. Finally, a negative value will imply the download of all available releases.

• keep_going (bool) – By default, the method stops adding a package when a hit is found (in either of these sources of information). If the flag keep_going is set to True (defaults to False), then it merges information from all sources. Note that some of this information may be repetitive.

Return type:

None

self_update()

Runs a self-update procedure, by re-looking up known sources.

Return type:

None

class auto_intersphinx.catalog.LookupCatalog(catalog)

Bases: object

A catalog that guarantees standardised version lookups.

Parameters:

catalog (Catalog) – The catalog to use as base for the lookup.

reset()

Internally creates all possible aliases for package names and versions.

This method will expand the catalog package names and version numbers so that the user can refer to these using environment, readthedocs.org or pypi.org names for packages, and PEP-440 compatible strings for version names during the lookup.

The catalog associated to this lookup is not modified in this process. All augmentations are built-into the object instance.

get(pkg, version, default=None)

Accesses one single pkg/version documentation URL.

Parameters:

• pkg (str) – The package name, as available on the catalog or through one of its environment, readthedocs.org or pypi.org names.

• version (str | None) – The version of the package to search for. This must be either an identifier from readthedocs.org or pypi.org, or a valid PEP-440 version number as a string.

• default (Any) – The default value to return in case we do not find a

• match.

Returns:

If a match is found, returns the URL for the documentation. Otherwise, returns the default value.