chore(release): 0.0.7
Squash-merge lib-standardisation: adopt repo standards across packaging, tooling, docs, and CI. - standardize pyproject.toml (canonical packaging, lint config, extras, GSDFC pydoclint) - add py.typed marker, modernize type hints and Google-style docstrings - nest generated docs under docs/lib and docs/mcp; add hand-written wiki - adopt standard Type A PyPI CI pipeline (tag==version guard + quality gate) - promote generated CHANGELOG.md; bump version to 0.0.7
This commit is contained in:
@@ -6,21 +6,32 @@ Utilities for loading and introspecting Python modules using Griffe.
|
||||
This module provides the `GriffeLoader` class and helper utilities used to
|
||||
discover Python modules, introspect their structure, and convert the results
|
||||
into doc-forge documentation models.
|
||||
|
||||
---
|
||||
|
||||
Notes:
|
||||
- All analysis is static; analyzed modules are never executed.
|
||||
- Private members (names starting with `_`) are skipped during conversion.
|
||||
- Imported aliases that cannot be resolved (stdlib/third-party names) are
|
||||
skipped; aliases that resolve within the documented project are kept.
|
||||
|
||||
---
|
||||
"""
|
||||
|
||||
import logging
|
||||
from pathlib import Path
|
||||
from typing import List, Optional
|
||||
|
||||
from griffe import (
|
||||
GriffeLoader as _GriffeLoader,
|
||||
ModulesCollection,
|
||||
LinesCollection,
|
||||
Object,
|
||||
AliasResolutionError,
|
||||
LinesCollection,
|
||||
ModulesCollection,
|
||||
Object,
|
||||
)
|
||||
from griffe import (
|
||||
GriffeLoader as _GriffeLoader,
|
||||
)
|
||||
|
||||
from docforge.models import Module, Project, DocObject
|
||||
from docforge.models import DocObject, Module, Project
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
@@ -28,7 +39,7 @@ logger = logging.getLogger(__name__)
|
||||
def discover_module_paths(
|
||||
module_name: str,
|
||||
project_root: Path | None = None,
|
||||
) -> List[str]:
|
||||
) -> list[str]:
|
||||
"""
|
||||
Discover Python modules within a package directory.
|
||||
|
||||
@@ -45,12 +56,12 @@ def discover_module_paths(
|
||||
module_name (str):
|
||||
Top-level package name to discover modules from.
|
||||
|
||||
project_root (Path, optional):
|
||||
project_root (Path | None):
|
||||
Root directory used to resolve module paths. If not provided, the
|
||||
current working directory is used.
|
||||
|
||||
Returns:
|
||||
List[str]:
|
||||
list[str]:
|
||||
A sorted list of unique dotted module import paths.
|
||||
|
||||
Raises:
|
||||
@@ -65,7 +76,7 @@ def discover_module_paths(
|
||||
if not pkg_dir.exists():
|
||||
raise FileNotFoundError(f"Package not found: {pkg_dir}")
|
||||
|
||||
module_paths: List[str] = []
|
||||
module_paths: list[str] = []
|
||||
|
||||
for path in pkg_dir.rglob("*.py"):
|
||||
if path.name == "__init__.py":
|
||||
@@ -87,6 +98,10 @@ class GriffeLoader:
|
||||
This loader uses the Griffe introspection engine to analyze Python source
|
||||
code and transform the extracted information into `Project`, `Module`,
|
||||
and `DocObject` instances used by doc-forge.
|
||||
|
||||
Attributes:
|
||||
_loader (_GriffeLoader):
|
||||
Internal Griffe loader with dedicated module and line collections.
|
||||
"""
|
||||
|
||||
def __init__(self) -> None:
|
||||
@@ -102,10 +117,10 @@ class GriffeLoader:
|
||||
)
|
||||
|
||||
def load_project(
|
||||
self,
|
||||
module_paths: List[str],
|
||||
project_name: Optional[str] = None,
|
||||
skip_import_errors: bool = None,
|
||||
self,
|
||||
module_paths: list[str],
|
||||
project_name: str | None = None,
|
||||
skip_import_errors: bool | None = None,
|
||||
) -> Project:
|
||||
"""
|
||||
Load multiple modules and assemble them into a Project model.
|
||||
@@ -115,14 +130,14 @@ class GriffeLoader:
|
||||
object.
|
||||
|
||||
Args:
|
||||
module_paths (List[str]):
|
||||
module_paths (list[str]):
|
||||
List of dotted module import paths to load.
|
||||
|
||||
project_name (str, optional):
|
||||
project_name (str | None):
|
||||
Optional override for the project name. Defaults to the top-level
|
||||
name of the first module.
|
||||
|
||||
skip_import_errors (bool, optional):
|
||||
skip_import_errors (bool | None):
|
||||
If True, modules that fail to load will be skipped instead of raising an error.
|
||||
|
||||
Returns:
|
||||
@@ -171,6 +186,21 @@ class GriffeLoader:
|
||||
Returns:
|
||||
Module:
|
||||
A populated `Module` instance.
|
||||
|
||||
Raises:
|
||||
ImportError:
|
||||
If the module cannot be loaded by Griffe.
|
||||
|
||||
KeyError:
|
||||
If the loaded module is missing from the module collection.
|
||||
|
||||
Example:
|
||||
Load a single module:
|
||||
|
||||
```python
|
||||
loader = GriffeLoader()
|
||||
module = loader.load_module("mypackage.submodule")
|
||||
```
|
||||
"""
|
||||
self._loader.load(path)
|
||||
griffe_module = self._loader.modules_collection[path]
|
||||
@@ -204,6 +234,8 @@ class GriffeLoader:
|
||||
for name, member in obj.members.items():
|
||||
if name.startswith("_"):
|
||||
continue
|
||||
if not self._is_resolvable_alias(member):
|
||||
continue
|
||||
|
||||
module.add_object(self._convert_object(member))
|
||||
|
||||
@@ -240,6 +272,8 @@ class GriffeLoader:
|
||||
for name, member in obj.members.items():
|
||||
if name.startswith("_"):
|
||||
continue
|
||||
if not self._is_resolvable_alias(member):
|
||||
continue
|
||||
doc_obj.add_member(self._convert_object(member))
|
||||
except AliasResolutionError:
|
||||
pass
|
||||
@@ -250,7 +284,7 @@ class GriffeLoader:
|
||||
# Safe extractors
|
||||
# -------------------------
|
||||
|
||||
def _safe_docstring(self, obj: Object) -> Optional[str]:
|
||||
def _safe_docstring(self, obj: Object) -> str | None:
|
||||
"""
|
||||
Safely extract a docstring from a Griffe object.
|
||||
|
||||
@@ -259,7 +293,7 @@ class GriffeLoader:
|
||||
Griffe object to inspect.
|
||||
|
||||
Returns:
|
||||
Optional[str]:
|
||||
str | None:
|
||||
The raw docstring text if available, otherwise `None`.
|
||||
"""
|
||||
try:
|
||||
@@ -267,21 +301,57 @@ class GriffeLoader:
|
||||
except AliasResolutionError:
|
||||
return None
|
||||
|
||||
def _safe_signature(self, obj: Object) -> Optional[str]:
|
||||
def _safe_signature(self, obj: Object) -> str | None:
|
||||
"""
|
||||
Safely extract the signature of a Griffe object.
|
||||
|
||||
Griffe exposes signatures as callables (``Object.signature``); the
|
||||
method is invoked and stringified to produce a clean, stable signature.
|
||||
Aliases that point outside the loaded project fail resolution and are
|
||||
reported as `None`.
|
||||
|
||||
Args:
|
||||
obj (Object):
|
||||
Griffe object to inspect.
|
||||
|
||||
Returns:
|
||||
Optional[str]:
|
||||
String representation of the object's signature if available, otherwise `None`.
|
||||
str | None:
|
||||
Clean string representation of the object's signature if
|
||||
available, otherwise `None`.
|
||||
"""
|
||||
try:
|
||||
if hasattr(obj, "signature") and obj.signature:
|
||||
return str(obj.signature)
|
||||
except AliasResolutionError:
|
||||
signature = getattr(obj, "signature", None)
|
||||
if signature is None:
|
||||
return None
|
||||
if callable(signature):
|
||||
signature = signature()
|
||||
if not signature:
|
||||
return None
|
||||
return str(signature).strip() or None
|
||||
except Exception:
|
||||
return None
|
||||
return None
|
||||
|
||||
def _is_resolvable_alias(self, obj: Object) -> bool:
|
||||
"""
|
||||
Report whether an object is a resolvable part of the documented API.
|
||||
|
||||
Aliases that cannot be resolved (stdlib or third-party imports) are
|
||||
treated as noise and excluded from the model. Non-alias objects are
|
||||
always resolvable.
|
||||
|
||||
Args:
|
||||
obj (Object):
|
||||
Griffe object to test.
|
||||
|
||||
Returns:
|
||||
bool:
|
||||
True if the object should be kept, False if it is an
|
||||
unresolvable alias.
|
||||
"""
|
||||
if obj.kind.value != "alias":
|
||||
return True
|
||||
try:
|
||||
_ = obj.canonical_path
|
||||
except AliasResolutionError:
|
||||
return False
|
||||
return True
|
||||
|
||||
Reference in New Issue
Block a user