mach package

Subpackages

Submodules

mach.base module

class mach.base.CommandContext(cwd: str, settings=None, log_manager=None, commands=None, **kwargs)

Bases: object

Holds run-time state so it can easily be passed to command providers.

exception mach.base.FailedCommandError(message, exit_code=1, reason='')

Bases: Exception

Raised by commands to signal a handled failure to be printed by mach

When caught by mach a FailedCommandError will print message and exit with ‘’exit_code’’. The optional ‘’reason’’ is a string in cases where other scripts may wish to handle the exception, though this is generally intended to communicate failure to mach.

exception mach.base.MachError

Bases: Exception

Base class for all errors raised by mach itself.

exception mach.base.MissingFileError

Bases: MachError

Attempted to load a mach commands file that doesn’t exist.

exception mach.base.NoCommandError(namespace)

Bases: MachError

No command was passed into mach.

exception mach.base.UnknownCommandError(command, verb, suggested_commands=None)

Bases: MachError

Raised when we attempted to execute an unknown command.

exception mach.base.UnrecognizedArgumentError(command, arguments)

Bases: MachError

Raised when an unknown argument is passed to mach.

mach.command_util module

class mach.command_util.DecoratorVisitor

Bases: NodeVisitor

visit_FunctionDef(node)
class mach.command_util.DetermineCommandVenvAction(option_strings, dest, topsrcdir, required=True)

Bases: Action

class mach.command_util.MachCommandReference(module: str | Path, command_dependencies: list | None = None)

Bases: object

A reference to a mach command.

Holds the metadata for a mach command.

module: Path
mach.command_util.command_virtualenv_info_for_module(module_path)
mach.command_util.load_command_module_from_command_name(command_name: str, topsrcdir: str)
mach.command_util.load_commands_from_directory(path: Path)

Scan for mach commands from modules in a directory.

This takes a path to a directory, loads the .py files in it, and registers and found mach command providers with this mach instance.

mach.command_util.load_commands_from_entry_point(group='mach.providers')

Scan installed packages for mach command provider entry points. An entry point is a function that returns a list of paths to files or directories containing command providers.

This takes an optional group argument which specifies the entry point group to use. If not specified, it defaults to ‘mach.providers’.

mach.command_util.load_commands_from_file(path: str | Path, module_name=None)

Scan for mach commands from a file.

This takes a path to a file and loads it as a Python module under the module name specified. If no name is specified, a random one will be chosen.

mach.command_util.load_commands_from_spec(spec: Dict[str, MachCommandReference], topsrcdir: str, missing_ok=False)

Load mach commands based on the given spec.

Takes a dictionary mapping command names to their metadata.

mach.command_util.suggest_command(command)

mach.config module

This file defines classes for representing config data/settings.

Config data is modeled as key-value pairs. Keys are grouped together into named sections. Individual config settings (options) have metadata associated with them. This metadata includes type, default value, valid values, etc.

The main interface to config data is the ConfigSettings class. 1 or more ConfigProvider classes are associated with ConfigSettings and define what settings are available.

class mach.config.BooleanType

Bases: ConfigType

static from_config(config, section, option)

Obtain the value of this type from a RawConfigParser.

Receives a RawConfigParser instance, a str section name, and the str option in that section to retrieve.

The implementation may assume the option exists in the RawConfigParser instance.

Implementations are not expected to validate the value. But, they should return the appropriate Python type.

static to_config(value)
static validate(value)

Validates a Python value conforms to this type.

Raises a TypeError or ValueError if it doesn’t conform. Does not do anything if the value is valid.

exception mach.config.ConfigException

Bases: Exception

class mach.config.ConfigSettings

Bases: Mapping

Interface for configuration settings.

This is the main interface to the configuration.

A configuration is a collection of sections. Each section contains key-value pairs.

When an instance is created, the caller first registers ConfigProvider instances with it. This tells the ConfigSettings what individual settings are available and defines extra metadata associated with those settings. This is used for validation, etc.

Once ConfigProvider instances are registered, a config is populated. It can be loaded from files or populated by hand.

ConfigSettings instances are accessed like dictionaries or by using attributes. e.g. the section “foo” is accessed through either settings.foo or settings[‘foo’].

Sections are modeled by the ConfigSection class which is defined inside this one. They look just like dicts or classes with attributes. To access the “bar” option in the “foo” section:

value = settings.foo.bar value = settings[‘foo’][‘bar’] value = settings.foo[‘bar’]

Assignment is similar:

settings.foo.bar = value settings[‘foo’][‘bar’] = value settings[‘foo’].bar = value

You can even delete user-assigned values:

del settings.foo.bar del settings[‘foo’][‘bar’]

If there is a default, it will be returned.

When settings are mutated, they are validated against the registered providers. Setting unknown settings or setting values to illegal values will result in exceptions being raised.

class ConfigSection(config, name, settings)

Bases: MutableMapping, object

Represents an individual config section.

get_meta(option)
property options
load_file(filename: str | Path)
load_files(filenames: List[Path])

Load a config from files specified by their paths.

Files are loaded in the order given. Subsequent files will overwrite values from previous files. If a file does not exist, it will be ignored.

load_fps(fps)

Load config data by reading file objects.

register_provider(provider)

Register a SettingsProvider with this settings interface.

write(fh)

Write the config to a file object.

class mach.config.ConfigType

Bases: object

Abstract base class for config values.

static from_config(config, section, option)

Obtain the value of this type from a RawConfigParser.

Receives a RawConfigParser instance, a str section name, and the str option in that section to retrieve.

The implementation may assume the option exists in the RawConfigParser instance.

Implementations are not expected to validate the value. But, they should return the appropriate Python type.

static to_config(value)
static validate(value)

Validates a Python value conforms to this type.

Raises a TypeError or ValueError if it doesn’t conform. Does not do anything if the value is valid.

class mach.config.DefaultValue

Bases: object

class mach.config.IntegerType

Bases: ConfigType

static from_config(config, section, option)

Obtain the value of this type from a RawConfigParser.

Receives a RawConfigParser instance, a str section name, and the str option in that section to retrieve.

The implementation may assume the option exists in the RawConfigParser instance.

Implementations are not expected to validate the value. But, they should return the appropriate Python type.

static validate(value)

Validates a Python value conforms to this type.

Raises a TypeError or ValueError if it doesn’t conform. Does not do anything if the value is valid.

class mach.config.PathType

Bases: StringType

static from_config(config, section, option)

Obtain the value of this type from a RawConfigParser.

Receives a RawConfigParser instance, a str section name, and the str option in that section to retrieve.

The implementation may assume the option exists in the RawConfigParser instance.

Implementations are not expected to validate the value. But, they should return the appropriate Python type.

static validate(value)

Validates a Python value conforms to this type.

Raises a TypeError or ValueError if it doesn’t conform. Does not do anything if the value is valid.

class mach.config.PositiveIntegerType

Bases: IntegerType

static validate(value)

Validates a Python value conforms to this type.

Raises a TypeError or ValueError if it doesn’t conform. Does not do anything if the value is valid.

class mach.config.StringType

Bases: ConfigType

static from_config(config, section, option)

Obtain the value of this type from a RawConfigParser.

Receives a RawConfigParser instance, a str section name, and the str option in that section to retrieve.

The implementation may assume the option exists in the RawConfigParser instance.

Implementations are not expected to validate the value. But, they should return the appropriate Python type.

static validate(value)

Validates a Python value conforms to this type.

Raises a TypeError or ValueError if it doesn’t conform. Does not do anything if the value is valid.

mach.config.reraise_attribute_error(func)

Used to make sure __getattr__ wrappers around __getitem__ raise AttributeError instead of KeyError.

mach.decorators module

class mach.decorators.Command(name, metrics_path: str | None = None, **kwargs)

Bases: object

Decorator for functions or methods that provide a mach command.

The decorator accepts arguments that define basic attributes of the command. The following arguments are recognized:

category – The string category to which this command belongs. Mach’s

help will group commands by category.

description – A brief description of what the command does.

parser – an optional argparse.ArgumentParser instance or callable

that returns an argparse.ArgumentParser instance to use as the basis for the command arguments.

For example:

@Command('foo', category='misc', description='Run the foo action')
def foo(self, command_context):
    pass
class mach.decorators.CommandArgument(*args, **kwargs)

Bases: object

Decorator for additional arguments to mach subcommands.

This decorator should be used to add arguments to mach commands. Arguments to the decorator are proxied to ArgumentParser.add_argument().

For example:

@Command('foo', help='Run the foo action')
@CommandArgument('-b', '--bar', action='store_true', default=False,
    help='Enable bar mode.')
def foo(self, command_context):
    pass
class mach.decorators.CommandArgumentGroup(group_name)

Bases: object

Decorator for additional argument groups to mach commands.

This decorator should be used to add arguments groups to mach commands. Arguments to the decorator are proxied to ArgumentParser.add_argument_group().

For example:

The name should be chosen so that it makes sense as part of the phrase ‘Command Arguments for <name>’ because that’s how it will be shown in the help message.

mach.decorators.SettingsProvider(cls)

Class decorator to denote that this class provides Mach settings.

When this decorator is encountered, the underlying class will automatically be registered with the Mach registrar and will (likely) be hooked up to the mach driver.

class mach.decorators.SubCommand(command, subcommand, description=None, parser=None, metrics_path: str | None = None, virtualenv_name: str | None = None)

Bases: object

Decorator for functions or methods that provide a sub-command.

Mach commands can have sub-commands. e.g. mach command foo or mach command bar. Each sub-command has its own parser and is effectively its own mach command.

The decorator accepts arguments that define basic attributes of the sub command:

command – The string of the command this sub command should be attached to.

subcommand – The string name of the sub command to register.

description – A textual description for this sub command.

global_order = 2

mach.dispatcher module

class mach.dispatcher.CommandAction(option_strings, dest, required=True, default=None, registrar=None, context=None)

Bases: Action

An argparse action that handles mach commands.

This class is essentially a reimplementation of argparse’s sub-parsers feature. We first tried to use sub-parsers. However, they were missing features like grouping of commands (http://bugs.python.org/issue14037).

The way this works involves light magic and a partial understanding of how argparse works.

Arguments registered with an argparse.ArgumentParser have an action associated with them. An action is essentially a class that when called does something with the encountered argument(s). This class is one of those action classes.

An instance of this class is created doing something like:

parser.add_argument(‘command’, action=CommandAction, registrar=r)

Note that a mach.registrar.Registrar instance is passed in. The Registrar holds information on all the mach commands that have been registered.

When this argument is registered with the ArgumentParser, an instance of this class is instantiated. One of the subtle but important things it does is tell the argument parser that it’s interested in all of the remaining program arguments. So, when the ArgumentParser calls this action, we will receive the command name plus all of its arguments.

For more, read the docs in __call__.

class mach.dispatcher.CommandFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: HelpFormatter

Custom formatter to format just a subcommand.

add_usage(*args)
class mach.dispatcher.NoUsageFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: HelpFormatter

mach.dispatcher.format_docstring(docstring)

Format a raw docstring into something suitable for presentation.

This function is based on the example function in PEP-0257.

mach.logging module

class mach.logging.ConvertToStructuredFilter(name='')

Bases: Filter

Filter that converts unstructured records into structured ones.

filter(record)

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

class mach.logging.LoggingManager

Bases: object

Holds and controls global logging state.

An application should instantiate one of these and configure it as needed.

This class provides a mechanism to configure the output of logging data both from mach and from the overall logging system (e.g. from other modules).

add_json_handler(fh)

Enable JSON logging on the specified file object.

add_terminal_logging(fh=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, level=20, write_interval=False, write_times=True)

Enable logging to the terminal.

create_terminal()
disable_unstructured()

Disable logging of unstructured messages.

enable_all_structured_loggers(terminal=True, json=True)

Enable logging of all structured messages from all loggers.

terminal and json determine which log handlers to operate on. By default, all known handlers are operated on.

enable_unstructured()

Enable logging of unstructured messages.

register_structured_logger(logger, terminal=True, json=True)

Register a structured logger.

This needs to be called for all structured loggers that don’t chain up to the mach logger in order for their output to be captured.

replace_terminal_handler(handler)

Replace the installed terminal handler.

Returns the old handler or None if none was configured. If the new handler is None, removes any existing handler and disables logging to the terminal.

property terminal
class mach.logging.StructuredHumanFormatter(start_time, write_interval=False, write_times=True, write_level=None)

Bases: Formatter

Log formatter that writes structured messages for humans.

It is important that this formatter never be added to a logger that produces unstructured/classic log messages. If it is, the call to format() could fail because the string could contain things (like JSON) that look like formatting character sequences.

Because of this limitation, format() will fail with a KeyError if an unstructured record is passed or if the structured message is malformed.

format(record)

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

class mach.logging.StructuredJSONFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases: Formatter

Log formatter that writes a structured JSON entry.

format(record)

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

class mach.logging.StructuredTerminalFormatter(start_time, write_interval=False, write_times=True, write_level=None)

Bases: StructuredHumanFormatter

Log formatter for structured messages writing to a terminal.

format(record)

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

set_terminal(terminal)
mach.logging.enable_blessed()
mach.logging.format_level(level, terminal=None)
mach.logging.format_seconds(total)

Format number of seconds to MM:SS.DD form.

mach.logging.formatted_stack_trace(record, formatter)

Formatting behavior here intended to mimic a portion of the standard library’s logging.Formatter::format function

mach.main module

class mach.main.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)

Bases: ArgumentParser

Custom implementation argument parser to make things look pretty.

error(message)

Custom error reporter to give more helpful text on bad commands.

format_help()
class mach.main.ContextWrapper(context, handler)

Bases: object

class mach.main.Mach(cwd: str)

Bases: object

Main mach driver type.

This type is responsible for holding global mach state and dispatching a command from arguments.

The following attributes may be assigned to the instance to influence behavior:

populate_context_handler – If defined, it must be a callable. The

callable signature is the following: populate_context_handler(key=None) It acts as a fallback getter for the mach.base.CommandContext instance. This allows to augment the context instance with arbitrary data for use in command handlers.

require_conditions – If True, commands that do not have any condition

functions applied will be skipped. Defaults to False.

settings_paths – A list of files or directories in which to search

for settings files to load.

USAGE = '%(prog)s [global arguments] command [command arguments]\n\nmach (German for "do") is the main interface to the Mozilla build system and\ncommon developer tasks.\n\nYou tell mach the command you want to perform and it does it for you.\n\nSome common commands are:\n\n    %(prog)s build     Build/compile the source tree.\n    %(prog)s help      Show full help, including the list of all commands.\n\nTo see more help for a specific command, run:\n\n  %(prog)s help <command>\n'
define_category(name, title, description, priority=50)

Provide a description for a named command category.

load_settings()
load_settings_by_file(paths: List[Path])

Load the specified settings files.

If a directory is specified, the following basenames will be searched for in this order:

machrc, .machrc

log(level, action, params, format_str)

Helper method to record a structured log event.

property require_conditions
run(argv, stdin=None, stdout=None, stderr=None)

Runs mach with arguments provided from the command line.

Returns the integer exit code that should be used. 0 means success. All other values indicate failure.

mach.main.get_argument_parser(context=None, action=<class 'mach.dispatcher.CommandAction'>, topsrcdir=None)

Returns an argument parser for the command-line interface.

mach.python_lockfile module

class mach.python_lockfile.PoetryHandle(work_dir: Path)

Bases: object

add_requirement(requirement: Requirement)
add_requirements_in_file(requirements_in: Path)
generate_lockfiles(do_update)

Generate pip-style lockfiles that satisfy provided requirements

One lockfile will be made for all mandatory requirements, and then an extra, compatible lockfile will be created for each optional requirement.

Parameters:

do_update – if True, then implicitly upgrade the versions of transitive dependencies

reuse_existing_lockfile(lockfile_path: Path)

Make minimal number of changes to the lockfile to satisfy new requirements

class mach.python_lockfile.PoetryLockfiles(poetry_lockfile: Path, pip_lockfile: Path)

Bases: object

mach.registrar module

class mach.registrar.MachRegistrar

Bases: object

Container for mach command and config providers.

dispatch(name, context, argv=None, subcommand=None, **kwargs)

Dispatch/run a command.

Commands can use this to call other commands.

register_category(name, title, description, priority=50)
register_command_handler(handler)
register_settings_provider(cls)

mach.requirements module

class mach.requirements.MachEnvRequirements

Bases: object

Requirements associated with a “site dependency manifest”, as defined in “python/sites/”.

Represents the dependencies of a site. The source files consist of colon-delimited fields. The first field specifies the action. The remaining fields are arguments to that action. The following actions are supported:

pth – Adds the path given as argument to “mach.pth” under

the virtualenv’s site packages directory.

pypi – Fetch the package, plus dependencies, from PyPI.

pypi-optional – Attempt to install the package and dependencies from PyPI.

Continue using the site, even if the package could not be installed.

packages.txt – Denotes that the specified path is a child manifest. It

will be read and processed as if its contents were concatenated into the manifest being read.

thunderbird-packages.txt – Denotes a Thunderbird child manifest.

Thunderbird child manifests are only activated when working on Thunderbird, and they can cannot have “pypi” or “pypi-optional” entries.

classmethod from_requirements_definition(topsrcdir: str, is_thunderbird, only_strict_requirements, requirements_definition)
pths_as_absolute(topsrcdir: str)
class mach.requirements.PthSpecifier(path: str)

Bases: object

class mach.requirements.PypiOptionalSpecifier(repercussion, requirement)

Bases: PypiSpecifier

class mach.requirements.PypiSpecifier(requirement)

Bases: object

exception mach.requirements.UnexpectedFlexibleRequirementException(raw_requirement)

Bases: Exception

mach.sentry module

class mach.sentry.ErrorReporter

Bases: object

abstract report_exception(exception)

Report the exception to remote error-tracking software.

class mach.sentry.NoopErrorReporter

Bases: ErrorReporter

Drops errors instead of reporting them.

This is useful in cases where error-reporting is specifically disabled, such as when telemetry hasn’t been allowed.

report_exception(exception)

Report the exception to remote error-tracking software.

class mach.sentry.SentryErrorReporter

Bases: ErrorReporter

Reports errors using Sentry.

report_exception(exception)

Report the exception to remote error-tracking software.

mach.sentry.register_sentry(argv, settings, topsrcdir: Path)

mach.settings module

class mach.settings.MachSettings

Bases: object

classmethod config_settings()

mach.site module

class mach.site.CommandSiteManager(topsrcdir: str, mach_virtualenv_root: str | None, virtualenv_root: str, site_name: str, active_metadata: MozSiteMetadata, populate_virtualenv: bool, requirements: MachEnvRequirements)

Bases: object

Activate sites and ad-hoc-install pip packages

Provides tools to ensure that a command’s scope will have expected, compatible packages. Manages prioritization of the import scope, and ensures consistency regardless of how a virtualenv is used (whether via in-process activation, or when used standalone to invoke a script).

A few notes:

  • The command environment always inherits Mach’s import scope. This is because “unloading” packages in Python is error-prone, so in-process activations will always carry Mach’s dependencies along with it. Accordingly, compatibility between each command environment and the Mach environment must be maintained

  • Unlike the Mach environment, command environments always have an associated physical virtualenv on-disk. This is because some commands invoke child Python processes, and that child process should have the same import scope.

activate()

Activate this site in the current Python context.

If you run a random Python script and wish to “activate” the site, you can simply instantiate an instance of this class and call .activate() to make the virtualenv active.

ensure()

Ensure that this virtualenv is built, up-to-date, and ready for use If using a virtualenv Python binary directly, it’s useful to call this function first to ensure that the virtualenv doesn’t have obsolete references or packages.

classmethod from_environment(topsrcdir: str, get_state_dir: Callable[[], str | None], site_name: str, command_virtualenvs_dir: str)
Parameters:

  • topsrcdir – The path to the Firefox repo

  • get_state_dir – A function that resolves the path to the checkout-scoped state_dir, generally ~/.mozbuild/srcdirs/<checkout-based-dir>/

  • site_name – The name of this site, such as “build”

  • command_virtualenvs_dir – The location under which this site’s virtualenv

  • created (should be) –

install_pip_package(package)

Install a package via pip.

The supplied package is specified using a pip requirement specifier. e.g. ‘foo’ or ‘foo==1.0’.

If the package is already installed, this is a no-op.

install_pip_requirements(path, require_hashes=True, quiet=False)

Install a pip requirements.txt file.

The supplied path is a text file containing pip requirement specifiers.

If require_hashes is True, each specifier must contain the expected hash of the downloaded package. See: https://pip.pypa.io/en/stable/reference/pip_install/#hash-checking-mode

class mach.site.ExternalPythonSite(python_executable)

Bases: object

Represents the Python site that is executing Mach

The external Python site could be a virtualenv (created by venv or virtualenv) or the system Python itself, so we can’t make any significant assumptions on its structure.

sys_path()

Return lists of sys.path entries: one for standard library, one for the site

These two lists are calculated at the same time so that we can interpret them in a single Python subprocess, as running a whole Python instance is very expensive in the context of Mach initialization.

sys_path_stdlib()

Return list of default sys.path entries for the standard library

exception mach.site.InstallPipRequirementsException

Bases: Exception

class mach.site.MachSiteManager(topsrcdir: str, virtualenv_root: str | None, requirements: MachEnvRequirements, original_python: ExternalPythonSite, site_packages_source: SitePackagesSource)

Bases: object

Represents the activate-able “import scope” Mach needs

Whether running independently, using the system packages, or automatically managing dependencies with “pip install”, this class provides an easy handle to verify that the “site” is up-to-date (whether than means that system packages don’t collide with vendored packages, or that the on-disk virtualenv needs rebuilding).

Note that, this is a virtual site: an on-disk Python virtualenv is only created if there will be “pip installs” into the Mach site.

activate()
attempt_populate_optional_packages()
ensure(*, force=False)
classmethod from_environment(topsrcdir: str, get_state_dir: Callable[[], str])
Parameters:

  • topsrcdir – The path to the Firefox repo

  • get_state_dir – A function that resolves the path to the checkout-scoped state_dir, generally ~/.mozbuild/srcdirs/<checkout-based-dir>/

class mach.site.MozSiteMetadata(hex_version: int, site_name: str, mach_site_packages_source: SitePackagesSource, original_python: ExternalPythonSite, prefix: str)

Bases: object

Details about a Moz-managed python site

When a Moz-managed site is active, its associated metadata is available at “MozSiteMetadata.current”.

Sites that have associated virtualenvs (so, those that aren’t strictly leaning on the external python packages) will have their metadata written to <prefix>/moz_virtualenv_metadata.json.

current: MozSiteMetadata | None = <mach.site.MozSiteMetadata object>
classmethod from_path(prefix)
classmethod from_runtime()
update_current_site(executable)

Updates necessary global state when a site is activated

Due to needing to fetch some state before the actual activation happens, this is represented as a context manager and should be used as follows:

with metadata.update_current_site(executable):

# Perform the actual implementation of changing the site, whether that is # by exec-ing “activate_this.py” in a virtualenv, modifying the sys.path # directly, or some other means …

write(is_finalized)
exception mach.site.MozSiteMetadataOutOfDateError

Bases: Exception

class mach.site.PythonVirtualenv(prefix)

Bases: object

Calculates paths of interest for general python virtual environments

install_optional_packages(optional_requirements)
pip_install(pip_install_args, **kwargs)
pip_install_with_constraints(pip_args)

Create a pip constraints file or existing packages

When pip installing an incompatible package, pip will follow through with the install but raise a warning afterwards.

To defend our environment from breakage, we run “pip install” but add all existing packages to a “constraints file”. This ensures that conflicts are raised as errors up-front, and the virtual environment doesn’t have conflicting packages installed.

Note: pip_args is expected to contain either the requested package or

requirements file.

resolve_sysconfig_packages_path(sysconfig_path)
site_packages_dirs()
class mach.site.RequirementsValidationResult

Bases: object

add_discrepancy(requirement, found)
classmethod from_packages(packages, requirements)
report()
class mach.site.SitePackagesSource(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

NONE = 'none'
SYSTEM = 'system'
VENV = 'pip'
classmethod for_mach()
class mach.site.SiteUpToDateResult(is_up_to_date, reason=None)

Bases: object

exception mach.site.VenvModuleNotFoundException

Bases: Exception

exception mach.site.VirtualenvOutOfDateException

Bases: Exception

mach.site.activate_virtualenv(virtualenv: PythonVirtualenv)
mach.site.resolve_requirements(topsrcdir, site_name)

mach.telemetry module

mach.telemetry.arcrc_path()
mach.telemetry.create_telemetry_from_environment(settings)

Creates and a Telemetry instance based on system details.

If telemetry isn’t enabled, the current interpreter isn’t Python 3, or Glean can’t be imported, then a “mock” telemetry instance is returned that doesn’t set or record any data. This allows consumers to optimistically set telemetry data without needing to specifically handle the case where the current system doesn’t support it.

mach.telemetry.initialize_telemetry_setting(settings, topsrcdir: str, state_dir: str)

Enables telemetry for employees or prompts the user.

mach.telemetry.is_applicable_telemetry_environment()
mach.telemetry.is_telemetry_enabled(settings)
mach.telemetry.print_telemetry_message_employee()
mach.telemetry.prompt_telemetry_message_contributor()
mach.telemetry.record_telemetry_settings(main_settings, state_dir: Path, is_enabled)
mach.telemetry.report_invocation_metrics(telemetry, command)
mach.telemetry.resolve_is_employee(topsrcdir: Path)

Detect whether or not the current user is a Mozilla employee.

Checks using Bugzilla authentication, if possible. Otherwise falls back to checking if email configured in VCS is “@mozilla.com”.

Returns True if the user could be identified as an employee, False if the user is confirmed as not being an employee, or None if the user couldn’t be identified.

mach.telemetry.resolve_is_employee_by_credentials(topsrcdir: Path)
mach.telemetry.resolve_is_employee_by_vcs(topsrcdir: Path)
mach.telemetry.resolve_setting_from_arcconfig(topsrcdir: Path, setting)

mach.telemetry_interface module

class mach.telemetry_interface.GleanTelemetry

Bases: object

Records and sends Telemetry using Glean.

Metrics are defined in python/mozbuild/metrics.yaml. Pings are defined in python/mozbuild/pings.yaml.

The “metrics” and “pings” properties may be replaced with no-op implementations if Glean isn’t available. This allows consumers to report telemetry without having to guard against incompatible environments.

Also tracks whether an employee was just automatically opted into telemetry during this mach invocation.

metrics(metrics_path: str | Path)
submit(_)
class mach.telemetry_interface.NoopTelemetry(failed_glean_import)

Bases: object

metrics(metrics_path: str | Path)
submit(is_bootstrap)

mach.terminal module

This file contains code for interacting with terminals.

All the terminal interaction code is consolidated so the complexity can be in one place, away from code that is commonly looked at.

class mach.terminal.LoggingHandler

Bases: Handler

Custom logging handler that works with terminal window dressing.

This is alternative terminal logging handler which contains smarts for emitting terminal control characters properly. Currently, it has generic support for “footer” elements at the bottom of the screen. Functionality can be added when needed.

emit(record)

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

flush()

Ensure all logging output has been flushed.

This version does nothing and is intended to be implemented by subclasses.

class mach.terminal.TerminalFooter(terminal)

Bases: object

Represents something drawn on the bottom of a terminal.

clear()
draw()

mach.util module

exception mach.util.UserError

Bases: Exception

Represents an error caused by something the user did wrong rather than an internal mach failure. Exceptions that are subclasses of this class will not be reported as failures to Sentry.

mach.util.get_state_dir(specific_to_topsrcdir=False, topsrcdir: str | Path | None = None)

Obtain path to a directory to hold state.

Parameters:

specific_to_topsrcdir (bool) – If True, return a state dir specific to the current srcdir instead of the global state dir (default: False)

Returns:

A path to the state dir (str)

mach.util.get_virtualenv_base_dir(topsrcdir)
mach.util.setenv(key, value)

Compatibility shim to ensure the proper string type is used with os.environ for the version of Python being used.

mach.util.strtobool(value: str)
mach.util.to_optional_path(path: Path | None)
mach.util.to_optional_str(path: Path | None)
mach.util.win_to_msys_path(path: Path)

Convert a windows-style path to msys-style.

Module contents