West APIs

This page documents the Python APIs provided by west, as well as some additional APIs used by the west extensions in the zephyr repository.

Warning

These APIs should be considered unstable until west version 1.0 (see west #38).

Contents:

west.commands

All built-in and extension commands are implemented as subclasses of the WestCommand class defined here. Some exception types are also provided.

WestCommand

class west.commands.WestCommand

Instance attributes:

name

As passed to the constructor.

help

As passed to the constructor.

description

As passed to the constructor.

accepts_unknown_args

As passed to the constructor.

requires_workspace

As passed to the constructor.

New in version 0.7.0.

parser

The argument parser created by calling WestCommand.add_parser().

Instance properties:

manifest

A property which returns the west.manifest.Manifest instance for the current manifest file or aborts the program if one was not provided. This is only safe to use from the do_run() method.

New in version 0.6.1.

Changed in version 0.7.0: This is now settable.

has_manifest

True if reading the manifest property will succeed instead of erroring out.

config

A settable property which returns the west.configuration.Configuration instance or aborts the program if one was not provided. This is only safe to use from the do_run() method.

New in version 0.13.0.

has_config

True if reading the config property will succeed instead of erroring out.

New in version 0.13.0.

git_version_info

A tuple of Git version information.

New in version 0.11.0.

Constructor:

WestCommand.__init__(name: str, help: str, description: str, accepts_unknown_args: bool = False, requires_workspace: bool = True)

Abstract superclass for a west command.

Some fields, such as name, help, and description, overlap with kwargs that should be passed to the argparse.ArgumentParser added by WestCommand.add_parser. This wart is by design: argparse doesn’t make many API stability guarantees, so this information must be duplicated here for future-proofing.

Parameters

  • name – the command’s name, as entered by the user

  • help – one-line command help text

  • description – multi-line command description

  • accepts_unknown_args – if true, the command can handle arbitrary unknown command line arguments in WestCommand.run. Otherwise, it’s a fatal to pass unknown arguments.

  • requires_workspace – if true, the command requires a west workspace to run, and running it outside of one is a fatal error.

New in version 0.6.0: The requires_installation parameter (removed in v0.13.0).

New in version 0.7.0: The requires_workspace parameter.

Changed in version 0.8.0: The topdir parameter can now be any os.PathLike.

Changed in version 0.13.0: The deprecated requires_installation parameter was removed.

Methods:

WestCommand.run(args: argparse.Namespace, unknown: List[str], topdir: Union[str, os.PathLike], manifest: Optional[west.manifest.Manifest] = None, config: Optional[west.configuration.Configuration] = None) → None

Run the command.

This raises west.commands.CommandContextError if the command cannot be run due to a context mismatch. Other exceptions may be raised as well.

Parameters

  • args – known arguments parsed via WestCommand.add_parser

  • unknown – unknown arguments present on the command line; must be empty unless accepts_unknown_args is true

  • topdir – west workspace topdir, accessible as a str via self.topdir from WestCommand.do_run

  • manifest – west.manifest.Manifest or None, accessible as self.manifest from WestCommand.do_run

  • config – west.configuration.Configuration or None, accessible as self.config from WestCommand.do_run

Changed in version 0.6.0: The topdir argument was added.

WestCommand.add_parser(parser_adder) → argparse.ArgumentParser

Registers a parser for this command, and returns it.

The parser object is stored in a parser attribute.

Parameters

parser_adder – The return value of a call to argparse.ArgumentParser.add_subparsers()

static WestCommand.check_call(args, cwd=None)

Runs subprocess.check_call(args, cwd=cwd) after logging the call at VERBOSE_VERY level.

Changed in version 0.11.0.

static WestCommand.check_output(args, cwd=None)

Runs subprocess.check_output(args, cwd=cwd) after logging the call at VERBOSE_VERY level.

Changed in version 0.11.0.

All subclasses must provide the following abstract methods, which are used to implement the above:

abstract WestCommand.do_add_parser(parser_adder) → argparse.ArgumentParser

Subclass method for registering command line arguments.

This is called by WestCommand.add_parser to register the command’s options and arguments.

Subclasses should parser_adder.add_parser() to add an ArgumentParser for that subcommand, then add any arguments. The final parser must be returned.

Parameters

parser_adder – The return value of a call to argparse.ArgumentParser.add_subparsers()

abstract WestCommand.do_run(args: argparse.Namespace, unknown: List[str])

Subclasses must implement; called to run the command.

Parameters

  • args – argparse.Namespace of parsed arguments

  • unknown – If accepts_unknown_args is true, a sequence of un-parsed argument strings.

Exceptions

class west.commands.CommandError(returncode=1)

Bases: RuntimeError

Indicates that a command failed.

returncode

Recommended program exit code for this error.

class west.commands.CommandContextError(returncode=1)

Bases: west.commands.CommandError

Indicates that a context-dependent command could not be run.

west.configuration

West configuration file handling.

West follows Git-like conventions for configuration file locations. There are three types of configuration file: system-wide files apply to all users on the current machine, global files apply to the current user, and local files apply to the current west workspace.

System files:

  • Linux: /etc/westconfig

  • macOS: /usr/local/etc/westconfig

  • Windows: %PROGRAMDATA%\west\config

Global files:

  • Linux: ~/.westconfig or (if $XDG_CONFIG_HOME is set) $XDG_CONFIG_HOME/west/config

  • macOS: ~/.westconfig

  • Windows: .westconfig in the user’s home directory, as determined by os.path.expanduser.

Local files:

  • Linux, macOS, Windows: <workspace-topdir>/.west/config

You can override these files’ locations with the WEST_CONFIG_SYSTEM, WEST_CONFIG_GLOBAL, and WEST_CONFIG_LOCAL environment variables.

Configuration values from later configuration files override configuration from earlier ones. Local values have highest precedence, and system values lowest.

Since west v0.13, the recommended class for reading this is west.configuration.Configuration.

Note that if you are writing a west extension, you can access the current Configuration object as self.configuration. See west.commands.WestCommand.

Configuration API

This is the recommended API to use since west v0.13.

class west.configuration.ConfigFile(value)

Types of west configuration file.

Enumeration members:

  • SYSTEM: system level configuration shared by all users

  • GLOBAL: global or user-wide configuration

  • LOCAL: per-workspace configuration

  • ALL: all three of the above, where applicable

class west.configuration.Configuration(topdir: Optional[Union[str, os.PathLike]] = None)

Represents the available configuration options and their values.

Allows getting, setting, and deleting configuration options in the system, global, and local files.

Sets take effect immediately and are not protected against concurrent gets. The caller is responsible for any necessary mutual exclusion.

New in version 0.13.0.

delete(option: str, configfile: Optional[west.configuration.ConfigFile] = None) → None

Delete an option from the given file or files.

If option is not set in the given configfile, KeyError is raised.

Parameters

  • option – option to delete, in ‘foo.bar’ form

  • configfile –

    If ConfigFile.ALL, delete option in all files where it is set.

    If None, delete option only in the highest precedence file where it is set.

    Otherwise, delete from the given ConfigFile.

get(option: str, default: Optional[str] = None, configfile: west.configuration.ConfigFile = ConfigFile.ALL) → Optional[str]

Get a configuration option’s value as a string.

Parameters

  • option – option to get, in ‘foo.bar’ form

  • default – default value to return if option is missing

  • configfile – type of config file look for the value in

getboolean(option: str, default: bool = False, configfile: west.configuration.ConfigFile = ConfigFile.ALL) → bool

Get a configuration option’s value as a bool.

The configparser module’s conversion to boolean is applied to any value discovered. Invalid values raise ValueError.

Parameters

  • option – option to get, in ‘foo.bar’ form

  • default – default value to return if option is missing

  • configfile – type of config file to look for the value in

getfloat(option: str, default: Optional[float] = None, configfile: west.configuration.ConfigFile = ConfigFile.ALL) → Optional[float]

Get a configuration option’s value as a float.

Parameters

  • option – option to get, in ‘foo.bar’ form

  • default – default value to return if option is missing

  • configfile – type of config file to look for the value in

getint(option: str, default: Optional[int] = None, configfile: west.configuration.ConfigFile = ConfigFile.ALL) → Optional[int]

Get a configuration option’s value as an int.

Parameters

  • option – option to get, in ‘foo.bar’ form

  • default – default value to return if option is missing

  • configfile – type of config file to look for the value in

items(configfile: west.configuration.ConfigFile = ConfigFile.ALL) → Iterable[Tuple[str, Any]]

Iterator of option, value pairs.

set(option: str, value: Any, configfile: west.configuration.ConfigFile = ConfigFile.LOCAL) → None

Set a configuration option’s value.

The write to the configuration file takes effect immediately. No concurrency protection is performed against concurrent access from the time that this Configuration object was created. If the file may have been modified since that time, either create a new Configuration object before using this method or lose the intervening modifications.

Parameters

  • option – option to set, in ‘foo.bar’ form

  • value – value to set option to

  • configfile – type of config file to set the value in

Deprecated APIs

The following APIs also use west.configuration.ConfigFile, but they operate by default on a global object which stores the current workspace configuration. This has proven to be a bad design decision since west’s APIs can be used from multiple workspaces. They were deprecated in west v0.13.0.

These APIs are preserved for compatibility with older extensions. They should not be used in new code when west v0.13.0 or later may be assumed.

west.configuration.read_config(configfile: typing.Optional[west.configuration.ConfigFile] = None, config: configparser.ConfigParser = <configparser.ConfigParser object>, topdir: typing.Optional[typing.Union[str, os.PathLike]] = None) → None

Read configuration files into config.

Reads the files given by configfile, storing the values into the configparser.ConfigParser object config. If config is not given, the global west.configuration.config object is used.

If configfile is given, only the files implied by its value are read. If not given, ConfigFile.ALL is used.

If configfile requests local configuration options (i.e. if it is ConfigFile.LOCAL or ConfigFile.ALL:

  • If topdir is given, topdir/.west/config is read

  • Next, if WEST_CONFIG_LOCAL is set in the environment, its contents (a file) are used.

  • Otherwise, the file system is searched for a local configuration file, and a failure to find one is ignored.

Parameters

  • configfile – a west.configuration.ConfigFile

  • config – configuration object to read into

  • topdir – west workspace root to read local options from

Changed in version 0.8.0: The deprecated read_config parameter was removed.

Changed in version 0.6.0: Errors due to an inability to find a local configuration file are ignored.

west.configuration.update_config(section: str, key: str, value: Any, configfile: west.configuration.ConfigFile = ConfigFile.LOCAL, topdir: Optional[Union[str, os.PathLike]] = None) → None

Sets section.key to value in the given configuration file.

Parameters

  • section – config section; will be created if it does not exist

  • key – key to set in the given section

  • value – value to set the key to

  • configfile – west.configuration.ConfigFile, must not be ALL

  • topdir – west workspace root to write local config options to

The destination file to write is given by configfile. The default value (ConfigFile.LOCAL) writes to the local configuration file given by:

  • topdir/.west/config, if topdir is given, or

  • the value of ‘WEST_CONFIG_LOCAL’ in the environment, if set, or

  • the local configuration file in the west workspace found by searching the file system (raising WestNotFound if one is not found).

west.configuration.config

Module-global ConfigParser instance for the current configuration. This should be initialized with west.configuration.read_config() before being read.

west.log

Provides common methods for printing messages to display to the user.

WestCommand instances should generally use the functions in this module rather than calling print() directly if possible, as these respect the color.ui configuration option and verbosity level.

This module’s functions are used whenever a running west command needs to print to standard out or error streams.

This is safe to use from extension commands if you want output that mirrors that of west itself.

Verbosity control

To set the global verbosity level, use set_verbosity().

west.log.set_verbosity(value)

Set the logging verbosity level.

Parameters

value – verbosity level to set, e.g. VERBOSE_VERY.

These verbosity levels are defined.

west.log.VERBOSE_NONE = 0

Default verbosity level, no dbg() messages printed.

west.log.VERBOSE_NORMAL = 1

Some verbose messages printed.

west.log.VERBOSE_VERY = 2

Very verbose output messages will be printed.

west.log.VERBOSE_EXTREME = 3

Extremely verbose output messages will be printed.

Output functions

The main functions are dbg(), inf(), wrn(), err(), and die(). Two special cases of inf(), banner() and small_banner(), are also available for grouping output into “sections”.

west.log.dbg(*args, level=1)

Print a verbose debug logging message.

Parameters

  • args – sequence of arguments to print.

  • value – verbosity level to set, e.g. VERBOSE_VERY.

The message is only printed if level is at least the current verbosity level.

west.log.inf(*args, colorize=False)

Print an informational message.

Parameters

  • args – sequence of arguments to print.

  • colorize – If this is True, the configuration option color.ui is undefined or true, and stdout is a terminal, then the message is printed in green.

west.log.wrn(*args)

Print a warning.

Parameters

args – sequence of arguments to print.

The message is prefixed with the string "WARNING: ".

If the configuration option color.ui is undefined or true and stdout is a terminal, then the message is printed in yellow.

west.log.err(*args, fatal=False)

Print an error.

This function does not abort the program. For that, use die().

Parameters

  • args – sequence of arguments to print.

  • fatal – if True, the the message is prefixed with “FATAL ERROR: “; otherwise, “ERROR: ” is used.

If the configuration option color.ui is undefined or true and stdout is a terminal, then the message is printed in red.

west.log.die(*args, exit_code=1) → NoReturn

Print a fatal error, and abort the program.

Parameters

  • args – sequence of arguments to print.

  • exit_code – return code the program should use when aborting.

Equivalent to die(*args, fatal=True), followed by an attempt to abort with the given exit_code.

west.log.banner(*args)

Prints args as a “banner” at inf() level.

The args are prefixed with ‘=== ‘ and colorized by default.

west.log.small_banner(*args)

Prints args as a smaller banner(), i.e. prefixed with ‘– ‘ and not colorized.

west.manifest

Parser and abstract data types for west manifests.

The main classes are Manifest and Project. These represent the contents of a manifest file. The recommended methods for parsing west manifests are Manifest.from_file() and Manifest.from_data().

Constants and functions

west.manifest.MANIFEST_PROJECT_INDEX = 0

Index in a Manifest.projects attribute where the ManifestProject instance for the workspace is stored.

west.manifest.MANIFEST_REV_BRANCH = 'manifest-rev'

A git revision which points to the most recent Project update.

west.manifest.QUAL_MANIFEST_REV_BRANCH = 'refs/heads/manifest-rev'

A fully qualified reference to MANIFEST_REV_BRANCH.

west.manifest.QUAL_REFS_WEST = 'refs/west/'

Git ref space used by west for internal purposes.

west.manifest.SCHEMA_VERSION = '0.13'

The latest manifest schema version supported by this west program.

This value changes when a new version of west includes new manifest file features not supported by earlier versions of west.

west.manifest.manifest_path() → str

Absolute path of the manifest file in the current workspace.

Exceptions raised:

  • west.util.WestNotFound if called from outside of a west workspace

  • MalformedConfig if the configuration file has no manifest.path key

  • FileNotFoundError if no manifest file exists as determined by manifest.path and manifest.file

west.manifest.validate(data: Any) → Dict[str, Any]

Validate manifest data

Raises an exception if the manifest data is not valid for loading by this version of west. (Actually attempting to load the data may still fail if the it contains imports which cannot be resolved.)

Returns the validated YAML dictionary, which may be convenient if the argument was a str and further loading is required.

Parameters

data – YAML manifest data as a string or object

Changed in version 0.13.0: This returns the validated dict containing the parsed YAML data.

Manifest and sub-objects

class west.manifest.Manifest(*, source_data: Optional[Union[str, Dict]] = None, topdir: Optional[Union[str, os.PathLike]] = None, config: Optional[west.configuration.Configuration] = None, importer: Optional[Callable[[west.manifest.Project, str], Optional[Union[str, List[str]]]]] = None, import_flags: west.manifest.ImportFlag = ImportFlag.DEFAULT, internal_import_ctx: Optional[west.manifest._import_ctx] = None)

The parsed contents of a west manifest file.

__init__(*, source_data: Optional[Union[str, Dict]] = None, topdir: Optional[Union[str, os.PathLike]] = None, config: Optional[west.configuration.Configuration] = None, importer: Optional[Callable[[west.manifest.Project, str], Optional[Union[str, List[str]]]]] = None, import_flags: west.manifest.ImportFlag = ImportFlag.DEFAULT, internal_import_ctx: Optional[west.manifest._import_ctx] = None)

Using one of the factory methods may be easier than direct instantiation.

Instance attributes:

  • abspath: absolute path to the manifest file, or None

  • posixpath: like abspath, but with slashes (/) as separators

  • relative_path: path to the manifest file relative to the workspace topdir (i.e. the combined manifest.path and manifest.file configuration options), or None

  • yaml_path: the value of the “self: path:” field in the manifest YAML, or None

  • repo_path: relative filesystem path to the manifest repository from the workspace topdir as a string, or None

  • repo_abspath: the absolute filesystem path to the manifest repository as a string with symlinks resolved, or None

  • repo_posixpath: like repo_abspath, but with slashes as separators

  • topdir: the workspace top level directory as a string

    with symlinks resolved, or None

  • projects: sequence of Project instances

  • has_imports: bool, True if the manifest contains an “import:” attribute in “self:” or “projects:” that were not ignored due to import_flags; False otherwise

  • group_filter: a group filter value equivalent to the resolved manifest’s “group-filter:”, along with any values from imported manifests. This value may be simpler than the actual input data.

You must give exactly one of the topdir and source_data kwargs:

  • Use topdir to load a manifest from a workspace

  • Use source_data to load data without any workspace

If topdir is given:

  • You may pass config if you already have the desired workspace configuration loaded. This is used to find the manifest file’s location from the manifest.path and manifest.file options. It’s your responsibility to make sure config is properly loaded from topdir in this case.

    If you don’t pass config, the constructor will instantiate the correct Configuration object itself.

  • The return value’s absolute paths will be relative to topdir. If topdir is not an absolute path, it will be resolved first (this resolves symlinks too). If it is absolute, it will not be resolved.

If source_data is given:

  • You cannot pass config.

  • Manifest imports will fail unless you pass importer or ignore them with import_flags.

  • All absolute paths (like projects[i].abspath) in the results will be None.

The importer kwarg, if given, is a callable. It is used as a callback by the constructor when it must import manifest data that aren’t found locally on the file system.

The importer callback will be called as:

importer(project, file)

where project is a west.manifest.Project and file is the missing manifest file. The file’s contents at refs/heads/manifest-rev should usually be returned by the callback, potentially after fetching the project’s revision from its remote URL and updating that ref.

The importer callback’s return value should be a string containing manifest data, or a list of strings if file is a directory containing YAML files. A return value of None will cause the import to be ignored.

Exceptions raised:

  • MalformedManifest: if the manifest data is invalid

  • ManifestImportFailed: if an import failed

  • ManifestVersionError: if this version of west is too old to parse the manifest (based on its schema version)

  • OSError: or subclasses, when files cannot be opened

  • ValueError: for other invalid arguments

Parameters

  • source_data – parsed YAML data as a Python object, or a string containing unparsed YAML data

  • topdir – west workspace top level directory

  • config – optional pre-loaded configuration from topdir

  • importer – provides missing manifest import data

  • import_flags – bit mask, controls import resolution

  • internal_import_ctx – for internal use only; do not use

Changed in version 0.7.0: The importer and import_flags keyword arguments.

Changed in version 0.13.0: All arguments were made keyword-only. The source_file argument was removed (use topdir instead). The function no longer raises WestNotFound.

New in version 0.13.0: The config argument.

New in version 0.13.0: The abspath, posixpath, relative_path, yaml_path, repo_path, repo_posixpath, and userdata attributes.

static from_topdir(topdir: Optional[Union[str, os.PathLike]] = None, config: Optional[west.configuration.Configuration] = None, importer: Optional[Callable[[west.manifest.Project, str], Optional[Union[str, List[str]]]]] = None, import_flags: west.manifest.ImportFlag = ImportFlag.DEFAULT) → west.manifest.Manifest

Manifest object factory given a workspace topdir.

The default behavior if topdir is not given is to find the current west workspace’s manifest file starting from the current working directory.

Parameters

  • topdir – workspace top-level directory

  • config – passed to Manifest()

  • importer – passed to Manifest()

  • import_flags – passed to Manifest()

New in version 0.13.0.

static from_file(source_file: Optional[Union[str, os.PathLike]] = None, importer: Optional[Callable[[west.manifest.Project, str], Optional[Union[str, List[str]]]]] = None, import_flags: west.manifest.ImportFlag = ImportFlag.DEFAULT) → west.manifest.Manifest

Manifest object factory given a source YAML file.

The default behavior if source_file is not given is to find the current west workspace’s manifest file and resolve it starting from the current working directory. This matches the from_topdir() behavior.

With source_file, the topdir is found starting there. As a special case, this factory allows you to load a Manifest from an arbitrary file in an arbitrary git repository in the workspace. The manifest.path and manifest.file configuration values do not have to refer to source_file in this case.

This can be useful to load an alternative manifest file within an existing workspace for purposes of comparing two manifests, for example.

Exceptions raised:

  • west.util.WestNotFound if no topdir can be found starting from source_file or the current working directory

  • CalledProcessError if the git repository containing source_file cannot be found

  • Other exceptions from the Manifest constructor

Parameters

  • source_file – source file to load

  • importer – passed to Manifest()

  • import_flags – passed to Manifest()

Changed in version 0.7.0: **kwargs added.

Changed in version 0.8.0: The source_file, manifest_path, and topdir arguments can now be any os.PathLike.

Changed in version 0.13.0: The manifest_path and topdir arguments were removed.

static from_data(source_data: Union[str, Dict], importer: Optional[Callable[[west.manifest.Project, str], Optional[Union[str, List[str]]]]] = None, import_flags: west.manifest.ImportFlag = ImportFlag.DEFAULT) → west.manifest.Manifest

Manifest object factory given parsed YAML data.

This factory does not read any configuration files.

Let the return value be m. Relative project paths in m (like m.projects[1].path) are taken from source_data. Absolute project paths are all None.

May raise the same exceptions as the Manifest constructor.

Parameters

  • source_data – parsed YAML data as a Python object, or a string with unparsed YAML data

  • importer – passed to Manifest

  • import_flags – passed to Manifest

Changed in version 0.7.0: **kwargs added, and source_data may be a str.

Changed in version 0.13.0: The manifest_path and topdir arguments were removed.

Conveniences for accessing sub-objects by name or other identifier:

get_projects(project_ids: Iterable[Union[str, os.PathLike]], allow_paths: bool = True, only_cloned: bool = False) → List[west.manifest.Project]

Get a list of Project objects in the manifest from project_ids.

If project_ids is empty, a copy of self.projects attribute is returned as a list. Otherwise, the returned list has projects in the same order as project_ids.

ValueError is raised if:

  • project_ids contains unknown project IDs

  • (with only_cloned) an uncloned project was found

The ValueError args attribute is a 2-tuple with a list of unknown project_ids at index 0, and a list of uncloned Project objects at index 1.

Parameters

  • project_ids – a sequence of projects, identified by name or (absolute or relative) path. Names are matched first; path checking can be disabled with allow_paths.

  • allow_paths – if false, project_ids is assumed to contain names only, not paths

  • only_cloned – raise an exception for uncloned projects

Changed in version 0.8.0: The project_ids sequence can now contain any os.PathLike.

New in version 0.6.1.

Additional methods:

as_dict() → Dict

Returns a dict representing self, fully resolved.

The value is “resolved” in that the result is as if all projects had been defined in a single manifest without any import attributes.

New in version 0.7.0.

as_frozen_dict() → Dict

Returns a dict representing self, but frozen.

The value is “frozen” in that all project revisions are the full SHAs pointed to by QUAL_MANIFEST_REV_BRANCH references.

Raises RuntimeError if a project SHA can’t be resolved.

as_yaml(**kwargs) → str

Returns a YAML representation for self, fully resolved.

The value is “resolved” in that the result is as if all projects had been defined in a single manifest without any import attributes.

Parameters

kwargs – passed to yaml.safe_dump()

New in version 0.7.0.

as_frozen_yaml(**kwargs) → str

Returns a YAML representation for self, but frozen.

The value is “frozen” in that all project revisions are the full SHAs pointed to by QUAL_MANIFEST_REV_BRANCH references.

Raises RuntimeError if a project SHA can’t be resolved.

Parameters

kwargs – passed to yaml.safe_dump()

New in version 0.7.0.

is_active(project: west.manifest.Project, extra_filter: Optional[Iterable[str]] = None) → bool

Is a project active?

Projects with empty ‘project.groups’ lists are always active.

Otherwise, if any group in ‘project.groups’ is enabled by this manifest’s ‘group-filter:’ list (and the ‘manifest.group-filter’ local configuration option, if we have a workspace), returns True.

Otherwise, i.e. if all of the project’s groups are disabled, this returns False.

“Inactive” projects should generally be considered absent from the workspace for purposes like updating it, listing projects, etc.

Parameters

  • project – project to check

  • extra_filter – an optional additional group filter

New in version 0.9.0.

class west.manifest.ImportFlag(value)

Bit flags for handling imports when resolving a manifest.

Note that any “path-prefix:” values set in an “import:” still take effect for the project itself even when IGNORE or IGNORE_PROJECTS are given. For example, in this manifest:

manifest:
  projects:
  - name: foo
    import:
      path-prefix: bar

Project ‘foo’ has path ‘bar/foo’ regardless of whether IGNORE or IGNORE_PROJECTS is given. This ensures the Project has the same path attribute as it normally would if imported projects weren’t being ignored.

DEFAULT = 0

The default value, 0, reads the file system to resolve “self: import:”, and runs git to resolve a “projects:” import.

IGNORE = 1

Ignore projects added via “import:” in “self:” and “projects:”

FORCE_PROJECTS = 2

Always invoke importer callback for “projects:” imports

IGNORE_PROJECTS = 4

Ignore projects added via “import:” : in “projects:” only; including any projects added via “import:” : in “self:”

class west.manifest.Project(name: str, url: str, revision: Optional[str] = None, path: Optional[Union[str, os.PathLike]] = None, submodules: Union[List[west.manifest.Submodule], bool] = False, clone_depth: Optional[int] = None, west_commands: Optional[Union[str, List[str]]] = None, topdir: Optional[Union[str, os.PathLike]] = None, remote_name: Optional[str] = None, groups: Optional[List[str]] = None, userdata: Optional[Any] = None)

Represents a project defined in a west manifest.

Attributes:

  • name: project’s unique name

  • url: project fetch URL

  • revision: revision to fetch from url when the project is updated

  • path: relative path to the project within the workspace (i.e. from topdir if that is set)

  • abspath: absolute path to the project in the native path name format (or None if topdir is)

  • posixpath: like abspath, but with slashes (/) as path separators

  • clone_depth: clone depth to fetch when first cloning the project, or None (the revision should not be a SHA if this is used)

  • west_commands: list of YAML files where extension commands in the project are declared

  • topdir: the top level directory of the west workspace the project is part of, or None

  • remote_name: the name of the remote which should be set up when the project is being cloned (default: ‘origin’)

  • groups: the project’s groups (as a list) as given in the manifest. If the manifest data contains no groups for the project, this is an empty list.

  • submodules: the project’s submodules configuration; either a list of Submodule objects, or a boolean.

  • userdata: the parsed ‘userdata’ field in the manifest, or None

Changed in version 0.8.0: The west_commands attribute is now always a list. In previous releases, it could be a string or None.

Changed in version 0.7.0: The remote attribute was removed. Its semantics could no longer be preserved when support for manifest import keys was added.

New in version 0.7.0: The remote_name and name_and_path attributes.

New in version 0.9.0: The group_filter and submodules attributes.

New in version 0.12.0: The userdata attribute.

Constructor:

__init__(name: str, url: str, revision: Optional[str] = None, path: Optional[Union[str, os.PathLike]] = None, submodules: Union[List[west.manifest.Submodule], bool] = False, clone_depth: Optional[int] = None, west_commands: Optional[Union[str, List[str]]] = None, topdir: Optional[Union[str, os.PathLike]] = None, remote_name: Optional[str] = None, groups: Optional[List[str]] = None, userdata: Optional[Any] = None)

Project constructor.

If topdir is None, then absolute path attributes (abspath and posixpath) will also be None.

Parameters

  • name – project’s name: attribute in the manifest

  • url – fetch URL

  • revision – fetch revision

  • path – path (relative to topdir), or None for name

  • submodules – submodules to pull within the project

  • clone_depth – depth to use for initial clone

  • west_commands – path to a west commands specification YAML file in the project, relative to its base directory, or list of these

  • topdir – the west workspace’s top level directory

  • remote_name – the name of the remote which should be set up if the project is being cloned (default: ‘origin’)

  • groups – a list of groups found in the manifest data for the project, after conversion to str and validation.

Changed in version 0.8.0: The path and topdir parameters can now be any os.PathLike.

Changed in version 0.7.0: The parameters were incompatibly changed from previous versions.

Methods:

as_dict() → Dict

Return a representation of this object as a dict, as it would be parsed from an equivalent YAML manifest.

New in version 0.7.0.

git(cmd: Union[str, List[str]], extra_args: Iterable[str] = (), capture_stdout: bool = False, capture_stderr: bool = False, check: bool = True, cwd: Optional[Union[str, os.PathLike]] = None) → subprocess.CompletedProcess

Run a git command in the project repository.

Parameters

  • cmd – git command as a string (or list of strings)

  • extra_args – sequence of additional arguments to pass to the git command (useful mostly if cmd is a string).

  • capture_stdout – if True, git’s standard output is captured in the CompletedProcess instead of being printed.

  • capture_stderr – Like capture_stdout, but for standard error. Use with caution: this may prevent error messages from being shown to the user.

  • check – if given, subprocess.CalledProcessError is raised if git finishes with a non-zero return code

  • cwd – directory to run git in (default: self.abspath)

Changed in version 0.6.1: The capture_stderr kwarg.

Changed in version 0.7.0: The (now removed) Project.format method is no longer called on arguments.

sha(rev: str, cwd: Optional[Union[str, os.PathLike]] = None) → str

Get the SHA for a project revision.

Parameters

  • rev – git revision (HEAD, v2.0.0, etc.) as a string

  • cwd – directory to run command in (default: self.abspath)

Changed in version 0.7.0: Standard error is now captured.

is_ancestor_of(rev1: str, rev2: str, cwd: Optional[Union[str, os.PathLike]] = None) → bool

Check if ‘rev1’ is an ancestor of ‘rev2’ in this project.

Returns True if rev1 is an ancestor commit of rev2 in the given project; rev1 and rev2 can be anything that resolves to a commit. (If rev1 and rev2 refer to the same commit, the return value is True, i.e. a commit is considered an ancestor of itself.) Returns False otherwise.

Parameters

  • rev1 – commit that could be the ancestor of rev2

  • rev2 – commit that could be a descendant or rev1

  • cwd – directory to run command in (default: self.abspath)

Changed in version 0.8.0: The cwd parameter can now be any os.PathLike.

is_cloned(cwd: Optional[Union[str, os.PathLike]] = None) → bool

Returns True if self.abspath looks like a git repository’s top-level directory, and False otherwise.

Parameters

cwd – directory to run command in (default: self.abspath)

Changed in version 0.8.0: The cwd parameter can now be any os.PathLike.

New in version 0.6.1.

is_up_to_date_with(rev: str, cwd: Optional[Union[str, os.PathLike]] = None) → bool

Check if the project is up to date with rev, returning True if so.

This is equivalent to is_ancestor_of(rev, 'HEAD', cwd=cwd).

Parameters

  • rev – base revision to check if project is up to date with.

  • cwd – directory to run command in (default: self.abspath)

Changed in version 0.8.0: The cwd parameter can now be any os.PathLike.

is_up_to_date(cwd: Optional[Union[str, os.PathLike]] = None) → bool

Check if the project HEAD is up to date with the manifest.

This is equivalent to is_up_to_date_with(self.revision, cwd=cwd).

Parameters

cwd – directory to run command in (default: self.abspath)

Changed in version 0.8.0: The cwd parameter can now be any os.PathLike.

read_at(path: Union[str, os.PathLike], rev: Optional[str] = None, cwd: Optional[Union[str, os.PathLike]] = None) → bytes

Read file contents in the project at a specific revision.

Parameters

  • path – relative path to file in this project

  • rev – revision to read path from (default: self.revision)

  • cwd – directory to run command in (default: self.abspath)

Changed in version 0.8.0: The cwd parameter can now be any os.PathLike.

New in version 0.7.0.

listdir_at(path: Union[str, os.PathLike], rev: Optional[str] = None, cwd: Optional[Union[str, os.PathLike]] = None, encoding: Optional[str] = None) → List[str]

List of directory contents in the project at a specific revision.

The return value is the directory contents as a list of files and subdirectories.

Parameters

  • path – relative path to file in this project

  • rev – revision to read path from (default: self.revision)

  • cwd – directory to run command in (default: self.abspath)

  • encoding – directory contents encoding (default: ‘utf-8’)

Changed in version 0.8.0: The cwd parameter can now be any os.PathLike.

New in version 0.7.0.

class west.manifest.ManifestProject(path: Optional[Union[str, os.PathLike]] = None, west_commands: Optional[Union[str, List[str]]] = None, topdir: Optional[Union[str, os.PathLike]] = None, userdata: Optional[Any] = None)

Represents the manifest repository as a Project.

Meaningful attributes:

  • name: the string "manifest"

  • topdir: the top level directory of the west workspace the manifest project controls, or None

  • path: relative path to the manifest repository within the workspace, or None (i.e. from topdir if that is set)

  • abspath: absolute path to the manifest repository in the native path name format (or None if topdir is)

  • posixpath: like abspath, but with slashes (/) as path separators

  • west_commands:west_commands: key in the manifest’s self: map. This may be a list of such if the self section imports multiple additional files with west commands.

  • userdata: the parsed ‘userdata’ field under self in the manifest file

Other readable attributes included for Project compatibility:

  • url: the empty string; the west manifest is not version-controlled by west itself, even though ‘west init’ can fetch a manifest repository from a Git remote

  • revision: "HEAD"

  • clone_depth: None, because there’s no URL

  • groups: the empty list

A limited subset of Project methods is supported. Results for calling others are not specified.

Changed in version 0.8.0: The url attribute is now the empty string instead of None. The abspath attribute is created using os.path.abspath() instead of os.path.realpath(), improving support for symbolic links.

as_dict() → Dict

Return a representation of this object as a dict, as it would be parsed from an equivalent YAML manifest.

New in version 0.6.0.

class west.manifest.Submodule(path: str, name: Optional[str] = None)

Represents a Git submodule within a project.

New in version 0.9.0.

Exceptions

class west.manifest.MalformedManifest

Bases: Exception

Manifest parsing failed due to invalid data.

class west.manifest.MalformedConfig

Bases: Exception

The west configuration was malformed.

class west.manifest.ManifestVersionError(version: str, file: Optional[Union[str, os.PathLike]] = None)

Bases: Exception

The manifest required a version of west more recent than the current version.

Changed in version 0.8.0: The file argument can now be any os.PathLike.

class west.manifest.ManifestImportFailed(project: Optional[west.manifest.Project], imp: Any)

Bases: Exception

An operation required to resolve a manifest failed.

Attributes:

  • project: the Project instance with the missing manifest data; None if it’s from the manifest via “manifest: self: import:”

  • imp: the parsed YAML data whose import was requested

Changed in version 0.8.0: The filename argument can now be any os.PathLike.

Changed in version 0.13.0: The filename argument was renamed imp, and can now take any value.

west.util

Miscellaneous utilities.

Functions

west.util.west_dir(start: Optional[Union[str, os.PathLike]] = None) → str

Returns the absolute path of the workspace’s .west directory.

Starts the search from the start directory, and goes to its parents. If the start directory is not specified, the current directory is used.

Raises WestNotFound if no .west directory is found.

Changed in version 0.8.0: The start parameter can be any os.PathLike.

west.util.west_topdir(start: Optional[Union[str, os.PathLike]] = None, fall_back: bool = True) → str

Like west_dir(), but returns the path to the parent directory of the .west/ directory instead, where project repositories are stored

Changed in version 0.8.0: The start parameter can be any os.PathLike.

Exceptions

class west.util.WestNotFound

Bases: RuntimeError

Neither the current directory nor any parent has a west workspace.