# mini_buildd.api module

API arguments and calls

Attention

Call handshake: In production, we occasionally see `W: Remote handshake failed for ...: 'tuple' object has no attribute 'signatures'`. Reproduce?

Attention

Call debmirror (external workarounds): `apt update` fails on `experimental` suites (contents not mirrored) (Debian Bug #819925)

This happens only on systems where APT is configured to download contents, most likely just because `apt-file` is installed. So, the easiest workaround is:

    apt purge apt-file

Closest to an actual fix is to install debmirror variant ‘+abfixes’ from `Hellfield Archive`, where the “bug” has been fixed (June 2023: at least available for bullseye and bookworm).

Note

Call stop: Ongoing `PACKAGING` or `BUILDING` are lost on restart

Stopping/restarting an instance will make ongoing `BUILDING` or `PACKAGING` fail – you need to API call ‘retry’ the whole (no-longer ongoing) `PACKAGING` then (from the repository instance).

It’s probably wise not to do unattended upgrades of the mini-buildd Debian package on heavily used production systems.

Note

Call keyring-packages: No compat for urold <= squeeze (`apt-key add`)

Since `2.x`, keyring packages will use `/etc/apt/trusted.gpg.d/<foo>.gpg`, not deprecated `apt-key add <foo>`.

In Debian, this is supported since `wheezy (2013)`.

For distributions `<= squeeze` (apt versions `~<= 0.8.x`), you would manually have to run `apt-key add /etc/apt/trusted.gpg.d/<foo>.gpg` after installation of the keyring package.

Note

Call keyring-packages: squeeze or older only: apt secure problems after initial (unauthorized) install of the archive-key package (Debian Bug #657561)

- aptitude always shows <NULL> archive

You can verify this problem via:

    # aptitude -v show YOURID-archive-keyring | grep ^Archive
    Archive: <NULL>, now

- BADSIG when verifying the archive keyring package’s signature

Both might be variants of Debian bug above (known to occur for <= squeeze). For both, check if this:

    # rm -rf /var/lib/apt/lists/*
    # apt-get update

fixes it.

class mini_buildd.api.Argument(id_list, doc='Undocumented', default=None, choices=None, header=None)

  Bases: `object`

  Generic Argument Class

  `value()` always provides a non-`None` value of the specific type, either the `default` or a `given` value.

  `strvalue()` always provides a non-`None` `str` value.

  The `default` value is given in the constructor. For server-specific defaults, this may be function – then the default value will be computed only at run time on the server.

  A `given` value can be provided via special `set()` method:

    - Empty `str`, `list` or false `bool` will yield `None`.

    - Non-empty `str` will be converted to the specific type.

    - Other given values will be used as is.

  Type | value() type | svalue() ex. | HTML GET | argparse
  --- | --- | --- | --- | ---
  Str | str | “string” | key=string | –key “string”
  Url | str | “http://..” | key=string | –key “string”
  MultilineStr | str | “long” | key=string | –key “string”
  Choice | str | “c0” | key=string | –key “string”
  Int | int | “17” | key=string | –key “int”
  Bool | bool | “True” | key=True | –key
  List | list of str | “v0,v1,..” | key=v0,v1.. | –key “v0” “v1”..

  HTML_TYPE = None
  HTML_SYNTAX = None
  VALUE_TYPE

    Validate that values are actually of that type

    alias of `str`

  SERVER_DEFAULT = '<server_default>'

    Magic string value to use as value when a default callable on the server should be used.

  classmethod s2v(str_value)

    Convert string to value

  classmethod v2s(value)

    Convert value to string

  required()
  needs_value()

    If user input is no_value

  choices()
  default()
  strdefault()
  value()
  strvalue()
  strgiven()
  icommand_line_given()
  set(given)
  argparse_kvsargs()

    Python ‘argparse’ support

  usage()

class mini_buildd.api.StrArgument(id_list, doc='Undocumented', default=None, choices=None, header=None)

  Bases: `Argument`

  HTML_TYPE = 'text'
  HTML_SYNTAX = 'Plain string'
  argparse_kvsargs()

    Python ‘argparse’ support

class mini_buildd.api.UrlArgument(id_list, doc='Undocumented', default=None, choices=None, header=None)

  Bases: `StrArgument`

  HTML_TYPE = 'url'
  HTML_SYNTAX = 'URL string'

class mini_buildd.api.MultilineStrArgument(id_list, doc='Undocumented', default=None, choices=None, header=None)

  Bases: `StrArgument`

  HTML_TYPE = 'textarea'
  HTML_SYNTAX = 'Multiline string'

class mini_buildd.api.ChoiceArgument(id_list, doc='Undocumented', default=None, choices=None, header=None)

  Bases: `Argument`

  HTML_TYPE = 'select'
  HTML_SYNTAX = 'Choice'
  value()
  argparse_kvsargs()

    Python ‘argparse’ support

class mini_buildd.api.IntArgument(id_list, doc='Undocumented', default=None, choices=None, header=None)

  Bases: `StrArgument`

  VALUE_TYPE

    alias of `int`

  HTML_TYPE = 'number'
  HTML_SYNTAX = 'Integer number'
  argparse_kvsargs()

    Python ‘argparse’ support

class mini_buildd.api.BoolArgument(*args, **kwargs)

  Bases: `ChoiceArgument`

  VALUE_TYPE

    alias of `bool`

  HTML_TYPE = 'checkbox'
  HTML_SYNTAX = 'Checkbox'
  classmethod s2v(str_value)

    Convert string to value

  icommand_line_given()

    Empty generator – bools are just command line options like `--with-foo`

  argparse_kvsargs()

    Python ‘argparse’ support

class mini_buildd.api.ListArgument(id_list, doc='Undocumented', default=None, choices=None, header=None)

  Bases: `StrArgument`

  VALUE_TYPE

    alias of `list`

  SEPARATOR = ','
  HTML_SYNTAX = 'List as comma-separated strings'
  classmethod s2v(str_value)

    Convert string to value

  classmethod v2s(value)

    Convert value to string

  icommand_line_given()
  argparse_kvsargs()

    Python ‘argparse’ support

class mini_buildd.api.Repository(id_list, **kwargs)

  Bases: `StrArgument`

  object()

class mini_buildd.api.Repositories(id_list, **kwargs)

  Bases: `ListArgument`

  objects()

class mini_buildd.api.Codenames(id_list, **kwargs)

  Bases: `ListArgument`

mini_buildd.api.diststr2repository(diststr)

class mini_buildd.api.Distribution(id_list, choices=<functools._lru_cache_wrapper object>, extra_doc='', **kwargs)

  Bases: `StrArgument`

  dist()

class mini_buildd.api.Distributions(id_list, choices=<functools._lru_cache_wrapper object>, **kwargs)

  Bases: `ListArgument`

class mini_buildd.api.Source(id_list, extra_doc='', **kwargs)

  Bases: `StrArgument`

class mini_buildd.api.UploadOptions(id_list, **kwargs)

  Bases: `StrArgument`

class mini_buildd.api.Output

  Bases: `ChoiceArgument`

  Meta API call option ‘output’

class mini_buildd.api.Rollbacks(id_list, extra_doc='', **kwargs)

  Bases: `IntArgument`

  range(suite)

    Get valid range for this suite

class mini_buildd.api.Call(**kwargs)

  Bases: `object`

  AUTH = <mini_buildd.config.Auth object>
  NEEDS_RUNNING_DAEMON = False
  CONFIRM = False
  RESULT_DESC = ''
  CATEGORY = 'Consumer'
  classmethod name()
  classmethod doc()
  classmethod doc_title()
  classmethod doc_body()
  classmethod uri()
  classmethod iarguments()
  classmethod from_sloppy_args(**kwargs)

    Construct ignoring any unknown arguments given

  set_args(**kwargs)
  classmethod from_command_line(command_line)
  set_request(request)
  classmethod get_plain(result, force_json=False)

    Get `str` result (non-`str` results get json pretty-formatted)

  plain(force_json=False)
  json_pretty()

    For (arg-less) use in templates only

  classmethod parse_command_line(command_line)
  icommand_line(full=False, with_user=False, user=None, exclude=None)
  command_line(full=False, with_user=False, user=None, exclude=None)
  command_line_full()
  http_args(with_confirm=False, with_output=None)
  url(endpoint=None, with_confirm=False, with_output='html', relative=False)
  url_relative()
  run()

class mini_buildd.api.Status(**kwargs)

  Bases: `Call`

  Get status of this instance

  RESULT_DESC = '{\n "version": mini-buildd\'s version\n "identity": Instance identity\n "url": Instance URL (HTTP)\n "incoming_url": Incoming URL (currently FTP)\n "load": Instance\'s (0 =< load <= 1). If negative, the instance is stopped\n "chroots": List of active chroots\n "remotes": Active or auto-reactivatable remotes\n ["repositories": Simplified structural representation of all repositories]\n}\n'
  classmethod iarguments()

class mini_buildd.api.PubKey(**kwargs)

  Bases: `Call`

  Get ASCII-armored GnuPG public key of this instance

  Used to sign the APT repositories (‘APT key’) and for authorization across instances.

  See `Customer's Manual, APT Bootstrap` for ways to employ the APT key on yor local system.

class mini_buildd.api.DputConf(**kwargs)

  Bases: `Call`

  Get recommended dput config snippet

  Usually, this is for integration in your personal `~/.dput.cf` (which will work for both, `dput` and `dput-ng`).

  Administrators may add custom site targets via `~mini-buildd/etc/dput.cf`.

  classmethod iarguments()

class mini_buildd.api.SourcesList(**kwargs)

  Bases: `Call`

  Get sources.list (apt lines)

  Usually, this output is put to a file like `/etc/apt/sources.list.d/mini-buildd-xyz.list`.

  classmethod iarguments()

class mini_buildd.api.Ls(**kwargs)

  Bases: `Call`

  List source package in repository

  classmethod iarguments()

class mini_buildd.api.Show(**kwargs)

  Bases: `Ls`

  Show source package in repository

class mini_buildd.api.Search(**kwargs)

  Bases: `Call`

  Search for source or binary package names in `repositories`, `builds` and `events`

  Be cautious with binary package files found outside of `repositories`:

  - Matches only found in `builds` usually failed installation as some criteria is not met.

  - Matches found in `events` originate from the initial (non source-only) user upload (and thus are local builds).

  EMPTY_RESULT = {'builds': [], 'events': [], 'repositories': []}
  MSG = {'builds': 'Binary packages maybe not installed/some criteria not met', 'events': 'Be cautious: Binary package originates from user upload (local build)', 'repositories': 'In repository, safe to use'}
  classmethod iarguments()

class mini_buildd.api.Debdiff(**kwargs)

  Bases: `Call`

  Compare two internal source packages

  classmethod iarguments()

class mini_buildd.api.Migrate(**kwargs)

  Bases: `_Staff`, `_Confirm`, `_CatDeveloper`, `Call`

  Migrate source package

  Migrates a source package along with all its binary packages. If run for a rollback distribution, this will perform a rollback restore.

  classmethod iarguments()

class mini_buildd.api.Remove(**kwargs)

  Bases: `_Admin`, `_Confirm`, `_CatAdministrator`, `Call`

  Remove source package

  Removes a source package along with all its binary packages.

  classmethod iarguments()

class mini_buildd.api.Port(**kwargs)

  Bases: `_Staff`, `_Running`, `_Confirm`, `_CatDeveloper`, `Call`

  Port internal source package

  An internal ‘port’ is a no-changes (i.e., only the changelog will be adapted) rebuild of the given locally-installed package.

  When `from_distribution` equals `to_distribution`, a rebuild will be done.

  classmethod iarguments()

class mini_buildd.api.PortExt(**kwargs)

  Bases: `_Staff`, `_Running`, `_Confirm`, `_CatDeveloper`, `Call`

  Port external source package

  An external ‘port’ is a no-changes (i.e., only the changelog will be adapted) rebuild of any given source package.

  classmethod iarguments()

class mini_buildd.api.Retry(**kwargs)

  Bases: `_Staff`, `_Running`, `_Confirm`, `_CatDeveloper`, `Call`

  Retry a previously failed source package

  RESULT_DESC = 'Changes file name that has been re-uploaded'
  BKEY_FORMAT = '<source>/<version>/<timecode>/source[ <arch>]'
  BKEY_REGEX = re.compile('[^/]+/[^/]+/[^/]+/[^/]+')
  classmethod iarguments()

class mini_buildd.api.Cancel(**kwargs)

  Bases: `_Staff`, `_Running`, `_Confirm`, `_CatDeveloper`, `Call`

  Cancel an ongoing package build

  classmethod iarguments()

class mini_buildd.api.SetUserKey(**kwargs)

  Bases: `_Login`, `_Confirm`, `_CatDeveloper`, `Call`

  Set a user’s GnuPG public key

  classmethod iarguments()

class mini_buildd.api.Subscribe(**kwargs)

  Bases: `_Login`, `Call`

  Subscribe to (email) notifications

  classmethod iarguments()

class mini_buildd.api.Unsubscribe(**kwargs)

  Bases: `Subscribe`

  Unsubscribe from (email) notifications

class mini_buildd.api.RemakeChroots(**kwargs)

  Bases: `_Admin`, `_Confirm`, `_Maintenance`, `_CatAdministrator`, `Call`

  Remake chroots

  Run actions ‘remove’, ‘prepare’, ‘check’ and ‘activate’.

  classmethod iarguments()

class mini_buildd.api.Reindex(**kwargs)

  Bases: `_Admin`, `_Confirm`, `_Maintenance`, `_CatAdministrator`, `Call`

  Force repository reindex

  Usually, you reindex by doing an explicit `check` on a Repository instance – however, that method would not reindex in case the repository config is unchanged. Use this call if you feel you need it anyway for whatever reason.

  If you just upgraded from 2.2.x, it’s recommended to run it once (2.4.x reindex additionally runs `repreprop flood`, which may make some arch=all packages available for (subsequently) added architectures).

  classmethod iarguments()

class mini_buildd.api.Start(**kwargs)

  Bases: `_Admin`, `_Confirm`, `_CatAdministrator`, `Call`

  Start Daemon (accept incoming)

  Does nothing if already started; will fail if Daemon instance is not activated.

class mini_buildd.api.Stop(**kwargs)

  Bases: `_Admin`, `_Confirm`, `_CatAdministrator`, `Call`

  Stop Daemon (stop accepting incoming)

  Does nothing if already stopped. Any ongoing events will be CANCELED.

  This state is not persisted. Please deactivate the Daemon instance via mini-buildd’s ‘setup’ page to persist over mini-buildd service restarts.

class mini_buildd.api.Wake(**kwargs)

  Bases: `_Staff`, `_Confirm`, `_CatDeveloper`, `Call`

  Wake a remote instance

  classmethod iarguments()

class mini_buildd.api.Handshake(**kwargs)

  Bases: `_CatAdministrator`, `Call`

  Check if signed message matches a remote, reply our signed message on success

  This is for internal use only.

  classmethod iarguments()

class mini_buildd.api.Cronjob(**kwargs)

  Bases: `_Admin`, `_Confirm`, `_CatAdministrator`, `Call`

  Run a cron job now (out of schedule)

  classmethod iarguments()

class mini_buildd.api.Uploaders(**kwargs)

  Bases: `_Admin`, `_Running`, `_CatAdministrator`, `Call`

  Get upload permissions for repositories

  classmethod iarguments()

class mini_buildd.api.SnapshotLs(**kwargs)

  Bases: `_Running`, `Call`

  Get list of repository snapshots for a distribution

  classmethod iarguments()

class mini_buildd.api.SnapshotCreate(**kwargs)

  Bases: `_Admin`, `_Confirm`, `_CatAdministrator`, `SnapshotLs`

  Create a repository snapshot

  classmethod iarguments()

class mini_buildd.api.SnapshotDelete(**kwargs)

  Bases: `SnapshotCreate`

  Delete a repository snapshot

class mini_buildd.api.Debmirror(**kwargs)

  Bases: `_Admin`, `_Confirm`, `_CatAdministrator`, `Call`

  Make local partial repository mirror via Debian package ‘debmirror’

  This may be useful if you plan on publishing a stripped-down (f.e., only certain repos, only `stable`, omit rollbacks) variant of your repo somewhere remote.

  PROGRAM = '/usr/bin/debmirror'
  DEB = 'debmirror'
  classmethod iarguments()

class mini_buildd.api.KeyringPackages(**kwargs)

  Bases: `_Admin`, `_Running`, `_Confirm`, `_CatAdministrator`, `Call`

  Build keyring packages

  classmethod iarguments()

class mini_buildd.api.TestPackages(**kwargs)

  Bases: `_Admin`, `_Running`, `_Confirm`, `_CatAdministrator`, `Call`

  Build test packages

  classmethod iarguments()

class mini_buildd.api.Setup(**kwargs)

  Bases: `_Admin`, `_Confirm`, `_Maintenance`, `_CatAdministrator`, `Call`

  Create, update or inspect your setup

  classmethod iarguments()
  class Report(result)

    Bases: `dict`

    SEVERITY_MESSAGES = {0: 'No issues found', 1: 'Notable issues found', 2: 'Warnings found', 3: 'Errors found'}
  classmethod report_path()
  classmethod report_load()
  report_save()
  class Instance(_call, model, options, update_args, **identifiers)

    Bases: `object`

    class Status(*values)

      Bases: `Enum`

      MISSING = 1
      EXISTS = 2
      ACTIVE = 3
      CHANGED = 4
      FAILED = 5
      DEACTIVATED = 6
    REPORT_STATUS = {Status.CHANGED: 2, Status.DEACTIVATED: 1, Status.FAILED: 3, Status.MISSING: 2}

      Report instances for these statuses with given severity

    diff()

      Overload/expand this for additional custom diffs

    update()
  classmethod ilocal_archive_urls()
  classmethod iapt_cacher_archive_urls()
  class Dists(items=None)

    Bases: `dict`

    classmethod iexpand_arch(arch)
    classmethod iexpand_archs(archs)
    set(codename, archs)
    as_argument_value()
    merge(dists)
  classmethod setup_inspect()
  classmethod setup_extend()

class mini_buildd.api.Calls

  Bases: `OrderedDict`

  Automatically collect all calls defined in this module, and make them accessible