refactor: Document public objects with __all__

src/griffe/agents/inspector.py

@@ -492,3 +492,6 @@ def _convert_object_to_annotation(obj: Any, parent: Module | Class) -> str | Nam
     except SyntaxError:
         return obj
     return safe_get_annotation(annotation_node.body, parent=parent)  # type: ignore[attr-defined]
+
+
+__all__ = ["inspect", "Inspector"]

src/griffe/agents/nodes/_all.py

@@ -109,3 +109,6 @@ def safe_get__all__(
             message += f": {error}"
         getattr(logger, log_level.value)(message)
         return []
+
+
+__all__ = ["get__all__", "safe_get__all__"]

src/griffe/agents/nodes/_ast.py

@@ -169,3 +169,16 @@ def ast_last_child(node: AST) -> AST:
     except ValueError as error:
         raise LastNodeError("there are no children node") from error
     return last
+
+
+__all__ = [
+    "ast_children",
+    "ast_first_child",
+    "ast_kind",
+    "ast_last_child",
+    "ast_next",
+    "ast_next_siblings",
+    "ast_previous",
+    "ast_previous_siblings",
+    "ast_siblings",
+]

src/griffe/agents/nodes/_docstrings.py

@@ -39,3 +39,6 @@ def get_docstring(
         lineno = doc.lineno
         return doc.s, lineno, doc.end_lineno
     return None, None, None
+
+
+__all__ = ["get_docstring"]

src/griffe/agents/nodes/_expressions.py

@@ -597,3 +597,15 @@ def safe_get_expression(
     parse_strings=False,
     msg_format=_msg_format % "condition",
 )
+
+
+__all__ = [
+    "get_annotation",
+    "get_base_class",
+    "get_condition",
+    "get_expression",
+    "safe_get_annotation",
+    "safe_get_base_class",
+    "safe_get_condition",
+    "safe_get_expression",
+]

src/griffe/agents/nodes/_imports.py

@@ -35,3 +35,6 @@ def relative_to_absolute(node: ast.ImportFrom, name: ast.alias, current_module:
     base = current_module.path + "." if node.level > 0 else ""
     node_module = node.module + "." if node.module else ""
     return base + node_module + name.name
+
+
+__all__ = ["relative_to_absolute"]

src/griffe/agents/nodes/_names.py

@@ -78,3 +78,6 @@ def get_instance_names(node: AST) -> list[str]:
         A list of names.
     """
     return [name.split(".", 1)[1] for name in get_names(node) if name.startswith("self.")]
+
+
+__all__ = ["get_instance_names", "get_name", "get_names"]

src/griffe/agents/nodes/_parameters.py

@@ -26,3 +26,6 @@ def get_call_keyword_arguments(node: Call, parent: Module | Class) -> dict[str,
         The keyword argument names and values.
     """
     return {kw.arg: safe_get_expression(kw.value, parent) for kw in node.keywords if kw.arg}
+
+
+__all__ = ["get_call_keyword_arguments"]

src/griffe/agents/nodes/_runtime.py

@@ -359,3 +359,6 @@ def alias_target_path(self) -> str | None:
             return child_module_path
         child_name = getattr(self.obj, "__name__", self.name)
         return f"{child_module_path}.{child_name}"
+
+
+__all__ = ["ObjectKind", "ObjectNode"]

src/griffe/agents/nodes/_values.py

@@ -473,3 +473,6 @@ def safe_get_value(node: AST | None, filepath: str | Path | None = None) -> str
         message += f": {error}"
         logger.exception(message)
         return None
+
+
+__all__ = ["get_value", "safe_get_value"]

src/griffe/agents/visitor.py

@@ -693,3 +693,6 @@ def visit_if(self, node: ast.If) -> None:
                 self.type_guarded = True
         self.generic_visit(node)
         self.type_guarded = False
+
+
+__all__ = ["visit", "Visitor"]

src/griffe/c3linear.py

@@ -115,3 +115,6 @@ def c3linear_merge(*lists: list[T]) -> list[T]:
         else:
             # Loop never broke, no linearization could possibly be found.
             raise ValueError("Cannot compute C3 linearization")
+
+
+__all__ = ["c3linear_merge"]

src/griffe/cli.py

@@ -470,3 +470,6 @@ def main(args: list[str] | None = None) -> int:
 
     commands: dict[str, Callable[..., int]] = {"check": check, "dump": dump}
     return commands[subcommand](**opts_dict)
+
+
+__all__ = ["check", "dump", "get_parser", "main"]

src/griffe/collections.py

@@ -71,3 +71,6 @@ def __contains__(self, item: Any) -> bool:
     @property
     def all_members(self) -> dict[str, Module]:  # noqa: D102
         return self.members
+
+
+__all__ = ["LinesCollection", "ModulesCollection"]

src/griffe/dataclasses.py

@@ -1595,3 +1595,20 @@ def as_dict(self, **kwargs: Any) -> dict[str, Any]:
         if self.annotation is not None:
             base["annotation"] = self.annotation
         return base
+
+
+__all__ = [
+    "Alias",
+    "Attribute",
+    "Class",
+    "Decorator",
+    "Docstring",
+    "Function",
+    "Kind",
+    "Module",
+    "Object",
+    "Parameter",
+    "ParameterKind",
+    "ParameterKind",
+    "Parameters",
+]

src/griffe/diff.py

@@ -564,3 +564,23 @@ def find_breaking_changes(
         ...     print(breakage.explain(style=style), file=sys.stderr)
     """
     yield from _member_incompatibilities(old_obj, new_obj, ignore_private=ignore_private)
+
+
+__all__ = [
+    "AttributeChangedTypeBreakage",
+    "AttributeChangedValueBreakage",
+    "Breakage",
+    "BreakageKind",
+    "ClassRemovedBaseBreakage",
+    "ExplanationStyle",
+    "find_breaking_changes",
+    "ObjectChangedKindBreakage",
+    "ObjectRemovedBreakage",
+    "ParameterAddedRequiredBreakage",
+    "ParameterChangedDefaultBreakage",
+    "ParameterChangedKindBreakage",
+    "ParameterChangedRequiredBreakage",
+    "ParameterMovedBreakage",
+    "ParameterRemovedBreakage",
+    "ReturnChangedTypeBreakage",
+]

src/griffe/docstrings/__init__.py

@@ -1,5 +1,5 @@
 """This module exposes objects related to docstrings."""
 
-from griffe.docstrings.parsers import Parser, parse
+from griffe.docstrings.parsers import Parser, parse, parsers
 
-__all__ = ["Parser", "parse"]
+__all__ = ["Parser", "parse", "parsers"]

src/griffe/docstrings/dataclasses.py

@@ -415,3 +415,32 @@ def __init__(self, kind: str, text: str, title: str | None = None) -> None:
         """
         super().__init__(title)
         self.value: DocstringAdmonition = DocstringAdmonition(annotation=kind, description=text)
+
+
+__all__ = [
+    "DocstringAdmonition",
+    "DocstringAttribute",
+    "DocstringDeprecated",
+    "DocstringElement",
+    "DocstringNamedElement",
+    "DocstringParameter",
+    "DocstringRaise",
+    "DocstringReceive",
+    "DocstringReturn",
+    "DocstringSection",
+    "DocstringSectionAdmonition",
+    "DocstringSectionAttributes",
+    "DocstringSectionDeprecated",
+    "DocstringSectionExamples",
+    "DocstringSectionKind",
+    "DocstringSectionOtherParameters",
+    "DocstringSectionParameters",
+    "DocstringSectionRaises",
+    "DocstringSectionReceives",
+    "DocstringSectionReturns",
+    "DocstringSectionText",
+    "DocstringSectionWarns",
+    "DocstringSectionYields",
+    "DocstringWarn",
+    "DocstringYield",
+]

src/griffe/docstrings/google.py

@@ -711,3 +711,6 @@ def parse(
         sections.append(DocstringSectionText("\n".join(current_section).rstrip("\n")))
 
     return sections
+
+
+__all__ = ["parse"]

src/griffe/docstrings/numpy.py

@@ -745,3 +745,6 @@ def parse(
         sections.append(DocstringSectionText("\n".join(current_section).rstrip("\n")))
 
     return sections
+
+
+__all__ = ["parse"]

src/griffe/docstrings/parsers.py

@@ -50,3 +50,6 @@ def parse(docstring: Docstring, parser: Parser | None, **options: Any) -> list[D
     if parser:
         return parsers[parser](docstring, **options)  # type: ignore[operator]
     return [DocstringSectionText(docstring.value)]
+
+
+__all__ = ["parse", "Parser", "parsers"]

src/griffe/docstrings/sphinx.py

@@ -393,3 +393,6 @@ def _strip_blank_lines(lines: list[str]) -> list[str]:
     FieldType(RETURN_NAMES, _read_return),
     FieldType(RETURN_TYPE_NAMES, _read_return_type),
 ]
+
+
+__all__ = ["parse"]

src/griffe/docstrings/utils.py

@@ -71,3 +71,6 @@ def parse_annotation(
             )
             return name_or_expr or annotation
     return annotation
+
+
+__all__ = ["parse_annotation", "warning"]

src/griffe/encoders.py

@@ -229,3 +229,6 @@ def json_decoder(obj_dict: dict[str, Any]) -> dict[str, Any] | Object | Alias |
             return _load_parameter(obj_dict)
         return _loader_map[kind](obj_dict)
     return obj_dict
+
+
+__all__ = ["JSONEncoder", "json_decoder"]

src/griffe/exceptions.py

@@ -83,3 +83,20 @@ class ExtensionNotLoadedError(ExtensionError):
 
 class GitError(GriffeError):
     """Exception raised for errors related to Git."""
+
+
+__all__ = [
+    "AliasResolutionError",
+    "BuiltinModuleError",
+    "CyclicAliasError",
+    "ExtensionError",
+    "ExtensionNotLoadedError",
+    "GitError",
+    "GriffeError",
+    "LastNodeError",
+    "LoadingError",
+    "NameResolutionError",
+    "RootNodeError",
+    "UnhandledEditableModuleError",
+    "UnimportableModuleError",
+]

src/griffe/expressions.py

@@ -272,3 +272,6 @@ def generator_items(self) -> tuple[Name | Expression, Name | Expression, Name |
             The return type.
         """
         return self.non_optional[2][0], self[2][2], self[2][4]
+
+
+__all__ = ["Expression", "Name"]

src/griffe/extensions/__init__.py

@@ -12,12 +12,12 @@
 )
 
 __all__ = [
-    "Extensions",
     "Extension",
+    "Extensions",
     "ExtensionType",
     "InspectorExtension",
-    "VisitorExtension",
-    "When",
     "load_extension",
     "load_extensions",
+    "VisitorExtension",
+    "When",
 ]

src/griffe/extensions/base.py

@@ -506,3 +506,15 @@ def load_extensions(exts: Sequence[str | dict[str, Any] | ExtensionType | type[E
         else:
             extensions.add(ext)
     return extensions
+
+
+__all__ = [
+    "builtin_extensions",
+    "Extension",
+    "Extensions",
+    "ExtensionType",
+    "InspectorExtension",
+    "load_extensions",
+    "VisitorExtension",
+    "When",
+]

src/griffe/extensions/hybrid.py

@@ -89,5 +89,4 @@ def visit(self, node: ast.AST) -> None:  # noqa: D102
             extension.inspect(object_node)
 
 
-# make it available
-Extension = HybridExtension
+__all__ = ["HybridExtension"]

src/griffe/finder.py

@@ -369,3 +369,6 @@ def _handle_editable_module(path: Path) -> list[Path]:
             ) and isinstance(node.value, ast.Dict):
                 return [Path(constant.s).parent for constant in node.value.values if isinstance(constant, ast.Str)]
     raise UnhandledEditableModuleError(path)
+
+
+__all__ = ["ModuleFinder", "NamespacePackage", "Package"]

src/griffe/git.py

@@ -165,3 +165,6 @@ def load_git(
             modules_collection=modules_collection,
             allow_inspection=allow_inspection,
         )
+
+
+__all__ = ["load_git"]

src/griffe/importer.py

@@ -86,3 +86,6 @@ def dynamic_import(import_path: str, import_paths: list[Path] | None = None) ->
         except AttributeError as error:
             raise ImportError("\n".join(errors)) from error
     return value
+
+
+__all__ = ["dynamic_import", "sys_path"]

src/griffe/loader.py

@@ -599,3 +599,6 @@ def load(
         submodules=submodules,
         try_relative_path=try_relative_path,
     )
+
+
+__all__ = ["GriffeLoader", "load"]

src/griffe/logger.py

@@ -90,3 +90,6 @@ def patch_loggers(get_logger_func: Callable[[str], Any]) -> None:
         get_logger_func: A function accepting a name as parameter and returning a logger.
     """
     _Logger._patch_loggers(get_logger_func)
+
+
+__all__ = ["get_logger", "LogLevel", "patch_loggers"]

src/griffe/merger.py

@@ -95,3 +95,6 @@ def merge_stubs(mod1: Module, mod2: Module) -> Module:
         raise ValueError("cannot merge regular (non-stubs) modules together")
     _merge_module_stubs(module, stubs)
     return module
+
+
+__all__ = ["merge_stubs"]

src/griffe/mixins.py

@@ -276,3 +276,12 @@ def from_json(cls: type[_ObjType], json_string: str, **kwargs: Any) -> _ObjType:
         if not isinstance(obj, cls):
             raise TypeError(f"provided JSON object is not of type {cls}")
         return obj
+
+
+__all__ = [
+    "DelMembersMixin",
+    "GetMembersMixin",
+    "ObjectAliasMixin",
+    "SerializationMixin",
+    "SetMembersMixin",
+]

src/griffe/stats.py

@@ -169,3 +169,6 @@ def _format_stats(stats: dict) -> str:
     serialize_time_per_module = serialize_time / modules
     lines.append(f"Time spent serializing: {serialize_time}ms, {serialize_time_per_module:.02f}ms/module")
     return "\n".join(lines)
+
+
+__all__ = ["stats"]

src/griffe/tests.py

@@ -282,3 +282,16 @@ def module_vtree(path: str, *, leaf_package: bool = True, return_leaf: bool = Fa
             filepath = modules[-1].filepath.with_name(f"{parts[-1]}.py")  # type: ignore[union-attr]
         modules[-1]._filepath = filepath
     return vtree(*modules, return_leaf=return_leaf)  # type: ignore[return-value]
+
+
+__all__ = [
+    "htree",
+    "module_vtree",
+    "temporary_inspected_module",
+    "temporary_pyfile",
+    "temporary_pypackage",
+    "temporary_visited_module",
+    "temporary_visited_package",
+    "TmpPackage",
+    "vtree",
+]