Docstring update (#58)

* migrate docstrings from reST to google format

* add raises note

Also change behaviour of the `from_option` method to fallback to
disabled instead of raising exception on unknown option

* fix part of warnings for sphinx

* make identation a bit more readable

* review fixes

* add verbose description for properties to make them parsed by sphinx extenstion

* add demo sphinx generator
This commit is contained in:
2022-04-17 20:25:28 +03:00
committed by GitHub
parent 0db619136d
commit d90f417cae
203 changed files with 5246 additions and 1636 deletions

View File

@ -32,20 +32,24 @@ from ahriman.models.package import Package
class Watcher:
"""
package status watcher
:ivar architecture: repository architecture
:ivar database: database instance
:ivar known: list of known packages. For the most cases `packages` should be used instead
:ivar logger: class logger
:ivar repository: repository object
:ivar status: daemon status
Attributes:
architecture(str): repository architecture
database(SQLite): database instance
known(Dict[str, Tuple[Package, BuildStatus]]): list of known packages. For the most cases `packages` should be used instead
logger(logging.Logger): class logger
repository(Repository): repository object
status(BuildStatus): daemon status
"""
def __init__(self, architecture: str, configuration: Configuration, database: SQLite) -> None:
"""
default constructor
:param architecture: repository architecture
:param configuration: configuration instance
:param database: database instance
Args:
architecture(str): repository architecture
configuration(Configuration): configuration instance
database(SQLite): database instance
"""
self.logger = logging.getLogger("http")
@ -59,14 +63,25 @@ class Watcher:
@property
def packages(self) -> List[Tuple[Package, BuildStatus]]:
"""
:return: list of packages together with their statuses
get current known packages list
Returns:
List[Tuple[Package, BuildStatus]]: list of packages together with their statuses
"""
return list(self.known.values())
def get(self, base: str) -> Tuple[Package, BuildStatus]:
"""
get current package base build status
:return: package and its status
Args:
base(str): package base
Returns:
Tuple[Package, BuildStatus]: package and its status
Raises:
UnknownPackage: if no package found
"""
try:
return self.known[base]
@ -92,7 +107,9 @@ class Watcher:
def remove(self, package_base: str) -> None:
"""
remove package base from known list if any
:param package_base: package base
Args:
package_base(str): package base
"""
self.known.pop(package_base, None)
self.database.package_remove(package_base)
@ -100,9 +117,14 @@ class Watcher:
def update(self, package_base: str, status: BuildStatusEnum, package: Optional[Package]) -> None:
"""
update package status and description
:param package_base: package base to update
:param status: new build status
:param package: optional new package description. In case if not set current properties will be used
Args:
package_base(str): package base to update
status(BuildStatusEnum): new build status
package(Optional[Package]): optional new package description. In case if not set current properties will be used
Raises:
UnknownPackage: if no package found
"""
if package is None:
try:
@ -116,6 +138,8 @@ class Watcher:
def update_self(self, status: BuildStatusEnum) -> None:
"""
update service status
:param status: new service status
Args:
status(BuildStatusEnum): new service status
"""
self.status = BuildStatus(status)