Merge pull request #8 from tacaswell/api/always_filter

API: make filtering the included packages the encouraged behavior

README.md

@@ -8,16 +8,17 @@ Usage in `conf.py`
 from intersphinx_registry import get_intersphinx_mapping
 
 # ...
-
-intersphinx_mapping = get_intersphinx_mapping()
+intersphinx_mapping = get_intersphinx_mapping(
+    only={"ipython", "matplotlib", "pandas", "python"}
+)
 intersphinx_mapping.update({
     'overwrite': ('<url>', None),
     'my-package' : ('<url>', None),
 })
 ```
 
 
-## Why ? 
+## 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
@@ -34,14 +35,4 @@ 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 an PR. 
-
-
-
-
-
-
-
-
-
-
+please send a PR.

intersphinx_registry/__init__.py

@@ -14,31 +14,37 @@
 
 registry_file = Path(__file__).parent / "registry.json"
 
+def _get_all_mappings() ->  Dict[str, Tuple[str, Optional[str]]]:
+    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(
-    *, only: Optional[Set[str]] = None
+    *, packages: Set[str] = set()
 ) -> Dict[str, Tuple[str, Optional[str]]]:
     """
     Return values of intersphinx_mapping for sphinx configuration.
 
-    For convenience, the return dict is a copy so should be ok to mutate
+    For convenience, the returned dictionary is a copy so should be ok to
+    mutate.
 
     Parameters
     ----------
-    only: Set of Str
-        list of libraries to include.
-        This is purely for optimisation as sphinx may download and load all the
-        `objects.inv` listed, in get_intersphinx_mapping. This let users reduce
-        the number of requested files.
+    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.
+
     """
-    mapping = cast(
-        Dict[str, Tuple[str, Optional[str]]],
-        {k: tuple(v) for (k, v) in json.loads(registry_file.read_bytes()).items()},
-    )
-    if only is None:
-        return mapping
-    else:
-        missing = set(only) - set(mapping)
-        if missing:
-            raise ValueError(f"Missing libraries in 'only': {repr(sorted(missing))}")
-        return {k: v for k, v in mapping.items() if k in only}
+    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()
+    missing = set(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}

intersphinx_registry/registry.json

@@ -1,6 +1,6 @@
 {
-  "Pillow": ["https://pillow.readthedocs.io/en/stable/", null],
-  "PyPUG": ["https://packaging.python.org/en/latest/", null],
+  "pillow": ["https://pillow.readthedocs.io/en/stable/", null],
+  "pypug": ["https://packaging.python.org/en/latest/", null],
   "anndata": ["https://anndata.readthedocs.io/en/stable/", null],
   "asdf-astropy": ["https://asdf-astropy.readthedocs.io/en/latest/", null],
   "astropy-dev": ["https://docs.astropy.org/en/latest/", null],

tests/test_basic.py

@@ -1,8 +1,8 @@
-from intersphinx_registry import get_intersphinx_mapping
+from intersphinx_registry import _get_all_mappings, get_intersphinx_mapping
 import pytest
 import requests
 
-MAPPING = get_intersphinx_mapping()
+MAPPING = _get_all_mappings()
 keys = set(MAPPING.keys())
 
 
@@ -27,5 +27,15 @@ def test_reach_objects_inv(key: str):
 
 
 def test_bad():
-    with pytest.raises(ValueError, match="Missing libraries"):
-        get_intersphinx_mapping(only={"-nonexistent-"})
+    with pytest.raises(ValueError, match="Some libraries in"):
+        get_intersphinx_mapping(packages={"-nonexistent-"})
+
+
+@pytest.mark.parametrize('key', sorted(keys))
+def test_lower_case(key):
+    """
+    We agreed that all keys in the mapping should be lower case
+    """
+    assert key == key.lower(), 'expecting all keys to be lowercase'
+
+