doc: improve API documentation
This commit is contained in:
parent
bc039b6bfb
commit
f46ffa08d8
15 changed files with 131 additions and 36 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -15,7 +15,10 @@ SPDX-License-Identifier: GPL-2.0-or-later
|
|||
- PackageQuery
|
||||
- RepoError
|
||||
- Repoquery
|
||||
- _QueryFilterKwargs
|
||||
- NEVRAForms
|
||||
- get_releasever
|
||||
inherited_members: true
|
||||
|
||||
## See also
|
||||
|
||||
|
|
|
|||
15
mkdocs.yml
15
mkdocs.yml
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 = [
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -10,6 +10,7 @@ if TYPE_CHECKING:
|
|||
from types import ModuleType
|
||||
|
||||
BACKEND = "dnf"
|
||||
"""Name of the backend"""
|
||||
NEEDS = ("dnf", "hawkey")
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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"]
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -10,6 +10,7 @@ if TYPE_CHECKING:
|
|||
from types import ModuleType
|
||||
|
||||
BACKEND = "libdnf5"
|
||||
"""Name of the backend"""
|
||||
NEEDS = ("libdnf5",)
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 (
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue