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

intersphinx_registry/reverse_lookup.py

@@ -0,0 +1,247 @@
+import json
+import re
+import sys
+import warnings
+from collections import namedtuple
+from io import BytesIO
+from pathlib import Path
+from urllib.parse import urljoin, urlparse
+
+import requests
+from sphinx.util.inventory import InventoryFile
+
+from .utils import _are_dependencies_available, _install_cache
+
+ReverseLookupResult = namedtuple(
+    "ReverseLookupResult",
+    ["url", "package", "domain", "rst_entry", "display_name", "inventory_url"],
+)
+
+
+def _normalize_url_for_matching(url: str) -> str:
+    """
+    Normalize URL for fuzzy matching by removing version-specific segments.
+
+    This helps match URLs like:
+    - /stable/ vs /latest/ vs /main/
+    - /v1.2.3/ vs /v2.0/ vs /1.5/
+    """
+    normalized = re.sub(r"/(latest|stable|main|dev|master)/", "/_VERSION_/", url)
+    normalized = re.sub(r"/v?\d+(\.\d+)*/", "/_VERSION_/", normalized)
+    return normalized
+
+
+def uri_match(user_url: str, inv_url: str) -> bool:
+    """
+    Check if two URIs match, handling index.html variations and version normalization.
+
+    Parameters
+    ----------
+    user_url : str
+        URL from user input or RST file
+    inv_url : str
+        URL from intersphinx inventory
+
+    Returns
+    -------
+    bool
+        True if the URLs match (considering index.html and version variations), False otherwise
+    """
+    if user_url == inv_url:
+        return True
+
+    variants = [user_url]
+    if user_url.endswith("/index.html"):
+        variants.append(user_url[:-10])  # Remove index.html, keep /
+    elif user_url.endswith("/"):
+        variants.append(user_url + "index.html")
+    else:
+        variants.append(user_url + "/index.html")
+
+    if inv_url in variants:
+        return True
+
+    inv_url_normalized = (
+        _normalize_url_for_matching(inv_url).rstrip("/").replace("/index.html", "")
+    )
+    for variant in variants:
+        variant_normalized = (
+            _normalize_url_for_matching(variant).rstrip("/").replace("/index.html", "")
+        )
+        if variant_normalized == inv_url_normalized:
+            return True
+
+    return False
+
+
+def _do_reverse_lookup(
+    urls: list[str],
+) -> list[ReverseLookupResult]:
+    """
+    Core reverse lookup logic: given URLs, find which packages they belong to and their rst references.
+
+    Parameters
+    ----------
+    urls : list[str]
+        List of URLs
+
+    Returns
+    -------
+    list[ReverseLookupResult]
+        List of ReverseLookupResult named tuples with fields:
+        url, package, domain, rst_entry, display_name
+    """
+    _install_cache()
+
+    registry_file = Path(__file__).parent / "registry.json"
+    registry = json.loads(registry_file.read_bytes())
+
+    package_urls: dict[str, list[str]] = {}
+
+    for url_str in urls:
+        matched = False
+        for package, (base_url, obj_path) in registry.items():
+            if url_str.startswith(base_url):
+                package_urls.setdefault(package, []).append(url_str)
+                matched = True
+                break
+
+        if not matched:
+            url_domain = urlparse(url_str).netloc
+            url_path_normalized = (
+                _normalize_url_for_matching(urlparse(url_str).path)
+                .rstrip("/")
+                .replace("/index.html", "")
+            )
+
+            for package, (base_url, obj_path) in registry.items():
+                base_domain = urlparse(base_url).netloc
+                if url_domain == base_domain:
+                    base_path_normalized = _normalize_url_for_matching(
+                        urlparse(base_url).path
+                    ).rstrip("/")
+                    if url_path_normalized.startswith(
+                        base_path_normalized
+                    ) or base_path_normalized.startswith(url_path_normalized):
+                        package_urls.setdefault(package, []).append(url_str)
+                        break
+
+    results: list[ReverseLookupResult] = []
+
+    for package, url_list in package_urls.items():
+        base_url, obj_path = registry[package]
+        inv_url = urljoin(base_url, obj_path if obj_path else "objects.inv")
+
+        try:
+            resp = requests.get(inv_url, timeout=25)
+            resp.raise_for_status()
+            inv = InventoryFile.load(BytesIO(resp.content), base_url, urljoin)
+        except Exception as e:
+            warnings.warn(
+                f"Failed to load inventory for '{package}' from {inv_url}: {e}",
+                UserWarning,
+                stacklevel=2,
+            )
+            for url_str in url_list:
+                results.append(
+                    ReverseLookupResult(url_str, package, None, None, None, None)
+                )
+            continue
+
+        inv_urls = {}
+        for key, v in inv.items():
+            for entry, (proj, ver, uri, display_name) in v.items():
+                inv_urls[uri] = (key, entry, display_name)
+
+        for url_str in url_list:
+            found = False
+
+            for inv_uri, (key, entry, display_name) in inv_urls.items():
+                if uri_match(url_str, inv_uri):
+                    results.append(
+                        ReverseLookupResult(
+                            url_str, package, key, entry, display_name, inv_uri
+                        )
+                    )
+                    found = True
+                    break
+
+            if not found:
+                results.append(
+                    ReverseLookupResult(url_str, package, None, None, None, None)
+                )
+
+    return results
+
+
+def _print_reverse_lookup_results(
+    results: list[ReverseLookupResult],
+) -> None:
+    """
+    Print formatted reverse lookup results.
+
+    Parameters
+    ----------
+    results : list[ReverseLookupResult]
+        List of ReverseLookupResult named tuples
+    """
+    if not results:
+        return
+
+    header_url = "URL"
+    header_rst = "Sphinx Reference"
+    header_display = "Description"
+
+    width_url = max(len(header_url), max(len(r.url) for r in results))
+    width_rst = max(
+        len(header_rst),
+        max(
+            (
+                len(f":{r.domain}:`{r.package}:{r.rst_entry}`")
+                if r.rst_entry
+                else len("NOT FOUND")
+            )
+            for r in results
+        ),
+    )
+    width_display = max(
+        len(header_display),
+        max((len(r.display_name) if r.display_name else 0) for r in results),
+    )
+
+    print(f"{header_url:<{width_url}}  {header_rst:<{width_rst}}  {header_display}")
+    print(f"{'-' * width_url}  {'-' * width_rst}  {'-' * width_display}")
+
+    for result in results:
+        if result.rst_entry:
+            rst_ref = f":{result.domain}:`{result.package}:{result.rst_entry}`"
+            display = (
+                result.display_name
+                if result.display_name and result.display_name != "-"
+                else result.rst_entry
+            )
+            print(
+                f"{result.url:<{width_url}}  {rst_ref:<{width_rst}}  {display:<{width_display}}"
+            )
+        elif result.package:
+            print(f"{result.url:<{width_url}}  {'NOT FOUND':<{width_rst}}")
+
+
+def reverse_lookup(urls: list[str]) -> None:
+    """
+    Reverse lookup: given URLs, find which packages they belong to and their rst references.
+
+    Parameters
+    ----------
+    urls : list[str]
+        List of URLs
+    """
+    if not urls:
+        print("ERROR: No URLs provided", file=sys.stderr)
+        return
+
+    if not _are_dependencies_available():
+        return
+
+    results = _do_reverse_lookup(urls)
+    _print_reverse_lookup_results(results)

intersphinx_registry/utils.py

@@ -0,0 +1,125 @@
+import shutil
+import sys
+from datetime import timedelta
+from pathlib import Path
+
+import platformdirs
+import requests_cache
+
+from . import __version__
+
+
+def _compress_user_path(path: str) -> str:
+    """
+    Replace home directory with ~ in a path string.
+
+    Parameters
+    ----------
+    path : str
+        Path to compress
+
+    Returns
+    -------
+    str
+        Path with home directory replaced by ~
+    """
+    home = str(Path.home())
+    if path.startswith(home):
+        return path.replace(home, "~", 1)
+    return path
+
+
+def _get_cache_dir() -> Path:
+    """
+    Get the cache directory for the current version of intersphinx_registry.
+
+    Returns
+    -------
+    Path
+        Cache directory path with version subdirectory
+    """
+    base_cache_dir = Path(platformdirs.user_cache_dir("intersphinx_registry"))
+    cache_dir = base_cache_dir / __version__
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    return cache_dir
+
+
+def _cleanup_old_caches() -> None:
+    """
+    Remove cache directories from old versions of intersphinx_registry.
+    Only keeps the current version's cache.
+    """
+    base_cache_dir = Path(platformdirs.user_cache_dir("intersphinx_registry"))
+
+    if not base_cache_dir.exists():
+        return
+
+    current_version = __version__
+
+    for version_dir in base_cache_dir.iterdir():
+        if version_dir.is_dir() and version_dir.name != current_version:
+            try:
+                shutil.rmtree(version_dir)
+            except Exception:
+                pass
+
+
+def _install_cache() -> None:
+    """
+    Install the version-specific requests cache.
+    Cleans up old caches on first use.
+    """
+    _cleanup_old_caches()
+
+    cache_dir = _get_cache_dir()
+    cache_path = cache_dir / "intersphinx_cache.sqlite"
+
+    requests_cache.install_cache(
+        str(cache_path),
+        backend="sqlite",
+        expire_after=timedelta(hours=6),
+        stale_if_error=True,
+        cache_control=True,
+    )
+
+
+def _are_dependencies_available() -> bool:
+    """
+    Check if CLI dependencies are missing or not.
+    Returns True if all dependencies are available, False otherwise.
+    """
+    missing = []
+    try:
+        import sphinx  # noqa: F401
+    except ModuleNotFoundError:
+        missing.append("sphinx")
+
+    try:
+        import requests  # noqa: F401
+    except ModuleNotFoundError:
+        missing.append("requests")
+
+    try:
+        import requests_cache  # noqa: F401
+    except ModuleNotFoundError:
+        missing.append("requests-cache")
+
+    try:
+        import platformdirs  # noqa: F401
+    except ModuleNotFoundError:
+        missing.append("platformdirs")
+
+    if missing:
+        print(
+            "ERROR: the lookup functionality requires additional dependencies.",
+            file=sys.stderr,
+        )
+        print(
+            "Please install with: pip install 'intersphinx_registry[cli]'",
+            file=sys.stderr,
+        )
+        print(f"Missing dependencies: {', '.join(missing)}", file=sys.stderr)
+        return False
+
+    return True

intersphinx_registry-0.2601.5.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+intersphinx_registry/__init__.py,sha256=A51oQMp2TiI5gE0SWH1tcmGhi2QkVSDHteeEoV4k0x8,2477
+intersphinx_registry/__main__.py,sha256=Onf2k3sdsvpaifbi8UFhnbF_yTEHGxRpTT5RUAAWSXU,81
+intersphinx_registry/_info.py,sha256=1aFYUmj1io6kGJaf_8wB9D7MjTkwl8BmOubUY7x3muk,2224
+intersphinx_registry/cli.py,sha256=3X9Rfz59sMlXYDSNTxSk-hrHcCO0OjrRdjGVDzLT--w,4265
+intersphinx_registry/lookup.py,sha256=ffUPEnKl37CObcu0Ul9dzEznSrEal9OeuZKzq5G1Yck,5273
+intersphinx_registry/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+intersphinx_registry/registry.json,sha256=PoZKwZLlAa2h5oWKuJKLRbQWoSGVN19JrxzF3MPvsiM,12711
+intersphinx_registry/rev_search.py,sha256=Gkd8YGWR8L7Gqc57u2YBg0d0iDBH47p8mBVtbCEAHKQ,23667
+intersphinx_registry/reverse_lookup.py,sha256=8kPvX-UUhWlO1o14kJd8PYWpecAXR8y9dAcbt_49SyE,7499
+intersphinx_registry/utils.py,sha256=_WjmtuzlXjuA9z1-Pv-CkgjHtORtlNV6faao2GP4rYI,3021
+intersphinx_registry-0.2601.5.dist-info/entry_points.txt,sha256=qbnBLPGMbSDiZHGpPOiuXwMFfAS7iVT3bakVKhwmHgo,70
+intersphinx_registry-0.2601.5.dist-info/licenses/LICENSE,sha256=j98x_c52nvqkLlr-U8tUaubJG3IBCIFEInYE4L_Yqqo,1086
+intersphinx_registry-0.2601.5.dist-info/WHEEL,sha256=Dyt6SBfaasWElUrURkknVFAZDHSTwxg3PaTza7RSbkY,100
+intersphinx_registry-0.2601.5.dist-info/METADATA,sha256=exl6YyihrpRQiscWMp-AMDofjYvysQbttZcifSVIpUU,5868
+intersphinx_registry-0.2601.5.dist-info/RECORD,,

intersphinx_registry-0.2601.5.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+intersphinx-registry=intersphinx_registry.cli:main
+

intersphinx_registry-0.2511.25.dist-info/METADATA

@@ -1,88 +0,0 @@
-Metadata-Version: 2.4
-Name: intersphinx_registry
-Version: 0.2511.25
-Summary: This package provides convenient utilities and data to write a sphinx config file.
-Author-email: Matthias Bussonnier <bussonniermatthias@gmail.com>
-Description-Content-Type: text/markdown
-Classifier: License :: OSI Approved :: MIT License
-License-File: LICENSE
-Requires-Dist: pytest>=7.0 ; extra == "tests"
-Requires-Dist: pytest-xdist ; extra == "tests"
-Requires-Dist: requests ; extra == "tests"
-Requires-Dist: mypy ; extra == "tests"
-Requires-Dist: types-requests ; extra == "tests"
-Project-URL: Home, https://github.com/Quansight-labs/intersphinx_registry
-Provides-Extra: tests
-
-# Intersphinx Registry
-
-A simple utility package that provide default inter sphinx mapping for a large chunk of the python ecosystem.
-
-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),
-})
-```
-
-## quick lookup
-
-You can use the following to lookup target/webpages of various packages.
-
-Call without arguments to get help:
-
-```
-$ python -m intersphinx_registry.lookup
-
-    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
-
-```
-
-You can search multiple packages as once.
-
-```
-$ python -m 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, it downloads the inventory of each mentioned package every time.
-
-
-## Why ?
-
-Sometime packages docs move and it's hard to keep track of. We _try_ to keep the
-registry up to date, so yo 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.2511.25.dist-info/RECORD

@@ -1,9 +0,0 @@
-intersphinx_registry/__init__.py,sha256=CLRYH6y4UUxQiJQUpvuaeDisoq-ZbkyVtH8GG1FIrxw,1813
-intersphinx_registry/_info.py,sha256=wlicM8WkAaykwDkeyp5JRGgYOG3Kp7diu0bjBlYfH9M,2223
-intersphinx_registry/lookup.py,sha256=cCOpg_Xmr0l7bvRvmHi6V_yrVDPWtgpSGRgUJf8YqFk,2298
-intersphinx_registry/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-intersphinx_registry/registry.json,sha256=0Y--5AOX1HVzLNNfYuyRUHJ1k-yrmc3GrFzv54o1MFM,12771
-intersphinx_registry-0.2511.25.dist-info/licenses/LICENSE,sha256=j98x_c52nvqkLlr-U8tUaubJG3IBCIFEInYE4L_Yqqo,1086
-intersphinx_registry-0.2511.25.dist-info/WHEEL,sha256=Dyt6SBfaasWElUrURkknVFAZDHSTwxg3PaTza7RSbkY,100
-intersphinx_registry-0.2511.25.dist-info/METADATA,sha256=7GUH9SkIR7TjKG2gjI2w2QdpBRkjJ7EpgvCQ0GluvQ8,3555
-intersphinx_registry-0.2511.25.dist-info/RECORD,,