auto_intersphinx.catalog#
This module contains instructions for documentation lookup.
Module Attributes
Type for the internal values of |
|
Base name for the catalog file distributed with this package. |
|
Regular expression for matching PEP-440 version numbers. |
Functions
|
Checks installed package metadata for documentation URLs. |
|
Checks PyPI for documentation pointers for a given package. |
|
Checks readthedocs.org for documentation pointers for the package. |
Classes
|
A type that can lookup and store information about Sphinx documents. |
|
A catalog that guarantees standardised version lookups. |
- auto_intersphinx.catalog.BUILTIN_CATALOG = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/auto-intersphinx/envs/v1.0.3/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)[source]#
Checks installed package metadata for documentation URLs.
- Parameters:
package (
str
) – Name of the package you want to checkversion – A version such as “stable”, “latest” or a formal version number parsed by
packaging.version.Version
.
- Return type:
- Returns:
A dictionary, that maps the version of the documentation found on PyPI to the URL.
- auto_intersphinx.catalog.docurls_from_rtd(package)[source]#
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:
- 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)[source]#
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 latestmax_entries
available on that particular package.- Parameters:
package (
str
) – Name of the PyPI package you want to checkmax_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 lastmax_entries
releases. Finally, a negative value will imply the download of all available releases.
- Return type:
- Returns:
A dictionary, that maps the version of the documentation found on PyPI to the URL.
- class auto_intersphinx.catalog.Catalog[source]#
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 asstable
,latest
,master
, ormain
are typically found as well.sources
: A dictionary mapping information sources for this particular entry. Keys are one ofpypi
,readthedocs
orenvironment
. 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.
- update_versions_from_environment(pkg, name)[source]#
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 (
Optional
[str
]) – 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 toNone
, then we just usepkg
as the name to lookup.
- Return type:
- Returns:
True
, if the update was successful (found versions), orFalse
, otherwise.
- update_versions_from_rtd(pkg, name)[source]#
Replaces package documentation URLs using information from readthedocs.org.
- Parameters:
- Return type:
- 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)[source]#
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 (
Optional
[str
]) – 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 toNone
, then we just usepkg
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 lastmax_entries
releases. Finally, a negative value will imply the download of all available releases.
- Return type:
- 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)[source]#
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 theorder
, and it is the following:Current Python environment (
environment
)readthedocs.org (
readthedocs
)PyPI (
pypi
)
- Parameters:
pkgs (
Iterable
[str
]) – List of packages that will have their versions updatedorder (
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, andpypi
, which will trigger pypi.org lookups from uploaded packages.names (
dict
[str
,dict
[str
,str
]]) – A dictionary, that eventually maps source names (as inorder
) 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 toNone
, 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 lastmax_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 flagkeep_going
is set toTrue
(defaults toFalse
), then it merges information from all sources. Note that some of this information may be repetitive.
- Return type:
- class auto_intersphinx.catalog.LookupCatalog(catalog)[source]#
Bases:
object
A catalog that guarantees standardised version lookups.
- Parameters:
catalog (
Catalog
) – The catalog to use as base for the lookup.
- reset()[source]#
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)[source]#
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 (
Optional
[str
]) – 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 amatch. –
- Returns:
If a match is found, returns the URL for the documentation. Otherwise, returns the
default
value.