intersphinx-registry 0.2511.7__tar.gz → 0.2601.5__tar.gz

intersphinx_registry-0.2601.5/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: intersphinx_registry
+Version: 0.2601.5
+Summary: This package provides convenient utilities and data to write a sphinx config file.
+Author-email: M Bussonnier <bussonniermatthias@gmail.com>
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+License-File: LICENSE
+Requires-Dist: intersphinx_registry[lookup] ; extra == "cli"
+Requires-Dist: sphinx>=8 ; extra == "lookup"
+Requires-Dist: requests ; extra == "lookup"
+Requires-Dist: requests-cache ; extra == "lookup"
+Requires-Dist: platformdirs ; extra == "lookup"
+Requires-Dist: pytest>=7.0 ; extra == "tests"
+Requires-Dist: pytest-xdist ; extra == "tests"
+Requires-Dist: mypy ; extra == "tests"
+Requires-Dist: types-requests ; extra == "tests"
+Requires-Dist: intersphinx_registry[cli] ; extra == "tests"
+Project-URL: Home, https://github.com/Quansight-labs/intersphinx_registry
+Provides-Extra: cli
+Provides-Extra: lookup
+Provides-Extra: tests
+
+# Intersphinx Registry
+
+A simple utility package that provides a default intersphinx mapping for a large chunk of the Python ecosystem.
+
+## Installation
+
+```bash
+# Core package only (for use in conf.py/Sphinx projects)
+pip install intersphinx_registry
+
+# With a command-line interface
+pip install intersphinx_registry[cli]
+# or
+uv tool install intersphinx_registry[cli]
+# or
+pipx install intersphinx_registry[cli]
+```
+
+You can also use it without installation:
+
+```bash
+uvx intersphinx-registry[cli] lookup numpy,scipy array
+```
+
+## Usage in `conf.py`
+
+```python
+from intersphinx_registry import get_intersphinx_mapping
+
+# ...
+intersphinx_mapping = get_intersphinx_mapping(
+    packages={"ipython", "matplotlib", "pandas", "python"}
+)
+intersphinx_mapping.update({
+    'overwrite': ('<url>', None),
+    'my-package': ('<url>', None),
+})
+```
+
+## Command-line interface
+
+The package provides a command-line interface for looking up intersphinx targets.
+
+> [!NOTE]
+> The CLI requires installing the `[cli]` extra: `pip install intersphinx_registry[cli]`
+
+```bash
+$ intersphinx-registry --version
+# or
+$ intersphinx-registry -v
+```
+
+### quick lookup
+
+You can use the lookup command to search for intersphinx targets and webpages across various packages.
+
+Call without arguments to get help:
+
+```bash
+$ intersphinx-registry lookup
+```
+
+Basic usage:
+
+```bash
+$ intersphinx-registry lookup <package>[,package] [search_term]
+```
+
+Examples:
+
+```bash
+$ intersphinx-registry lookup numpy,scipy array
+$ intersphinx-registry lookup ipython formatters.html
+```
+
+You can search multiple packages at once:
+
+```bash
+$ intersphinx-registry lookup numpy,scipy Universal
+std:label ufuncs                             NumPy 2.1    'Universal functions (ufunc)'                         https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs
+std:label ufuncs-basics                      NumPy 2.1    'Universal functions (ufunc) basics'                  https://numpy.org/doc/stable/user/basics.ufuncs.html#ufuncs-basics
+std:label ufuncs-internals                   NumPy 2.1    'Universal functions'                                 https://numpy.org/doc/stable/dev/internals.code-explanations.html#ufuncs-internals
+std:doc   reference/ufuncs                   NumPy 2.1    'Universal functions (ufunc)'                         https://numpy.org/doc/stable/reference/ufuncs.html
+std:doc   user/basics.ufuncs                 NumPy 2.1    'Universal functions (ufunc) basics'                  https://numpy.org/doc/stable/user/basics.ufuncs.html
+std:label non-uniform-random-number-sampling SciPy 1.14.1 'Universal Non-Uniform Random Number Sampling in SciPy' https://docs.scipy.org/doc/scipy/tutorial/stats/sampling.html#non-uniform-random-number-sampling
+std:doc   tutorial/stats/sampling            SciPy 1.14.1 'Universal Non-Uniform Random Number Sampling in SciPy' https://docs.scipy.org/doc/scipy/tutorial/stats/sampling.html
+```
+
+> [!WARNING]
+> There is no cache; the lookup command downloads the inventory of each mentioned package every time.
+
+You can also use the lookup functionality via the module interface:
+
+```bash
+$ python -m intersphinx_registry.lookup <package>[,package] [search_term]
+```
+
+### reverse-lookup
+
+Find which package a documentation URL belongs to and get its Sphinx reference.
+
+```bash
+$ intersphinx-registry reverse-lookup <url> [url...]
+```
+
+Examples:
+
+```bash
+$ intersphinx-registry reverse-lookup https://numpy.org/doc/stable/reference/arrays.html
+$ intersphinx-registry reverse-lookup https://docs.python.org/3/ https://numpy.org/doc/stable/
+```
+
+This is useful when you have a link to documentation and want to know the corresponding Sphinx reference (`:domain:package:target`) that you can use in your own documentation with intersphinx.
+
+### rev-search
+
+Scan `.rst` files in a directory for hardcoded URLs and suggest replacements with Sphinx references.
+
+```bash
+$ intersphinx-registry rev-search <directory-or-file>
+```
+
+Examples:
+
+```bash
+$ intersphinx-registry rev-search docs/
+$ intersphinx-registry rev-search docs/index.rst
+```
+
+This command helps you convert hardcoded URLs in your reStructuredText documentation into proper intersphinx references. It scans your documentation files, finds URLs that match known packages in the registry, and shows you a diff-style output of the suggested changes.
+
+## Why ?
+
+Sometimes, packages docs move and it's hard to keep track of them. We _try_ to keep the
+registry up to date, so you do not have to ask yourself questions and update your
+intersphinx-mapping.
+
+You also might not want to think about adding intersphinx mapping when you refer
+to dependencies.
+
+## A package url is wrong !
+
+Please send a PR updating only this package in the `registry.json`. We try to
+link only to _stable_ package, not dev versions.
+
+## A package is missing !
+
+We can't do all packages, but if you think a package is widely used and missing,
+please send a PR.
+

intersphinx_registry-0.2601.5/README.md

@@ -0,0 +1,149 @@
+# Intersphinx Registry
+
+A simple utility package that provides a default intersphinx mapping for a large chunk of the Python ecosystem.
+
+## Installation
+
+```bash
+# Core package only (for use in conf.py/Sphinx projects)
+pip install intersphinx_registry
+
+# With a command-line interface
+pip install intersphinx_registry[cli]
+# or
+uv tool install intersphinx_registry[cli]
+# or
+pipx install intersphinx_registry[cli]
+```
+
+You can also use it without installation:
+
+```bash
+uvx intersphinx-registry[cli] lookup numpy,scipy array
+```
+
+## Usage in `conf.py`
+
+```python
+from intersphinx_registry import get_intersphinx_mapping
+
+# ...
+intersphinx_mapping = get_intersphinx_mapping(
+    packages={"ipython", "matplotlib", "pandas", "python"}
+)
+intersphinx_mapping.update({
+    'overwrite': ('<url>', None),
+    'my-package': ('<url>', None),
+})
+```
+
+## Command-line interface
+
+The package provides a command-line interface for looking up intersphinx targets.
+
+> [!NOTE]
+> The CLI requires installing the `[cli]` extra: `pip install intersphinx_registry[cli]`
+
+```bash
+$ intersphinx-registry --version
+# or
+$ intersphinx-registry -v
+```
+
+### quick lookup
+
+You can use the lookup command to search for intersphinx targets and webpages across various packages.
+
+Call without arguments to get help:
+
+```bash
+$ intersphinx-registry lookup
+```
+
+Basic usage:
+
+```bash
+$ intersphinx-registry lookup <package>[,package] [search_term]
+```
+
+Examples:
+
+```bash
+$ intersphinx-registry lookup numpy,scipy array
+$ intersphinx-registry lookup ipython formatters.html
+```
+
+You can search multiple packages at once:
+
+```bash
+$ intersphinx-registry lookup numpy,scipy Universal
+std:label ufuncs                             NumPy 2.1    'Universal functions (ufunc)'                         https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs
+std:label ufuncs-basics                      NumPy 2.1    'Universal functions (ufunc) basics'                  https://numpy.org/doc/stable/user/basics.ufuncs.html#ufuncs-basics
+std:label ufuncs-internals                   NumPy 2.1    'Universal functions'                                 https://numpy.org/doc/stable/dev/internals.code-explanations.html#ufuncs-internals
+std:doc   reference/ufuncs                   NumPy 2.1    'Universal functions (ufunc)'                         https://numpy.org/doc/stable/reference/ufuncs.html
+std:doc   user/basics.ufuncs                 NumPy 2.1    'Universal functions (ufunc) basics'                  https://numpy.org/doc/stable/user/basics.ufuncs.html
+std:label non-uniform-random-number-sampling SciPy 1.14.1 'Universal Non-Uniform Random Number Sampling in SciPy' https://docs.scipy.org/doc/scipy/tutorial/stats/sampling.html#non-uniform-random-number-sampling
+std:doc   tutorial/stats/sampling            SciPy 1.14.1 'Universal Non-Uniform Random Number Sampling in SciPy' https://docs.scipy.org/doc/scipy/tutorial/stats/sampling.html
+```
+
+> [!WARNING]
+> There is no cache; the lookup command downloads the inventory of each mentioned package every time.
+
+You can also use the lookup functionality via the module interface:
+
+```bash
+$ python -m intersphinx_registry.lookup <package>[,package] [search_term]
+```
+
+### reverse-lookup
+
+Find which package a documentation URL belongs to and get its Sphinx reference.
+
+```bash
+$ intersphinx-registry reverse-lookup <url> [url...]
+```
+
+Examples:
+
+```bash
+$ intersphinx-registry reverse-lookup https://numpy.org/doc/stable/reference/arrays.html
+$ intersphinx-registry reverse-lookup https://docs.python.org/3/ https://numpy.org/doc/stable/
+```
+
+This is useful when you have a link to documentation and want to know the corresponding Sphinx reference (`:domain:package:target`) that you can use in your own documentation with intersphinx.
+
+### rev-search
+
+Scan `.rst` files in a directory for hardcoded URLs and suggest replacements with Sphinx references.
+
+```bash
+$ intersphinx-registry rev-search <directory-or-file>
+```
+
+Examples:
+
+```bash
+$ intersphinx-registry rev-search docs/
+$ intersphinx-registry rev-search docs/index.rst
+```
+
+This command helps you convert hardcoded URLs in your reStructuredText documentation into proper intersphinx references. It scans your documentation files, finds URLs that match known packages in the registry, and shows you a diff-style output of the suggested changes.
+
+## Why ?
+
+Sometimes, packages docs move and it's hard to keep track of them. We _try_ to keep the
+registry up to date, so you do not have to ask yourself questions and update your
+intersphinx-mapping.
+
+You also might not want to think about adding intersphinx mapping when you refer
+to dependencies.
+
+## A package url is wrong !
+
+Please send a PR updating only this package in the `registry.json`. We try to
+link only to _stable_ package, not dev versions.
+
+## A package is missing !
+
+We can't do all packages, but if you think a package is widely used and missing,
+please send a PR.

intersphinx_registry-0.2601.5/intersphinx_registry/__init__.py

@@ -0,0 +1,79 @@
+"""
+This package provides convenient utilities and data to write a sphinx config file.
+"""
+
+from __future__ import annotations
+
+import json
+import warnings
+from pathlib import Path
+from typing import Optional, Tuple, cast
+
+# See issue 4, we this the best format is Major.YYMM.day,
+# in case of multiple releases a day we can borrow the next day's date.
+# no 0 in front of the day as it is not pep440 compliant.
+version_info = (0, 2601, 5)
+__version__ = ".".join(map(str, version_info))
+
+registry_file = Path(__file__).parent / "registry.json"
+
+# Mapping of removed aliases to their canonical package names
+_ALIASES = {
+    "rtd": "readthedocs",
+    "server": "jupyter-server",
+}
+
+
+def _get_all_mappings() -> dict[str, tuple[str, str | None]]:
+    return cast(
+        dict[str, Tuple[str, Optional[str]]],
+        {k: tuple(v) for (k, v) in json.loads(registry_file.read_bytes()).items()},
+    )
+
+
+def get_intersphinx_mapping(
+    *, packages: set[str] = set()
+) -> dict[str, tuple[str, str | None]]:
+    """
+    Return values of intersphinx_mapping for sphinx configuration.
+
+    For convenience, the returned dictionary is a copy so should be ok to
+    mutate.
+
+    Parameters
+    ----------
+    packages: Set of Str
+        Libraries to include.
+
+        Sphinx will download and load all the `objects.inv` for listed
+        packages. Getting all mappings is discourage as it will download all
+        the `object.inv` which can be a non-negligible amount of data.
+
+    """
+    if len(packages) == 0:
+        raise ValueError(
+            'You must explicitly give a list of packages for which to download intersphinx inventories: get_intersphinx_mapping(packages=["IPython", "numpy",...]).'
+        )
+
+    mapping = _get_all_mappings()
+
+    # Check for aliases and replace them with canonical names
+    resolved_packages = set()
+    for pkg in packages:
+        if pkg in _ALIASES:
+            canonical = _ALIASES[pkg]
+            warnings.warn(
+                f"Package alias '{pkg}' is deprecated. Use '{canonical}' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            resolved_packages.add(canonical)
+        else:
+            resolved_packages.add(pkg)
+
+    missing = resolved_packages - set(mapping)
+    if missing:
+        raise ValueError(
+            f"Some libraries in 'packages' not found in registry: {repr(sorted(missing))}"
+        )
+    return {k: v for k, v in mapping.items() if k in resolved_packages}

intersphinx_registry-0.2601.5/intersphinx_registry/__main__.py

@@ -0,0 +1,4 @@
+from intersphinx_registry.cli import main
+
+if __name__ == "__main__":
+    main()

{intersphinx_registry-0.2511.7 → intersphinx_registry-0.2601.5}/intersphinx_registry/_info.py

@@ -1,8 +1,8 @@
 """
 Experimental, print info about all (or a subset of), all the known inventories.
 
-As this is likely to make _many_ concurrent connections; 
-we use aoihttp and sphobjinv which are not listed as dependencies.
+As this is likely to make _many_ concurrent connections;
+we use aiohttp and sphobjinv which are not listed as dependencies.
 """
 
 import asyncio
@@ -66,7 +66,7 @@ for key, base_url, data in results:
     flattened.append((key, base_url, inv.project, inv.version, inv.count))
 
 if not flattened:
-    sys.exit("Could not reach any pacakges")
+    sys.exit("Could not reach any packages")
 width = [len(x) for x in flattened[0][:-1]]
 
 for item in flattened:
@@ -76,5 +76,5 @@ for item in flattened:
 for key, url, proj, version, count in flattened:
     w_key, w_url, w_proj, w_version = width
     print(
-        f"{key:<{w_key}}  {proj!r:<{w_proj+2}} {version:<{w_version}} {count:<5} {url:<{w_url}}"
+        f"{key:<{w_key}}  {proj!r:<{w_proj + 2}} {version:<{w_version}} {count:<5} {url:<{w_url}}"
     )

intersphinx_registry-0.2601.5/intersphinx_registry/cli.py

@@ -0,0 +1,128 @@
+import argparse
+import sys
+
+from intersphinx_registry import __version__
+from intersphinx_registry.lookup import clear_cache, lookup_packages, print_info
+from intersphinx_registry.reverse_lookup import reverse_lookup
+from intersphinx_registry.rev_search import rev_search
+from intersphinx_registry.utils import _are_dependencies_available
+
+
+def lookup_command(args):
+    if not _are_dependencies_available():
+        sys.exit(1)
+
+    if not args.packages:
+        print("Usage: intersphinx-registry lookup <package>[,package] [search_term]\n")
+        print("Examples:")
+        print("  intersphinx-registry lookup numpy,scipy array")
+        print("  intersphinx-registry lookup ipython formatters.html")
+        sys.exit(0)
+
+    lookup_packages(args.packages, args.search_term)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="intersphinx-registry",
+        description="Default intersphinx mapping for the Python ecosystem",
+        epilog="For more information, see: https://github.com/Quansight-labs/intersphinx_registry",
+    )
+
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"intersphinx-registry {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(
+        title="subcommands",
+        description="available subcommands",
+        dest="subcommand",
+        help="subcommand help",
+    )
+
+    # Lookup subcommand
+    lookup_parser = subparsers.add_parser(
+        "lookup",
+        help="Search and lookup intersphinx targets/webpages",
+        description="Search intersphinx inventories for documentation targets",
+    )
+    lookup_parser.add_argument(
+        "packages",
+        nargs="?",
+        default=None,
+        help="Comma-separated list of package names (e.g., numpy,scipy)",
+    )
+    lookup_parser.add_argument(
+        "search_term",
+        nargs="?",
+        default=None,
+        help="Optional search term to filter results",
+    )
+    lookup_parser.set_defaults(func=lookup_command)
+
+    reverse_lookup_parser = subparsers.add_parser(
+        "reverse-lookup",
+        help="Find which packages documentation URLs belong to",
+        description="Given URLs, find which packages they come from",
+        epilog="Examples:\n"
+        "  intersphinx-registry reverse-lookup https://numpy.org/doc/stable/reference/arrays.html\n"
+        "  intersphinx-registry reverse-lookup https://docs.python.org/3/ https://numpy.org/doc/stable/",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    reverse_lookup_parser.add_argument(
+        "urls",
+        nargs="*",
+        help="URLs to look up (space-separated)",
+    )
+
+    def _reverse_lookup_wrapper(args):
+        if not args.urls:
+            reverse_lookup_parser.print_help()
+            sys.exit(0)
+        reverse_lookup(args.urls)
+
+    reverse_lookup_parser.set_defaults(func=_reverse_lookup_wrapper)
+
+    rev_search_parser = subparsers.add_parser(
+        "rev-search",
+        help="Search .rst files for URLs that can be replaced with Sphinx references",
+        description="Scan directory for .rst files and find URLs that can be replaced",
+        epilog="Examples:\n"
+        "  intersphinx-registry rev-search docs/\n"
+        "  intersphinx-registry rev-search .",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    rev_search_parser.add_argument(
+        "directory",
+        help="Directory to search for .rst files",
+    )
+    rev_search_parser.set_defaults(func=lambda args: rev_search(args.directory))
+
+    clear_cache_parser = subparsers.add_parser(
+        "clear-cache",
+        help="Clear the intersphinx inventory cache",
+        description="Clear the cached intersphinx inventory files",
+    )
+    clear_cache_parser.set_defaults(func=lambda args: clear_cache())
+
+    info_parser = subparsers.add_parser(
+        "info",
+        help="Display information about the intersphinx-registry installation",
+        description="Show version, cache location, registry file location, and package count",
+    )
+    info_parser.set_defaults(func=lambda args: print_info())
+
+    args = parser.parse_args()
+
+    if args.subcommand is None:
+        parser.print_help()
+        sys.exit(0)
+
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()