docs: fix types in docstrings

This commit is contained in:
arcanis committed 2026-11-19 15:50:36 +02:00
1 parent 0bd22a049c
commit a428b62993
45 files changed
+89 -77

No files matched your search

@@ -45,7 +45,7 @@ class Application(ApplicationPackages, ApplicationRepository):
>>> application.add(["ahriman"], PackageSource.AUR)
>>>
>>> # check for updates
>>> updates = application.updates([], aur=True, local=True, manual=True, vcs=True)
>>> updates = application.updates([], aur=True, local=True, manual=True, vcs=True, check_files=False)
>>> # updates for specified packages
>>> application.update(updates)
@@ -41,7 +41,7 @@ class UpdatesIterator(Iterator[list[str] | None]):
Typical usage of this class is something like:
>>> application = ...
>>> iterator = UpdatesIterator(application, None)
>>> iterator = UpdatesIterator(application, 3600)
>>>
>>> for updates in iterator:
>>> print(updates)
@@ -158,7 +158,7 @@ class Statistics(Handler):
Args:
event_type(str): event type
events(list[Event]): list of events
chart_path(Path): path to save plot if any
chart_path(Path | None): path to save plot if any
"""
# event statistics
Statistics.event_stats(event_type, events)
@@ -175,7 +175,7 @@ class Statistics(Handler):
Args:
event_type(str): event type
events(list[Event]): list of events
chart_path(Path): path to save plot if any
chart_path(Path | None): path to save plot if any
"""
key: Callable[[Event], str] = lambda event: event.object_id
by_object_id = {
@@ -77,7 +77,7 @@ class UnsafeCommands(Handler):
check if command is unsafe
Args:
command(str): command to check
command(list[str]): command and arguments to check
unsafe_commands(list[str]): list of unsafe commands
parser(argparse.ArgumentParser): generated argument parser
"""
+1 -1
View File
@@ -88,7 +88,7 @@ class _Context:
iterate over keys in local storage
Returns:
str: context key iterator
Iterator[str]: context key iterator
"""
return iter(self._content)
@@ -134,7 +134,7 @@ class Configuration(configparser.RawConfigParser):
repository identifier
Returns:
RepositoryId: repository unique identifier
RepositoryId | None: repository unique identifier
"""
return self._repository_id
@@ -58,7 +58,7 @@ class Migrations(LazyLogging):
configuration(Configuration): configuration instance
Returns:
MigrationResult: current schema version
MigrationResult: schema versions before and after migration
"""
return Migrations(connection, configuration).run()
@@ -144,8 +144,8 @@ class Migrations(LazyLogging):
"""
perform migrations
Return:
MigrationResult: current schema version
Returns:
MigrationResult: schema versions before and after migration
"""
migrations = self.migrations()
@@ -35,7 +35,7 @@ class BuildOperations(Operations):
Args:
package_base(str | None): optional filter by package base
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -57,9 +57,9 @@ class BuildOperations(Operations):
retrieve packages from build queue
Args:
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
Return:
Returns:
list[Package]: list of packages to be built
"""
repository_id = repository_id or self._repository_id
@@ -81,7 +81,7 @@ class BuildOperations(Operations):
Args:
package(Package): package to be inserted
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -35,7 +35,7 @@ class ChangesOperations(Operations):
Args:
package_base(str): package base to search
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
Returns:
Changes: changes for the package base if available
@@ -69,7 +69,7 @@ class ChangesOperations(Operations):
Args:
package_base(str): package base to insert
changes(Changes): package changes (as in patch format)
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -101,7 +101,7 @@ class ChangesOperations(Operations):
Args:
package_base(str | None): optional filter by package base
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -36,10 +36,10 @@ class DependenciesOperations(Operations):
Args:
package_base(str | None): package base to search
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
Returns:
Dependencies: dependencies for the package base if available
dict[str, Dependencies]: dependencies keyed by package base, optionally filtered by package base
"""
repository_id = repository_id or self._repository_id
@@ -69,7 +69,7 @@ class DependenciesOperations(Operations):
Args:
package_base(str): package base
dependencies(Dependencies): package dependencies
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -97,7 +97,7 @@ class DependenciesOperations(Operations):
Args:
package_base(str | None): optional filter by package base
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -42,7 +42,7 @@ class EventOperations(Operations):
to_date(int | float | None, optional): maximal creation date, exclusive (Default value = None)
limit(int, optional): limit records to the specified count, -1 means unlimited (Default value = -1)
offset(int, optional): records offset (Default value = 0)
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
Returns:
list[Event]: list of audit log events
@@ -84,7 +84,7 @@ class EventOperations(Operations):
Args:
event(Event): event to insert
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -40,9 +40,9 @@ class LogsOperations(Operations):
process_id(str | None, optional): process identifier to filter (Default value = None)
limit(int, optional): limit records to the specified count, -1 means unlimited (Default value = -1)
offset(int, optional): records offset (Default value = 0)
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
Return:
Returns:
list[LogRecord]: sorted package log records
"""
repository_id = repository_id or self._repository_id
@@ -79,7 +79,7 @@ class LogsOperations(Operations):
Args:
log_record(LogRecord): log record object
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -106,7 +106,7 @@ class LogsOperations(Operations):
Args:
package_base(str): package base to remove logs
version(str | None): package version. If set it will remove only logs belonging to another version
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -133,7 +133,7 @@ class LogsOperations(Operations):
Args:
keep_last_records(int): number of last records to keep
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -66,7 +66,7 @@ class Operations(LazyLogging):
dictionary factory based on official documentation
Args:
cursor(Cursor): cursor descriptor
cursor(sqlite3.Cursor): cursor descriptor
row(tuple[Any, ...]): fetched row
Returns:
@@ -82,7 +82,7 @@ class Operations(LazyLogging):
perform operation in connection
Args:
query(Callable[[Connection], T]): function to be called with connection
query(Callable[[sqlite3.Connection], T]): function to be called with connection
commit(bool, optional): if ``True`` commit() will be called on success (Default value = False)
Returns:
@@ -225,7 +225,7 @@ class PackageOperations(Operations):
Args:
package_base(str): package base name
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
enabled(bool): new hold status
"""
repository_id = repository_id or self._repository_id
@@ -248,7 +248,7 @@ class PackageOperations(Operations):
Args:
package_base(str): package base name
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -264,7 +264,7 @@ class PackageOperations(Operations):
Args:
package(Package): package properties
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -280,9 +280,9 @@ class PackageOperations(Operations):
get package list and their build statuses from database
Args:
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
Return:
Returns:
list[tuple[Package, BuildStatus]]: list of package properties and their statuses
"""
repository_id = repository_id or self._repository_id
@@ -303,7 +303,7 @@ class PackageOperations(Operations):
Args:
package_base(str): package base name
status(BuildStatus): new build status
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
"""
repository_id = repository_id or self._repository_id
@@ -116,7 +116,7 @@ class SQLite(
Args:
package_base(str): package base to remove
repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
repository_id(RepositoryId | None, optional): repository unique identifier override (Default value = None)
Examples:
This method completely removes the package from all tables and must be used, e.g. on package removal::
+1 -1
View File
@@ -254,7 +254,7 @@ class PasswordError(ValueError):
def __init__(self, details: Any) -> None:
"""
Args:
details(Any); error details
details(Any): error details
"""
ValueError.__init__(self, f"Password error: {details}")
@@ -35,6 +35,7 @@ class RepositoryStatsPrinter(StringPrinter):
def __init__(self, repository_id: RepositoryId, statistics: RepositoryStats) -> None:
"""
Args:
repository_id(RepositoryId): repository unique identifier
statistics(RepositoryStats): repository statistics
"""
StringPrinter.__init__(self, str(repository_id))
@@ -90,6 +90,9 @@ class UpdatePrinter(StringPrinter):
"""
generate version property
Args:
package(Package): package whose current and updated versions are shown
Returns:
tuple[str, str]: extract current and updated versions for the package
"""
@@ -81,7 +81,7 @@ class SyncHttpClient(LazyLogging):
get or create session
Returns:
request.Session: created session object
requests.Session: created session object
"""
session = requests.Session()
@@ -107,10 +107,10 @@ class JinjaTemplate:
sort content before rendering
Args:
content(list[dict[str, str]]): content of the template
content(list[dict[str, Any]]): content of the template
Returns:
list[dict[str, str]]: sorted content according to comparator defined
list[dict[str, Any]]: sorted content according to comparator defined
"""
comparator: Callable[[dict[str, str]], Comparable] = lambda item: item["filename"]
return sorted(content, key=comparator)
@@ -122,6 +122,9 @@ class JinjaTemplate:
Args:
result(Result): build result
template_name(Path | str): name of the template or path to it (legacy configuration)
Returns:
str: rendered report
"""
templates = self.templates[:]
if isinstance(template_name, Path):
+2 -2
View File
@@ -82,10 +82,10 @@ class RSS(Report, JinjaTemplate):
sort content before rendering
Args:
content(list[dict[str, str]]): content of the template
content(list[dict[str, Any]]): content of the template
Returns:
list[dict[str, str]]: sorted content according to comparator defined
list[dict[str, Any]]: sorted content according to comparator defined
"""
comparator: Callable[[dict[str, str]], Comparable] = \
lambda item: parsedate_to_datetime(item["build_date"])
@@ -86,7 +86,7 @@ class RepositoryProperties(EventLogger, LazyLogging):
package_base(str): package base to lookup
Returns:
User | None: user found in database if any and empty object otherwise
User: user found in database if any and empty user object otherwise
"""
username = packagers.for_base(package_base)
if username is None: # none to search
+1 -1
View File
@@ -103,7 +103,7 @@ class GPG(SyncHttpClient):
filepath(Path): path to the file which will be signed
Returns:
str: path to signature file
Path: path to signature file
"""
return filepath.parent / f"{filepath.name}.sig"
@@ -164,7 +164,7 @@ class Client:
package_base(str): package base to retrieve
Returns:
list[Dependencies]: package implicit dependencies if available
Dependencies: package implicit dependencies if available
Raises:
NotImplementedError: not implemented method
@@ -114,7 +114,7 @@ class LocalClient(Client):
package_base(str): package base to retrieve
Returns:
list[Dependencies]: package implicit dependencies if available
Dependencies: package implicit dependencies if available
"""
return self.database.dependencies_get(package_base, self.repository_id).get(package_base, Dependencies())
@@ -151,7 +151,7 @@ class Watcher(LazyLogging):
package_base(str): package base to retrieve
Returns:
list[Dependencies]: package implicit dependencies if available
Dependencies: package implicit dependencies if available
"""
return self.client.package_dependencies_get(package_base)
@@ -269,7 +269,7 @@ class WebClient(Client, SyncAhrimanClient):
package_base(str): package base to retrieve
Returns:
list[Dependencies]: package implicit dependencies if available
Dependencies: package implicit dependencies if available
"""
with contextlib.suppress(Exception):
response = self.make_request("GET", self._dependencies_url(package_base),
@@ -57,7 +57,7 @@ class RemoteService(Upload, HttpUpload):
get or create session
Returns:
request.Session: created session object
requests.Session: created session object
"""
return self.client.session
+2 -2
View File
@@ -101,8 +101,8 @@ def check_output(*args: str, exception: Exception | Callable[[int, list[str], st
Args:
*args(str): command line arguments
exception(Exception | Callable[[int, list[str], str, str]] | None, optional): exception which has to be raised
instead of default subprocess exception. If callable us is supplied, the
exception(Exception | Callable[[int, list[str], str, str], Exception] | None, optional): exception to raise
instead of the default subprocess exception. If a callable is supplied, the
:exc:`subprocess.CalledProcessError` arguments will be passed (Default value = None)
cwd(Path | None, optional): current working directory (Default value = None)
input_data(str | None, optional): data which will be written to command stdin (Default value = None)
@@ -69,11 +69,13 @@ class AURPackage:
>>>
>>> from ahriman.core.alpm.pacman import Pacman
>>> from ahriman.core.configuration import Configuration
>>> from ahriman.models.pacman_synchronization import PacmanSynchronization
>>> from ahriman.models.repository_id import RepositoryId
>>>
>>> configuration = Configuration()
>>> pacman = Pacman(RepositoryId("x86_64", "aur"), configuration)
>>> metadata = pacman.package_get("pacman")
>>> pacman = Pacman(RepositoryId("x86_64", "aur"), configuration,
>>> refresh_database=PacmanSynchronization.DISABLED)
>>> metadata = pacman.package("pacman")
>>> package = AURPackage.from_pacman(next(metadata)) # load package from pyalpm wrapper
"""
@@ -182,7 +182,7 @@ class BuildPlan(Iterable[Package]):
iterate over selected packages in stable package-base order
Returns:
Package: selected package
Iterator[Package]: iterator over selected packages
"""
return iter(self.packages)
@@ -34,7 +34,7 @@ class FilesystemPackage:
Attributes:
package_name(str): package name
depends(set[str]): list of package dependencies
directories(set[Path]): list of directories this package contains
directories(list[Path]): list of directories this package contains
files(list[Path]): list of files this package contains
opt_depends(set[str]): list of package optional dependencies
"""
@@ -80,7 +80,8 @@ class FilesystemPackage:
include_optional(bool): include optional dependencies to check
Returns:
bool: whether this package depends on any other package in the list of packages
bool: ``True`` if this package has no dependencies among the supplied packages, ignoring packages
that have a required dependency on this package
"""
return not any(
package
@@ -38,9 +38,9 @@ class MetricsTimer:
>>> with MetricsTimer() as timer:
>>> do_something()
>>> print("Time elapsed for first function: %f", timer.elapsed)
>>> print(f"Time elapsed for first function: {timer.elapsed:f}")
>>> do_something_different()
>>> print("Time elapsed for all functions: %f", timer.elapsed)
>>> print(f"Time elapsed for all functions: {timer.elapsed:f}")
"""
def __init__(self) -> None:
+3 -3
View File
@@ -44,8 +44,8 @@ class Package(LazyLogging):
Attributes:
base(str): package base name
packager(str | None): package packager if available
packages(dict[str, PackageDescription): map of package names to their properties.
Filled only on load from archive
packages(dict[str, PackageDescription]): map of package names to their properties.
Available properties depend on the source used to load the package
remote(RemoteSource): package remote source if applicable
version(str): package full version
@@ -56,7 +56,7 @@ class Package(LazyLogging):
it will contain every data available in the JSON body. Otherwise, if generate package from local archive::
>>> package = Package.from_archive(local_path, pacman)
>>> package = Package.from_archive(local_path)
it will probably miss file descriptions (in case if there are multiple packages which belong to the base).
@@ -57,11 +57,13 @@ class PackageDescription:
>>> from pathlib import Path
>>> from ahriman.core.alpm.pacman import Pacman
>>> from ahriman.core.configuration import Configuration
>>> from ahriman.models.pacman_synchronization import PacmanSynchronization
>>> from ahriman.models.repository_id import RepositoryId
>>>
>>> configuration = Configuration()
>>> pacman = Pacman(RepositoryId("x86_64", "aur"), configuration)
>>> pyalpm_description = next(package for package in pacman.package_get("pacman"))
>>> pacman = Pacman(RepositoryId("x86_64", "aur"), configuration,
>>> refresh_database=PacmanSynchronization.DISABLED)
>>> pyalpm_description = next(package for package in pacman.package("pacman"))
>>> description = PackageDescription.from_package(
>>> pyalpm_description, Path("/var/cache/pacman/pkg/pacman-6.0.1-4-x86_64.pkg.tar.zst"))
"""
+1 -1
View File
@@ -27,7 +27,7 @@ class Packagers:
Attributes:
default(str | None): default packager username if any to be used if no override for the specified base was found
overrides: dict[str, str | None]: packager username override for specific package base
overrides(dict[str, str | None]): packager username override for specific package base
"""
default: str | None = None
@@ -109,7 +109,7 @@ class PkgbuildPatch:
Args:
key(str | None): variable key
source(str): source value string to parse
source(str | list[str]): source string to parse or list to use as is
Returns:
Self: parsed patch object
@@ -56,7 +56,7 @@ class RepositoryStats:
construct statistics from list of repository packages
Args:
packages(list[Packages]): list of repository packages
packages(list[Package]): list of repository packages
Returns:
Self: constructed statistics object
@@ -41,7 +41,7 @@ class ScanPaths:
compiled regular expressions
Returns:
list[re.Pattern]: a list of compiled regular expressions
list[re.Pattern[str]]: a list of compiled regular expressions
"""
return [re.compile(path) for path in self.paths]
@@ -15,7 +15,7 @@ def pacman_database(configuration: Configuration, pacman: Pacman) -> PacmanDatab
pacman(Pacman): pacman test instance
Returns:
DatabaseSync: database sync test instance
PacmanDatabase: pacman database test instance
"""
database = next(iter(pacman.handle.get_syncdbs()))
return PacmanDatabase(database, configuration)