intersphinx-registry 0.2511.7__py2.py3-none-any.whl → 0.2601.5__py2.py3-none-any.whl

intersphinx_registry/__init__.py

@@ -4,28 +4,36 @@ This package provides convenient utilities and data to write a sphinx config fil
 
 from __future__ import annotations
 
-from pathlib import Path
 import json
-from typing import Dict, Tuple, Set, Optional, cast
+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, 2511, 7)
+version_info = (0, 2601, 5)
 __version__ = ".".join(map(str, version_info))
 
 registry_file = Path(__file__).parent / "registry.json"
 
-def _get_all_mappings() ->  Dict[str, Tuple[str, Optional[str]]]:
+# 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]]],
+        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, Optional[str]]]:
+    *, packages: set[str] = set()
+) -> dict[str, tuple[str, str | None]]:
     """
     Return values of intersphinx_mapping for sphinx configuration.
 
@@ -37,16 +45,35 @@ def get_intersphinx_mapping(
     packages: Set of Str
         Libraries to include.
 
-        Sphinx will download and load all the `objects.inv` for listed 
+        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",...]).')
+        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()
-    missing = set(packages) - set(mapping)
+
+    # 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 packages}
+        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/__main__.py

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

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/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()

intersphinx_registry/lookup.py

@@ -1,67 +1,142 @@
+import json
+import shutil
 import sys
-
-from . import get_intersphinx_mapping
-from . import __version__
-from urllib.parse import urljoin
-
+from io import BytesIO
+from pathlib import Path
 from typing import Optional
+from urllib.parse import urljoin
 
+import requests
 from sphinx.util.inventory import InventoryFile
-from io import BytesIO
 
-import requests
+from . import __version__, get_intersphinx_mapping
+from .utils import (
+    _are_dependencies_available,
+    _compress_user_path,
+    _get_cache_dir,
+    _install_cache,
+)
 
-if len(sys.argv) not in [2, 3]:
-    sys.exit(
-        """Usage: python -m intersphinx_registry.lookup <package>[,package] [search_term]
 
-        Example:
+def clear_cache() -> None:
+    """Clear the intersphinx inventory cache for the current version."""
+    if not _are_dependencies_available():
+        return
 
-        $ python -m intersphinx_registry.lookup numpy,scipy array
-        $ python -m intersphinx_registry.lookup ipython formatters.html
+    cache_dir = _get_cache_dir()
 
-        """
-    )
+    if cache_dir.exists():
+        for item in cache_dir.iterdir():
+            try:
+                if item.is_file():
+                    item.unlink()
+                elif item.is_dir():
+                    shutil.rmtree(item)
+            except Exception as e:
+                print(f"Warning: Could not remove {item}: {e}")
+
+    print("Cache cleared successfully")
+
+
+def get_info() -> dict[str, str]:
+    """
+    Get information about the intersphinx-registry installation.
+
+    Returns
+    -------
+    dict[str, str]
+        Dictionary containing version and cache location
+    """
+    info = {
+        "version": __version__,
+    }
+
+    try:
+        cache_dir = _get_cache_dir()
+        info["cache_location"] = str(cache_dir)
+    except Exception:
+        info["cache_location"] = "N/A (dependencies not installed)"
+
+    return info
+
+
+def print_info() -> None:
+    """Print information about the intersphinx-registry installation."""
+    info = get_info()
 
+    cache_location = _compress_user_path(info["cache_location"])
 
-def main():
-    print(f"Instersphinx-registry version {__version__}")
+    print("Intersphinx Registry Information")
+    print("=" * 50)
+    print(f"Version:               {info['version']}")
+    print(f"Cache location:        {cache_location}")
 
-    packages = set(sys.argv[1].split(","))
+    try:
+        registry_file_path = Path(__file__).parent / "registry.json"
+        registry = json.loads(registry_file_path.read_bytes())
+        print(f"Packages in registry:  {len(registry)}")
+    except Exception as e:
+        print(f"Packages in registry:  Error reading registry ({e})")
 
-    search_term: Optional[str]
-    if len(sys.argv) == 3:
-        search_term = sys.argv[2]
-    else:
-        search_term = None
 
-    # there will be only one url
+def lookup_packages(packages_str: str, search_term: Optional[str] = None) -> None:
+    """
+    Look up intersphinx targets for specified packages.
+
+    Parameters
+    ----------
+    packages_str : str
+        Comma-separated list of package names
+    search_term : str, optional
+        Search term to filter results
+    """
+    if not _are_dependencies_available():
+        return
+
+    packages = set(packages_str.split(","))
+
+    _install_cache()
+
     urls = [
         (u[0], (u[1] if u[1] else "objects.inv"))
         for u in get_intersphinx_mapping(packages=packages).values()
     ]
 
-    flattened = []
+    flattened: list[tuple[str, str, str, str, str, str]] = []
     for base_url, obj in urls:
-
         final_url = urljoin(base_url, obj)
 
-        resp = requests.get(final_url)
-
-        inv = InventoryFile.load(BytesIO(resp.content), base_url, urljoin)
+        try:
+            resp = requests.get(final_url, timeout=30)
+            resp.raise_for_status()
+            inv = InventoryFile.load(BytesIO(resp.content), base_url, urljoin)
+        except requests.RequestException as e:
+            print(f"Warning: Failed to fetch {final_url}: {e}", file=sys.stderr)
+            continue
+        except Exception as e:
+            print(
+                f"Warning: Failed to load inventory from {final_url}: {e}",
+                file=sys.stderr,
+            )
+            continue
 
         for key, v in inv.items():
             inv_entries = sorted(v.items())
-            for entry, (_proj, _ver, url_path, display_name) in inv_entries:
-                # display_name = display_name * (display_name != '-')
-                flattened.append((key, entry, _proj, _ver, display_name, url_path))
-
-    filtered = []
-
-    width = [len(x) for x in flattened[0]]
-
-    for item in flattened:
-        key, entry, proj, version, display_name, url_path = item
+            for entry, item in inv_entries:
+                flattened.append(
+                    (
+                        key,
+                        entry,
+                        item.project_name,
+                        item.project_version,
+                        item.display_name,
+                        item.uri,
+                    )
+                )
+
+    filtered: list[tuple[str, str, str, str, str, str]] = []
+    for item_tuple in flattened:
+        key, entry, proj, version, display_name, url_path = item_tuple
         if (
             (search_term is None)
             or (search_term in entry)
@@ -69,15 +144,40 @@ def main():
             or (search_term in url_path)
         ):
             filtered.append((key, entry, proj, version, display_name, url_path))
-            width = [max(w, len(x)) for w, x in zip(width, item)]
 
+    if not filtered:
+        return
+
+    width = [0] * 6
+    for item_tuple in filtered:
+        for i, x in enumerate(item_tuple):
+            width[i] = max(width[i], len(str(x)))
 
     for key, entry, proj, version, display_name, url_path in filtered:
         w_key, w_entry, w_proj, w_version, w_di, w_url = width
         print(
-            f"{key:<{w_key}}  {entry:<{w_entry}}  {proj:<{w_proj}}  {version:<{w_version}}  {display_name!r:<{w_di+2}}  {url_path}"
+            f"{key:<{w_key}}  {entry:<{w_entry}}  {proj:<{w_proj}}  "
+            f"{version:<{w_version}}  {display_name!r:<{w_di + 2}}  {url_path}"
         )
 
 
 if __name__ == "__main__":
-    main()
+    if len(sys.argv) not in [2, 3]:
+        sys.exit(
+            """Usage: python -m intersphinx_registry.lookup <package>[,package] [search_term]
+
+        Example:
+
+        $ python -m intersphinx_registry.lookup numpy,scipy array
+        $ python -m intersphinx_registry.lookup ipython formatters.html
+
+        """
+        )
+
+    packages_str = sys.argv[1]
+    search_term = sys.argv[2] if len(sys.argv) == 3 else None
+
+    try:
+        lookup_packages(packages_str, search_term)
+    except Exception as e:
+        sys.exit(f"ERROR: {e}")

intersphinx_registry/registry.json

@@ -119,6 +119,7 @@
   "poliastro": ["https://docs.poliastro.space/en/stable/", null],
   "pooch": ["https://www.fatiando.org/pooch/latest/", null],
   "prompt_toolkit": ["https://python-prompt-toolkit.readthedocs.io/en/stable/", null],
+  "py-free-threading": ["https://py-free-threading.github.io/", null],
   "py": ["https://pylib.readthedocs.io/en/latest/", null],
   "pyarrow": ["https://arrow.apache.org/docs/", null],
   "pybaselines": ["https://pybaselines.readthedocs.io/en/stable/", null],
@@ -152,14 +153,12 @@
   "rpy2": ["https://rpy2.github.io/doc/latest/html/", null],
   "rsciio": ["https://hyperspy.org/rosettasciio/", null],
   "rst-to-myst": ["https://rst-to-myst.readthedocs.io/en/stable/", null],
-  "rtd": ["https://docs.readthedocs.io/en/stable/", null],
   "rtd-dev": ["https://dev.readthedocs.io/en/latest/", null],
   "scanpy": ["https://scanpy.readthedocs.io/en/stable/", null],
-  "scipy": ["https://scipy.github.io/devdocs/", null],
+  "scipy": ["https://docs.scipy.org/doc/scipy/", null],
   "scipy-lecture-notes": ["https://scipy-lectures.org/", null],
   "scriptconfig": ["https://scriptconfig.readthedocs.io/en/latest/", null],
   "seaborn": ["https://seaborn.pydata.org/", null],
-  "server": ["https://jupyter-server.readthedocs.io/en/stable/", null],
   "setuptools": ["https://setuptools.pypa.io/en/stable/", null],
   "six": ["https://six.readthedocs.io/", null],
   "skimage": ["https://scikit-image.org/docs/stable/", null],