SourceMirror - Base source mirror class

The SourceMirror plugin allows one to customize how Source.translate_url() will behave when looking up mirrors, allowing some additional flexibility in the implementation of source mirrors.

Abstract Methods

For loading and configuration purposes, SourceMirrors may optionally implement the Plugin base class Plugin.configure() method in order to load any custom configuration in the config dictionary.

The remaining Plugin base class abstract methods are not relevant to the SourceMirror plugin object and need not be implemented.

SourceMirrors expose the following abstract methods. Unless explicitly mentioned, these methods are mandatory to implement.

  • SourceMirror.translate_url()

    Produce an appropriate URL for the given URL and alias.

Class Reference

exception SourceMirrorError(message: str, *, detail: str | None = None, reason: str | None = None, temporary: bool = False)

Bases: BstError

This exception should be raised by SourceMirror implementations to report errors to the user.

Parameters:

  • message – The breif error description to report to the user

  • detail – A possibly multiline, more detailed error message

  • reason – An optional machine readable reason string, used for test cases

Since: 2.2

class SourceMirror

Bases: Plugin

Base SourceMirror class.

All SourceMirror plugins derive from this class, this interface defines how the core will be interacting with SourceMirror plugins.

Since: 2.2

BST_MIN_VERSION: str | None = '2.2'

The minimum required version of BuildStream required by this plugin.

The version must be expressed as the string “<major>.<minor>”, where the major version number is the API version and the minor version number is the revision of the same BuildStream API where new symbols might have been added to the API.

Example:

The following statement means that this plugin works with BuildStream 2.X, only if X >= 2:

class Foo(Source):

    # Our plugin requires 2.2
    BST_MIN_VERSION = "2.2"

Note

This version works exactly the same was as the min-version which must be specified in the project.conf file.

set_supported_aliases(aliases: List[str])

Set the aliases for which self can translate urls.

Parameters:

aliases – The list of aliases supported by this plugin

translate_url(*, alias: str, alias_url: str, source_url: str, extra_data: Dict[str, Any] | None) → str

Produce an alternative url for url for the given alias.

This method implements the behavior of Source.translate_url().

Parameters:

  • alias – The alias to translate for

  • alias_url – The default URL configured for this alias in the originating project

  • source_url – The URL as specified by original source YAML, excluding the alias

  • extra_data – An optional extra dictionary to return additional data