hippogriffe 0.1.3__tar.gz → 0.2.1__tar.gz

{hippogriffe-0.1.3 → hippogriffe-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hippogriffe
-Version: 0.1.3
+Version: 0.2.1
 Summary: Tweaks for `mkdocstrings[python]`
 Project-URL: repository, https://github.com/patrick-kidger/hippogriffe
 Author-email: Patrick Kidger <contact@kidger.site>
@@ -265,9 +265,9 @@ plugins:
     - hippogriffe:
         show_bases: true/false
         show_source_links: all/toplevel/none
-        extra_public_modules:
-            - foo
-            - bar
+        extra_public_objects:
+            - foo.SomeClass
+            - bar.subpackage.some_function
 ```
 
 **show_bases:**
@@ -278,19 +278,21 @@ If `false` then base classes will not be displayed alongside a class. Defaults t
 
 Sets which objects will have links to their location in the repository (as configured via the usual MkDocs `repo_url`). If `all` then all objects will have links. If `toplevel` then just `::: somelib.value` will have links, but their members will not. If `none` then no links will be added. Defaults to `toplevel`.
 
-**extra_public_modules:**
+**extra_public_objects:**
 
-A list of module names whose elements should be treated as part of the public API. Pretty-formatting of type annotations is done strictly: every annotation must be part of the known public API, else an error will be raised. The public API is defined as the combination of:
+Pretty-formatting of type annotations is done strictly: every annotation must be part of the known public API, else an error will be raised. The public API is defined as the combination of:
 
 - Everything you document using `::: yourlib.Foo`, and all of their members.
 - Anything from the standard library.
-- All objects belonging to any of `extra_public_modules`.
+- All objects belonging to any of `extra_public_objects`.
 
 For example,
 ```yml
 plugins:
     - hippogriffe:
-        extra_public_modules:
-            - jax
-            - torch
+        extra_public_objects:
+            - jax.Array
+            - torch.Tensor
 ```
+
+List each object under whatever public path `somelib.Foo` that you would like it to be displayed under (and from which it must be accessible), not whichever private path `somelib._internal.foo.Foo` it is defined at.

{hippogriffe-0.1.3 → hippogriffe-0.2.1}/README.md

@@ -43,9 +43,9 @@ plugins:
     - hippogriffe:
         show_bases: true/false
         show_source_links: all/toplevel/none
-        extra_public_modules:
-            - foo
-            - bar
+        extra_public_objects:
+            - foo.SomeClass
+            - bar.subpackage.some_function
 ```
 
 **show_bases:**
@@ -56,19 +56,21 @@ If `false` then base classes will not be displayed alongside a class. Defaults t
 
 Sets which objects will have links to their location in the repository (as configured via the usual MkDocs `repo_url`). If `all` then all objects will have links. If `toplevel` then just `::: somelib.value` will have links, but their members will not. If `none` then no links will be added. Defaults to `toplevel`.
 
-**extra_public_modules:**
+**extra_public_objects:**
 
-A list of module names whose elements should be treated as part of the public API. Pretty-formatting of type annotations is done strictly: every annotation must be part of the known public API, else an error will be raised. The public API is defined as the combination of:
+Pretty-formatting of type annotations is done strictly: every annotation must be part of the known public API, else an error will be raised. The public API is defined as the combination of:
 
 - Everything you document using `::: yourlib.Foo`, and all of their members.
 - Anything from the standard library.
-- All objects belonging to any of `extra_public_modules`.
+- All objects belonging to any of `extra_public_objects`.
 
 For example,
 ```yml
 plugins:
     - hippogriffe:
-        extra_public_modules:
-            - jax
-            - torch
+        extra_public_objects:
+            - jax.Array
+            - torch.Tensor
 ```
+
+List each object under whatever public path `somelib.Foo` that you would like it to be displayed under (and from which it must be accessible), not whichever private path `somelib._internal.foo.Foo` it is defined at.

{hippogriffe-0.1.3 → hippogriffe-0.2.1}/hippogriffe/_extension.py

@@ -2,6 +2,7 @@ import ast
 import builtins
 import contextlib
 import functools as ft
+import importlib
 import inspect
 import pathlib
 import re
@@ -33,23 +34,38 @@ class _PublicApi:
         pkg: griffe.Module,
         top_level_public_api: set[str],
         builtin_modules: list[str],
-        stdlib_modules: list[str],
-        extra_public_modules: list[str],
+        extra_public_objects: list[str],
     ):
         self._objects: set[griffe.Object] = set()
         self._toplevel_objects: set[griffe.Object] = set()
         self._data: dict[str, list[str]] = {}
         self._builtin_modules = builtin_modules
-        self._public_modules = stdlib_modules + extra_public_modules
+        for object_path in extra_public_objects:
+            object_pieces = object_path.split(".")
+            for i in reversed(range(1, len(object_pieces))):
+                module_name = "".join(object_pieces[:i])
+                object_name = object_pieces[i:]
+                try:
+                    object = importlib.import_module(module_name)
+                except Exception:
+                    continue
+                for object_piece in object_name:
+                    object = getattr(object, object_piece)
+                private_path = f"{object.__module__}.{object.__qualname__}"
+                try:
+                    paths = self._data[private_path]
+                except KeyError:
+                    paths = self._data[private_path] = []
+                paths.append(object_path)
         # Don't infinite loop on cycles. We only store Objects, and not Aliases, as in
         # cycles then the aliases with be distinct: `X.Y.X.Y` is not `X.Y`, though the
         # underlying object is the same.
 
-        agenda: list[tuple[griffe.Object, bool]] = [(pkg, False)]
+        agenda: list[tuple[griffe.Object, str, bool]] = [(pkg, pkg.path, False)]
         seen: set[griffe.Object] = {pkg}
         while len(agenda) > 0:
-            item, force_public = agenda.pop()
-            toplevel_public = item.path in top_level_public_api
+            item, public_path, force_public = agenda.pop()
+            toplevel_public = public_path in top_level_public_api
             if force_public or toplevel_public:
                 # If we're in the public API, then we consider all of our children to be
                 # in it as well... (this saves us from having to parse out `filters` and
@@ -58,7 +74,7 @@ class _PublicApi:
                     paths = self._data[item.path]
                 except KeyError:
                     paths = self._data[item.path] = []
-                paths.append(item.path)
+                paths.append(public_path)
                 self._objects.add(item)
                 if toplevel_public:
                     self._toplevel_objects.add(item)
@@ -70,13 +86,13 @@ class _PublicApi:
             for member in item.all_members.values():
                 # Skip private elements
                 if member.name.startswith("_") and not (
-                    member.name.startswith("__") and item.name.endswith("__")
+                    member.name.startswith("__") and member.name.endswith("__")
                 ):
                     continue
                 if isinstance(member, griffe.Alias):
                     try:
                         final_member = member.final_target
-                    except griffe.AliasResolutionError:
+                    except (griffe.AliasResolutionError, griffe.CyclicAliasError):
                         continue
                     if member.name != final_member.name:
                         # Renaming during import counts as private.
@@ -87,7 +103,7 @@ class _PublicApi:
                     final_member = member
                 if final_member in seen:
                     continue
-                agenda.append((final_member, sub_force_public))
+                agenda.append((final_member, member.path, sub_force_public))
                 seen.add(final_member)
 
     def toplevel(self) -> Iterable[griffe.Object]:
@@ -103,16 +119,17 @@ class _PublicApi:
             for m in self._builtin_modules:
                 if key.startswith(m + "."):
                     return key.removeprefix(m + "."), False
-            for m in self._public_modules:
+            for m in sys.stdlib_module_names:
                 if key.startswith(m + "."):
                     return key, False
-            # Not using `KeyError` because that displays its message with `repr`.
+            # Note that this message must not have any newlines in it, to display
+            # correctly.
             raise _NotInPublicApiException(
-                f"Tried and failed to find {key} in the public API. Commons reasons "
-                "for this error are:\n"
-                "- If it is from outside this package, then that package is not listed "
-                "under the `hippogriffe.extra_public_modules`\n"
-                "- If it is from inside this package, then it may have been written "
+                f"Tried and failed to find `{key}` in the public API. Commons reasons "
+                "for this error are (1) if it is from outside this package, then this "
+                "object is not listed (under whatever public path it should be "
+                "displayed as) in `hippogriffe.extra_public_objects`; (2) if it is "
+                "from inside this package, then it may have been written "
                 "`::: somelib.Foo:` with a trailing colon, when just `:::somelib.Foo` "
                 "is correct."
             ) from e
@@ -211,20 +228,17 @@ def _resolved_bases(cls: griffe.Class) -> list[str | griffe.Object]:
     return resolved_bases
 
 
-def _collect_bases(
-    cls: griffe.Class, public_api: _PublicApi, public_modules: set[str]
-) -> dict[str, bool]:
+def _collect_bases(cls: griffe.Class, public_api: _PublicApi) -> dict[str, bool]:
     bases: dict[str, bool] = {}
     for base in _resolved_bases(cls):
         if isinstance(base, str):
             # builtins case above
-            if "builtins" in public_modules:
-                bases[base] = False
+            bases[base] = False
         elif isinstance(base, griffe.Class):
             try:
                 base, autoref = public_api[base.path]
             except _NotInPublicApiException:
-                bases.update(_collect_bases(base, public_api, public_modules))
+                bases.update(_collect_bases(base, public_api))
             else:
                 bases[base] = autoref
     return bases
@@ -254,11 +268,23 @@ def _get_repo_url(repo_url: None | str) -> tuple[pathlib.Path, str]:
     else:
         toplevel = pathlib.Path(git_toplevel.stdout.decode().strip())
         commit_hash = git_head.stdout.decode().strip()
-    raw_url = repo_url.removeprefix("https://").removeprefix("https://")
-    if raw_url.startswith("github.com") or raw_url.startswith("gitlab.com"):
+    if "://" in repo_url:
+        protocol, repo_url = repo_url.split("://", 1)
+        protocol = f"{protocol}://"
+    else:
+        protocol = ""
+    supported_site = False
+    if repo_url.startswith("github.com"):
+        supported_site = True
+        fragment = "L{start}-L{end}"
+    elif repo_url.startswith("gitlab.com"):
+        supported_site = True
+        fragment = "L{start}-{end}"
+    if supported_site:
+        # Expect url in the form `https://github.com/org/repo`, strip any trailing paths
+        repo_url = "/".join(repo_url.split("/")[:3])
         repo_url = (
-            f"{repo_url.removesuffix('/')}/blob/{commit_hash}/{{path}}"
-            "#L{start}-{end}"
+            f"{protocol}{repo_url}/blob/{commit_hash}/{{path}}#{fragment}"
         )
     else:
         # We need to format the `repo_url` to what the repo expects, so we have to
@@ -324,8 +350,7 @@ class HippogriffeExtension(griffe.Extension):
             pkg,
             top_level_public_api=self.top_level_public_api,
             builtin_modules=self.config.builtin_modules,
-            stdlib_modules=self.config.stdlib_modules,
-            extra_public_modules=self.config.extra_public_modules,
+            extra_public_objects=self.config.extra_public_objects,
         )
 
         def use_public_name(context: None | dict, obj: Any) -> None | wl.AbstractDoc:
@@ -342,21 +367,34 @@ class HippogriffeExtension(griffe.Extension):
                 new_path, _ = public_api[f"{obj.__module__}.{obj.__qualname__}"]
                 return wl.TextDoc(new_path)
 
-        public_modules = set(self.config.extra_public_modules) | set(
-            self.config.stdlib_modules
-        )
         for obj in public_api:
             if obj.is_function:
                 assert type(obj) is griffe.Function
-                obj.extra["mkdocstrings"]["template"] = "hippogriffe/fn.html.jinja"
-                _pretty_fn(obj, use_public_name)
+                try:
+                    _pretty_fn(obj, use_public_name)
+                except _NotInPublicApiException as e:
+                    # Defer error until later -- right now our `public_api` is an
+                    # overestimation of the 'true' public API as for a public class
+                    # `Foo` then we actually include all of its attributes in the public
+                    # API here, even if those aren't documented.
+                    # It's fairly common to have nonpublic annotations in nonpublic
+                    # methods, and we shouldn't die on those now -- if the method is
+                    # never documented then we don't need to worry. Putting this here is
+                    # totally sneaky, it's letting jinja think this is a template and
+                    # having it raise a TemplateNotFound error when it tries to format
+                    # this object.
+                    obj.extra["mkdocstrings"]["template"] = (
+                        f"{e} This arose whilst pretty-printing `{obj.path}`. You may "
+                        "ignore the rest of this error message, which comes from jinja."
+                        "                                                        "
+                    )
+                else:
+                    obj.extra["mkdocstrings"]["template"] = "hippogriffe/fn.html.jinja"
             elif obj.is_class:
                 assert type(obj) is griffe.Class
                 obj.extra["mkdocstrings"]["template"] = "hippogriffe/class.html.jinja"
                 if self.config.show_bases:
-                    public_bases = list(
-                        _collect_bases(obj, public_api, public_modules).items()
-                    )
+                    public_bases = list(_collect_bases(obj, public_api).items())
                     obj.extra["hippogriffe"]["public_bases"] = public_bases
 
         if self.config.show_source_links == "none":

{hippogriffe-0.1.3 → hippogriffe-0.2.1}/hippogriffe/_plugin.py

@@ -1,6 +1,5 @@
 import pathlib
 import re
-import sys
 import typing
 
 from mkdocs.config import Config
@@ -25,13 +24,8 @@ class PluginConfig(Config):
     show_source_links = Choice(["all", "toplevel", "none"], default="toplevel")
     """Whether to include [source] links to the repo."""
 
-    extra_public_modules = Type(list, default=[])
-    """Any third-party modules whose objects are allowed in the public API."""
-
-    stdlib_modules = Type(list, default=list(sys.stdlib_module_names))
-    """A list of stdlib modules. This is concatenated with `extra_public_modules` to
-    form the list of external modules that are allowed in the public API
-    """
+    extra_public_objects = Type(list, default=[])
+    """Any third-party objects which are allowed in the public API."""
 
     builtin_modules = Type(
         list, default=["builtins", "collections.abc", "typing", "typing_extensions"]

{hippogriffe-0.1.3 → hippogriffe-0.2.1}/pyproject.toml

@@ -25,7 +25,7 @@ name = "hippogriffe"
 readme = "README.md"
 requires-python = ">=3.10"
 urls = {repository = "https://github.com/patrick-kidger/hippogriffe"}
-version = "0.1.3"
+version = "0.2.1"
 
 [project.optional-dependencies]
 dev = ["pre-commit"]