mirror of
https://github.com/arcan1s/ahriman.git
synced 2025-04-24 07:17:17 +00:00
Some minor documentation related fixes
* Improve some wording (again) * Change default type for refresh option to False (does not affect behavior) * Update docstrings to reflect last changes * Configuration.__convert_path has been replaced by shlex * aiosecurity functions support kwargs now
This commit is contained in:
parent
90be3276dd
commit
5a09d46f9a
@ -11,8 +11,8 @@ Depending on the goal the package can be used in different ways. Nevertheless, i
|
||||
from ahriman.core.database import SQLite
|
||||
|
||||
architecture = "x86_64"
|
||||
configuration = Configuration.from_path(Path("/etc/ahriman.ini"), architecture, quiet=False)
|
||||
sqlite = SQLite.load(configuration)
|
||||
configuration = Configuration.from_path(Path("/etc/ahriman.ini"), architecture)
|
||||
database = SQLite.load(configuration)
|
||||
|
||||
At this point there are ``configuration`` and ``database`` instances which can be used later at any time anywhere, e.g.
|
||||
|
||||
@ -27,7 +27,7 @@ Almost all actions are wrapped by ``ahriman.core.repository.Repository`` class
|
||||
|
||||
from ahriman.core.repository import Repository
|
||||
|
||||
repository = Repository(architecture, configuration, database, no_report=False, unsafe=False)
|
||||
repository = Repository(architecture, configuration, database, report=True, unsafe=False)
|
||||
|
||||
And the ``repository`` instance can be used to perform repository maintenance
|
||||
|
||||
@ -37,6 +37,6 @@ And the ``repository`` instance can be used to perform repository maintenance
|
||||
built_packages = repository.packages_built()
|
||||
update_result = repository.process_update(built_packages)
|
||||
|
||||
repository.process_triggers(update_result)
|
||||
repository.triggers.on_result(update_result, repository.packages())
|
||||
|
||||
For the more info please refer to the classes documentation.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.TH AHRIMAN "1" "2022\-12\-02" "ahriman" "Generated Python Manual"
|
||||
.TH AHRIMAN "1" "2022\-12\-04" "ahriman" "Generated Python Manual"
|
||||
.SH NAME
|
||||
ahriman
|
||||
.SH SYNOPSIS
|
||||
@ -10,7 +10,7 @@ ArcH linux ReposItory MANager
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
\fB\-a\fR \fI\,ARCHITECTURE\/\fR, \fB\-\-architecture\fR \fI\,ARCHITECTURE\/\fR
|
||||
target architectures (can be used multiple times)
|
||||
target architectures. For several subcommands it can be used multiple times
|
||||
|
||||
.TP
|
||||
\fB\-c\fR \fI\,CONFIGURATION\/\fR, \fB\-\-configuration\fR \fI\,CONFIGURATION\/\fR
|
||||
|
||||
@ -28,7 +28,7 @@ This package contains application (aka executable) related classes and everythin
|
||||
``ahriman.core`` package
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This package contains everything which is required for any time of application run and separated into several packages:
|
||||
This package contains everything required for the most of application actions and it is separated into several packages:
|
||||
|
||||
* ``ahriman.core.alpm`` package controls pacman related functions. It provides wrappers for ``pyalpm`` library and safe calls for repository tools (``repo-add`` and ``repo-remove``). Also this package contains ``ahriman.core.alpm.remote`` package which provides wrapper for remote sources (e.g. AUR RPC and official repositories RPC).
|
||||
* ``ahriman.core.auth`` package provides classes for authorization methods used by web mostly. Base class is ``ahriman.core.auth.Auth`` which must be called by ``load`` method.
|
||||
@ -54,7 +54,7 @@ This package also provides some generic functions and classes which may be used
|
||||
``ahriman.models`` package
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
It provides models for any other part of application. Unlike ``ahriman.core`` package classes from here provides only conversion methods (e.g. create class from another or convert to). Mostly case classes and enumerations.
|
||||
It provides models for any other part of application. Unlike ``ahriman.core`` package classes from here provide only conversion methods (e.g. create class from another or convert to). Mostly case classes and enumerations.
|
||||
|
||||
``ahriman.web`` package
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -77,7 +77,7 @@ Application run
|
||||
* Return result (success or failure) of each subprocess and exit from application.
|
||||
* Some handlers may override their status and throw ``ExitCode`` exception. This exception is just silently suppressed and changes application exit code to ``1``.
|
||||
|
||||
In most cases handlers spawn god class ``ahriman.application.application.Application`` class and call required methods.
|
||||
In the most cases handlers spawn god class ``ahriman.application.application.Application`` class and call required methods.
|
||||
|
||||
Application is designed to run from ``systemd`` services and provides parametrized by architecture timer and service file for that.
|
||||
|
||||
@ -206,7 +206,7 @@ In order to configure users there are special commands.
|
||||
Triggers
|
||||
^^^^^^^^
|
||||
|
||||
Triggers are extensions which can be used in order to perform any actions on application start, after the update process and, finally, before the application exit. The package provides two default extensions - one is report generation and another one is remote upload feature.
|
||||
Triggers are extensions which can be used in order to perform any actions on application start, after the update process and, finally, before the application exit.
|
||||
|
||||
The main idea is to load classes by their full path (e.g. ``ahriman.core.upload.UploadTrigger``) by using ``importlib``: get the last part of the import and treat it as class name, join remain part by ``.`` and interpret as module path, import module and extract attribute from it.
|
||||
|
||||
|
||||
@ -44,7 +44,7 @@ Base authorization settings. ``OAuth`` provider requires ``aioauth-client`` libr
|
||||
* ``max_age`` - parameter which controls both cookie expiration and token expiration inside the service, integer, optional, default is 7 days.
|
||||
* ``oauth_provider`` - OAuth2 provider class name as is in ``aioauth-client`` (e.g. ``GoogleClient``, ``GithubClient`` etc), string, required in case if ``oauth`` is used.
|
||||
* ``oauth_scopes`` - scopes list for OAuth2 provider, which will allow retrieving user email (which is used for checking user permissions), e.g. ``https://www.googleapis.com/auth/userinfo.email`` for ``GoogleClient`` or ``user:email`` for ``GithubClient``, space separated list of strings, required in case if ``oauth`` is used.
|
||||
* ``salt`` - password hash salt, string, required in case if authorization enabled (automatically generated by ``create-user`` subcommand).
|
||||
* ``salt`` - password hash salt, string, required in case if authorization enabled (automatically generated by ``user-add`` subcommand).
|
||||
|
||||
Authorized users are stored inside internal database, if any of external provides are used the password field for non-service users must be empty.
|
||||
|
||||
@ -115,7 +115,7 @@ Report generation settings.
|
||||
|
||||
* ``target`` - list of reports to be generated, space separated list of strings, required. It must point to valid section (or to section with architecture), e.g. ``somerandomname`` must point to existing section, ``email`` must point to either ``email`` or ``email:x86_64`` (the one with architecture has higher priority).
|
||||
|
||||
Type will be read from several ways:
|
||||
Type will be read from several sources:
|
||||
|
||||
* In case if ``type`` option set inside the section, it will be used.
|
||||
* Otherwise, it will look for type from section name removing architecture name.
|
||||
@ -180,7 +180,7 @@ Remote synchronization settings.
|
||||
|
||||
* ``target`` - list of synchronizations to be used, space separated list of strings, required. It must point to valid section (or to section with architecture), e.g. ``somerandomname`` must point to existing section, ``github`` must point to one of ``github`` of ``github:x86_64`` (with architecture it has higher priority).
|
||||
|
||||
Type will be read from several ways:
|
||||
Type will be read from several sources:
|
||||
|
||||
* In case if ``type`` option set inside the section, it will be used.
|
||||
* Otherwise, it will look for type from section name removing architecture name.
|
||||
|
||||
45
docs/faq.rst
45
docs/faq.rst
@ -169,13 +169,30 @@ Unlike ``RemotePullTrigger`` trigger, the ``RemotePushTrigger`` more likely will
|
||||
How to change PKGBUILDs before build
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Well it is supported also. The recommended way is to patch specific function, e.g. by running ``sudo -u ahriman ahriman patch-add ahriman version``. This command will prompt for new value of the PKGBUILD variable ``version``. You can also write it to file and read from it ``sudo -u ahriman ahriman patch-add ahriman version version.patch``.
|
||||
Well it is supported also. The recommended way is to patch specific function, e.g. by running
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo -u ahriman ahriman patch-add ahriman version
|
||||
|
||||
This command will prompt for new value of the PKGBUILD variable ``version``. You can also write it to file and read from it:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo -u ahriman ahriman patch-add ahriman version version.patch
|
||||
|
||||
Alternatively you can create full-diff patches, which are calculated by using ``git diff`` from current PKGBUILD master branch:
|
||||
|
||||
#. Clone sources from AUR.
|
||||
#. Make changes you would like to (e.g. edit ``PKGBUILD``, add external patches).
|
||||
#. Run ``sudo -u ahriman ahriman patch-set-add /path/to/local/directory/with/PKGBUILD``.
|
||||
#.
|
||||
Clone sources from AUR.
|
||||
#.
|
||||
Make changes you would like to (e.g. edit ``PKGBUILD``, add external patches).
|
||||
#.
|
||||
Run command
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo -u ahriman ahriman patch-set-add /path/to/local/directory/with/PKGBUILD
|
||||
|
||||
The last command will calculate diff from current tree to the ``HEAD`` and will store it locally. Patches will be applied on any package actions (e.g. it can be used for dependency management).
|
||||
|
||||
@ -691,7 +708,7 @@ How to enable basic authorization
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo -u ahriman ahriman user-add -r write api
|
||||
sudo -u ahriman ahriman user-add -r full api
|
||||
|
||||
This command will ask for the password, just type it in stdin; *do not* leave the field blank, user will not be able to authorize, and finally configure the application:
|
||||
|
||||
@ -702,7 +719,11 @@ How to enable basic authorization
|
||||
password = pa55w0rd
|
||||
|
||||
#.
|
||||
Create end-user ``sudo -u ahriman ahriman user-add -r write my-first-user`` with password.
|
||||
Create end-user with password:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo -u ahriman ahriman user-add -r full my-first-user
|
||||
|
||||
#.
|
||||
Restart web service ``systemctl restart ahriman-web@x86_64``.
|
||||
@ -739,10 +760,16 @@ How to enable OAuth authorization
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo -u ahriman ahriman user-add --as-service -r write api
|
||||
sudo -u ahriman ahriman user-add --as-service -r full api
|
||||
|
||||
#.
|
||||
Create end-user ``sudo -u ahriman ahriman user-add -r write my-first-user``. When it will ask for the password leave it blank.
|
||||
Create end-user:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo -u ahriman ahriman user-add -r full my-first-user
|
||||
|
||||
When it will ask for the password leave it blank.
|
||||
|
||||
#.
|
||||
Restart web service ``systemctl restart ahriman-web@x86_64``.
|
||||
@ -765,7 +792,7 @@ The service provides several commands aim to do easy repository backup and resto
|
||||
Copy created archive from source server ``server1.example.com`` to target ``server2.example.com``.
|
||||
|
||||
#.
|
||||
Install ahriman as usual on the target server ``server2.example.com`` if you didn't yet.
|
||||
Install package as usual on the target server ``server2.example.com`` if you didn't yet.
|
||||
|
||||
#.
|
||||
Extract archive e.g. by using subcommand:
|
||||
|
||||
@ -68,8 +68,8 @@ def _parser() -> argparse.ArgumentParser:
|
||||
parser = argparse.ArgumentParser(prog="ahriman", description="ArcH linux ReposItory MANager",
|
||||
epilog="Argument list can also be read from file by using @ prefix.",
|
||||
fromfile_prefix_chars="@", formatter_class=_formatter)
|
||||
parser.add_argument("-a", "--architecture", help="target architectures (can be used multiple times)",
|
||||
action="append")
|
||||
parser.add_argument("-a", "--architecture", help="target architectures. For several subcommands it can be used "
|
||||
"multiple times", action="append")
|
||||
parser.add_argument("-c", "--configuration", help="configuration path", type=Path, default=Path("/etc/ahriman.ini"))
|
||||
parser.add_argument("--force", help="force run, remove file lock", action="store_true")
|
||||
parser.add_argument("-l", "--lock", help="lock file", type=Path,
|
||||
@ -169,7 +169,7 @@ def _set_daemon_parser(root: SubParserAction) -> argparse.ArgumentParser:
|
||||
action=argparse.BooleanOptionalAction, default=True)
|
||||
parser.add_argument("-y", "--refresh", help="download fresh package databases from the mirror before actions, "
|
||||
"-yy to force refresh even if up to date",
|
||||
action="count", default=0)
|
||||
action="count", default=False)
|
||||
parser.set_defaults(handler=handlers.Daemon, dry_run=False, exit_code=False, package=[])
|
||||
return parser
|
||||
|
||||
@ -263,7 +263,7 @@ def _set_package_add_parser(root: SubParserAction) -> argparse.ArgumentParser:
|
||||
parser.add_argument("-n", "--now", help="run update function after", action="store_true")
|
||||
parser.add_argument("-y", "--refresh", help="download fresh package databases from the mirror before actions, "
|
||||
"-yy to force refresh even if up to date",
|
||||
action="count", default=0)
|
||||
action="count", default=False)
|
||||
parser.add_argument("-s", "--source", help="explicitly specify the package source for this command",
|
||||
type=PackageSource, choices=enum_values(PackageSource), default=PackageSource.Auto)
|
||||
parser.add_argument("--without-dependencies", help="do not add dependencies", action="store_true")
|
||||
@ -483,7 +483,7 @@ def _set_repo_check_parser(root: SubParserAction) -> argparse.ArgumentParser:
|
||||
action=argparse.BooleanOptionalAction, default=True)
|
||||
parser.add_argument("-y", "--refresh", help="download fresh package databases from the mirror before actions, "
|
||||
"-yy to force refresh even if up to date",
|
||||
action="count", default=0)
|
||||
action="count", default=False)
|
||||
parser.set_defaults(handler=handlers.Update, dry_run=True, aur=True, local=True, manual=False)
|
||||
return parser
|
||||
|
||||
@ -748,7 +748,7 @@ def _set_repo_update_parser(root: SubParserAction) -> argparse.ArgumentParser:
|
||||
action=argparse.BooleanOptionalAction, default=True)
|
||||
parser.add_argument("-y", "--refresh", help="download fresh package databases from the mirror before actions, "
|
||||
"-yy to force refresh even if up to date",
|
||||
action="count", default=0)
|
||||
action="count", default=False)
|
||||
parser.set_defaults(handler=handlers.Update)
|
||||
return parser
|
||||
|
||||
|
||||
@ -29,61 +29,65 @@ except ImportError:
|
||||
__all__ = ["authorized_userid", "check_authorized", "forget", "remember"]
|
||||
|
||||
|
||||
async def authorized_userid(*args: Any) -> Any:
|
||||
async def authorized_userid(*args: Any, **kwargs: Any) -> Any:
|
||||
"""
|
||||
handle aiohttp security methods
|
||||
|
||||
Args:
|
||||
*args(Any): argument list as provided by authorized_userid function
|
||||
**kwargs(Any): named argument list as provided by authorized_userid function
|
||||
|
||||
Returns:
|
||||
Any: None in case if no aiohttp_security module found and function call otherwise
|
||||
"""
|
||||
if _has_aiohttp_security:
|
||||
return await aiohttp_security.authorized_userid(*args) # pylint: disable=no-value-for-parameter
|
||||
return await aiohttp_security.authorized_userid(*args, **kwargs) # pylint: disable=no-value-for-parameter
|
||||
return None
|
||||
|
||||
|
||||
async def check_authorized(*args: Any) -> Any:
|
||||
async def check_authorized(*args: Any, **kwargs: Any) -> Any:
|
||||
"""
|
||||
handle aiohttp security methods
|
||||
|
||||
Args:
|
||||
*args(Any): argument list as provided by check_authorized function
|
||||
**kwargs(Any): named argument list as provided by authorized_userid function
|
||||
|
||||
Returns:
|
||||
Any: None in case if no aiohttp_security module found and function call otherwise
|
||||
"""
|
||||
if _has_aiohttp_security:
|
||||
return await aiohttp_security.check_authorized(*args) # pylint: disable=no-value-for-parameter
|
||||
return await aiohttp_security.check_authorized(*args, **kwargs) # pylint: disable=no-value-for-parameter
|
||||
return None
|
||||
|
||||
|
||||
async def forget(*args: Any) -> Any:
|
||||
async def forget(*args: Any, **kwargs: Any) -> Any:
|
||||
"""
|
||||
handle aiohttp security methods
|
||||
|
||||
Args:
|
||||
*args(Any): argument list as provided by forget function
|
||||
**kwargs(Any): named argument list as provided by authorized_userid function
|
||||
|
||||
Returns:
|
||||
Any: None in case if no aiohttp_security module found and function call otherwise
|
||||
"""
|
||||
if _has_aiohttp_security:
|
||||
return await aiohttp_security.forget(*args) # pylint: disable=no-value-for-parameter
|
||||
return await aiohttp_security.forget(*args, **kwargs) # pylint: disable=no-value-for-parameter
|
||||
return None
|
||||
|
||||
|
||||
async def remember(*args: Any) -> Any:
|
||||
async def remember(*args: Any, **kwargs: Any) -> Any:
|
||||
"""
|
||||
handle disabled auth
|
||||
|
||||
Args:
|
||||
*args(Any): argument list as provided by remember function
|
||||
**kwargs(Any): named argument list as provided by authorized_userid function
|
||||
|
||||
Returns:
|
||||
Any: None in case if no aiohttp_security module found and function call otherwise
|
||||
"""
|
||||
if _has_aiohttp_security:
|
||||
return await aiohttp_security.remember(*args) # pylint: disable=no-value-for-parameter
|
||||
return await aiohttp_security.remember(*args, **kwargs) # pylint: disable=no-value-for-parameter
|
||||
return None
|
||||
|
||||
@ -20,10 +20,11 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import configparser
|
||||
import shlex
|
||||
import sys
|
||||
|
||||
from pathlib import Path
|
||||
from typing import Any, Dict, Generator, List, Optional, Tuple, Type
|
||||
from typing import Any, Dict, List, Optional, Tuple, Type
|
||||
|
||||
from ahriman.core.exceptions import InitializeError
|
||||
from ahriman.models.repository_paths import RepositoryPaths
|
||||
@ -72,7 +73,7 @@ class Configuration(configparser.RawConfigParser):
|
||||
to ``True``, the keys without values will be allowed (Default value = False)
|
||||
"""
|
||||
configparser.RawConfigParser.__init__(self, allow_no_value=allow_no_value, converters={
|
||||
"list": self.__convert_list,
|
||||
"list": shlex.split,
|
||||
"path": self.__convert_path,
|
||||
})
|
||||
self.architecture: Optional[str] = None
|
||||
@ -126,39 +127,6 @@ class Configuration(configparser.RawConfigParser):
|
||||
configuration.merge_sections(architecture)
|
||||
return configuration
|
||||
|
||||
@staticmethod
|
||||
def __convert_list(value: str) -> List[str]:
|
||||
"""
|
||||
convert string value to list of strings
|
||||
|
||||
Args:
|
||||
value(str): string configuration value
|
||||
|
||||
Returns:
|
||||
List[str]: list of string from the parsed string
|
||||
|
||||
Raises:
|
||||
ValueError: in case if option value contains unclosed quotes
|
||||
"""
|
||||
def generator() -> Generator[str, None, None]:
|
||||
quote_mark = None
|
||||
word = ""
|
||||
for char in value:
|
||||
if char in ("'", "\"") and quote_mark is None: # quoted part started, store quote and do nothing
|
||||
quote_mark = char
|
||||
elif char == quote_mark: # quoted part ended, reset quotation
|
||||
quote_mark = None
|
||||
elif char == " " and quote_mark is None: # found space outside the quotation, yield the word
|
||||
yield word
|
||||
word = ""
|
||||
else: # append character to the buffer
|
||||
word += char
|
||||
if quote_mark: # there is unmatched quote
|
||||
raise ValueError(f"unmatched quote in {value}")
|
||||
yield word # sequence done, return whatever we found
|
||||
|
||||
return [word for word in generator() if word]
|
||||
|
||||
@staticmethod
|
||||
def section_name(section: str, suffix: str) -> str:
|
||||
"""
|
||||
|
||||
@ -46,8 +46,7 @@ class Repository(Executor, UpdateHandler):
|
||||
>>> built_packages = repository.packages_built()
|
||||
>>> update_result = repository.process_update(built_packages)
|
||||
>>>
|
||||
>>> repository.process_report(["email"], update_result)
|
||||
>>> repository.process_sync(["s3"], update_result.success)
|
||||
>>> repository.triggers.on_result(update_result, repository.packages())
|
||||
"""
|
||||
|
||||
def load_archives(self, packages: Iterable[Path]) -> List[Package]:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user