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 thedo_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.
-
git_version_info
¶ A tuple of Git version information.
New in version 0.11.0.
Constructor:
-
WestCommand.
__init__
(name, help, description, accepts_unknown_args=False, requires_workspace=True, requires_installation=None)¶ 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 byWestCommand.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.
requires_installation – deprecated equivalent for “requires_workspace”; this may go away eventually.
Changed in version 0.8.0: The topdir parameter can now be any
os.PathLike
.New in version 0.6.0: The requires_installation parameter.
New in version 0.7.0: The requires_workspace parameter.
Methods:
-
WestCommand.
run
(args, unknown, topdir, manifest=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 truetopdir – west workspace topdir, accessible as a str via
self.topdir
fromWestCommand.do_run
manifest –
west.manifest.Manifest
orNone
, accessible asself.manifest
fromWestCommand.do_run
Changed in version 0.6.0: The topdir argument was added.
-
WestCommand.
add_parser
(parser_adder)¶ Registers a parser for this command, and returns it.
The parser object is stored in a
parser
attribute of.- 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)¶ 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 anArgumentParser
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, unknown)¶ Subclasses must implement; called to run the command.
- Parameters
args –
argparse.Namespace
of parsed argumentsunknown – 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.
This provides API access to west configuration files and data.
Reading and writing options¶
-
west.configuration.
read_config
(configfile: Optional[west.configuration.ConfigFile] = None, config: configparser.ConfigParser = <configparser.ConfigParser object>, topdir: Optional[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
orConfigFile.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: 4>, 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 ALLtopdir – 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).
-
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
Global configuration instance¶
-
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.
Prints args as a “banner” at inf() level.
The args are prefixed with ‘=== ‘ and colorized by default.
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.10'¶ 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 workspaceMalformedConfig
if the configuration file has nomanifest.path
keyFileNotFoundError
if no manifest file exists as determined bymanifest.path
andmanifest.file
-
west.manifest.
validate
(data: Any) → None¶ 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.)
- Parameters
data – YAML manifest data as a string or object
Manifest and sub-objects¶
-
class
west.manifest.
Manifest
(source_file: Optional[Union[str, os.PathLike]] = None, source_data: Optional[Union[str, Dict]] = None, manifest_path: Optional[Union[str, os.PathLike]] = None, topdir: 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: 0>, **kwargs: Dict[str, Any])¶ The parsed contents of a west manifest file.
-
__init__
(source_file: Optional[Union[str, os.PathLike]] = None, source_data: Optional[Union[str, Dict]] = None, manifest_path: Optional[Union[str, os.PathLike]] = None, topdir: 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: 0>, **kwargs: Dict[str, Any])¶ Using
from_file
orfrom_data
is usually easier than direct instantiation.Instance attributes:
projects
: sequence ofProject
topdir
: west workspace top level directory, or Nonepath
: path to the manifest file itself, or Nonehas_imports
: bool, True if the manifest contains an “import:” attribute in “self:” or “projects:”; False otherwisegroup_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.
Exactly one of source_file and source_data must be given.
If source_file is given:
If topdir is too,
projects
is rooted there.Otherwise, topdir is found starting at source_file.
If source_data is given:
If topdir is too,
projects
is rooted there.Otherwise, there is no root:
projects[i].abspath
and other absolute path attributes areNone
.If
source_data['manifest']['self']['path']
is unset, manifest_path is used as a fallback.
The importer kwarg, if given, is a callable. It is called when source_file requires importing manifest data that aren’t found locally. It will be called as:
importer(project, file)
where
project
is aProject
andfile
is the missing file. The file’s contents at refs/heads/manifest-rev should usually be returned, potentially after fetching the project’s revision from its remote URL and updating that ref.The 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 invalidManifestImportFailed
: if the manifest could not be resolved due to import errorsManifestVersionError
: if this version of west is too old to parse the manifestWestNotFound
: if topdir was needed and not foundValueError
: for other invalid arguments
- Parameters
source_file – YAML file containing manifest data
source_data – parsed YAML data as a Python object, or a string containing unparsed YAML data
manifest_path – fallback
ManifestProject
path
attributetopdir – used as the west workspace top level directory
importer – callback to resolve missing manifest import data
import_flags – bit mask, controls import resolution
Changed in version 0.7.0: The importer and import_flags keyword arguments.
-
static
from_file
(source_file: Optional[Union[str, os.PathLike]] = None, **kwargs) → west.manifest.Manifest¶ Manifest object factory given a source YAML file.
The default behavior is to find the current west workspace’s manifest file and resolve it.
Results depend on the keyword arguments given in kwargs:
If both source_file and topdir are given, the returned Manifest object is based on the data in source_file, rooted at topdir. The configuration variable
manifest.path
is ignored in this case, thoughmanifest.group-filter
will still be read if it exists.This allows parsing a manifest file “as if” its project hierarchy were rooted at another location in the system.
If neither source_file nor topdir is given, the file system is searched for topdir. That workspace’s
manifest.path
configuration option is used to find source_file,topdir/<manifest.path>/<manifest.file>
.If only source_file is given, topdir is found starting there. The directory containing source_file doesn’t have to be
manifest.path
in this case.If only topdir is given, that workspace’s
manifest.path
is used to find source_file.
Exceptions raised:
west.util.WestNotFound
if no topdir can be foundMalformedManifest
if source_file contains invalid dataManifestVersionError
if this version of west is too old to parse the manifest.MalformedConfig
ifmanifest.path
is needed and can’t be readValueError
if topdir is given but is not a west workspace root
- Parameters
source_file – source file to load
kwargs – Manifest.__init__ keyword arguments
Changed in version 0.8.0: The source_file, manifest_path, and topdir arguments can now be any
os.PathLike
.Changed in version 0.7.0:
**kwargs
added.-
static
from_data
(source_data: Union[str, Dict], **kwargs) → west.manifest.Manifest¶ Manifest object factory given parsed YAML data.
This factory does not read any configuration files.
Letting the return value be
m
. Results then depend on keyword arguments in kwargs:Unless topdir is given, all absolute paths in
m
, likem.projects[1].abspath
, areNone
.Relative paths, like
m.projects[1].path
, are taken from source_data.If
source_data['manifest']['self']['path']
is not set, thenm.projects[MANIFEST_PROJECT_INDEX].abspath
will be set to manifest_path if given.
Returns the same exceptions as the Manifest constructor.
- Parameters
source_data – parsed YAML data as a Python object, or a string with unparsed YAML data
kwargs – Manifest.__init__ keyword arguments
Changed in version 0.7.0:
**kwargs
added, and source_data may be astr
.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 unclonedProject
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)¶ Represents a project defined in a west manifest.
Attributes:
name
: project’s unique nameurl
: project fetch URLrevision
: revision to fetch fromurl
when the project is updatedpath
: relative path to the project within the workspace (i.e. fromtopdir
if that is set)abspath
: absolute path to the project in the native path name format (orNone
iftopdir
is)posixpath
: likeabspath
, but with slashes (/
) as path separatorsclone_depth
: clone depth to fetch when first cloning the project, orNone
(the revision should not be a SHA if this is used)west_commands
: list of YAML files where extension commands in the project are declaredtopdir
: the top level directory of the west workspace the project is part of, orNone
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.
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.
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)¶ Project constructor.
If topdir is
None
, then absolute path attributes (abspath
andposixpath
) will also beNone
.- Parameters
name – project’s
name:
attribute in the manifesturl – 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 codecwd – 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
ifself.abspath
looks like a git repository’s top-level directory, andFalse
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)¶ 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, orNone
path
: relative path to the manifest repository within the workspace, orNone
(i.e. fromtopdir
if that is set)abspath
: absolute path to the manifest repository in the native path name format (orNone
iftopdir
is)posixpath
: likeabspath
, but with slashes (/
) as path separatorswest_commands
:west_commands:
key in the manifest’sself:
map. This may be a list of such if the self section imports multiple additional files with west commands.
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 remoterevision
:"HEAD"
clone_depth
:None
, because there’s no URLgroups
: 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 usingos.path.abspath()
instead ofos.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 in a way that made a manifest operation fail.
-
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: west.manifest.Project, filename: Union[str, os.PathLike])¶ Bases:
Exception
An operation required to resolve a manifest failed.
Attributes:
project
: the Project instance with the missing manifest datafilename
: the missing file, as a str
Changed in version 0.8.0: The filename argument can now be any
os.PathLike
.
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.