arcanis/ahriman
1
0
Fork 0
mirror of https://github.com/arcan1s/ahriman.git synced 2026-03-23 18:03:39 +00:00
Code Issues Projects Releases Wiki Activity

docs: update docstrings

Browse Source
This commit is contained in:
Evgenii Alekseev
2026-03-22 17:06:26 +02:00
parent 34014d1cdd
commit 3ad2c494af
34 changed files with 73 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/ahriman/core/alpm/pkgbuild_parser.py
View File

@@ -104,7 +104,7 @@ class PkgbuildParser(shlex.shlex):
# ignore substitution and extend bash symbols
self.wordchars += "${}#:+-@!"
# in case of default behaviour, it will ignore, for example, segment part of url outside of quotes
# in case of default behavior, it will ignore, for example, segment part of url outside of quotes
self.commenters = ""
@staticmethod

2
src/ahriman/core/alpm/remote/aur.py
View File

@@ -72,7 +72,7 @@ class AUR(Remote):
parse RPC response to package list
Args:
response(dict[str, Any]): RPC response json
response(dict[str, Any]): RPC response JSON
Returns:
list[AURPackage]: list of parsed packages

2
src/ahriman/core/alpm/remote/official.py
View File

@@ -74,7 +74,7 @@ class Official(Remote):
parse RPC response to package list
Args:
response(dict[str, Any]): RPC response json
response(dict[str, Any]): RPC response JSON
Returns:
list[AURPackage]: list of parsed packages

2
src/ahriman/core/alpm/remote/official_syncdb.py
View File

@@ -32,7 +32,7 @@ class OfficialSyncdb(Official):
updates.
This approach also has limitations, because we don't require superuser rights (neither going to download database
separately), the database file might be outdated and must be handled manually (or kind of). This behaviour might be
separately), the database file might be outdated and must be handled manually (or kind of). This behavior might be
changed in the future.
Still we leave search function based on the official repositories RPC.

6
src/ahriman/core/auth/auth.py
View File

@@ -50,13 +50,13 @@ class Auth(LazyLogging):
@property
def auth_control(self) -> str:
"""
This workaround is required to make different behaviour for login interface.
This workaround is required to make different behavior for login interface.
In case of internal authentication it must provide an interface (modal form) to log in with button sends POST
request. But for an external providers behaviour can be different: e.g. OAuth provider requires sending GET
request. But for an external providers behavior can be different: e.g. OAuth provider requires sending GET
request to external resource
Returns:
str: login control as html code to insert
str: login control as HTML code to insert
"""
return "<button type=\"button\" class=\"btn btn-link\" data-bs-toggle=\"modal\" data-bs-target=\"#login-modal\" style=\"text-decoration: none\"><i class=\"bi bi-box-arrow-in-right\"></i> login</button>"

8
src/ahriman/core/auth/helpers.py
View File

@@ -30,7 +30,13 @@ except ImportError:
from typing import Any
__all__ = ["authorized_userid", "check_authorized", "forget", "remember"]
__all__ = [
"authorized_userid",
"check_authorized",
"forget",
"get_session",
"remember",
]
async def authorized_userid(*args: Any, **kwargs: Any) -> Any:

4
src/ahriman/core/auth/oauth.py
View File

@@ -62,10 +62,10 @@ class OAuth(Mapping):
@property
def auth_control(self) -> str:
"""
get authorization html control
get authorization HTML control
Returns:
str: login control as html code to insert
str: login control as HTML code to insert
"""
return "<a class=\"nav-link\" href=\"/api/v1/login\" title=\"login via OAuth2\"><i class=\"bi bi-box-arrow-in-right\"></i> login</a>"

2
src/ahriman/core/configuration/configuration.py
View File

@@ -72,7 +72,7 @@ class Configuration(configparser.RawConfigParser):
def __init__(self, allow_no_value: bool = False, allow_multi_key: bool = True) -> None:
"""
Args:
allow_no_value(bool, optional): copies :class:`configparser.RawConfigParser` behaviour. In case if it is set
allow_no_value(bool, optional): copies :class:`configparser.RawConfigParser` behavior. In case if it is set
to ``True``, the keys without values will be allowed (Default value = False)
allow_multi_key(bool, optional): if set to ``False``, then the default dictionary class will be used to
store keys internally. Otherwise, the special implementation will be used, which supports arrays

2
src/ahriman/core/http/sync_http_client.py
View File

@@ -171,7 +171,7 @@ class SyncHttpClient(LazyLogging):
headers(dict[str, str] | None, optional): request headers (Default value = None)
params(list[tuple[str, str]] | None, optional): request query parameters (Default value = None)
data(Any | None, optional): request raw data parameters (Default value = None)
json(dict[str, Any] | None, optional): request json parameters (Default value = None)
json(dict[str, Any] | None, optional): request JSON parameters (Default value = None)
files(dict[str, MultipartType] | None, optional): multipart upload (Default value = None)
stream(bool | None, optional): handle response as stream (Default value = None)
session(requests.Session | None, optional): session object if any (Default value = None)

2
src/ahriman/core/report/console.py
View File

@@ -27,7 +27,7 @@ from ahriman.models.result import Result
class Console(Report):
"""
html report generator
HTML report generator
Attributes:
use_utf(bool): print utf8 symbols instead of ASCII

4
src/ahriman/core/report/html.py
View File

@@ -27,10 +27,10 @@ from ahriman.models.result import Result
class HTML(Report, JinjaTemplate):
"""
html report generator
HTML report generator
Attributes:
report_path(Path): output path to html report
report_path(Path): output path to HTML report
template(Path | str): name or path to template for full package list
"""

2
src/ahriman/core/report/report.py
View File

@@ -71,7 +71,7 @@ class Report(LazyLogging):
Args:
repository_id(RepositoryId): repository unique identifier
configuration(Configuration): configuration instance
target(str): target to generate report aka section name (e.g. html)
target(str): target to generate report aka section name (e.g. HTML)
Returns:
Report: client according to current settings

2
src/ahriman/core/triggers/trigger.py
View File

@@ -34,7 +34,7 @@ class Trigger(LazyLogging):
Attributes:
CONFIGURATION_SCHEMA(ConfigurationSchema): (class attribute) configuration schema template
REQUIRES_REPOSITORY(bool): (class attribute) either trigger requires loaded repository or not
REQUIRES_REPOSITORY(bool): (class attribute) either trigger requires a repository to be loaded or not
configuration(Configuration): configuration instance
repository_id(RepositoryId): repository unique identifier

10
src/ahriman/core/utils.py
View File

@@ -231,13 +231,13 @@ def check_user(root: Path, *, unsafe: bool) -> None:
def dataclass_view(instance: Any) -> dict[str, Any]:
"""
convert dataclass instance to json object
convert dataclass instance to JSON object
Args:
instance(Any): dataclass instance
Returns:
dict[str, Any]: json representation of the dataclass with empty field removed
dict[str, Any]: JSON representation of the dataclass with empty field removed
"""
return asdict(instance, dict_factory=lambda fields: {key: value for key, value in fields if value is not None})
@@ -287,15 +287,15 @@ def filelock(path: Path) -> Iterator[FileLock]:
def filter_json(source: T, known_fields: Iterable[str] | None = None) -> T:
"""
recursively filter json object removing ``None`` values and optionally filtering by known fields
recursively filter JSON object removing ``None`` values and optionally filtering by known fields
Args:
source(T): raw json object (dict, list, or scalar)
source(T): raw JSON object (dict, list, or scalar)
known_fields(Iterable[str] | None, optional): list of fields which have to be known for the target object
(Default value = None)
Returns:
T: json without ``None`` values
T: JSON without ``None`` values
Examples:
This wrapper is mainly used for the dataclasses, thus the flow must be something like this::

4
src/ahriman/models/aur_package.py
View File

@@ -62,7 +62,7 @@ class AURPackage:
Examples:
Mainly this class must be used from class methods instead of default :func:`__init__()`::
>>> package = AURPackage.from_json(metadata) # load package from json dump
>>> package = AURPackage.from_json(metadata) # load package from JSON dump
>>> # ...or alternatively...
>>> package = AURPackage.from_repo(metadata) # load package from official repository RPC
>>> # properties of the class are built based on ones from AUR RPC, thus additional method is required
@@ -175,7 +175,7 @@ class AURPackage:
construct package descriptor from official repository RPC properties
Args:
dump(dict[str, Any]): json dump body
dump(dict[str, Any]): JSON dump body
Returns:
Self: AUR package descriptor

2
src/ahriman/models/build_status.py
View File

@@ -89,7 +89,7 @@ class BuildStatus:
def view(self) -> dict[str, Any]:
"""
generate json status view
generate JSON status view
Returns:
dict[str, Any]: json-friendly dictionary

6
src/ahriman/models/changes.py
View File

@@ -41,10 +41,10 @@ class Changes:
@classmethod
def from_json(cls, dump: dict[str, Any]) -> Self:
"""
construct changes from the json dump
construct changes from the JSON dump
Args:
dump(dict[str, Any]): json dump body
dump(dict[str, Any]): JSON dump body
Returns:
Self: changes object
@@ -55,7 +55,7 @@ class Changes:
def view(self) -> dict[str, Any]:
"""
generate json change view
generate JSON change view
Returns:
dict[str, Any]: json-friendly dictionary

4
src/ahriman/models/counters.py
View File

@@ -49,10 +49,10 @@ class Counters:
@classmethod
def from_json(cls, dump: dict[str, Any]) -> Self:
"""
construct counters from json dump
construct counters from JSON dump
Args:
dump(dict[str, Any]): json dump body
dump(dict[str, Any]): JSON dump body
Returns:
Self: status counters

6
src/ahriman/models/event.py
View File

@@ -72,10 +72,10 @@ class Event:
@classmethod
def from_json(cls, dump: dict[str, Any]) -> Self:
"""
construct event from the json dump
construct event from the JSON dump
Args:
dump(dict[str, Any]): json dump body
dump(dict[str, Any]): JSON dump body
Returns:
Self: event object
@@ -102,7 +102,7 @@ class Event:
def view(self) -> dict[str, Any]:
"""
generate json event view
generate JSON event view
Returns:
dict[str, Any]: json-friendly dictionary

6
src/ahriman/models/internal_status.py
View File

@@ -50,10 +50,10 @@ class InternalStatus:
@classmethod
def from_json(cls, dump: dict[str, Any]) -> Self:
"""
construct internal status from json dump
construct internal status from JSON dump
Args:
dump(dict[str, Any]): json dump body
dump(dict[str, Any]): JSON dump body
Returns:
Self: internal status
@@ -70,7 +70,7 @@ class InternalStatus:
def view(self) -> dict[str, Any]:
"""
generate json status view
generate JSON status view
Returns:
dict[str, Any]: json-friendly dictionary

6
src/ahriman/models/log_record.py
View File

@@ -41,11 +41,11 @@ class LogRecord:
@classmethod
def from_json(cls, package_base: str, dump: dict[str, Any]) -> Self:
"""
construct log record from the json dump
construct log record from the JSON dump
Args:
package_base(str): package base for which log record belongs
dump(dict[str, Any]): json dump body
dump(dict[str, Any]): JSON dump body
Returns:
Self: log record object
@@ -63,7 +63,7 @@ class LogRecord:
def view(self) -> dict[str, Any]:
"""
generate json log record view
generate JSON log record view
Returns:
dict[str, Any]: json-friendly dictionary

10
src/ahriman/models/package.py
View File

@@ -50,11 +50,11 @@ class Package(LazyLogging):
version(str): package full version
Examples:
Different usages of this class may generate different (incomplete) data, e.g. if instantiating class from json::
Different usages of this class may generate different (incomplete) data, e.g. if instantiating class from JSON::
>>> package = Package.from_json(dump)
it will contain every data available in the json body. Otherwise, if generate package from local archive::
it will contain every data available in the JSON body. Otherwise, if generate package from local archive::
>>> package = Package.from_archive(local_path, pacman)
@@ -273,10 +273,10 @@ class Package(LazyLogging):
@classmethod
def from_json(cls, dump: dict[str, Any]) -> Self:
"""
construct package properties from json dump
construct package properties from JSON dump
Args:
dump(dict[str, Any]): json dump body
dump(dict[str, Any]): JSON dump body
Returns:
Self: package properties
@@ -396,7 +396,7 @@ class Package(LazyLogging):
def view(self) -> dict[str, Any]:
"""
generate json package view
generate JSON package view
Returns:
dict[str, Any]: json-friendly dictionary

8
src/ahriman/models/package_description.py
View File

@@ -49,7 +49,7 @@ class PackageDescription:
Examples:
Unlike the :class:`ahriman.models.package.Package` class, this implementation only holds properties.
The recommended way to deal with it is to read data based on the source type - either json or
The recommended way to deal with it is to read data based on the source type - either JSON or
:class:`pyalpm.Package` instance::
>>> description = PackageDescription.from_json(dump)
@@ -126,10 +126,10 @@ class PackageDescription:
@classmethod
def from_json(cls, dump: dict[str, Any]) -> Self:
"""
construct package properties from json dump
construct package properties from JSON dump
Args:
dump(dict[str, Any]): json dump body
dump(dict[str, Any]): JSON dump body
Returns:
Self: package properties
@@ -169,7 +169,7 @@ class PackageDescription:
def view(self) -> dict[str, Any]:
"""
generate json package view
generate JSON package view
Returns:
dict[str, Any]: json-friendly dictionary

8
src/ahriman/models/pkgbuild_patch.py
View File

@@ -87,10 +87,10 @@ class PkgbuildPatch:
@classmethod
def from_json(cls, dump: dict[str, Any]) -> Self:
"""
construct patch descriptor from the json dump
construct patch descriptor from the JSON dump
Args:
dump(dict[str, Any]): json dump body
dump(dict[str, Any]): JSON dump body
Returns:
Self: patch object
@@ -125,7 +125,7 @@ class PkgbuildPatch:
# the source value looks like shell array, remove brackets and parse with shlex
return shlex.split(shell_array[1:-1])
case json_array if json_array.startswith("[") and json_array.endswith("]"):
# json (aka python) array, parse with json parser instead
# JSON (aka python) array, parse with JSON parser instead
parsed: list[str] = json.loads(json_array)
return parsed
case variable:
@@ -220,7 +220,7 @@ class PkgbuildPatch:
def view(self) -> dict[str, Any]:
"""
generate json patch view
generate JSON patch view
Returns:
dict[str, Any]: json-friendly dictionary

6
src/ahriman/models/remote_source.py
View File

@@ -74,10 +74,10 @@ class RemoteSource:
@classmethod
def from_json(cls, dump: dict[str, Any]) -> Self:
"""
construct remote source from the json dump (or database row)
construct remote source from the JSON dump (or database row)
Args:
dump(dict[str, Any]): json dump body
dump(dict[str, Any]): JSON dump body
Returns:
Self: remote source
@@ -102,7 +102,7 @@ class RemoteSource:
def view(self) -> dict[str, Any]:
"""
generate json package remote view
generate JSON package remote view
Returns:
dict[str, Any]: json-friendly dictionary

4
src/ahriman/models/report_settings.py
View File

@@ -28,10 +28,10 @@ class ReportSettings(StrEnum):
Attributes:
Disabled(ReportSettings): option which generates no report for testing purpose
HTML(ReportSettings): html report generation
HTML(ReportSettings): HTML report generation
Email(ReportSettings): email report generation
Console(ReportSettings): print result to console
Telegram(ReportSettings): markdown report to telegram channel
Telegram(ReportSettings): Markdown report to telegram channel
RSS(ReportSettings): RSS report generation
RemoteCall(ReportSettings): remote ahriman server call
"""

2
src/ahriman/models/repository_id.py
View File

@@ -70,7 +70,7 @@ class RepositoryId:
def view(self) -> dict[str, Any]:
"""
generate json package view
generate JSON package view
Returns:
dict[str, Any]: json-friendly dictionary

4
src/ahriman/models/repository_stats.py
View File

@@ -38,10 +38,10 @@ class RepositoryStats:
@classmethod
def from_json(cls, dump: dict[str, Any]) -> Self:
"""
construct counters from json dump
construct counters from JSON dump
Args:
dump(dict[str, Any]): json dump body
dump(dict[str, Any]): JSON dump body
Returns:
Self: status counters

2
src/ahriman/models/worker.py
View File

@@ -45,7 +45,7 @@ class Worker:
def view(self) -> dict[str, Any]:
"""
generate json patch view
generate JSON worker view
Returns:
dict[str, Any]: json-friendly dictionary

4
src/ahriman/web/middlewares/exception_handler.py
View File

@@ -42,13 +42,13 @@ __all__ = ["exception_handler"]
def _is_templated_unauthorized(request: Request) -> bool:
"""
check if the request is eligible for rendering html template
check if the request is eligible for rendering HTML template
Args:
request(Request): source request to check
Returns:
bool: ``True`` in case if response should be rendered as html and ``False`` otherwise
bool: ``True`` in case if response should be rendered as HTML and ``False`` otherwise
"""
return request.path in ("/api/v1/login", "/api/v1/logout") \
and "application/json" not in request.headers.getall("accept", [])

2
src/ahriman/web/server_info.py
View File

@@ -39,7 +39,7 @@ async def server_info(view: BaseView) -> dict[str, Any]:
view(BaseView): view of the request
Returns:
dict[str, Any]: server info as a json response
dict[str, Any]: server info as a JSON response
"""
autorefresh_intervals = [
{

2
src/ahriman/web/views/api/docs.py
View File

@@ -57,7 +57,7 @@ class DocsView(BaseView):
@aiohttp_jinja2.template("api.jinja2")
async def get(self) -> dict[str, Any]:
"""
return static docs html
return static docs HTML
Returns:
dict[str, Any]: parameters for jinja template

2
src/ahriman/web/views/api/swagger.py
View File

@@ -60,7 +60,7 @@ class SwaggerView(BaseView):
get api specification
Returns:
Response: 200 with json api specification
Response: 200 with JSON api specification
"""
spec = self.request.app["swagger_dict"]
is_body_parameter: Callable[[dict[str, str]], bool] = lambda p: p["in"] == "body" or p["in"] == "formData"

2
src/ahriman/web/views/base.py
View File

@@ -169,7 +169,7 @@ class BaseView(View, CorsViewMixin):
filter and convert data and return :class:`aiohttp.web.Response` object
Args:
data(dict[str, Any] | list[Any]): response in json format
data(dict[str, Any] | list[Any]): response in JSON format
**kwargs(Any): keyword arguments for :func:`aiohttp.web.json_response` function
Returns: