doc: improve API documentation

This commit is contained in:
Maxwell G 2025-03-12 14:30:04 -05:00
commit f46ffa08d8
Signed by: gotmax23
GPG key ID: F79E4E25E8C661F8
15 changed files with 131 additions and 36 deletions

View file

@ -7,6 +7,8 @@ SPDX-License-Identifier: GPL-2.0-or-later
# fedrq.backends.dnf.backend
::: fedrq.backends.dnf.backend
options:
inherited_members: true
## See also

View file

@ -15,7 +15,10 @@ SPDX-License-Identifier: GPL-2.0-or-later
- PackageQuery
- RepoError
- Repoquery
- _QueryFilterKwargs
- NEVRAForms
- get_releasever
inherited_members: true
## See also

View file

@ -43,22 +43,33 @@ markdown_extensions:
- pymdownx.superfences
plugins:
- mkdocstrings:
default_handler: python
default_handler: python_xref
handlers:
python:
python_xref:
options:
extensions:
# Doesn't work with xref
# - griffe_pydantic:
# schema: true
- griffe_inherited_docstrings
relative_crossrefs: true
docstring_style: google
docstring_section_style: list
show_if_no_docstring: true
merge_init_into_class: true
filters: ["!^__?", "!LOG", "!logger"]
show_signature_annotations: true
separate_signature: true
show_symbol_type_heading: true
summary: true
paths:
- src/
inventories:
- https://docs.python.org/3/objects.inv
- https://dnf.readthedocs.io/en/latest/objects.inv
- https://dnf5.readthedocs.io/en/latest/objects.inv
- https://docs.pydantic.dev/latest/objects.inv
- https://typing-extensions.readthedocs.io/en/latest/objects.inv
- gen-files:
scripts:
- doc/mkdocs_mangen.py

View file

@ -52,11 +52,15 @@ doc = [
# This is a transitive dependency of mkdocstrings-python
# 0.32.0 breaks black function signature formatting
"griffe !=0.32.0, !=0.32.1",
# Not compatible with python-xref
# "griffe-pydantic",
"griffe-inherited-docstrings",
"mkdocs",
"mkdocs-exclude",
"mkdocs-gen-files",
"mkdocs-material",
"mkdocstrings[python]>=0.18",
"mkdocstrings-python-xref",
"releaserr",
]
formatters = [

View file

@ -54,7 +54,11 @@ ghp-import==2.1.0
griffe==1.5.7
# via
# fedrq (pyproject.toml)
# griffe-inherited-docstrings
# mkdocstrings-python
# mkdocstrings-python-xref
griffe-inherited-docstrings==1.1.1
# via fedrq (pyproject.toml)
h11==0.14.0
# via httpcore
httpcore==1.0.7
@ -137,7 +141,11 @@ mkdocstrings==0.28.1
# fedrq (pyproject.toml)
# mkdocstrings-python
mkdocstrings-python==1.15.0
# via mkdocstrings
# via
# mkdocstrings
# mkdocstrings-python-xref
mkdocstrings-python-xref==1.14.0
# via fedrq (pyproject.toml)
mypy==1.15.0
# via fedrq (pyproject.toml)
mypy-extensions==1.0.0

View file

@ -33,7 +33,11 @@ ghp-import==2.1.0
griffe==1.5.7
# via
# fedrq (pyproject.toml)
# griffe-inherited-docstrings
# mkdocstrings-python
# mkdocstrings-python-xref
griffe-inherited-docstrings==1.1.1
# via fedrq (pyproject.toml)
h11==0.14.0
# via httpcore
httpcore==1.0.7
@ -109,7 +113,11 @@ mkdocstrings==0.28.1
# fedrq (pyproject.toml)
# mkdocstrings-python
mkdocstrings-python==1.15.0
# via mkdocstrings
# via
# mkdocstrings
# mkdocstrings-python-xref
mkdocstrings-python-xref==1.14.0
# via fedrq (pyproject.toml)
mypy-extensions==1.0.0
# via black
packaging==24.2

View file

@ -351,7 +351,6 @@ class BaseMakerBase(metaclass=abc.ABCMeta):
"""
Set configuration options. Must be called before reading repos.
"""
...
@abc.abstractmethod
def set_var(self, key: str, value: Any) -> None:
@ -359,7 +358,6 @@ class BaseMakerBase(metaclass=abc.ABCMeta):
Set substitutions (e.g. arch, basearch, releasever).
Needs to be called before reading repos.
"""
...
# Private for now
@abc.abstractmethod
@ -445,14 +443,22 @@ class BaseMakerBase(metaclass=abc.ABCMeta):
key-values options that should be set on the Repo object values
(like $basearch) will be substituted automatically.
"""
...
@property
@abc.abstractmethod
def backend(self) -> BackendMod: ...
def backend(self) -> BackendMod:
"""
Return the backend's module
"""
@abc.abstractmethod
def repolist(self, enabled: bool | None = None) -> list[str]: ...
def repolist(self, enabled: bool | None = None) -> list[str]:
"""
List available repoids.
Args:
enabled: Only show enabled repositories
"""
@abc.abstractmethod
def enable_source_repos(self) -> None:
@ -460,7 +466,6 @@ class BaseMakerBase(metaclass=abc.ABCMeta):
Enable the corresponding -source repos of the currently enabled
repositories
"""
...
class NEVRAFormsCompat(Protocol):
@ -489,7 +494,6 @@ class RepoqueryBase(Generic[_PackageT_co, _PackageQueryT_co], metaclass=abc.ABCM
"""
Return a set of the system's arch and basearch.
"""
...
def _get_resolve_options(
self,
@ -537,7 +541,6 @@ class RepoqueryBase(Generic[_PackageT_co, _PackageQueryT_co], metaclass=abc.ABCM
with_src:
Whether to consider `.src` packages when resolving `specs`
"""
...
def arch_filterm(
self,
@ -595,7 +598,6 @@ class RepoqueryBase(Generic[_PackageT_co, _PackageQueryT_co], metaclass=abc.ABCM
"""
Return the PackageQuery object for this backend
"""
return self.base.sack.query()
def query(
self,
@ -661,7 +663,10 @@ class RepoqueryBase(Generic[_PackageT_co, _PackageQueryT_co], metaclass=abc.ABCM
@property
@abc.abstractmethod
def backend(self) -> BackendMod: ...
def backend(self) -> BackendMod:
"""
Return backend module
"""
RepoqueryAlias: TypeAlias = RepoqueryBase

View file

@ -2,8 +2,7 @@
# SPDX-License-Identifier: GPL-2.0-or-later
"""
This module (and the other experimental modules in fedrq) are not meant for
public use.
This module (and the other experimental modules in fedrq) are not meant for public use.
They are subject to breaking changes in minor releases and should not be relied
on by external code.
Once the functionality has stabilized, this code will be moved out of the

View file

@ -10,6 +10,7 @@ if TYPE_CHECKING:
from types import ModuleType
BACKEND = "dnf"
"""Name of the backend"""
NEEDS = ("dnf", "hawkey")

View file

@ -51,9 +51,12 @@ if t.TYPE_CHECKING:
LOG = logging.getLogger(__name__)
Package: type[PackageCompat] = dnf.package.Package
"""Annotated alias to dnf.package.Package"""
PackageQueryCompat.register(dnf.query.Query)
PackageQuery: type[PackageQueryCompat] = dnf.query.Query
"""Annotated alias to dnf.query.Query"""
RepoError = dnf.exceptions.RepoError
"""Error when loading repositories"""
class BaseMaker(BaseMakerBase):
@ -210,6 +213,10 @@ class BaseMaker(BaseMakerBase):
class NEVRAForms(int, Enum):
"""
Enum of NEVRAForms to pass to [`Repoquery.resolve_pkg_specs`][^.]
"""
NEVRA = hawkey.FORM_NEVRA
NEVR = hawkey.FORM_NEVR
NEV = hawkey.FORM_NEV
@ -220,6 +227,11 @@ class NEVRAForms(int, Enum):
# Use PackageCompat as the TypeVar, as the the native dnf objects
# don't provide typing.
class Repoquery(RepoqueryBase[PackageCompat, PackageQueryCompat[PackageCompat]]):
"""
Helpers to query a repository.
Provides a unified repoquery interface for different backends.
"""
def __init__(self, base: dnf.Base) -> None:
self.base: dnf.Base = base
@ -263,6 +275,9 @@ class Repoquery(RepoqueryBase[PackageCompat, PackageQueryCompat[PackageCompat]])
@property
def backend(self) -> BackendMod:
"""
Return fedrq.backends.dnf.backend module
"""
return t.cast("BackendMod", sys.modules[__name__])
@ -275,6 +290,9 @@ def get_releasever():
def get_changelogs(package: t.Any) -> Iterator[ChangelogEntry]:
"""
Given a Package object, return an iterator of ChangelogEntry objects.
"""
for entry in package.changelogs:
yield ChangelogEntry(
text=entry["text"], author=entry["author"], date=entry["timestamp"]

View file

@ -2,8 +2,7 @@
# SPDX-License-Identifier: GPL-2.0-or-later
"""
This module (and the other experimental modules in fedrq) are not meant for
public use.
This module (and the other experimental modules in fedrq) are not meant for public use.
They are subject to breaking changes in minor releases and should not be relied
on by external code.
Once the functionality has stabilized, this code will be moved out of the

View file

@ -10,6 +10,7 @@ if TYPE_CHECKING:
from types import ModuleType
BACKEND = "libdnf5"
"""Name of the backend"""
NEEDS = ("libdnf5",)

View file

@ -56,6 +56,10 @@ CONVERT_TO_LIST = (str, int)
class _QueryFilterKwargs(t.TypedDict, total=False):
"""
Keyword-arguments accepted by [`Repoquery.query`][(m).].
"""
name: t.Union[StrIter, libdnf5.rpm.PackageSet]
name__eq: t.Union[StrIter, libdnf5.rpm.PackageSet]
name__neq: t.Union[StrIter, libdnf5.rpm.PackageSet]
@ -194,6 +198,9 @@ class BaseMaker(BaseMakerBase):
"""
base: libdnf5.base.Base
"""The underlying dnf.base object"""
initialized: bool
"""INTERNAL: Whether the base object has been initialized"""
def __init__(
self,
@ -232,6 +239,9 @@ class BaseMaker(BaseMakerBase):
@property
def conf(self) -> libdnf5.conf.ConfigMain:
"""
Return libdnf5 config object.
"""
return self.base.get_config()
# Not part of the BaseMakerBase interface
@ -249,6 +259,10 @@ class BaseMaker(BaseMakerBase):
# Not part of the BaseMakerBase interface
@property
def vars(self) -> libdnf5.conf.Vars:
"""
Return libdnf5 Vars object.
Not part of the BaseMakerBase interface!
"""
return self.base.get_vars()
# Not part of the BaseMakerBase interface
@ -267,6 +281,10 @@ class BaseMaker(BaseMakerBase):
# Not part of the BaseMakerBase interface
@property
def rs(self) -> libdnf5.repo.RepoSackWeakPtr:
"""
Return libdnf5 RepoSack object.
Not part of the BaseMakerBase interface!
"""
self.setup()
return self.base.get_repo_sack()
@ -450,6 +468,9 @@ class BaseMaker(BaseMakerBase):
@property
def backend(self) -> BackendMod:
"""
Return fedrq.backends.libdnf5.backend module
"""
return t.cast(BackendMod, sys.modules[__name__])
def repolist(self, enabled: bool | None = None) -> list[str]:
@ -463,11 +484,12 @@ class BaseMaker(BaseMakerBase):
class Package(libdnf5.rpm.Package, PackageCompat):
"""
[libdnf5.rpm.Package][] subclass with strong [dnf.package.Package][] compatability
"""
DEBUGINFO_SUFFIX = "-debuginfo"
DEBUGSOURCE_SUFFIX = "-debugsource"
"""
libdnf5.rpm.Package subclass with strong dnf.package.Package compatability
"""
def __hash__(self) -> int:
return hash(self.get_id().id)
@ -483,13 +505,13 @@ class Package(libdnf5.rpm.Package, PackageCompat):
return self.get_arch() > other.get_arch()
def __ge__(self, other) -> bool:
return self > other or self == other
return self == other or self > other
def __lt__(self, other) -> bool:
return not (self > other)
def __le__(self, other) -> bool:
return self < other or self == other
return self == other or self < other
@property
def name(self) -> str:
@ -687,7 +709,7 @@ libdnf5._rpm.Package_swigregister(Package)
class Reldep5(libdnf5.rpm.Reldep):
"""
Subclass of libdnf5.rpm.Reldep with a useful __str__() method
Subclass of [libdnf5.rpm.Reldep][] with a useful __str__() method
"""
def __str__(self) -> str:
@ -727,11 +749,11 @@ _sc = _setattr_compat
class PackageQuery(libdnf5.rpm.PackageQuery, PackageQueryCompat[Package]):
__rq__: Repoquery
"""
Subclass of [libdnf5.rpm.PackageQuery][] with [dnf.query.Query][] compatability
"""
"""
Subclass of libdnf5.rpm.PackageQuery with hawkey.Query compatability
"""
__rq__: Repoquery
def _filter( # type: ignore[override]
self,
@ -878,6 +900,10 @@ def _convert_value(key: str, value: _ValT) -> t.Union[list[_ValT], _ValT]:
class NEVRAForms(int, Enum):
"""
Enum of NEVRAForms to pass to [`Repoquery.resolve_pkg_specs`][^.]
"""
NEVRA = libdnf5.rpm.Nevra.Form_NEVRA
NEVR = libdnf5.rpm.Nevra.Form_NEVR
NEV = libdnf5.rpm.Nevra.Form_NEV
@ -886,6 +912,11 @@ class NEVRAForms(int, Enum):
class Repoquery(RepoqueryBase[Package, PackageQuery]):
"""
Helpers to query a repository.
Provides a unified repoquery interface for different backends.
"""
def __init__(self, base: libdnf5.base.Base) -> None:
self.base: libdnf5.base.Base = base
@ -899,11 +930,6 @@ class Repoquery(RepoqueryBase[Package, PackageQuery]):
obj.__rq__ = self
return obj
def query(
self, *, arch: str | Iterable[str] | None = None, **kwargs
) -> PackageQuery:
return t.cast(PackageQuery, super().query(arch=arch, **kwargs))
def resolve_pkg_specs(
self,
specs: Collection[str],
@ -942,10 +968,13 @@ class Repoquery(RepoqueryBase[Package, PackageQuery]):
@property
def backend(self) -> BackendMod:
"""
Return fedrq.backends.libdnf5.backend module
"""
return t.cast(BackendMod, sys.modules[__name__])
def _dnf_getreleasever() -> str: # pragma: no cover
def _dnf_getreleasever() -> str:
# This is taken from dnf and slightly modified to fit fedrq's code style standards.
#
# SPDX-License-Identifier: GPL-2.0-or-later
@ -1016,6 +1045,9 @@ def get_releasever() -> str:
def get_changelogs(package: Package) -> Iterator[ChangelogEntry]:
"""
Given a Package object, return an iterator of ChangelogEntry objects.
"""
entries = package.get_changelogs()
for entry in entries:
date_obj = DT.fromtimestamp(_gc(entry, "timestamp"), tz=TZ.utc).date()
@ -1025,6 +1057,7 @@ def get_changelogs(package: Package) -> Iterator[ChangelogEntry]:
RepoError = RuntimeError
"""Error when loading repositories"""
PackageQueryAlias: TypeAlias = PackageQuery

View file

@ -3,8 +3,7 @@
"""
This module (and the other experimental modules in fedrq) are not meant for
public use.
This module (and the other experimental modules in fedrq) are not meant for public use.
They are subject to breaking changes in minor releases and should not be relied
on by external code.
Once the functionality has stabilized, this code will be moved out of the

View file

@ -86,11 +86,15 @@ class ReleaseConfig(BaseModel):
copr_chroot_fmt: t.Optional[str] = None
repo_aliases: dict[str, str] = {}
repogs: Repos = Field(DefaultRepoGs, exclude=True)
_repogs: Repos = PrivateAttr(DefaultRepoGs)
class Config:
arbitrary_types_allowed = True
@property
def repogs(self) -> Repos:
return self.repogs
@validator("repogs", always=True)
def _v_repogs(cls, value: Repos, values: dict[str, t.Any]) -> Repos:
return (