ahriman.models package

Submodules

ahriman.models.action module

class Action(*values)

Bases: StrEnum

base action enumeration

List

list available values

Type:: Action

Remove

remove everything from local storage

Type:: Action

Update

update local storage or add to

Type:: Action

ahriman.models.aur_package module

class AURPackage(*, id: int, name: str, package_base_id: int, package_base: str, version: str, num_votes: int, popularity: float, first_submitted: ~datetime.datetime, last_modified: ~datetime.datetime, url_path: str, description: str = '', url: str | None = None, out_of_date: ~datetime.datetime | None = None, maintainer: str | None = None, submitter: str | None = None, repository: str = 'aur', depends: list[str] = <factory>, make_depends: list[str] = <factory>, opt_depends: list[str] = <factory>, check_depends: list[str] = <factory>, conflicts: list[str] = <factory>, provides: list[str] = <factory>, license: list[str] = <factory>, keywords: list[str] = <factory>, groups: list[str] = <factory>)

Bases: object

AUR package descriptor

id

package ID

Type:: int

name

package name

Type:: str

package_base_id

package base ID

Type:: int

version

package base version

Type:: str

description

package base description

Type:: str

url

package upstream URL

Type:: str | None

num_votes

number of votes for the package

Type:: int

popularity

package popularity

Type:: float

out_of_date

package out of date timestamp if any

Type:: datetime.datetime | None

maintainer

package maintainer

Type:: str | None

submitter

package first submitter

Type:: str | None

first_submitted

timestamp of the first package submission

Type:: datetime.datetime

last_modified

timestamp of the last package submission

Type:: datetime.datetime

url_path

AUR package path

Type:: str

repository

repository name of the package

Type:: str

depends

list of package dependencies

Type:: list[str]

make_depends

list of package make dependencies

Type:: list[str]

opt_depends

list of package optional dependencies

Type:: list[str]

check_depends

list of package test dependencies

Type:: list[str]

conflicts

conflicts list for the package

Type:: list[str]

provides

list of packages which this package provides

Type:: list[str]

license

list of package licenses

Type:: list[str]

keywords

list of package keywords

Type:: list[str]

groups

list of package groups

Type:: list[str]

Examples

Mainly this class must be used from class methods instead of default __init__():

>>> package = AURPackage.from_json(metadata)  # load package from json dump
>>> # ...or alternatively...
>>> package = AURPackage.from_repo(metadata)  # load package from official repository RPC
>>> # properties of the class are built based on ones from AUR RPC, thus additional method is required
>>>
>>> from ahriman.core.alpm.pacman import Pacman
>>> from ahriman.core.configuration import Configuration
>>> from ahriman.models.repository_id import RepositoryId
>>>
>>> configuration = Configuration()
>>> pacman = Pacman(RepositoryId("x86_64", "aur"), configuration)
>>> metadata = pacman.package_get("pacman")
>>> package = AURPackage.from_pacman(next(metadata))  # load package from pyalpm wrapper

classmethod from_json(dump: dict[str, Any]) → Self

construct package descriptor from RPC properties

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: AUR package descriptor
Return type:: Self

classmethod from_pacman(package: pyalpm.Package) → Self

construct package descriptor from official repository wrapper

Parameters:: package (Package) – pyalpm package descriptor
Returns:: AUR package descriptor
Return type:: Self

classmethod from_repo(dump: dict[str, Any]) → Self

construct package descriptor from official repository RPC properties

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: AUR package descriptor
Return type:: Self

static convert(descriptor: dict[str, Any]) → dict[str, Any]

covert AUR RPC key names to package keys

Parameters:: descriptor (dict[str, Any]) – RPC package descriptor
Returns:: package descriptor with names converted to snake case
Return type:: dict[str, Any]

ahriman.models.auth_settings module

class AuthSettings(*values)

Bases: StrEnum

web authorization type

Disabled

authorization is disabled

Type:: AuthSettings

Configuration

configuration based authorization

Type:: AuthSettings

OAuth

OAuth based provider

Type:: AuthSettings

PAM

PAM based provider

Type:: AuthSettings

static from_option(value: str) → AuthSettings

construct value from configuration

Parameters:: value (str) – configuration value
Returns:: parsed value
Return type:: AuthSettings

property is_enabled: bool

get enabled flag

Returns:: False in case if authorization is disabled and True otherwise
Return type:: bool

ahriman.models.build_status module

class BuildStatus(status: ~ahriman.models.build_status.BuildStatusEnum = BuildStatusEnum.Unknown, timestamp: int = <factory>)

Bases: object

build status holder

status

build status

Type:: BuildStatusEnum

timestamp

build status update time

Type:: int

classmethod from_json(dump: dict[str, Any]) → Self

construct status properties from json dump

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: status properties
Return type:: Self

pretty_print() → str

generate pretty string representation

Returns:: print-friendly string
Return type:: str

view() → dict[str, Any]

generate json status view

Returns:: json-friendly dictionary
Return type:: dict[str, Any]

class BuildStatusEnum(*values)

Bases: StrEnum

build status enumeration

Unknown

build status is unknown

Type:: BuildStatusEnum

Pending

package is out-of-dated and will be built soon

Type:: BuildStatusEnum

Building

package is building right now

Type:: BuildStatusEnum

Failed

package build failed

Type:: BuildStatusEnum

Success

package has been built without errors

Type:: BuildStatusEnum

ahriman.models.changes module

class Changes(last_commit_sha: str | None = None, changes: str | None = None)

Bases: object

package source files changes holder

last_commit_sha

last commit hash

Type:: str | None

changes

package change since the last commit if available

Type:: str | None

classmethod from_json(dump: dict[str, Any]) → Self

construct changes from the json dump

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: changes object
Return type:: Self

view() → dict[str, Any]

generate json change view

Returns:: json-friendly dictionary
Return type:: dict[str, Any]

property is_empty: bool

validate that changes are not empty

Returns:: True in case if changes are not set and False otherwise
Return type:: bool

ahriman.models.context_key module

class ContextKey(key: str, return_type: type[T])

Bases: Generic[T]

ahriman context key for typing purposes

key

context key to lookup

Type:: str

return_type

return type used for the specified context key

Type:: type[T]

classmethod from_type(return_type: type[T]) → Self

construct key from type

Parameters:: return_type (type[T]) – return type used for the specified context key
Returns:: context key with autogenerated
Return type:: Self

ahriman.models.counters module

class Counters(*, total: int, unknown: int = 0, pending: int = 0, building: int = 0, failed: int = 0, success: int = 0)

Bases: object

package counters

total

total packages count

Type:: int

unknown

packages in unknown status count

Type:: int

pending

packages in pending status count

Type:: int

building

packages in building status count

Type:: int

failed

packages in failed status count

Type:: int

success

packages in success status count

Type:: int

classmethod from_json(dump: dict[str, Any]) → Self

construct counters from json dump

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: status counters
Return type:: Self

classmethod from_packages(packages: list[tuple[Package, BuildStatus]]) → Self

construct counters from packages statuses

Parameters:: packages (list[tuple[Package, BuildStatus]]) – list of package and their status as per watcher property
Returns:: status counters
Return type:: Self

ahriman.models.dependencies module

class Dependencies(paths: dict[str, list[str]] = <factory>)

Bases: object

package paths dependencies

paths

map of the paths used by this package to set of packages in which they were found

Type:: dict[str, list[str]]

classmethod from_json(dump: dict[str, Any]) → Self

construct dependencies from the json dump

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: dependencies object
Return type:: Self

view() → dict[str, Any]

generate json dependencies view

Returns:: json-friendly dictionary
Return type:: dict[str, Any]

ahriman.models.event module

class Event(event: str | EventType, object_id: str, message: str | None = None, created: int | None = None, **kwargs: Any)

Bases: object

audit log event

created

event timestamp

Type:: int

data

event metadata

Type:: dict[str, Any]

event

event type

Type:: str | EventType

message

event message if available

Type:: str | None

object_id

object identifier

Type:: str

Parameters:

event (str | EventType) – event type
object_id (str) – object identifier
message (str | None) – event message if available
created (int | None, optional) – event timestamp (Default value = None)
**kwargs (Any) – event metadata

classmethod from_json(dump: dict[str, Any]) → Self

construct event from the json dump

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: event object
Return type:: Self

get(key: str) → Any

get a property

Parameters:: key (str) – key to lookup in data
Returns:: metadata property if available or None otherwise
Return type:: Any

view() → dict[str, Any]

generate json event view

Returns:: json-friendly dictionary
Return type:: dict[str, Any]

class EventType(*values)

Bases: StrEnum

predefined event types

PackageOutdated

package has been marked as out-of-date

Type:: EventType

PackageRemoved

package has been removed

Type:: EventType

PackageUpdateFailed

package update has been failed

Type:: EventType

PackageUpdated

package has been updated

Type:: EventType

ahriman.models.filesystem_package module

class FilesystemPackage(*, package_name: str, depends: set[str], opt_depends: set[str], directories: list[~pathlib.Path] = <factory>, files: list[~pathlib.Path] = <factory>)

Bases: object

class representing a simplified model for the package installed to filesystem

package_name

package name

Type:: str

depends

list of package dependencies

Type:: set[str]

directories

list of directories this package contains

Type:: set[Path]

files

list of files this package contains

Type:: list[Path]

opt_depends

list of package optional dependencies

Type:: set[str]

depends_on(package_name: str, *, include_optional: bool) → bool

check if package depends on given package name

Parameters:

package_name (str) – package name to check dependencies
include_optional (bool) – include optional dependencies to check

Returns:

True in case if the given package in the dependencies lists

Return type:

bool

is_root_package(packages: Iterable[FilesystemPackage], *, include_optional: bool) → bool

check if the package is the one of the root packages. This method checks if there are any packages which are dependency of the package and - to avoid circular dependencies - does not depend on the package. In addition, if include_optional is set to True, then it will also check optional dependencies of the package

Parameters:

packages (Iterable[FilesystemPackage]) – list of packages in which we need to search
include_optional (bool) – include optional dependencies to check

Returns:

whether this package depends on any other package in the list of packages

Return type:

bool

ahriman.models.internal_status module

class InternalStatus(*, status: BuildStatus, architecture: str | None = None, packages: Counters = Counters(total=0, unknown=0, pending=0, building=0, failed=0, success=0), repository: str | None = None, stats: RepositoryStats | None = None, version: str | None = None)

Bases: object

internal server status

status

service status

Type:: BuildStatus

architecture

repository architecture

Type:: str | None

packages

packages statuses counter object

Type:: Counters

repository

repository name

Type:: str | None

stats

repository stats

Type:: RepositoryStats | None

version

service version

Type:: str | None

classmethod from_json(dump: dict[str, Any]) → Self

construct internal status from json dump

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: internal status
Return type:: Self

view() → dict[str, Any]

generate json status view

Returns:: json-friendly dictionary
Return type:: dict[str, Any]

ahriman.models.log_handler module

class LogHandler(*values)

Bases: StrEnum

log handler as described by default configuration

Console

write logs to console

Type:: LogHandler

Syslog

write logs to syslog device /dev/null

Type:: LogHandler

Journald

write logs to journald directly

Type:: LogHandler

ahriman.models.log_record module

class LogRecord(log_record_id: LogRecordId, created: float, message: str)

Bases: object

log record

log_record_id

log record identifier

Type:: LogRecordId

created

log record creation timestamp

Type:: float

message

log record message

Type:: str

classmethod from_json(package_base: str, dump: dict[str, Any]) → Self

construct log record from the json dump

Parameters:

package_base (str) – package base for which log record belongs
dump (dict[str, Any]) – json dump body

Returns:

log record object

Return type:

Self

view() → dict[str, Any]

generate json log record view

Returns:: json-friendly dictionary
Return type:: dict[str, Any]

ahriman.models.log_record_id module

class LogRecordId(package_base: str, version: str, process_id: str = '')

Bases: object

log record process identifier

DEFAULT_PROCESS_ID

(class attribute) default process identifier

Type:: str

package_base

package base for which log record belongs

Type:: str

version

package version for which log record belongs

Type:: str

process_id

unique process identifier

Type:: str, optional

ahriman.models.metrics_timer module

class MetricsTimer

Bases: object

metrics implementation

start_time

timer start time in monotonic time

Type:: float | None

Examples

This class implements simple timer which allows to measure the time elapsed of the function. Usually it should be used like:

>>> with MetricsTimer() as timer:
>>>     do_something()
>>>     print("Time elapsed for first function: %f", timer.elapsed)
>>>     do_something_different()
>>>     print("Time elapsed for all functions: %f", timer.elapsed)

property elapsed: float

get elapsed time since the start of the timer

Returns:: time elapsed in seconds
Return type:: float
Raises:: InitializeError – in case if timer was not initialized correctly

ahriman.models.migration module

class Migration(*, index: int, name: str, steps: list[str], migrate_data: Callable[[Connection, Configuration], None])

Bases: object

migration implementation

index

migration position

Type:: int

name

migration name

Type:: str

steps

migration steps

Type:: list[str]

migrate_data

data migration callback

Type:: Callable[[Connection, Configuration], None]

ahriman.models.migration_result module

class MigrationResult(*, old_version: int, new_version: int)

Bases: object

migration result implementation model

old_version

old schema version before migrations

Type:: int

new_version

new schema version after migrations

Type:: int

validate() → None

perform version validation

Raises:: MigrationError – if old version is newer than new one or negative

property is_outdated: bool

check migration and check if there are pending migrations

Returns:: True in case if it requires migrations and False otherwise
Return type:: bool

ahriman.models.package module

class Package(*, base: str, version: str, remote: RemoteSource, packages: dict[str, PackageDescription], packager: str | None = None)

Bases: LazyLogging

package properties representation

base

package base name

Type:: str

packager

package packager if available

Type:: str | None

packages

map of package names to their properties. Filled only on load from archive

Type:: dict[str, PackageDescription

remote

package remote source if applicable

Type:: RemoteSource

version

package full version

Type:: str

Examples

Different usages of this class may generate different (incomplete) data, e.g. if instantiating class from json:

>>> package = Package.from_json(dump)

it will contain every data available in the json body. Otherwise, if generate package from local archive:

>>> package = Package.from_archive(local_path, pacman)

it will probably miss file descriptions (in case if there are multiple packages which belong to the base).

The specific class load method must be defined based on the source provided. The following methods (mostly) must be used: from_archive(), from_aur(), from_build(), from_official() for sources ahriman.models.package_source.PackageSource.Archive, ahriman.models.package_source.PackageSource.AUR, ahriman.models.package_source.PackageSource.Local and ahriman.models.package_source.PackageSource.Repository respectively:

>>> ahriman_package = Package.from_aur("ahriman")
>>> pacman_package = Package.from_official("pacman", pacman)

classmethod from_archive(path: Path, pacman: Pacman) → Self

construct package properties from package archive

Parameters:

path (Path) – path to package archive
pacman (Pacman) – alpm wrapper instance

Returns:

package properties

Return type:

Self

classmethod from_aur(name: str, packager: str | None = None, *, include_provides: bool = False) → Self

construct package properties from AUR page

Parameters:

name (str) – package name (either base or normal name)
packager (str | None, optional) – packager to be used for this build (Default value = None)
include_provides (bool, optional) – search by provides if no exact match found (Default value = False)

Returns:

package properties

Return type:

Self

classmethod from_build(path: Path, architecture: str, packager: str | None = None) → Self

construct package properties from sources directory

Parameters:

path (Path) – path to package sources directory
architecture (str) – load package for specific architecture
packager (str | None, optional) – packager to be used for this build (Default value = None)

Returns:

package properties

Return type:

Self

classmethod from_json(dump: dict[str, Any]) → Self

construct package properties from json dump

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: package properties
Return type:: Self

classmethod from_official(name: str, pacman: Pacman, packager: str | None = None, *, use_syncdb: bool = True, include_provides: bool = False) → Self

construct package properties from official repository page

Parameters:

name (str) – package name (either base or normal name)
pacman (Pacman) – alpm wrapper instance
packager (str | None, optional) – packager to be used for this build (Default value = None)
use_syncdb (bool, optional) – use pacman databases instead of official repositories RPC (Default value = True)
include_provides (bool, optional) – search by provides if no exact match found (Default value = False)

Returns:

package properties

Return type:

Self

next_pkgrel(local_version: str | None) → str | None

generate next pkgrel variable. The package release will be incremented if local_version is more or equal to the version; in this case the function will return new pkgrel value, otherwise None will be returned

Parameters:: local_version (str | None) – locally stored package version if available
Returns:: new generated package release version if any. In case if the release contains dot (e.g. 1.2), the minor part will be incremented by 1. If the release does not contain major.minor notation, the minor version equals to 1 will be appended
Return type:: str | None

pretty_print() → str

generate pretty string representation

Returns:: print-friendly string
Return type:: str

vercmp(version: str) → int

typed wrapper around pyalpm.vercmp()

Parameters:: version (str) – version to compare
Returns:: negative if current version is less than provided, positive if greater than and zero if equals
Return type:: int

view() → dict[str, Any]

generate json package view

Returns:: json-friendly dictionary
Return type:: dict[str, Any]

with_packages(packages: Iterable[Path], pacman: Pacman) → None

replace packages descriptions with ones from archives

Parameters:

packages (Iterable[Path]) – paths to package archives
pacman (Pacman) – alpm wrapper instance

property depends: list[str]

get package base dependencies

Returns:: sum of dependencies per each package
Return type:: list[str]

property depends_build: set[str]

get full list of external dependencies which has to be installed for build process

Returns:: full dependencies list used by devtools
Return type:: set[str]

property depends_check: list[str]

get package test dependencies

Returns:: sum of test dependencies per each package
Return type:: list[str]

property depends_make: list[str]

get package make dependencies

Returns:: sum of make dependencies per each package
Return type:: list[str]

property depends_opt: list[str]

get package optional dependencies

Returns:: sum of optional dependencies per each package
Return type:: list[str]

property groups: list[str]

get package base groups

Returns:: sum of groups per each package
Return type:: list[str]

property is_single_package: bool

is it possible to transform package base to single package or not

Returns:: true in case if this base has only one package with the same name
Return type:: bool

property is_vcs: bool

get VCS flag based on the package base

Returns:: True in case if package base looks like VCS package and False otherwise
Return type:: bool

property licenses: list[str]

get package base licenses

Returns:: sum of licenses per each package
Return type:: list[str]

property packages_full: list[str]

get full packages list including provides

Returns:: full list of packages which this base contains
Return type:: list[str]

ahriman.models.package_description module

class PackageDescription(*, architecture: str | None = None, archive_size: int | None = None, build_date: int | None = None, depends: list[str] = <factory>, make_depends: list[str] = <factory>, opt_depends: list[str] = <factory>, check_depends: list[str] = <factory>, description: str | None = None, filename: str | None = None, groups: list[str] = <factory>, installed_size: int | None = None, licenses: list[str] = <factory>, provides: list[str] = <factory>, url: str | None = None)

Bases: object

package specific properties

architecture

package architecture

Type:: str | None

archive_size

package archive size

Type:: int | None

build_date

package build date

Type:: int | None

check_depends

package dependencies list used for check functions

Type:: list[str]

depends

package dependencies list

Type:: list[str]

opt_depends

optional package dependencies list

Type:: list[str]

make_depends

package dependencies list used for building

Type:: list[str]

description

package description

Type:: str | None

filename

package archive name

Type:: str | None

groups

package groups

Type:: list[str]

installed_size

package installed size

Type:: int | None

licenses

package licenses list

Type:: list[str]

provides

list of provided packages

Type:: list[str]

url

package url

Type:: str | None

Examples

Unlike the ahriman.models.package.Package class, this implementation only holds properties. The recommended way to deal with it is to read data based on the source type - either json or pyalpm.Package instance:

>>> description = PackageDescription.from_json(dump)
>>>
>>> from pathlib import Path
>>> from ahriman.core.alpm.pacman import Pacman
>>> from ahriman.core.configuration import Configuration
>>> from ahriman.models.repository_id import RepositoryId
>>>
>>> configuration = Configuration()
>>> pacman = Pacman(RepositoryId("x86_64", "aur"), configuration)
>>> pyalpm_description = next(package for package in pacman.package_get("pacman"))
>>> description = PackageDescription.from_package(
>>>     pyalpm_description, Path("/var/cache/pacman/pkg/pacman-6.0.1-4-x86_64.pkg.tar.zst"))

classmethod from_aur(package: AURPackage) → Self

construct properties from AUR package model

Parameters:: package (AURPackage) – AUR package model
Returns:: package properties based on source AUR package
Return type:: Self

classmethod from_json(dump: dict[str, Any]) → Self

construct package properties from json dump

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: package properties
Return type:: Self

classmethod from_package(package: pyalpm.Package, path: Path) → Self

construct class from alpm package class

Parameters:

package (Package) – alpm generated object
path (Path) – path to package archive

Returns:

package properties based on tarball

Return type:

Self

view() → dict[str, Any]

generate json package view

Returns:: json-friendly dictionary
Return type:: dict[str, Any]

property filepath: Path | None

wrapper for filename, convert it to Path object

Returns:: path object for current filename
Return type:: Path | None

ahriman.models.package_source module

class PackageSource(*values)

Bases: StrEnum

package source for addition enumeration

Auto

automatically determine type of the source

Type:: PackageSource

Archive

source is a package archive

Type:: PackageSource

AUR

source is an AUR package for which it should search

Type:: PackageSource

Directory

source is a directory which contains packages

Type:: PackageSource

Local

source is locally stored PKGBUILD

Type:: PackageSource

Remote

source is remote (http, ftp etc…) link

Type:: PackageSource

Repository

source is official repository

Type:: PackageSource

Examples

In case if source is unknown the resolve() and the source descriptor is available method must be used:

>>> real_source = PackageSource.Auto.resolve("ahriman", configuration.repository_paths)

the code above will ensure that the presudo-source Auto will not be processed later.

resolve(source: str, paths: RepositoryPaths) → PackageSource

resolve auto into the correct type

Parameters:

source (str) – source of the package
paths (RepositoryPaths) – repository paths instance

Returns:

non-auto type of the package source

Return type:

PackageSource

ahriman.models.packagers module

class Packagers(default: str | None = None, overrides: dict[str, str | None] = <factory>)

Bases: object

holder for packagers overrides

default

default packager username if any to be used if no override for the specified base was found

Type:: str | None

overrides

dict[str, str | None]: packager username override for specific package base

Type:: dict[str, str | None]

for_base(package_base: str) → str | None

extract username for the specified package base

Parameters:: package_base (str) – package base to lookup
Returns:: package base override if set and default packager username otherwise
Return type:: str | None

ahriman.models.pacman_synchronization module

class PacmanSynchronization(*values)

Bases: IntEnum

pacman database synchronization flag

Disabled

do not synchronize local database

Type:: PacmanSynchronization

Enabled

synchronize local database (same as pacman -Sy)

Type:: PacmanSynchronization

Force

force synchronize local database (same as pacman -Syy)

Type:: PacmanSynchronization

ahriman.models.pkgbuild module

class Pkgbuild(fields: dict[str, PkgbuildPatch])

Bases: Mapping[str, Any]

model and proxy for PKGBUILD properties

DEFAULT_ENCODINGS

(class attribute) default encoding to be applied on the file content

Type:: str

fields

PKGBUILD fields

Type:: dict[str, PkgbuildPatch]

classmethod from_file(path: Path, encoding: str | None = None) → Self

parse PKGBUILD from the file

Parameters:

path (Path) – path to the PKGBUILD file
encoding (str | None, optional) – the encoding of the file (Default value = None)

Returns:

constructed instance of self

Return type:

Self

Raises:

EncodeError – if encoding is unknown

classmethod from_io(stream: IO[str]) → Self

parse PKGBUILD from input stream

Parameters:: stream (IO[str]) – input stream containing PKGBUILD content
Returns:: constructed instance of self
Return type:: Self

static local_files(path: Path) → Iterator[Path]

extract list of local files

Parameters:: path (Path) – path to package sources directory
Yields:: Path – list of paths of files which belong to the package and distributed together with this tarball. All paths are relative to the path
Raises:: PackageInfoError – if there are parsing errors

static supported_architectures(path: Path) → set[str]

load supported architectures from package sources

Parameters:: path (Path) – path to package sources directory
Returns:: list of package supported architectures
Return type:: set[str]

packages() → dict[str, Self]

extract properties from internal package functions

Returns:: map of package name to its inner properties if defined
Return type:: dict[str, Self]

property variables: dict[str, str]

list of variables defined and (maybe) used in this PKGBUILD

Returns:: map of variable name to its value. The value will be included here in case if it presented in the internal dictionary, it is not a function and the value has string type
Return type:: dict[str, str]

ahriman.models.pkgbuild_patch module

class PkgbuildPatch(key: str | None, value: str | list[str])

Bases: object

wrapper for patching PKBGUILDs

key

name of the property in PKGBUILD, e.g. version, url etc. If not set, patch will be considered as full PKGBUILD diffs

Type:: str | None

value

value of the stored PKGBUILD property. It must be either string or list of string values

Type:: str | list[str]

classmethod from_env(variable: str) → Self

construct patch from environment variable. Functions are not supported

Parameters:: variable (str) – variable in bash form, i.e. KEY=VALUE
Returns:: patch object
Return type:: Self

classmethod from_json(dump: dict[str, Any]) → Self

construct patch descriptor from the json dump

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: patch object
Return type:: Self

classmethod parse(key: str | None, source: str | list[str]) → Self

parse string value to the PKGBUILD patch value. This method simply takes string, tries to identify it as array or just string and return the respective value. Functions are returned as is. Shell arrays and single values are returned without quotes. If source is list, then value is returned as is

Parameters:

key (str | None) – variable key
source (str) – source value string to parse

Returns:

parsed patch object

Return type:

Self

static quote(source: str) → str

like shlex.quote(), but better. The difference in this method from the library one is that it uses double quotes on top level instead of single quotes to allow shell variable substitution

Parameters:: source (str) – source value string to quote
Returns:: quoted string
Return type:: str

static unquote(source: str) → str

like shlex.quote(), but opposite

Parameters:: source (str) – source string to remove quotes
Returns:: string with quotes removed
Return type:: str
Raises:: ValueError – if no closing quotation

serialize() → str

serialize key-value pair into PKGBUILD string. List values will be put inside parentheses. All string values (including the ones inside list values) will be put inside quotes, no shell variables expanding supported at the moment

Returns:: serialized key-value pair, print-friendly
Return type:: str

substitute(variables: dict[str, str]) → str | list[str]

substitute variables into the value

Parameters:: variables (dict[str, str]) – map of variables available for usage
Returns:: substituted value. All unknown variables will remain as links to their values. This function doesn’t support recursive substitution
Return type:: str | list[str]

view() → dict[str, Any]

generate json patch view

Returns:: json-friendly dictionary
Return type:: dict[str, Any]

write(pkgbuild_path: Path) → None

write serialized value into PKGBUILD by specified path

Parameters:: pkgbuild_path (Path) – path to PKGBUILD file

property is_function: bool

parse key and define whether it function or not

Returns:: True in case if key ends with parentheses and False otherwise
Return type:: bool

property is_plain_diff: bool

check if patch is full diff one or just single-variable patch

Returns:: True in case key set and False otherwise
Return type:: bool

ahriman.models.process_status module

class ProcessStatus(process_id: str, status: bool, consumed_time: float)

Bases: object

terminated process status descriptor

process_id

unique process identifier

Type:: str

status

process exit code status

Type:: bool

consumed_time

consumed time in seconds

Type:: float

ahriman.models.property module

class Property(name: str, value: Any, indent: int = 1, *, is_required: bool = False)

Bases: object

holder of object properties descriptor

name

name of the property

Type:: str

value

property value

Type:: Any

is_required

if set to True then this property is required

Type:: bool

indent

property indentation level

Type:: int

ahriman.models.remote_source module

class RemoteSource(*, source: PackageSource, git_url: str | None = None, web_url: str | None = None, path: str | None = None, branch: str | None = None)

Bases: object

remote package source properties

branch

branch of the git repository

Type:: str | None

git_url

url of the git repository

Type:: str | None

path

path to directory with PKGBUILD inside the git repository

Type:: str | None

source

package source pointer used by some parsers

Type:: PackageSource

web_url

url of the package in the web interface

Type:: str | None

classmethod from_json(dump: dict[str, Any]) → Self

construct remote source from the json dump (or database row)

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: remote source
Return type:: Self

git_source() → tuple[str, str]

get git source if available

Returns:: git url and branch
Return type:: tuple[str, str]
Raises:: InitializeError – in case if git url and/or branch are not set

view() → dict[str, Any]

generate json package remote view

Returns:: json-friendly dictionary
Return type:: dict[str, Any]

property is_remote: bool

check if source is remote

Returns:: True in case if package is well-known remote source (e.g. AUR) and False otherwise
Return type:: bool

property pkgbuild_dir: Path | None

get path to directory with package sources (PKGBUILD etc.)

Returns:: path to directory with package sources based on settings if available
Return type:: Path | None

ahriman.models.report_settings module

class ReportSettings(*values)

Bases: StrEnum

report targets enumeration

Disabled

option which generates no report for testing purpose

Type:: ReportSettings

HTML

html report generation

Type:: ReportSettings

Email

email report generation

Type:: ReportSettings

Console

print result to console

Type:: ReportSettings

Telegram

markdown report to telegram channel

Type:: ReportSettings

RSS

RSS report generation

Type:: ReportSettings

RemoteCall

remote ahriman server call

Type:: ReportSettings

static from_option(value: str) → ReportSettings

construct value from configuration

Parameters:: value (str) – configuration value
Returns:: parsed value
Return type:: ReportSettings

ahriman.models.repository_id module

class RepositoryId(architecture: str, name: str)

Bases: object

unique identifier of the repository

architecture

repository architecture

Type:: str

name

repository name

Type:: str

query() → list[tuple[str, str]]

generate query parameters

Returns:: json view as query parameters
Return type:: list[tuple[str, str]]

view() → dict[str, Any]

generate json package view

Returns:: json-friendly dictionary
Return type:: dict[str, Any]

property id: str

get repository id to be used for databases

Returns:: unique id for this repository
Return type:: str
Raises:: ValueError – if repository identifier is empty

property is_empty: bool

check if all data is supplied for the loading

Returns:: True in case if architecture or name are not set and False otherwise
Return type:: bool

ahriman.models.repository_paths module

class RepositoryPaths(root: Path, repository_id: RepositoryId, *, _force_current_tree: bool = False)

Bases: LazyLogging

repository paths holder. For the most operations with paths you want to use this object

repository_id

repository unique identifier

Type:: RepositoryId

root

repository root (i.e. ahriman home)

Type:: Path

Examples

This class can be used in order to access the repository tree structure:

>>> paths = RepositoryPaths(Path("/var/lib/ahriman"), RepositoryId("x86_64", "aur"))

Additional methods can be used in order to ensure that tree is created:

>>> paths.tree_create()

Access to directories inside can be done by either using properties or specifying the package base:

>>> cache_dir = paths.cache
>>> ahriman_cache_dir = paths.cache_for("ahriman")

classmethod known_architectures(root: Path, name: str = '') → set[str]

get known architecture names

Parameters:

root (Path) – repository root
name (str, optional) – repository name (Default value = “”)

Returns:

list of repository architectures for which there is created tree

Return type:

set[str]

classmethod known_repositories(root: Path) → set[str]

get known repository names

Parameters:: root (Path) – repository root
Returns:: list of repository names for which there is created tree. Returns empty set in case if repository is loaded in legacy mode
Return type:: set[str]

archive_for(package_base: str) → Path

get path to archive specified search criteria

Parameters:: package_base (str) – package base name
Returns:: path to archive directory for package base
Return type:: Path

cache_for(package_base: str) → Path

get path to cached PKGBUILD and package sources for the package base

Parameters:: package_base (str) – package base name
Returns:: full path to directory for specified package base cache
Return type:: Path

ensure_exists(directory: Path) → Path

get path based on directory callable provided and ensure it exists

Parameters:: directory (Path) – path to directory to check
Returns:: original path based on extractor provided. Directory will always exist
Return type:: Path

Examples

This method calls directory accessor and then checks if there is a directory and - otherwise - creates it:

>>> paths.ensure_exists(paths.archive_for(package_base))

preserve_owner() → Iterator[None]

perform any action preserving owner for any newly created file or directory

Examples

This method is designed to use as context manager when you are going to perform operations which might change filesystem, especially if you are doing it under unsafe flag, e.g.:

>>> with paths.preserve_owner():
>>>     paths.tree_create()

Note, however, that this method doesn’t handle any exceptions and will eventually interrupt if there will be any.

tree_clear(package_base: str) → None

clear package specific files

Parameters:: package_base (str) – package base name

tree_create() → None: create ahriman working tree

property archive: Path

archive directory root

Returns:: archive directory root
Return type:: Path

property build_root: Path

same as chroot, but exactly build chroot

Returns:: path to directory in which build process is run
Return type:: Path

property cache: Path

get directory for packages cache (mainly used for VCS packages)

Returns:: full path to cache directory
Return type:: Path

property chroot: Path

get directory for devtools chroot

Returns:: full patch to devtools chroot directory
Return type:: Path

property packages: Path

get directory for built packages

Returns:: full path to built packages directory
Return type:: Path

property pacman: Path

get directory for pacman local package cache

Returns:: full path to pacman local database cache
Return type:: Path

property repository: Path

get repository directory

Returns:: full path to the repository directory
Return type:: Path

property root_owner: tuple[int, int]

get UID and GID of the root directory

Returns:: owner user and group of the root directory
Return type:: tuple[int, int]

ahriman.models.repository_stats module

class RepositoryStats(*, bases: int, packages: int, archive_size: int, installed_size: int)

Bases: object

repository stats representation

classmethod from_json(dump: dict[str, Any]) → Self

construct counters from json dump

Parameters:: dump (dict[str, Any]) – json dump body
Returns:: status counters
Return type:: Self

classmethod from_packages(packages: list[Package]) → Self

construct statistics from list of repository packages

Parameters:: packages (list[Packages]) – list of repository packages
Returns:: constructed statistics object
Return type:: Self

ahriman.models.result module

class Result(*, added: Iterable[Package] | None = None, updated: Iterable[Package] | None = None, removed: Iterable[Package] | None = None, failed: Iterable[Package] | None = None)

Bases: object

build result class holder

STATUS_PRIORITIES

(class attribute) list of statues according to their priorities

Type:: list[str]

Parameters:

added (Iterable[Package] | None, optional) – initial list of successfully added packages (Default value = None)
updated (Iterable[Package] | None, optional) – initial list of successfully updated packages (Default value = None)
removed (Iterable[Package] | None, optional) – initial list of successfully removed packages (Default value = None)
failed (Iterable[Package] | None, optional) – initial list of failed packages (Default value = None)

add_added(package: Package) → None

add new package to new packages list

Parameters:: package (Package) – package removed

add_failed(package: Package) → None

add new package to failed built

Parameters:: package (Package) – package with errors during build

add_removed(package: Package) → None

add new package to removed list

Parameters:: package (Package) – package removed

add_updated(package: Package) → None

add new package to success built

Parameters:: package (Package) – package built

merge(other: Result) → Self

merge other result into this one. This method assumes that other has fresh info about status and override it

Parameters:: other (Result) – instance of the newest result
Returns:: updated instance
Return type:: Self

refine() → Self

merge packages between different results (e.g. remove failed from added, etc.) removing duplicates

Returns:: updated instance
Return type:: Self

property failed: list[Package]

get list of failed packages

Returns:: list of packages which were failed
Return type:: list[Package]

property is_empty: bool

get if build result is empty or not

Returns:: True in case if success list is empty and False otherwise
Return type:: bool

property removed: list[Package]

get list of removed packages

Returns:: list of packages successfully removed
Return type:: list[Package]

property success: list[Package]

get list of success builds

Returns:: list of packages with success result
Return type:: list[Package]

ahriman.models.scan_paths module

class ScanPaths(paths: list[str])

Bases: object

paths used for scan filesystem

paths

list of regular expressions to be used to match paths

Type:: list[str]

is_allowed(path: Path) → bool

check whether path is allowed to scan or not

Parameters:: path (Path) – path to be checked
Returns:: True in case if paths contains at least one element to which the path is matched and False otherwise
Return type:: bool

property patterns: list[Pattern[str]]

compiled regular expressions

Returns:: a list of compiled regular expressions
Return type:: list[re.Pattern]

ahriman.models.series_statistics module

class SeriesStatistics(series: list[float | int])

Bases: object

series statistics helper

series

list of values to be processed

Type:: list[float | int]

property max: float | int | None

get max value in series

Returns:: None if series is empty and maximal value otherwise``
Return type:: float | int | None

property mean: float | int | None

get mean value in series

Returns:: None if series is empty and mean value otherwise
Return type:: float | int | None

property min: float | int | None

get min value in series

Returns:: None if series is empty and minimal value otherwise
Return type:: float | int | None

property st_dev: float | None

get standard deviation in series

Returns:: None if series size is less than 1, 0 if series contains single element and standard deviation otherwise
Return type:: float | None

property total: int

retrieve amount of elements

Returns:: the series collection size
Return type:: int

ahriman.models.sign_settings module

class SignSettings(*values)

Bases: StrEnum

sign targets enumeration

Disabled

option which generates no report for testing purpose

Type:: SignSettings

Packages

sign each package

Type:: SignSettings

Repository

sign repository database file

Type:: SignSettings

static from_option(value: str) → SignSettings

construct value from configuration

Parameters:: value (str) – configuration value
Returns:: parsed value
Return type:: SignSettings

ahriman.models.smtp_ssl_settings module

class SmtpSSLSettings(*values)

Bases: StrEnum

SMTP SSL mode enumeration

Disabled

no SSL enabled

Type:: SmtpSSLSettings

SSL

use SMTP_SSL instead of normal SMTP client

Type:: SmtpSSLSettings

STARTTLS

use STARTTLS in normal SMTP client

Type:: SmtpSSLSettings

static from_option(value: str) → SmtpSSLSettings

construct value from configuration

Parameters:: value (str) – configuration value
Returns:: parsed value
Return type:: SmtpSSLSettings

ahriman.models.upload_settings module

class UploadSettings(*values)

Bases: StrEnum

remote synchronization targets enumeration

Disabled

no sync will be performed, required for testing purpose

Type:: UploadSettings

Rsync

sync via rsync

Type:: UploadSettings

S3

sync to Amazon S3

Type:: UploadSettings

GitHub

sync to GitHub releases page

Type:: UploadSettings

RemoteService

sync to another ahriman instance

Type:: UploadSettings

static from_option(value: str) → UploadSettings

construct value from configuration

Parameters:: value (str) – configuration value
Returns:: parsed value
Return type:: UploadSettings

ahriman.models.user module

class User(*, username: str, password: str, access: UserAccess, packager_id: str | None = None, key: str | None = None)

Bases: object

authorized web user model

SUPPORTED_ALGOS

(class attribute) list of the supported hashing algorithms

Type:: set[str]

username

username

Type:: str

password

hashed user password with salt

Type:: str

access

user role

Type:: UserAccess

packager_id

packager id to be used. If not set, the default service packager will be used

Type:: str | None

key

personal packager key if any. If user id is empty, it is interpreted as default key

Type:: str | None

Examples

Simply create user from database data and perform required validation:

>>> password = User.generate_password(24)
>>> user = User(username="ahriman", password=password, access=UserAccess.Full)

Since the password supplied may be plain text, the hash_password() method can be used to hash the password:

>>> user = user.hash_password("salt")

Having the user instance and password, it can be validated:

>>> if user.check_credentials(password, "salt"):
>>>     print("password is valid")
>>> else:
>>>     print("password is invalid")

…and finally access can be verified:

>>> if user.verify_access(UserAccess.Read):
>>>     print(f"user {user.username} has read access")

static generate_password(length: int) → str

generate password with specified length

Parameters:: length (int) – password length
Returns:: random string which contains letters and numbers
Return type:: str

check_credentials(password: str, salt: str) → bool

validate user password

Parameters:

password (str) – entered password
salt (str) – salt for hashed password

Returns:

True in case if password matches, False otherwise

Return type:

bool

Raises:

ValueError – if user password is set to unsupported algorithm

hash_password(salt: str) → Self

generate hashed password from plain text

Parameters:: salt (str) – salt for hashed password
Returns:: user with hashed password to store in configuration
Return type:: Self

verify_access(required: UserAccess) → bool

validate if user has access to requested resource

Parameters:: required (UserAccess) – required access level
Returns:: True in case if user is allowed to do this request and False otherwise
Return type:: bool

property algo: str | None

extract algorithm used for the hashing password

Returns:: first part of password hash (e.g. $2$ ) if available or None otherwise
Return type:: str | None

ahriman.models.user_access module

class UserAccess(*values)

Bases: StrEnum

web user access enumeration

Unauthorized

user can access specific resources which are marked as available without authorization (e.g. login, logout, static)

Type:: UserAccess

Read

user can read the page

Type:: UserAccess

Reporter

user can read everything and is able to perform some modifications

Type:: UserAccess

Full

user has full access

Type:: UserAccess

permits(other: UserAccess) → bool

compare enumeration between each other and check if current permission allows the other

Parameters:: other (UserAccess) – other permission to compare
Returns:: True in case if current permission allows the operation and False otherwise
Return type:: bool

ahriman.models.waiter module

class Waiter(wait_timeout: float, *, interval: float = 10)

Bases: object

simple waiter implementation

interval

interval in seconds between checks

Type:: float

wait_timeout

timeout in seconds to wait for. Negative value will result in immediate exit. Zero value means infinite timeout

Type:: float

is_timed_out(elapsed: float) → bool

check if timer is out

elapsed

elapsed time in seconds

Type:: float

Returns:: True in case current monotonic time is more than start_time and wait_timeout doesn’t equal to 0
Return type:: bool

wait(in_progress: ~collections.abc.Callable[[~Params], bool], *args: ~typing.~Params, **kwargs: ~typing.~Params) → WaiterResult

wait until requirements are not met

Parameters:

in_progress (Callable[Params, bool]) – function to check if timer should wait for another cycle
*args (Params.args) – positional arguments for check call
**kwargs (Params.kwargs) – keyword arguments for check call

Returns:

waiter result object

Return type:

WaiterResult

class WaiterResult(took: float)

Bases: object

representation of a waiter result. This class should not be used directly, use derivatives instead

took

consumed time in seconds

Type:: float

class WaiterTaskFinished(took: float)

Bases: WaiterResult

a waiter result used to notify that the task has been completed successfully

class WaiterTimedOut(took: float)

Bases: WaiterResult

a waiter result used to notify that the waiter run out of time

ahriman.models.worker module

class Worker(address: str, *, identifier: str = '')

Bases: object

worker descriptor

address

worker address to be reachable outside

Type:: str

identifier

worker unique identifier. If none set it will be automatically generated from the address

Type:: str

view() → dict[str, Any]

generate json patch view

Returns:: json-friendly dictionary
Return type:: dict[str, Any]

ahriman.models package

Submodules

ahriman.models.action module

ahriman.models.aur_package module

ahriman.models.auth_settings module

ahriman.models.build_status module

ahriman.models.changes module

ahriman.models.context_key module

ahriman.models.counters module

ahriman.models.dependencies module

ahriman.models.event module

ahriman.models.filesystem_package module

ahriman.models.internal_status module

ahriman.models.log_handler module

ahriman.models.log_record module

ahriman.models.log_record_id module

ahriman.models.metrics_timer module

ahriman.models.migration module

ahriman.models.migration_result module

ahriman.models.package module

ahriman.models.package_description module

ahriman.models.package_source module

ahriman.models.packagers module

ahriman.models.pacman_synchronization module

ahriman.models.pkgbuild module

ahriman.models.pkgbuild_patch module

ahriman.models.process_status module

ahriman.models.property module

ahriman.models.remote_source module

ahriman.models.report_settings module

ahriman.models.repository_id module

ahriman.models.repository_paths module

ahriman.models.repository_stats module

ahriman.models.result module

ahriman.models.scan_paths module

ahriman.models.series_statistics module

ahriman.models.sign_settings module

ahriman.models.smtp_ssl_settings module

ahriman.models.upload_settings module

ahriman.models.user module

ahriman.models.user_access module

ahriman.models.waiter module

ahriman.models.worker module

Module contents