hippogriffe 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

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,60 +34,77 @@ 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
-        seen: set[griffe.Alias | griffe.Object] = set()  # Don't infinite loop on cycles
-
-        agenda: list[tuple[griffe.Alias | griffe.Object, bool]] = [(pkg, False)]
-        while len(agenda) > 0:
-            item, force_public = agenda.pop()
-            seen.add(item)
-            # Skip private elements
-            if item.name.startswith("_") and not (
-                item.name.startswith("__") and item.name.endswith("__")
-            ):
-                continue
-            if isinstance(item, griffe.Alias):
+        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:
-                    final_item = item.final_target
-                except griffe.AliasResolutionError:
-                    continue
-                if item.name != final_item.name:
-                    # Renaming during import counts as private.
-                    # (In particular this happens for backward compatibility, e.g.
-                    # `equinox.nn.inference_mode` and `equinox.tree_inference`.)
+                    object = importlib.import_module(module_name)
+                except Exception:
                     continue
-            else:
-                final_item = item
-
-            toplevel_public = item.path in top_level_public_api
+                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, str, bool]] = [(pkg, pkg.path, False)]
+        seen: set[griffe.Object] = {pkg}
+        while len(agenda) > 0:
+            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
                 # `members` from our documentation)
-                agenda.extend(
-                    (x, True) for x in item.all_members.values() if x not in seen
-                )
                 try:
-                    paths = self._data[final_item.path]
+                    paths = self._data[item.path]
                 except KeyError:
-                    paths = self._data[final_item.path] = []
-                paths.append(item.path)
-                self._objects.add(final_item)
+                    paths = self._data[item.path] = []
+                paths.append(public_path)
+                self._objects.add(item)
                 if toplevel_public:
-                    self._toplevel_objects.add(final_item)
+                    self._toplevel_objects.add(item)
+                sub_force_public = True
             else:
                 # ...if we're not in the public API then check our members -- some of
                 # them might be in the public API.
-                agenda.extend(
-                    (x, False) for x in item.all_members.values() if x not in seen
-                )
+                sub_force_public = False
+            for member in item.all_members.values():
+                # Skip private elements
+                if member.name.startswith("_") and not (
+                    member.name.startswith("__") and member.name.endswith("__")
+                ):
+                    continue
+                if isinstance(member, griffe.Alias):
+                    try:
+                        final_member = member.final_target
+                    except griffe.AliasResolutionError:
+                        continue
+                    if member.name != final_member.name:
+                        # Renaming during import counts as private.
+                        # (In particular this happens for backward compatibility, e.g.
+                        # `equinox.nn.inference_mode` and `equinox.tree_inference`.)
+                        continue
+                else:
+                    final_member = member
+                if final_member in seen:
+                    continue
+                agenda.append((final_member, member.path, sub_force_public))
+                seen.add(final_member)
 
     def toplevel(self) -> Iterable[griffe.Object]:
         return self._toplevel_objects
@@ -101,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
@@ -209,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
@@ -322,8 +338,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:
@@ -340,21 +355,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/_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.2.dist-info → hippogriffe-0.2.0.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: hippogriffe
-Version: 0.1.2
-Summary: A simple ipynb->md converter for MkDocs
+Version: 0.2.0
+Summary: Tweaks for `mkdocstrings[python]`
 Project-URL: repository, https://github.com/patrick-kidger/hippogriffe
 Author-email: Patrick Kidger <contact@kidger.site>
 License:                                  Apache License
@@ -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 accessilbe), not whatever private path `somelib._internal.foo.Foo` it is defined at.

{hippogriffe-0.1.2.dist-info → hippogriffe-0.2.0.dist-info}/RECORD

@@ -1,12 +1,12 @@
 hippogriffe/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-hippogriffe/_extension.py,sha256=zg3Q5h5ziLOX46BXYOpwrXQ7EFGJP7UwKXjKMh7GYjY,14014
-hippogriffe/_plugin.py,sha256=H0oPka_7URED9wOVYAWUNTWTJXFmH6q7g2W2G5hy64c,4564
+hippogriffe/_extension.py,sha256=5c5Hb4qW4v3UjGn2x2MwXB_8CI6PfLUOQ0kO0soflA0,15992
+hippogriffe/_plugin.py,sha256=9omje-ROpvo24YYSIcul8XjKwuzFhV7rE9a1f3XDUws,4307
 hippogriffe/assets/_hippogriffe.css,sha256=BgyZLCaOaZNgQErdUb01vpNso4ilUMmoZ5d_OeVpfRE,147
 hippogriffe/templates/material/hippogriffe/class.html.jinja,sha256=5i624gIuZfnf5toH3jWclzg1qlekqIZ2ODbpzeZcULw,954
 hippogriffe/templates/material/hippogriffe/fn.html.jinja,sha256=vxrWOPkPkGD3Po9hbcYlyEjsJKhJmOHic4G5t2J0djc,196
 hippogriffe/templates/material/hippogriffe/hippogriffe.jinja,sha256=KxTBKY0XqiFzqTT1iqFxhN2GhmtwLT4GWc8S86zyjOc,583
-hippogriffe-0.1.2.dist-info/METADATA,sha256=IiWbdutZDQd0mrtyQyES29rTdHJEyrZmK7I0jQL0UJ0,16274
-hippogriffe-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-hippogriffe-0.1.2.dist-info/entry_points.txt,sha256=Et3dFNWG-biZ7XCvPI9na-buFT_hht1YT0p0JDNEQQM,158
-hippogriffe-0.1.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-hippogriffe-0.1.2.dist-info/RECORD,,
+hippogriffe-0.2.0.dist-info/METADATA,sha256=Ud_6bXxxqtLRQltCwOPUzH2MfpzAHDcNCeWMfOrpTu8,16449
+hippogriffe-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hippogriffe-0.2.0.dist-info/entry_points.txt,sha256=Et3dFNWG-biZ7XCvPI9na-buFT_hht1YT0p0JDNEQQM,158
+hippogriffe-0.2.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+hippogriffe-0.2.0.dist-info/RECORD,,