arcanis/ahriman
1
0
Fork 0
mirror of https://github.com/arcan1s/ahriman.git synced 2025-04-24 07:17:17 +00:00
Code Issues Projects Releases Wiki Activity

docs: improve application help messages

Browse Source
This commit is contained in:
Evgenii Alekseev 2024-09-24 17:58:08 +03:00
parent b412966f86
commit 16ab96ee6a
40 changed files with 303 additions and 188 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Dockerfile
View File

@ -12,7 +12,7 @@ ENV AHRIMAN_PACMAN_MIRROR=""
ENV AHRIMAN_PORT=""
ENV AHRIMAN_POSTSETUP_COMMAND=""
ENV AHRIMAN_PRESETUP_COMMAND=""
ENV AHRIMAN_REPOSITORY="aur-clone"
ENV AHRIMAN_REPOSITORY="aur"
ENV AHRIMAN_REPOSITORY_SERVER=""
ENV AHRIMAN_REPOSITORY_ROOT="/var/lib/ahriman/ahriman"
ENV AHRIMAN_UNIX_SOCKET=""

2
docs/advanced-usage.rst
View File

@ -11,7 +11,7 @@ Depending on the goal the package can be used in different ways. Nevertheless, i
from ahriman.core.database import SQLite
from ahriman.models.repository_id import RepositoryId
repository_id = RepositoryId("x86_64", "aur-clone")
repository_id = RepositoryId("x86_64", "aur")
configuration = Configuration.from_path(Path("/etc/ahriman.ini"), repository_id)
database = SQLite.load(configuration)

8
docs/ahriman.application.rst
View File

@ -21,6 +21,14 @@ ahriman.application.ahriman module
:no-undoc-members:
:show-inheritance:
ahriman.application.help\_formatter module
------------------------------------------
.. automodule:: ahriman.application.help_formatter
:members:
:no-undoc-members:
:show-inheritance:
ahriman.application.lock module
-------------------------------

18
docs/architecture.rst
View File

@ -118,12 +118,12 @@ Having default root as ``/var/lib/ahriman`` (differs from container though), the
├── ahriman.db
├── cache
├── chroot
│ └── aur-clone
│ └── aur
├── packages
│ └── aur-clone
│ └── aur
│ └── x86_64
├── pacman
│ └── aur-clone
│ └── aur
│ └── x86_64
│ ├── local
│ │ └── ALPM_DB_VERSION
@ -133,12 +133,12 @@ Having default root as ``/var/lib/ahriman`` (differs from container though), the
│ └── multilib.db
│
└── repository
└── aur-clone
└── aur
└── x86_64
├── aur-clone.db -> aur-clone.db.tar.gz
├── aur-clone.db.tar.gz
├── aur-clone.files -> aur-clone.files.tar.gz
└── aur-clone.files.tar.gz
├── aur.db -> aur.db.tar.gz
├── aur.db.tar.gz
├── aur.files -> aur.files.tar.gz
└── aur.files.tar.gz
There are multiple subdirectories, some of them are commons for any repository, but some of them are not.
@ -371,7 +371,7 @@ There are several supported synchronization providers, currently they are ``rsyn
``rsync`` provider does not have any specific logic except for running external rsync application with configured arguments. The service does not handle SSH configuration, thus it has to be configured before running application manually.
``s3`` provider uses ``boto3`` package and implements sync feature. The files are stored in architecture specific directory (e.g. if bucket is ``repository``, packages will be stored in ``repository/aur-clone/x86_64`` for the ``aur-clone`` repository and ``x86_64`` architecture), bucket must be created before any action and API key must have permissions to write to the bucket. No external configuration required. In order to upload only changed files the service compares calculated hashes with the Amazon ETags, the implementation used is described `here <https://teppen.io/2018/10/23/aws_s3_verify_etags/>`__.
``s3`` provider uses ``boto3`` package and implements sync feature. The files are stored in architecture specific directory (e.g. if bucket is ``repository``, packages will be stored in ``repository/aur/x86_64`` for the ``aur`` repository and ``x86_64`` architecture), bucket must be created before any action and API key must have permissions to write to the bucket. No external configuration required. In order to upload only changed files the service compares calculated hashes with the Amazon ETags, the implementation used is described `here <https://teppen.io/2018/10/23/aws_s3_verify_etags/>`__.
``github`` provider authenticates through basic auth, API key with repository write permissions is required. There will be created a release with the name of the architecture in case if it does not exist; files will be uploaded to the release assets. It also stores array of files and their MD5 checksums in release body in order to upload only changed ones. According to the GitHub API in case if there is already uploaded asset with the same name (e.g. database files), asset will be removed first.

4
docs/configuration.rst
View File

@ -3,8 +3,8 @@ Configuration
Some groups can be specified for each architecture and/or repository separately. E.g. if there are ``build`` and ``build:x86_64`` groups it will use an option from ``build:x86_64`` for the ``x86_64`` architecture and ``build`` for any other (architecture specific group has higher priority). In case if both groups are presented, architecture specific options will be merged into global ones overriding them. The order which will be used for option resolution is the following:
#. Repository and architecture specific, e.g. ``build:aur-clone:x86_64``.
#. Repository specific, e.g. ``build:aur-clone``.
#. Repository and architecture specific, e.g. ``build:aur:x86_64``.
#. Repository specific, e.g. ``build:aur``.
#. Architecture specific, e.g. ``build:x86_64``.
#. Default section, e.g. ``build``.

6
docs/faq/docker.rst
View File

@ -46,7 +46,7 @@ The following environment variables are supported:
* ``AHRIMAN_PORT`` - HTTP server port if any, default is empty.
* ``AHRIMAN_POSTSETUP_COMMAND`` - if set, the command which will be called (as root) after the setup command, but before any other actions.
* ``AHRIMAN_PRESETUP_COMMAND`` - if set, the command which will be called (as root) right before the setup command.
* ``AHRIMAN_REPOSITORY`` - repository name, default is ``aur-clone``.
* ``AHRIMAN_REPOSITORY`` - repository name, default is ``aur``.
* ``AHRIMAN_REPOSITORY_SERVER`` - optional override for the repository URL. Useful if you would like to download packages from remote instead of local filesystem.
* ``AHRIMAN_REPOSITORY_ROOT`` - repository root. Because of filesystem rights it is required to override default repository root. By default, it uses ``ahriman`` directory inside ahriman's home, which can be passed as mount volume.
* ``AHRIMAN_UNIX_SOCKET`` - full path to unix socket which is used by web server, default is empty. Note that more likely you would like to put it inside ``AHRIMAN_REPOSITORY_ROOT`` directory (e.g. ``/var/lib/ahriman/ahriman/ahriman-web.sock``) or to ``/run/ahriman``.
@ -106,9 +106,9 @@ In order to create configuration for additional repositories, the ``AHRIMAN_POST
.. code-block:: shell
docker run --privileged -p 8080:8080 -e AHRIMAN_PORT=8080 -e AHRIMAN_UNIX_SOCKET=/var/lib/ahriman/ahriman/ahriman-web.sock -e AHRIMAN_POSTSETUP_COMMAND="ahriman --architecture x86_64 --repository aur-clone-v2 service-setup --build-as-user ahriman --packager 'ahriman bot <ahriman@example.com>'" -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
docker run --privileged -p 8080:8080 -e AHRIMAN_PORT=8080 -e AHRIMAN_UNIX_SOCKET=/var/lib/ahriman/ahriman/ahriman-web.sock -e AHRIMAN_POSTSETUP_COMMAND="ahriman --architecture x86_64 --repository aur-v2 service-setup --build-as-user ahriman --packager 'ahriman bot <ahriman@example.com>'" -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
The command above will also create configuration for the repository named ``aur-clone-v2``.
The command above will also create configuration for the repository named ``aur-v2``.
Note, however, that the command above is only required in case if the service is going to be used to run subprocesses. Otherwise, everything else (web interface, status, etc) will be handled as usual.

8
docs/faq/general.rst
View File

@ -14,8 +14,8 @@ TL;DR
.. code-block:: shell
yay -S ahriman
ahriman -a x86_64 -r aur-clone service-setup --packager "ahriman bot <ahriman@example.com>"
systemctl enable --now ahriman@x86_64-aur-clone.timer
ahriman -a x86_64 -r aur service-setup --packager "ahriman bot <ahriman@example.com>"
systemctl enable --now ahriman@x86_64-aur.timer
Long answer
"""""""""""
@ -29,7 +29,7 @@ The alternative way (though not recommended) is to run service instead of timer:
.. code-block:: shell
systemctl enable --now ahriman-daemon@x86_64-aur-clone
systemctl enable --now ahriman-daemon@x86_64-aur
How to validate settings
^^^^^^^^^^^^^^^^^^^^^^^^
@ -77,7 +77,7 @@ states that default build command is ``extra-x86_64-build``. But if there is sec
[build:i686]
build_command = extra-i686-build
the ``extra-i686-build`` command will be used for ``i686`` architecture. You can also override settings for different repositories and architectures; in this case section names will be ``build:aur-clone`` (repository name only) and ``build:aur-clone:i686`` (both repository name and architecture).
the ``extra-i686-build`` command will be used for ``i686`` architecture. You can also override settings for different repositories and architectures; in this case section names will be ``build:aur`` (repository name only) and ``build:aur:i686`` (both repository name and architecture).
How to generate build reports
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

8
docs/faq/maintenance-packages.rst
View File

@ -30,9 +30,9 @@ The application provides special plugin which generates keyring package. This pl
.. code-block:: shell
sudo -u ahriman ahriman package-add aur-clone-keyring --source local --now
sudo -u ahriman ahriman package-add aur-keyring --source local --now
where ``aur-clone`` is your repository name.
where ``aur`` is your repository name.
This plugin might have some issues, in case of any of them, kindly create `new issue <https://github.com/arcan1s/ahriman/issues/new/choose>`__.
@ -68,6 +68,6 @@ The application provides special plugin which generates mirrorlist package also.
.. code-block:: shell
sudo -u ahriman ahriman package-add aur-clone-mirrorlist --source local --now
sudo -u ahriman ahriman package-add aur-mirrorlist --source local --now
where ``aur-clone`` is your repository name.
where ``aur`` is your repository name.

8
docs/faq/reporting.rst
View File

@ -21,7 +21,7 @@ How to report by email
[email]
host = smtp.example.com
link_path = http://example.com/aur-clone/x86_64
link_path = http://example.com/aur/x86_64
password = ...
port = 465
receivers = me@example.com
@ -47,8 +47,8 @@ How to generate index page
target = html
[html]
path = ${repository:root}/repository/aur-clone/x86_64/index.html
link_path = http://example.com/aur-clone/x86_64
path = ${repository:root}/repository/aur/x86_64/index.html
link_path = http://example.com/aur/x86_64
Having this configuration, the generated ``index.html`` will be also automatically synced to remote services (e.g. S3).
@ -106,7 +106,7 @@ How to post build report to telegram
[telegram]
api_key = aaAAbbBBccCC
chat_id = @ahriman
link_path = http://example.com/aur-clone/x86_64
link_path = http://example.com/aur/x86_64
``${api_key}`` is the one sent by `@BotFather <https://t.me/botfather>`__, ``${chat_id}`` is the value retrieved from previous step.

2
docs/faq/synchronization.rst
View File

@ -29,7 +29,7 @@ There are several choices:
[rsync]
remote = 192.168.0.1:/srv/repo
After that just add ``/srv/repo`` to the ``pacman.conf`` as usual. You can also upload to S3 (``Server = https://s3.eu-central-1.amazonaws.com/repository/aur-clone/x86_64``) or to GitHub (``Server = https://github.com/ahriman/repository/releases/download/aur-clone-x86_64``).
After that just add ``/srv/repo`` to the ``pacman.conf`` as usual. You can also upload to S3 (``Server = https://s3.eu-central-1.amazonaws.com/repository/aur/x86_64``) or to GitHub (``Server = https://github.com/ahriman/repository/releases/download/aur-x86_64``).
How to sync to S3
^^^^^^^^^^^^^^^^^

16
docs/migration.rst
View File

@ -23,9 +23,9 @@ To 2.12.0
This release includes paths migration. Unlike usual case, no automatic migration is performed because it might break user configuration. The following noticeable changes have been made:
* Path to pre-built packages now includes repository name, i.e. it has been changed from ``/var/lib/ahriman/packages/x86_64`` to ``/var/lib/ahriman/packages/aur-clone/x86_64``.
* Path to pacman databases now includes repository name too, it has been changed from ``/var/lib/ahriman/pacman/x86_64`` to ``/var/lib/ahriman/pacman/aur-clone/x86_64``.
* Path to repository itself also includes repository name, from ``/var/lib/ahriman/repository/x86_64`` to ``/var/lib/ahriman/repository/aur-clone/x86_64``.
* Path to pre-built packages now includes repository name, i.e. it has been changed from ``/var/lib/ahriman/packages/x86_64`` to ``/var/lib/ahriman/packages/aur/x86_64``.
* Path to pacman databases now includes repository name too, it has been changed from ``/var/lib/ahriman/pacman/x86_64`` to ``/var/lib/ahriman/pacman/aur/x86_64``.
* Path to repository itself also includes repository name, from ``/var/lib/ahriman/repository/x86_64`` to ``/var/lib/ahriman/repository/aur/x86_64``.
In order to migrate to the new filesystem tree the following actions are required:
@ -41,16 +41,16 @@ In order to migrate to the new filesystem tree the following actions are require
Create directory tree. It can be done by running ``ahriman service-tree-migrate`` subcommand. It performs copying between the old repository tree and the new one. Alternatively directories can be copied by hands.
#.
Edit configuration in case if anything is pointing to the old path, e.g. HTML report generation, in the way in which it will point to the directory inside repository specific one, e.g. ``/var/lib/ahriman/repository/x86_64`` to ``/var/lib/ahriman/repository/aur-clone/x86_64``.
Edit configuration in case if anything is pointing to the old path, e.g. HTML report generation, in the way in which it will point to the directory inside repository specific one, e.g. ``/var/lib/ahriman/repository/x86_64`` to ``/var/lib/ahriman/repository/aur/x86_64``.
#.
Run setup command (i.e. ``ahriman service-setup``) again with the same arguments as used before. This step can be done manually by editing devtools pacman configuration (``/usr/share/devtools/pacman.conf.d/ahriman-x86_64.conf`` by default) replacing ``Server`` with path to the repository, e.g.:
.. code-block:: ini
[aur-clone]
[aur]
SigLevel = Optional TrustAll
Server = file:///var/lib/ahriman/repository/aur-clone/x86_64
Server = file:///var/lib/ahriman/repository/aur/x86_64
In case of manual interventions make sure to remove architecture reference from ``web`` sections (if any) to avoid ambiguity.
@ -58,9 +58,9 @@ In order to migrate to the new filesystem tree the following actions are require
Make sure to update remote synchronization services if any. Almost all of them rely on current repository tree by default, so it is required to setup either redirects or configure to synchronize to the old locations (e.g. ``object_path`` option for S3 synchronization).
#.
Enable and start services again. Unit template parameter should include both repository architecture and name, dash separated, e.g. ``x86_64-aur-clone``, where ``x86_64`` is the repository architecture and ``aur-clone`` is the repository name:
Enable and start services again. Unit template parameter should include both repository architecture and name, dash separated, e.g. ``x86_64-aur``, where ``x86_64`` is the repository architecture and ``aur`` is the repository name:
.. code-block:: shell
sudo systemctl enable --now ahriman@x86_64-aur-clone.timer
sudo systemctl enable --now ahriman@x86_64-aur.timer
sudo systemctl enable --now ahriman-web

24
docs/setup.rst
View File

@ -10,7 +10,7 @@ Initial setup
.. code-block:: shell
sudo ahriman -a x86_64 -r aur-clone service-setup ...
sudo ahriman -a x86_64 -r aur service-setup ...
``service-setup`` literally does the following steps:
@ -19,7 +19,7 @@ Initial setup
.. code-block:: shell
echo 'PACKAGER="John Doe <john@doe.com>"' | sudo -u ahriman tee -a /var/lib/ahriman/.makepkg.conf
echo 'PACKAGER="ahriman bot <ahriman@example.com>"' | sudo -u ahriman tee -a /var/lib/ahriman/.makepkg.conf
#.
Configure build tools (it is required for correct dependency management system):
@ -29,26 +29,26 @@ Initial setup
.. code-block:: shell
ln -s /usr/bin/archbuild /usr/local/bin/aur-clone-x86_64-build
ln -s /usr/bin/archbuild /usr/local/bin/aur-x86_64-build
#.
Create configuration file (same as previous ``{name}.conf``):
.. code-block:: shell
cp /usr/share/devtools/pacman.conf.d/{extra,aur-clone}.conf
cp /usr/share/devtools/pacman.conf.d/{extra,aur}.conf
#.
Change configuration file, add your own repository, add multilib repository etc:
.. code-block:: shell
echo '[multilib]' | tee -a /usr/share/devtools/pacman.conf.d/aur-clone-x86_64.conf
echo 'Include = /etc/pacman.d/mirrorlist' | tee -a /usr/share/devtools/pacman.conf.d/aur-clone-x86_64.conf
echo '[multilib]' | tee -a /usr/share/devtools/pacman.conf.d/aur-x86_64.conf
echo 'Include = /etc/pacman.d/mirrorlist' | tee -a /usr/share/devtools/pacman.conf.d/aur-x86_64.conf
echo '[aur-clone]' | tee -a /usr/share/devtools/pacman.conf.d/aur-clone-x86_64.conf
echo 'SigLevel = Optional TrustAll' | tee -a /usr/share/devtools/pacman.conf.d/aur-clone-x86_64.conf
echo 'Server = file:///var/lib/ahriman/repository/$repo/$arch' | tee -a /usr/share/devtools/pacman.conf.d/aur-clone-x86_64.conf
echo '[aur]' | tee -a /usr/share/devtools/pacman.conf.d/aur-x86_64.conf
echo 'SigLevel = Optional TrustAll' | tee -a /usr/share/devtools/pacman.conf.d/aur-x86_64.conf
echo 'Server = file:///var/lib/ahriman/repository/$repo/$arch' | tee -a /usr/share/devtools/pacman.conf.d/aur-x86_64.conf
#.
Set ``build_command`` option to point to your command:
@ -56,14 +56,14 @@ Initial setup
.. code-block:: shell
echo '[build]' | tee -a /etc/ahriman.ini.d/build.ini
echo 'build_command = aur-clone-x86_64-build' | tee -a /etc/ahriman.ini.d/build.ini
echo 'build_command = aur-x86_64-build' | tee -a /etc/ahriman.ini.d/build.ini
#.
Configure ``/etc/sudoers.d/ahriman`` to allow running command without a password:
.. code-block:: shell
echo 'Cmnd_Alias CARCHBUILD_CMD = /usr/local/bin/aur-clone-x86_64-build *' | tee -a /etc/sudoers.d/ahriman
echo 'Cmnd_Alias CARCHBUILD_CMD = /usr/local/bin/aur-x86_64-build *' | tee -a /etc/sudoers.d/ahriman
echo 'ahriman ALL=(ALL) NOPASSWD:SETENV: CARCHBUILD_CMD' | tee -a /etc/sudoers.d/ahriman
chmod 400 /etc/sudoers.d/ahriman
@ -74,7 +74,7 @@ Initial setup
.. code-block:: shell
systemctl enable --now ahriman@x86_64-aur-clone.timer
systemctl enable --now ahriman@x86_64-aur.timer
#.
Start and enable status page:

4
package/archlinux/ahriman.install
View File

@ -34,8 +34,8 @@ Whereas old local tree is still supported it is highly recommended to migrate to
* edit local configuration to avoid pointing to the old paths;
* run setup command (i.e. ahriman service-setup) with the same arguments as did before;
* update remote services in order to support new paths (or setup redirects) if any;
* enable web and timer services again by using x86_64-aur-clone suffix,
where x86_64 is the repository architecture and aur-clone is the repository name.
* enable web and timer services again by using x86_64-aur suffix,
where x86_64 is the repository architecture and aur is the repository name.
For more information kindly refer to migration notes https://ahriman.readthedocs.io/en/stable/migration.html.
EOF

170
src/ahriman/application/ahriman.py
View File

@ -25,6 +25,7 @@ from typing import TypeVar
from ahriman import __version__
from ahriman.application import handlers
from ahriman.application.help_formatter import _HelpFormatter
from ahriman.core.utils import enum_values, extract_user
from ahriman.models.action import Action
from ahriman.models.build_status import BuildStatusEnum
@ -45,19 +46,6 @@ __all__: list[str] = []
SubParserAction = TypeVar("SubParserAction", bound="argparse._SubParsersAction[argparse.ArgumentParser]")
def _formatter(prog: str) -> argparse.HelpFormatter:
"""
formatter for the help message
Args:
prog(str): application name
Returns:
argparse.HelpFormatter: formatter used by default
"""
return argparse.ArgumentDefaultsHelpFormatter(prog, width=120)
# pylint: disable=too-many-statements
def _parser() -> argparse.ArgumentParser:
"""
@ -67,8 +55,28 @@ def _parser() -> argparse.ArgumentParser:
argparse.ArgumentParser: command line parser for the application
"""
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)
epilog="""
Quick setup command (replace repository name, architecture and packager as needed):
>>> ahriman -a x86_64 -r aur service-setup --packager "ahriman bot <ahriman@example.com>"
Add new package from AUR:
>>> ahriman package-add ahriman --now
Check for updates and build out-of-dated packages (add ``--dry-run`` to build it later):
>>> ahriman repo-update
Remove package from the repository:
>>> ahriman package-remove ahriman
Start web service (requires additional configuration):
>>> ahriman web
""",
fromfile_prefix_chars="@", formatter_class=_HelpFormatter)
parser.add_argument("-a", "--architecture", help="filter by target architecture")
parser.add_argument("-c", "--configuration", help="configuration path", type=Path,
default=Path("/") / "etc" / "ahriman.ini")
@ -154,7 +162,7 @@ def _set_aur_search_parser(root: SubParserAction) -> argparse.ArgumentParser:
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("aur-search", aliases=["search"], help="search for package",
description="search for package in AUR using API", formatter_class=_formatter)
description="search for package in AUR using API", formatter_class=_HelpFormatter)
parser.add_argument("search", help="search terms, can be specified multiple times, the result will match all terms",
nargs="+")
parser.add_argument("-e", "--exit-code", help="return non-zero exit status if result is empty", action="store_true")
@ -179,7 +187,8 @@ def _set_help_commands_unsafe_parser(root: SubParserAction) -> argparse.Argument
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("help-commands-unsafe", help="list unsafe commands",
description="list unsafe commands as defined in default args", formatter_class=_formatter)
description="list unsafe commands as defined in default args",
formatter_class=_HelpFormatter)
parser.add_argument("subcommand", help="instead of showing commands, just test command line for unsafe subcommand "
"and return 0 in case if command is safe and 1 otherwise", nargs="*")
parser.set_defaults(handler=handlers.UnsafeCommands, architecture="", lock=None, quiet=True, report=False,
@ -199,7 +208,7 @@ def _set_help_parser(root: SubParserAction) -> argparse.ArgumentParser:
"""
parser = root.add_parser("help", help="show help message",
description="show help message for application or command and exit",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("subcommand", help="show help message for specific command", nargs="?")
parser.set_defaults(handler=handlers.Help, architecture="", lock=None, quiet=True, report=False, repository="",
unsafe=True, parser=_parser)
@ -218,7 +227,7 @@ def _set_help_updates_parser(root: SubParserAction) -> argparse.ArgumentParser:
"""
parser = root.add_parser("help-updates", help="check for service updates",
description="request AUR for current version and compare with current service version",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("-e", "--exit-code", help="return non-zero exit code if updates available", action="store_true")
parser.set_defaults(handler=handlers.ServiceUpdates, architecture="", lock=None, quiet=True, report=False,
repository="", unsafe=True)
@ -236,7 +245,8 @@ def _set_help_version_parser(root: SubParserAction) -> argparse.ArgumentParser:
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("help-version", aliases=["version"], help="application version",
description="print application and its dependencies versions", formatter_class=_formatter)
description="print application and its dependencies versions",
formatter_class=_HelpFormatter)
parser.set_defaults(handler=handlers.Versions, architecture="", lock=None, quiet=True, report=False,
repository="", unsafe=True)
return parser
@ -256,15 +266,15 @@ def _set_package_add_parser(root: SubParserAction) -> argparse.ArgumentParser:
description="add existing or new package to the build queue",
epilog="This subcommand should be used for new package addition. It also supports flag "
"--now in case if you would like to build the package immediately. "
"You can add new package from one of supported sources: "
"1) if it is already built package you can specify the path to the archive; "
"2) you can also add built packages from the directory (e.g. during the migration "
"from another repository source); "
"3) it is also possible to add package from local PKGBUILD, but in this case it "
"will be ignored during the next automatic updates; "
"4) ahriman supports downloading archives from remote (e.g. HTTP) sources; "
"5) and finally you can add package from AUR.",
formatter_class=_formatter)
"You can add new package from one of supported sources:\n\n"
"1. If it is already built package you can specify the path to the archive.\n"
"2. You can also add built packages from the directory (e.g. during the migration "
"from another repository source).\n"
"3. It is also possible to add package from local PKGBUILD, but in this case it "
"will be ignored during the next automatic updates.\n"
"4. Ahriman supports downloading archives from remote (e.g. HTTP) sources.\n"
"5. Finally you can add package from AUR.",
formatter_class=_HelpFormatter)
parser.add_argument("package", help="package source (base name, path to local files, remote URL)", nargs="+")
parser.add_argument("--changes", help="calculate changes from the latest known commit if available",
action=argparse.BooleanOptionalAction, default=True)
@ -298,7 +308,7 @@ def _set_package_changes_parser(root: SubParserAction) -> argparse.ArgumentParse
parser = root.add_parser("package-changes", help="get package changes",
description="retrieve package changes stored in database",
epilog="This feature requests package status from the web interface if it is available.",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("package", help="package base")
parser.add_argument("-e", "--exit-code", help="return non-zero exit status if result is empty", action="store_true")
parser.set_defaults(handler=handlers.Change, action=Action.List, lock=None, quiet=True, report=False, unsafe=True)
@ -317,7 +327,7 @@ def _set_package_changes_remove_parser(root: SubParserAction) -> argparse.Argume
"""
parser = root.add_parser("package-changes-remove", help="remove package changes",
description="remove the package changes stored remotely",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("package", help="package base")
parser.set_defaults(handler=handlers.Change, action=Action.Remove, exit_code=False, lock=None, quiet=True,
report=False, unsafe=True)
@ -335,7 +345,7 @@ def _set_package_remove_parser(root: SubParserAction) -> argparse.ArgumentParser
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("package-remove", aliases=["remove"], help="remove package",
description="remove package from the repository", formatter_class=_formatter)
description="remove package from the repository", formatter_class=_HelpFormatter)
parser.add_argument("package", help="package name or base", nargs="+")
parser.set_defaults(handler=handlers.Remove)
return parser
@ -354,7 +364,7 @@ def _set_package_status_parser(root: SubParserAction) -> argparse.ArgumentParser
parser = root.add_parser("package-status", aliases=["status"], help="get package status",
description="request status of the package",
epilog="This feature requests package status from the web interface if it is available.",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("package", help="filter status by package base", nargs="*")
parser.add_argument("--ahriman", help="get service status itself", action="store_true")
parser.add_argument("-e", "--exit-code", help="return non-zero exit status if result is empty", action="store_true")
@ -380,7 +390,7 @@ def _set_package_status_remove_parser(root: SubParserAction) -> argparse.Argumen
description="remove the package from the status page",
epilog="Please note that this subcommand does not remove the package itself, it just "
"clears the status page.",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("package", help="remove specified packages from status page", nargs="+")
parser.set_defaults(handler=handlers.StatusUpdate, action=Action.Remove, lock=None, quiet=True, report=False,
unsafe=True)
@ -398,7 +408,8 @@ def _set_package_status_update_parser(root: SubParserAction) -> argparse.Argumen
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("package-status-update", aliases=["status-update"], help="update package status",
description="update package status on the status page", formatter_class=_formatter)
description="update package status on the status page",
formatter_class=_HelpFormatter)
parser.add_argument("package", help="set status for specified packages. "
"If no packages supplied, service status will be updated",
nargs="*")
@ -424,8 +435,8 @@ def _set_patch_add_parser(root: SubParserAction) -> argparse.ArgumentParser:
epilog="Unlike ``patch-set-add``, this function allows to patch only one PKGBUILD "
"function, e.g. typing ``ahriman patch-add ahriman pkgver`` it will change the "
"``pkgver`` inside PKGBUILD, typing ``ahriman patch-add ahriman build()`` "
"it will change ``build()`` function inside PKGBUILD",
formatter_class=_formatter)
"it will change ``build()`` function inside PKGBUILD.",
formatter_class=_HelpFormatter)
parser.add_argument("package", help="package base")
parser.add_argument("variable", help="PKGBUILD variable or function name. If variable is a function, "
"it must end with ()")
@ -446,8 +457,8 @@ def _set_patch_list_parser(root: SubParserAction) -> argparse.ArgumentParser:
Returns:
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("patch-list", help="list patch sets",
description="list available patches for the package", formatter_class=_formatter)
parser = root.add_parser("patch-list", help="list patch sets", description="list available patches for the package",
formatter_class=_HelpFormatter)
parser.add_argument("package", help="package base")
parser.add_argument("-e", "--exit-code", help="return non-zero exit status if result is empty", action="store_true")
parser.add_argument("-v", "--variable", help="if set, show only patches for specified PKGBUILD variables",
@ -468,7 +479,7 @@ def _set_patch_remove_parser(root: SubParserAction) -> argparse.ArgumentParser:
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("patch-remove", help="remove patch set", description="remove patches for the package",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("package", help="package base")
parser.add_argument("-v", "--variable", help="should be used for single-function patches in case if you wold like "
"to remove only specified PKGBUILD variables. In case if not set, "
@ -490,12 +501,13 @@ def _set_patch_set_add_parser(root: SubParserAction) -> argparse.ArgumentParser:
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("patch-set-add", help="add patch set", description="create or update source patches",
epilog="In order to add a patch set for the package you will need to clone "
"the AUR package manually, add required changes (e.g. external patches, "
"edit PKGBUILD) and run command, e.g. ``ahriman patch-set-add path/to/directory``. "
"By default it tracks *.patch and *.diff files, but this behavior can be changed "
"by using --track option",
formatter_class=_formatter)
epilog="In order to add a patch set for the package you will need to:\n\n"
"1. Clone the AUR package manually.\n"
"2. Add required changes (e.g. external patches, edit PKGBUILD).\n"
"3. Run command, e.g. ``ahriman patch-set-add path/to/directory``.\n\n"
"By default it tracks ``*.patch`` and ``*.diff`` files, but this behavior can be "
"changed by using ``--track`` option.",
formatter_class=_HelpFormatter)
parser.add_argument("package", help="path to directory with changed files for patch addition/update", type=Path)
parser.add_argument("-t", "--track", help="files which has to be tracked", action="append",
default=["*.diff", "*.patch"])
@ -515,7 +527,8 @@ def _set_repo_backup_parser(root: SubParserAction) -> argparse.ArgumentParser:
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("repo-backup", help="backup repository data",
description="backup repository settings and database", formatter_class=_formatter)
description="backup repository settings and database",
formatter_class=_HelpFormatter)
parser.add_argument("path", help="path of the output archive", type=Path)
parser.set_defaults(handler=handlers.Backup, architecture="", lock=None, report=False, repository="",
unsafe=True)
@ -534,7 +547,7 @@ def _set_repo_check_parser(root: SubParserAction) -> argparse.ArgumentParser:
"""
parser = root.add_parser("repo-check", aliases=["check"], help="check for updates",
description="check for packages updates. Same as repo-update --dry-run --no-manual",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("package", help="filter check by package base", nargs="*")
parser.add_argument("--changes", help="calculate changes from the latest known commit if available",
action=argparse.BooleanOptionalAction, default=True)
@ -566,7 +579,7 @@ def _set_repo_create_keyring_parser(root: SubParserAction) -> argparse.ArgumentP
description="create package which contains list of trusted keys as set by "
"configuration. Note, that this action will only create package, the package "
"itself has to be built manually",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.set_defaults(handler=handlers.Triggers, trigger=["ahriman.core.support.KeyringTrigger"])
return parser
@ -585,7 +598,7 @@ def _set_repo_create_mirrorlist_parser(root: SubParserAction) -> argparse.Argume
description="create package which contains list of available mirrors as set by "
"configuration. Note, that this action will only create package, the package "
"itself has to be built manually",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.set_defaults(handler=handlers.Triggers, trigger=["ahriman.core.support.MirrorlistTrigger"])
return parser
@ -602,7 +615,7 @@ def _set_repo_daemon_parser(root: SubParserAction) -> argparse.ArgumentParser:
"""
parser = root.add_parser("repo-daemon", aliases=["daemon"], help="run application as daemon",
description="start process which periodically will run update process",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("-i", "--interval", help="interval between runs in seconds", type=int, default=60 * 60 * 12)
parser.add_argument("--aur", help="enable or disable checking for AUR updates",
action=argparse.BooleanOptionalAction, default=True)
@ -644,7 +657,7 @@ def _set_repo_rebuild_parser(root: SubParserAction) -> argparse.ArgumentParser:
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("repo-rebuild", aliases=["rebuild"], help="rebuild repository",
description="force rebuild whole repository", formatter_class=_formatter)
description="force rebuild whole repository", formatter_class=_HelpFormatter)
parser.add_argument("--depends-on", help="only rebuild packages that depend on specified packages", action="append")
parser.add_argument("--dry-run", help="just perform check for packages without rebuild process itself",
action="store_true")
@ -676,7 +689,7 @@ def _set_repo_remove_unknown_parser(root: SubParserAction) -> argparse.ArgumentP
"""
parser = root.add_parser("repo-remove-unknown", aliases=["remove-unknown"], help="remove unknown packages",
description="remove packages which are missing in AUR and do not have local PKGBUILDs",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("--dry-run", help="just perform check for packages without removal", action="store_true")
parser.set_defaults(handler=handlers.RemoveUnknown)
return parser
@ -695,7 +708,7 @@ def _set_repo_report_parser(root: SubParserAction) -> argparse.ArgumentParser:
parser = root.add_parser("repo-report", aliases=["report"], help="generate report",
description="generate repository report according to current settings",
epilog="Create and/or update repository report as configured.",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.set_defaults(handler=handlers.Triggers, trigger=["ahriman.core.report.ReportTrigger"])
return parser
@ -711,7 +724,7 @@ def _set_repo_restore_parser(root: SubParserAction) -> argparse.ArgumentParser:
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("repo-restore", help="restore repository data",
description="restore settings and database", formatter_class=_formatter)
description="restore settings and database", formatter_class=_HelpFormatter)
parser.add_argument("path", help="path of the input archive", type=Path)
parser.add_argument("-o", "--output", help="root path of the extracted files", type=Path, default=Path("/"))
parser.set_defaults(handler=handlers.Restore, architecture="", lock=None, report=False, repository="",
@ -732,7 +745,7 @@ def _set_repo_sign_parser(root: SubParserAction) -> argparse.ArgumentParser:
parser = root.add_parser("repo-sign", aliases=["sign"], help="sign packages",
description="(re-)sign packages and repository database according to current settings",
epilog="Sign repository and/or packages as configured.",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("package", help="sign only specified packages", nargs="*")
parser.set_defaults(handler=handlers.Sign)
return parser
@ -749,7 +762,7 @@ def _set_repo_statistics_parser(root: SubParserAction) -> argparse.ArgumentParse
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("repo-statistics", help="repository statistics",
description="fetch repository statistics", formatter_class=_formatter)
description="fetch repository statistics", formatter_class=_HelpFormatter)
parser.add_argument("package", help="fetch only events for the specified package", nargs="?")
parser.add_argument("--chart", help="create updates chart and save it to the specified path", type=Path)
parser.add_argument("-e", "--event", help="event type filter",
@ -773,7 +786,8 @@ def _set_repo_status_update_parser(root: SubParserAction) -> argparse.ArgumentPa
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("repo-status-update", help="update repository status",
description="update repository status on the status page", formatter_class=_formatter)
description="update repository status on the status page",
formatter_class=_HelpFormatter)
parser.add_argument("-s", "--status", help="new status",
type=BuildStatusEnum, choices=enum_values(BuildStatusEnum), default=BuildStatusEnum.Success)
parser.set_defaults(handler=handlers.StatusUpdate, action=Action.Update, lock=None, package=[], quiet=True,
@ -794,7 +808,7 @@ def _set_repo_sync_parser(root: SubParserAction) -> argparse.ArgumentParser:
parser = root.add_parser("repo-sync", aliases=["sync"], help="sync repository",
description="sync repository files to remote server according to current settings",
epilog="Synchronize the repository to remote services as configured.",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.set_defaults(handler=handlers.Triggers, trigger=["ahriman.core.upload.UploadTrigger"])
return parser
@ -811,7 +825,7 @@ def _set_repo_tree_parser(root: SubParserAction) -> argparse.ArgumentParser:
"""
parser = root.add_parser("repo-tree", help="dump repository tree",
description="dump repository tree based on packages dependencies",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("-p", "--partitions", help="also divide packages by independent partitions",
type=int, default=1)
parser.set_defaults(handler=handlers.Structure, lock=None, quiet=True, report=False, unsafe=True)
@ -830,7 +844,7 @@ def _set_repo_triggers_parser(root: SubParserAction) -> argparse.ArgumentParser:
"""
parser = root.add_parser("repo-triggers", help="run triggers",
description="run triggers on empty build result as configured by settings",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("trigger", help="instead of running all triggers as set by configuration, just process "
"specified ones in order of mention", nargs="*")
parser.set_defaults(handler=handlers.Triggers)
@ -849,7 +863,7 @@ def _set_repo_update_parser(root: SubParserAction) -> argparse.ArgumentParser:
"""
parser = root.add_parser("repo-update", aliases=["update"], help="update packages",
description="check for packages updates and run build process if requested",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("package", help="filter check by package base", nargs="*")
parser.add_argument("--aur", help="enable or disable checking for AUR updates",
action=argparse.BooleanOptionalAction, default=True)
@ -894,7 +908,7 @@ def _set_service_clean_parser(root: SubParserAction) -> argparse.ArgumentParser:
epilog="The subcommand clears every temporary directories (builds, caches etc). Normally "
"you should not run this command manually. Also in case if you are going to clear "
"the chroot directories you will need root privileges.",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("--cache", help="clear directory with package caches",
action=argparse.BooleanOptionalAction, default=False)
parser.add_argument("--chroot", help="clear build chroot", action=argparse.BooleanOptionalAction, default=False)
@ -920,7 +934,7 @@ def _set_service_config_parser(root: SubParserAction) -> argparse.ArgumentParser
"""
parser = root.add_parser("service-config", aliases=["config", "repo-config"], help="dump configuration",
description="dump configuration for the specified architecture",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("section", help="filter settings by section", nargs="?")
parser.add_argument("key", help="filter settings by key", nargs="?")
parser.add_argument("--info", help="show additional information, e.g. configuration files",
@ -944,7 +958,7 @@ def _set_service_config_validate_parser(root: SubParserAction) -> argparse.Argum
parser = root.add_parser("service-config-validate", aliases=["config-validate", "repo-config-validate"],
help="validate system configuration",
description="validate configuration and print found errors",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("-e", "--exit-code", help="return non-zero exit status if configuration is invalid",
action="store_true")
parser.set_defaults(handler=handlers.Validate, lock=None, quiet=True, report=False, unsafe=True)
@ -967,7 +981,7 @@ def _set_service_key_import_parser(root: SubParserAction) -> argparse.ArgumentPa
"(in case if signature and keys are available in PKGBUILD). This process will "
"fail in case if key is not known for build user. This subcommand can be used "
"in order to import the PGP key to user keychain.",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("--key-server", help="key server for key import", default="keyserver.ubuntu.com")
parser.add_argument("key", help="PGP key to import from public server")
parser.set_defaults(handler=handlers.KeyImport, architecture="", lock=None, report=False, repository="")
@ -986,7 +1000,7 @@ def _set_service_repositories(root: SubParserAction) -> argparse.ArgumentParser:
"""
parser = root.add_parser("service-repositories", help="show repositories",
description="list all available repositories",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("--id-only", help="show machine readable identifier instead",
action=argparse.BooleanOptionalAction, default=False)
parser.set_defaults(handler=handlers.Repositories, architecture="", lock=None, report=False, repository="",
@ -1007,8 +1021,8 @@ def _set_service_run(root: SubParserAction) -> argparse.ArgumentParser:
parser = root.add_parser("service-run", aliases=["run"], help="run multiple commands",
description="run multiple commands on success run of the previous command",
epilog="Commands must be quoted by using usual bash rules. Processes will be spawned "
"under the same user as this command",
formatter_class=_formatter)
"under the same user as this command.",
formatter_class=_HelpFormatter)
parser.add_argument("command", help="command to be run (quoted) without ``ahriman``", nargs="+")
parser.set_defaults(handler=handlers.Run, architecture="", lock=None, report=False, repository="",
unsafe=True, parser=_parser)
@ -1028,8 +1042,8 @@ def _set_service_setup_parser(root: SubParserAction) -> argparse.ArgumentParser:
parser = root.add_parser("service-setup", aliases=["init", "repo-init", "repo-setup", "setup"],
help="initial service configuration",
description="create initial service configuration, requires root",
epilog="Create _minimal_ configuration for the service according to provided options.",
formatter_class=_formatter)
epilog="Create **minimal** configuration for the service according to provided options.",
formatter_class=_HelpFormatter)
parser.add_argument("--build-as-user", help="force makepkg user to the specific one")
parser.add_argument("--from-configuration", help="path to default devtools pacman configuration",
type=Path, default=Path("/") / "usr" / "share" / "devtools" / "pacman.conf.d" / "extra.conf")
@ -1062,7 +1076,7 @@ def _set_service_shell_parser(root: SubParserAction) -> argparse.ArgumentParser:
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("service-shell", aliases=["shell"], help="invoke python shell",
description="drop into python shell", formatter_class=_formatter)
description="drop into python shell", formatter_class=_HelpFormatter)
parser.add_argument("code", help="instead of dropping into shell, just execute the specified code", nargs="?")
parser.add_argument("-v", "--verbose", help=argparse.SUPPRESS, action="store_true")
parser.set_defaults(handler=handlers.Shell, lock=None, report=False)
@ -1080,7 +1094,8 @@ def _set_service_tree_migrate_parser(root: SubParserAction) -> argparse.Argument
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("service-tree-migrate", help="migrate repository tree",
description="migrate repository tree between versions", formatter_class=_formatter)
description="migrate repository tree between versions",
formatter_class=_HelpFormatter)
parser.set_defaults(handler=handlers.TreeMigrate, lock=None, quiet=True, report=False)
return parser
@ -1098,7 +1113,7 @@ def _set_user_add_parser(root: SubParserAction) -> argparse.ArgumentParser:
parser = root.add_parser("user-add", help="create or update user",
description="update user for web services with the given password and role. "
"In case if password was not entered it will be asked interactively",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("username", help="username for web service")
parser.add_argument("--key", help="optional PGP key used by this user. The private key must be imported")
parser.add_argument("--packager", help="optional packager id used for build process in form of "
@ -1124,7 +1139,7 @@ def _set_user_list_parser(root: SubParserAction) -> argparse.ArgumentParser:
"""
parser = root.add_parser("user-list", help="user known users and their access",
description="list users from the user mapping and their roles",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("username", help="filter users by username", nargs="?")
parser.add_argument("-e", "--exit-code", help="return non-zero exit status if result is empty", action="store_true")
parser.add_argument("-R", "--role", help="filter users by role", type=UserAccess, choices=enum_values(UserAccess))
@ -1145,7 +1160,7 @@ def _set_user_remove_parser(root: SubParserAction) -> argparse.ArgumentParser:
"""
parser = root.add_parser("user-remove", help="remove user",
description="remove user from the user mapping and update the configuration",
formatter_class=_formatter)
formatter_class=_HelpFormatter)
parser.add_argument("username", help="username for web service")
parser.set_defaults(handler=handlers.Users, action=Action.Remove, architecture="", exit_code=False, lock=None,
quiet=True, report=False, repository="")
@ -1162,7 +1177,8 @@ def _set_web_parser(root: SubParserAction) -> argparse.ArgumentParser:
Returns:
argparse.ArgumentParser: created argument parser
"""
parser = root.add_parser("web", help="web server", description="start web server", formatter_class=_formatter)
parser = root.add_parser("web", help="web server", description="start web server",
formatter_class=_HelpFormatter)
parser.set_defaults(handler=handlers.Web, architecture="", lock=Path("ahriman-web.pid"), report=False,
repository="", parser=_parser)
return parser

54
src/ahriman/application/help_formatter.py Normal file
View File

@ -0,0 +1,54 @@
#
# Copyright (c) 2021-2024 ahriman team.
#
# This file is part of ahriman
# (see https://github.com/arcan1s/ahriman).
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
#
import argparse
import re
import textwrap
class _HelpFormatter(argparse.ArgumentDefaultsHelpFormatter):
"""
:class:`argparse.ArgumentDefaultsHelpFormatter` extension which keeps new lines in help messages
"""
def __init__(self, prog: str) -> None:
"""
Args:
prog(str): application name
"""
argparse.ArgumentDefaultsHelpFormatter.__init__(self, prog, width=120)
self._whitespace_matcher = re.compile(r"[ \t]+")
def _fill_text(self, text: str, width: int, indent: str) -> str:
"""
implementation of the protected method to format text. Format text, keeping new lines
Args:
text(str): text to format
width(int): maximal text width
indent(str): indentation string
Returns:
str: formatted text
"""
text = self._whitespace_matcher.sub(" ", text).strip()
return "\n".join([
textwrap.fill(line, width, initial_indent=indent, subsequent_indent=indent)
for line in text.splitlines()
])

2
src/ahriman/application/lock.py
View File

@ -58,7 +58,7 @@ class Lock(LazyLogging):
>>>
>>> configuration = Configuration()
>>> try:
>>> with Lock(args, RepositoryId("x86_64", "aur-clone"), configuration):
>>> with Lock(args, RepositoryId("x86_64", "aur"), configuration):
>>> do_something()
>>> except Exception as exception:
>>> handle_exceptions(exception)

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

@ -51,7 +51,7 @@ class Configuration(configparser.RawConfigParser):
>>> from pathlib import Path
>>>
>>> configuration = Configuration.from_path(Path("/etc/ahriman.ini"), RepositoryId("x86_64", "aur-clone"))
>>> configuration = Configuration.from_path(Path("/etc/ahriman.ini"), RepositoryId("x86_64", "aur"))
>>> repository_name = configuration.get("repository", "name")
>>> makepkg_flags = configuration.getlist("build", "makepkg_flags")

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

@ -41,7 +41,7 @@ class Report(LazyLogging):
class method :func:`load()` which can be used in order to determine right report instance::
>>> configuration = Configuration()
>>> report = Report.load(RepositoryId("x86_64", "aur-clone"), configuration, "email")
>>> report = Report.load(RepositoryId("x86_64", "aur"), configuration, "email")
The :func:`generate()` method can be used in order to perform the report itself, whereas :func:`run()` method
handles exception and raises :exc:`ahriman.core.exceptions.ReportError` instead::

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

@ -103,7 +103,7 @@ class Tree:
>>>
>>> configuration = Configuration()
>>> database = SQLite.load(configuration)
>>> repository = Repository.load(RepositoryId("x86_64", "aur-clone"), configuration, database, report=True)
>>> repository = Repository.load(RepositoryId("x86_64", "aur"), configuration, database, report=True)
>>> packages = repository.packages()
>>>
>>> tree = Tree.resolve(packages)

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

@ -52,7 +52,7 @@ class Trigger(LazyLogging):
>>> configuration = Configuration()
>>> configuration.set_option("build", "triggers", "my.awesome.package.CustomTrigger")
>>>
>>> loader = TriggerLoader.load(RepositoryId("x86_64", "aur-clone"), configuration)
>>> loader = TriggerLoader.load(RepositoryId("x86_64", "aur"), configuration)
>>> loader.on_result(Result(), [])
"""

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

@ -50,7 +50,7 @@ class TriggerLoader(LazyLogging):
Having such configuration you can create instance of the loader::
>>> loader = TriggerLoader.load(RepositoryId("x86_64", "aur-clone"), configuration)
>>> loader = TriggerLoader.load(RepositoryId("x86_64", "aur"), configuration)
>>> print(loader.triggers)
After that you are free to run triggers::

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

@ -44,7 +44,7 @@ class Upload(LazyLogging):
exception::
>>> configuration = Configuration()
>>> upload = Upload.load(RepositoryId("x86_64", "aur-clone"), configuration, "s3")
>>> upload = Upload.load(RepositoryId("x86_64", "aur"), configuration, "s3")
>>> upload.run(configuration.repository_paths.repository, [])
Or in case if direct access to exception is required, the :func:`sync()` method can be used::

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

@ -72,7 +72,7 @@ class AURPackage:
>>> from ahriman.models.repository_id import RepositoryId
>>>
>>> configuration = Configuration()
>>> pacman = Pacman(RepositoryId("x86_64", "aur-clone"), configuration)
>>> pacman = Pacman(RepositoryId("x86_64", "aur"), configuration)
>>> metadata = pacman.package_get("pacman")
>>> package = AURPackage.from_pacman(next(metadata)) # load package from pyalpm wrapper
"""

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

@ -60,7 +60,7 @@ class PackageDescription:
>>> from ahriman.models.repository_id import RepositoryId
>>>
>>> configuration = Configuration()
>>> pacman = Pacman(RepositoryId("x86_64", "aur-clone"), configuration)
>>> pacman = Pacman(RepositoryId("x86_64", "aur"), configuration)
>>> pyalpm_description = next(package for package in pacman.package_get("pacman"))
>>> description = PackageDescription.from_package(
>>> pyalpm_description, Path("/var/cache/pacman/pkg/pacman-6.0.1-4-x86_64.pkg.tar.zst"))

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

@ -43,7 +43,7 @@ class RepositoryPaths(LazyLogging):
Examples:
This class can be used in order to access the repository tree structure::
>>> paths = RepositoryPaths(Path("/var/lib/ahriman"), RepositoryId("x86_64", "aur-clone"))
>>> paths = RepositoryPaths(Path("/var/lib/ahriman"), RepositoryId("x86_64", "aur"))
Additional methods can be used in order to ensure that tree is created::

2
src/ahriman/web/schemas/package_schema.py
View File

@ -46,5 +46,5 @@ class PackageSchema(Schema):
})
packager = fields.String(metadata={
"description": "packager for the last success package build",
"example": "John Doe <john@doe.com>",
"example": "ahriman bot <ahriman@example.com>",
})

2
src/ahriman/web/schemas/repository_id_schema.py
View File

@ -31,5 +31,5 @@ class RepositoryIdSchema(Schema):
})
repository = fields.String(metadata={
"description": "Repository name",
"example": "aur-clone",
"example": "aur",
})

12
tests/ahriman/application/conftest.py
View File

@ -5,6 +5,7 @@ from pytest_mock import MockerFixture
from ahriman.application.ahriman import _parser
from ahriman.application.application import Application
from ahriman.application.help_formatter import _HelpFormatter
from ahriman.application.lock import Lock
from ahriman.core.configuration import Configuration
from ahriman.core.database import SQLite
@ -44,6 +45,17 @@ def args() -> argparse.Namespace:
repository=None, repository_id=None, wait_timeout=-1)
@pytest.fixture
def formatter() -> _HelpFormatter:
"""
fixture for help message formatter
Returns:
_HelpFormatter: help message formatter test instance
"""
return _HelpFormatter("ahriman")
@pytest.fixture
def lock(args: argparse.Namespace, configuration: Configuration) -> Lock:
"""

14
tests/ahriman/application/handlers/test_handler.py
View File

@ -73,8 +73,8 @@ def test_execute(args: argparse.Namespace, mocker: MockerFixture) -> None:
must run execution in multiple processes
"""
ids = [
RepositoryId("i686", "aur-clone"),
RepositoryId("x86_64", "aur-clone"),
RepositoryId("i686", "aur"),
RepositoryId("x86_64", "aur"),
]
mocker.patch("ahriman.application.handlers.Handler.repositories_extract", return_value=ids)
starmap_mock = mocker.patch("multiprocessing.pool.Pool.starmap")
@ -89,8 +89,8 @@ def test_execute_multiple_not_supported(args: argparse.Namespace, mocker: Mocker
"""
args.command = "web"
mocker.patch("ahriman.application.handlers.Handler.repositories_extract", return_value=[
RepositoryId("i686", "aur-clone"),
RepositoryId("x86_64", "aur-clone"),
RepositoryId("i686", "aur"),
RepositoryId("x86_64", "aur"),
])
mocker.patch.object(Handler, "ALLOW_MULTI_ARCHITECTURE_RUN", False)
@ -103,7 +103,7 @@ def test_execute_single(args: argparse.Namespace, mocker: MockerFixture) -> None
must run execution in current process if only one architecture supplied
"""
mocker.patch("ahriman.application.handlers.Handler.repositories_extract", return_value=[
RepositoryId("x86_64", "aur-clone"),
RepositoryId("x86_64", "aur"),
])
starmap_mock = mocker.patch("multiprocessing.pool.Pool.starmap")
@ -179,7 +179,7 @@ def test_repositories_extract_repository_legacy(args: argparse.Namespace, config
known_repositories_mock = mocker.patch("ahriman.models.repository_paths.RepositoryPaths.known_repositories",
return_value=set())
assert Handler.repositories_extract(args) == [RepositoryId("arch", "aur-clone")]
assert Handler.repositories_extract(args) == [RepositoryId("arch", "aur")]
known_architectures_mock.assert_not_called()
known_repositories_mock.assert_called_once_with(configuration.repository_paths.root)
@ -255,6 +255,6 @@ def test_repositories_extract_systemd_legacy(args: argparse.Namespace, configura
known_repositories_mock = mocker.patch("ahriman.models.repository_paths.RepositoryPaths.known_repositories",
return_value=set())
assert Handler.repositories_extract(args) == [RepositoryId("i686", "aur-clone")]
assert Handler.repositories_extract(args) == [RepositoryId("i686", "aur")]
known_architectures_mock.assert_not_called()
known_repositories_mock.assert_called_once_with(configuration.repository_paths.root)

4
tests/ahriman/application/handlers/test_handler_setup.py
View File

@ -33,8 +33,8 @@ def _default_args(args: argparse.Namespace) -> argparse.Namespace:
args.makeflags_jobs = True
args.mirror = "mirror"
args.multilib = True
args.packager = "John Doe <john@doe.com>"
args.repository = "aur-clone"
args.packager = "ahriman bot <ahriman@example.com>"
args.repository = "aur"
args.server = None
args.sign_key = "key"
args.sign_target = [SignSettings.Packages]

22
tests/ahriman/application/test_ahriman.py
View File

@ -1318,7 +1318,8 @@ def test_subparsers_service_setup(parser: argparse.ArgumentParser) -> None:
"""
service-setup command must imply lock, quiet, report and unsafe
"""
args = parser.parse_args(["-a", "x86_64", "-r", "repo", "service-setup", "--packager", "John Doe <john@doe.com>"])
args = parser.parse_args(["-a", "x86_64", "-r", "repo", "service-setup",
"--packager", "ahriman bot <ahriman@example.com>"])
assert args.architecture == "x86_64"
assert args.lock is None
assert args.quiet
@ -1331,10 +1332,11 @@ def test_subparsers_service_setup_option_from_configuration(parser: argparse.Arg
"""
service-setup command must convert from-configuration option to path instance
"""
args = parser.parse_args(["-a", "x86_64", "-r", "repo", "service-setup", "--packager", "John Doe <john@doe.com>"])
args = parser.parse_args(["-a", "x86_64", "-r", "repo", "service-setup",
"--packager", "ahriman bot <ahriman@example.com>"])
assert isinstance(args.from_configuration, Path)
args = parser.parse_args(["-a", "x86_64", "-r", "repo", "service-setup", "--packager", "John Doe <john@doe.com>",
"--from-configuration", "path"])
args = parser.parse_args(["-a", "x86_64", "-r", "repo", "service-setup",
"--packager", "ahriman bot <ahriman@example.com>", "--from-configuration", "path"])
assert isinstance(args.from_configuration, Path)
@ -1342,8 +1344,8 @@ def test_subparsers_service_setup_option_sign_target(parser: argparse.ArgumentPa
"""
service-setup command must convert sign-target option to SignSettings instance
"""
args = parser.parse_args(["-a", "x86_64", "-r", "repo", "service-setup", "--packager", "John Doe <john@doe.com>",
"--sign-target", "packages"])
args = parser.parse_args(["-a", "x86_64", "-r", "repo", "service-setup",
"--packager", "ahriman bot <ahriman@example.com>", "--sign-target", "packages"])
assert args.sign_target
assert all(isinstance(target, SignSettings) for target in args.sign_target)
@ -1352,7 +1354,8 @@ def test_subparsers_service_setup_option_sign_target_empty(parser: argparse.Argu
"""
service-setup command must accept empty sign-target list as None
"""
args = parser.parse_args(["-a", "x86_64", "-r", "repo", "service-setup", "--packager", "John Doe <john@doe.com>"])
args = parser.parse_args(["-a", "x86_64", "-r", "repo", "service-setup",
"--packager", "ahriman bot <ahriman@example.com>"])
assert args.sign_target is None
@ -1360,8 +1363,9 @@ def test_subparsers_service_setup_option_sign_target_multiple(parser: argparse.A
"""
service-setup command must accept multiple sign-target
"""
args = parser.parse_args(["-a", "x86_64", "-r", "repo", "service-setup", "--packager", "John Doe <john@doe.com>",
"--sign-target", "packages", "--sign-target", "repository"])
args = parser.parse_args(["-a", "x86_64", "-r", "repo", "service-setup",
"--packager", "ahriman bot <ahriman@example.com>", "--sign-target", "packages",
"--sign-target", "repository"])
assert args.sign_target == [SignSettings.Packages, SignSettings.Repository]

19
tests/ahriman/application/test_help_formatter.py Normal file
View File

@ -0,0 +1,19 @@
from ahriman.application.help_formatter import _HelpFormatter
def test_whitespace_matcher(formatter: _HelpFormatter) -> None:
"""
must only match spaces or tabs
"""
assert formatter._whitespace_matcher.match(" ")
assert formatter._whitespace_matcher.match("\t")
assert formatter._whitespace_matcher.match("\n") is None
assert formatter._whitespace_matcher.match("\r") is None
def test_fill_text(formatter: _HelpFormatter) -> None:
"""
must wrap text keeping new lines
"""
assert formatter._fill_text("first\n 1 longwordhere", 10, "") == "first\n 1 longwor\ndhere"

4
tests/ahriman/application/test_lock.py
View File

@ -26,10 +26,10 @@ def test_path(args: argparse.Namespace, configuration: Configuration) -> None:
assert Lock(args, repository_id, configuration).path is None
args.lock = Path("/run/ahriman.pid")
assert Lock(args, repository_id, configuration).path == Path("/run/ahriman_x86_64-aur-clone.pid")
assert Lock(args, repository_id, configuration).path == Path("/run/ahriman_x86_64-aur.pid")
args.lock = Path("ahriman.pid")
assert Lock(args, repository_id, configuration).path == Path("/run/ahriman/ahriman_x86_64-aur-clone.pid")
assert Lock(args, repository_id, configuration).path == Path("/run/ahriman/ahriman_x86_64-aur.pid")
assert Lock(args, RepositoryId("", ""), configuration).path == Path("/run/ahriman/ahriman.pid")

2
tests/ahriman/conftest.py
View File

@ -555,7 +555,7 @@ def repository_id() -> RepositoryId:
Returns:
RepositoryId: repository identifier test instance
"""
return RepositoryId("x86_64", "aur-clone")
return RepositoryId("x86_64", "aur")
@pytest.fixture

10
tests/ahriman/core/configuration/test_configuration.py
View File

@ -22,7 +22,7 @@ def test_repository_name(configuration: Configuration) -> None:
"""
must return valid repository name
"""
assert configuration.repository_name == "aur-clone"
assert configuration.repository_name == "aur"
def test_repository_paths(configuration: Configuration, repository_paths: RepositoryPaths) -> None:
@ -68,8 +68,8 @@ def test_section_name(configuration: Configuration) -> None:
assert configuration.section_name("build") == "build"
assert configuration.section_name("build", None) == "build"
assert configuration.section_name("build", "x86_64") == "build:x86_64"
assert configuration.section_name("build", "aur-clone", "x86_64") == "build:aur-clone:x86_64"
assert configuration.section_name("build", "aur-clone", None) == "build:aur-clone"
assert configuration.section_name("build", "aur", "x86_64") == "build:aur:x86_64"
assert configuration.section_name("build", "aur", None) == "build:aur"
assert configuration.section_name("build", None, "x86_64") == "build:x86_64"
@ -379,8 +379,8 @@ def test_override_sections(configuration: Configuration, repository_id: Reposito
"""
assert configuration.override_sections("build", repository_id) == [
"build:x86_64",
"build:aur-clone",
"build:aur-clone:x86_64",
"build:aur",
"build:aur:x86_64",
]

18
tests/ahriman/core/support/pkgbuild/test_keyring_generator.py
View File

@ -71,7 +71,7 @@ def test_pkgdesc(database: SQLite, gpg: GPG, configuration: Configuration) -> No
"""
_, repository_id = configuration.check_loaded()
assert KeyringGenerator(database, gpg, repository_id, configuration, "keyring").pkgdesc == "aur-clone PGP keyring"
assert KeyringGenerator(database, gpg, repository_id, configuration, "keyring").pkgdesc == "aur PGP keyring"
configuration.set_option("keyring", "description", "description")
assert KeyringGenerator(database, gpg, repository_id, configuration, "keyring").pkgdesc == "description"
@ -83,7 +83,7 @@ def test_pkgname(database: SQLite, gpg: GPG, configuration: Configuration) -> No
"""
_, repository_id = configuration.check_loaded()
assert KeyringGenerator(database, gpg, repository_id, configuration, "keyring").pkgname == "aur-clone-keyring"
assert KeyringGenerator(database, gpg, repository_id, configuration, "keyring").pkgname == "aur-keyring"
configuration.set_option("keyring", "package", "keyring")
assert KeyringGenerator(database, gpg, repository_id, configuration, "keyring").pkgname == "keyring"
@ -169,7 +169,7 @@ def test_install(keyring_generator: KeyringGenerator) -> None:
"""
assert keyring_generator.install() == """post_upgrade() {
if usr/bin/pacman-key -l >/dev/null 2>&1; then
usr/bin/pacman-key --populate aur-clone
usr/bin/pacman-key --populate aur
usr/bin/pacman-key --updatedb
fi
}
@ -186,9 +186,9 @@ def test_package(keyring_generator: KeyringGenerator) -> None:
must generate package function correctly
"""
assert keyring_generator.package() == """{
install -Dm644 "$srcdir/aur-clone.gpg" "$pkgdir/usr/share/pacman/keyrings/aur-clone.gpg"
install -Dm644 "$srcdir/aur-clone-revoked" "$pkgdir/usr/share/pacman/keyrings/aur-clone-revoked"
install -Dm644 "$srcdir/aur-clone-trusted" "$pkgdir/usr/share/pacman/keyrings/aur-clone-trusted"
install -Dm644 "$srcdir/aur.gpg" "$pkgdir/usr/share/pacman/keyrings/aur.gpg"
install -Dm644 "$srcdir/aur-revoked" "$pkgdir/usr/share/pacman/keyrings/aur-revoked"
install -Dm644 "$srcdir/aur-trusted" "$pkgdir/usr/share/pacman/keyrings/aur-trusted"
}"""
@ -196,6 +196,6 @@ def test_sources(keyring_generator: KeyringGenerator) -> None:
"""
must return valid sources files list
"""
assert keyring_generator.sources().get("aur-clone.gpg")
assert keyring_generator.sources().get("aur-clone-revoked")
assert keyring_generator.sources().get("aur-clone-trusted")
assert keyring_generator.sources().get("aur.gpg")
assert keyring_generator.sources().get("aur-revoked")
assert keyring_generator.sources().get("aur-trusted")

8
tests/ahriman/core/support/pkgbuild/test_mirrorlist_generator.py
View File

@ -12,7 +12,7 @@ def test_init_path(configuration: Configuration) -> None:
_, repository_id = configuration.check_loaded()
assert MirrorlistGenerator(repository_id, configuration, "mirrorlist").path == \
Path("etc") / "pacman.d" / "aur-clone-mirrorlist"
Path("etc") / "pacman.d" / "aur-mirrorlist"
configuration.set_option("mirrorlist", "path", "/etc")
assert MirrorlistGenerator(repository_id, configuration, "mirrorlist").path == Path("etc")
@ -37,7 +37,7 @@ def test_pkgdesc(configuration: Configuration) -> None:
_, repository_id = configuration.check_loaded()
assert MirrorlistGenerator(repository_id, configuration, "mirrorlist").pkgdesc == \
"aur-clone mirror list for use by pacman"
"aur mirror list for use by pacman"
configuration.set_option("mirrorlist", "description", "description")
assert MirrorlistGenerator(repository_id, configuration, "mirrorlist").pkgdesc == "description"
@ -49,7 +49,7 @@ def test_pkgname(configuration: Configuration) -> None:
"""
_, repository_id = configuration.check_loaded()
assert MirrorlistGenerator(repository_id, configuration, "mirrorlist").pkgname == "aur-clone-mirrorlist"
assert MirrorlistGenerator(repository_id, configuration, "mirrorlist").pkgname == "aur-mirrorlist"
configuration.set_option("mirrorlist", "package", "mirrorlist")
assert MirrorlistGenerator(repository_id, configuration, "mirrorlist").pkgname == "mirrorlist"
@ -81,7 +81,7 @@ def test_package(mirrorlist_generator: MirrorlistGenerator) -> None:
must generate package function correctly
"""
assert mirrorlist_generator.package() == """{
install -Dm644 "$srcdir/mirrorlist" "$pkgdir/etc/pacman.d/aur-clone-mirrorlist"
install -Dm644 "$srcdir/mirrorlist" "$pkgdir/etc/pacman.d/aur-mirrorlist"
}"""

6
tests/ahriman/core/upload/test_s3.py
View File

@ -18,7 +18,7 @@ def test_object_path(configuration: Configuration, mocker: MockerFixture) -> Non
_, repository_id = configuration.check_loaded()
# new-style tree
assert S3(repository_id, configuration, "customs3").object_path == Path("aur-clone/x86_64")
assert S3(repository_id, configuration, "customs3").object_path == Path("aur/x86_64")
# legacy tree
mocker.patch.object(RepositoryPaths, "_suffix", Path("x86_64"))
@ -58,12 +58,12 @@ def test_files_remove(s3_remote_objects: list[Any]) -> None:
must remove remote objects
"""
local_files = {
Path(item.key): item.e_tag for item in s3_remote_objects if item.key != "aur-clone/x86_64/a"
Path(item.key): item.e_tag for item in s3_remote_objects if item.key != "aur/x86_64/a"
}
remote_objects = {Path(item.key): item for item in s3_remote_objects}
S3.files_remove(local_files, remote_objects)
remote_objects[Path("aur-clone/x86_64/a")].delete.assert_called_once_with()
remote_objects[Path("aur/x86_64/a")].delete.assert_called_once_with()
def test_files_upload(s3: S3, s3_remote_objects: list[Any], mocker: MockerFixture) -> None:

12
tests/ahriman/models/conftest.py
View File

@ -67,11 +67,13 @@ def internal_status(counters: Counters) -> InternalStatus:
Returns:
InternalStatus: internal status test instance
"""
return InternalStatus(status=BuildStatus(),
architecture="x86_64",
packages=counters,
version=__version__,
repository="aur-clone")
return InternalStatus(
status=BuildStatus(),
architecture="x86_64",
packages=counters,
version=__version__,
repository="aur",
)
@pytest.fixture

2
tests/testresources/core/ahriman.ini
View File

@ -30,7 +30,7 @@ triggers = ahriman.core.report.ReportTrigger ahriman.core.upload.UploadTrigger
triggers_known = ahriman.core.distributed.WorkerLoaderTrigger ahriman.core.distributed.WorkerRegisterTrigger ahriman.core.distributed.WorkerTrigger ahriman.core.distributed.WorkerUnregisterTrigger ahriman.core.gitremote.RemotePullTrigger ahriman.core.gitremote.RemotePushTrigger ahriman.core.report.ReportTrigger ahriman.core.upload.UploadTrigger ahriman.core.support.KeyringTrigger ahriman.core.support.MirrorlistTrigger
[repository]
name = aur-clone
name = aur
root = ../../../
[sign]