West API

本页介绍 west 提供的 Python API，以及 Zephyr 仓库中的 west 扩展使用的一些附加 API。

west.commands

所有内置命令和扩展命令都通过继承这里定义的 WestCommand 实现。此外，这里还提供一些异常类型。

WestCommand

class west.commands.WestCommand(name: str, help: str, description: str, accepts_unknown_args: bool = False, requires_workspace: bool = True, verbosity: Verbosity = Verbosity.INF)

Abstract superclass for a west command.

实例属性：

name: 与传给构造函数的值相同。

help: 与传给构造函数的值相同。内置命令必须提供，扩展命令会忽略它，见 https://github.com/zephyrproject-rtos/west/issues/927

description: 与传给构造函数的值相同。

accepts_unknown_args: 与传给构造函数的值相同。

requires_workspace: 与传给构造函数的值相同。

在 0.7.0 版本加入.

parser: 调用 WestCommand.add_parser() 创建的参数解析器。

实例属性访问器：

manifest: 返回当前清单文件对应的 west.manifest.Manifest 实例；如果未提供实例，则终止程序。只能在 do_run() 方法中安全使用该属性。

在 0.6.1 版本加入.

在 0.7.0 版本发生变更: 现在可以设置该属性。

has_manifest: 如果读取 manifest 属性会成功而非报错，则为 True。

config: 可设置的属性，返回 west.configuration.Configuration 实例；如果未提供实例，则终止程序。只能在 do_run() 方法中安全使用。

在 0.13.0 版本加入.

has_config: 如果读取 config 属性会成功而非报错，则为 True。

在 0.13.0 版本加入.

git_version_info: 包含 Git 版本信息的元组。

在 0.11.0 版本加入.

color_ui: west 配置允许彩色输出时为 True，否则为 False。

在 1.0.0 版本加入.

构造函数：

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

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.

参数:

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.
verbosity -- command output verbosity level; can be changed later

在 0.6.0 版本加入: requires_installation 参数（在 v0.13.0 中移除）。

在 0.7.0 版本加入: requires_workspace 参数。

在 0.8.0 版本发生变更: topdir 参数现在可以是任意 os.PathLike 对象。

在 0.13.0 版本发生变更: 已弃用的 requires_installation 参数被移除。

在 1.0.0 版本加入: verbosity 参数。

方法：

run(args: Namespace, unknown: list[str], topdir: str | PathLike, manifest: Manifest | None = None, config: Configuration | None = 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.

参数:

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

在 0.6.0 版本发生变更: 新增 topdir 参数。

add_parser(parser_adder) → ArgumentParser

Registers a parser for this command, and returns it.

The parser object is stored in a parser attribute.

参数:: parser_adder -- The return value of a call to argparse.ArgumentParser.add_subparsers()

add_pre_run_hook(hook: Callable[[WestCommand], None]) → None

Add a hook which will be called right before do_run().

This can be useful to defer work that needs a fully set up command to work.

参数:: hook -- hook to add

在 1.0.0 版本加入.

check_call(args, **kwargs): 先以 Verbosity.DBG_MORE 级别记录调用，再运行 subprocess.check_call(args, **kwargs)。

在 1.2.0 版本发生变更: cwd 关键字参数被用于接收任意关键字参数的 **kwargs 替代。

在 0.11.0 版本发生变更.

check_output(args, **kwargs): 先以 Verbosity.DBG_MORE 级别记录调用，再运行 subprocess.check_output(args, **kwargs)。

在 1.2.0 版本发生变更: The cwd keyword argument was replaced with a catch-all **kwargs.

在 0.11.0 版本发生变更.

run_subprocess(args, **kwargs): 先以 Verbosity.DBG_MORE 级别记录调用，再运行 subprocess.run(args, **kwargs)。

在 1.2.0 版本加入.

所有子类都必须提供以下抽象方法，用于实现上述功能：

abstractmethod do_add_parser(parser_adder) → 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.

参数:: parser_adder -- The return value of a call to argparse.ArgumentParser.add_subparsers()

abstractmethod do_run(args: Namespace, unknown: list[str])

Subclasses must implement; called to run the command.

参数:

args -- argparse.Namespace of parsed arguments
unknown -- If accepts_unknown_args is true, a sequence of un-parsed argument strings.

命令需要输出信息时应使用以下方法。它们用于从已弃用的 west.log 模块迁移到按命令提供的接口，以便在未来版本中为 west 命令实现全局“静默”模式：

dbg(*args, level: Verbosity = Verbosity.DBG, end: str = '\n')

Print a verbose debug message.

The message is only printed if self.verbosity is at least level.

参数:

args -- sequence of arguments to print
level -- verbosity level of the message

在 1.2.0 版本发生变更: end 参数。

在 1.0.0 版本加入.

inf(*args, colorize: bool = False, end: str = '\n')

Print an informational message.

The message is only printed if self.verbosity is at least INF.

参数:

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.

在 1.2.0 版本发生变更: The end argument.

在 1.0.0 版本加入.

wrn(*args, end: str = '\n')

Print a warning.

The message is only printed if self.verbosity is at least WRN.

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.

参数:: args -- sequence of arguments to print.

在 1.2.0 版本发生变更: The end argument.

在 1.0.0 版本加入.

err(*args, fatal: bool = False, end: str = '\n')

Print an error.

The message is only printed if self.verbosity is at least ERR.

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

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

参数:

args -- sequence of arguments to print.
fatal -- if True, the the message is prefixed with "FATAL ERROR: "; otherwise, "ERROR: " is used.

在 1.2.0 版本发生变更: The end argument.

在 1.0.0 版本加入.

die(*args, exit_code: int = 1) → NoReturn

Print a fatal error using err(), and abort the program.

参数:

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.

在 1.0.0 版本加入.

banner(*args)

Prints args as a "banner" using inf().

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

在 1.0.0 版本加入.

small_banner(*args): Prints args as a smaller banner(), i.e. prefixed with '-- ' and not colorized.

在 1.0.0 版本加入.

输出详细程度

自 west v1.0 起，west 命令应使用 west.commands.WestCommand.dbg()、west.commands.WestCommand.inf() 等方法输出信息，见上文。本节介绍用于声明输出详细程度的相关枚举。

class west.commands.Verbosity(*values)

Verbosity levels for WestCommand instances.

QUIET = 0: No output is printed when WestCommand.dbg(), .inf(), etc. are called.

ERR = 1: Only error messages are printed.

WRN = 2: Only error and warnings are printed.

INF = 3: Errors, warnings, and informational messages are printed.

DBG = 4: Like INFO, but WestCommand.dbg(..., level=Verbosity.DBG) output is also printed.

DBG_MORE = 5: Like DEBUG, but WestCommand.dbg(..., level=Verbosity.DBG_MORE) output is also printed.

DBG_EXTREME = 6: Like DEBUG_MORE, but WestCommand.dbg(..., level=Verbosity.DBG_EXTREME) output is also printed.

在 1.0.0 版本加入.

异常

class west.commands.CommandError(returncode=1)

基类：RuntimeError

Indicates that a command failed.

returncode: 此错误建议使用的程序退出码。

class west.commands.CommandContextError(returncode=1)

基类：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.

自 west v0.13 起，推荐通过 west.configuration.Configuration 读取配置。

编写 west 扩展时，可通过 self.config 访问当前 Configuration 对象，见 west.commands.WestCommand。

配置 API

这是自 west v0.13 起推荐使用的 API。

class west.configuration.ConfigFile(*values)

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: str | PathLike | None = None)

Represents the available configuration options and their values.

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

Setting values affects files immediately and is not protected against concurrent reads. The caller is responsible for any necessary mutual exclusion.

WEST_CONFIG_* environment variables take effect when and only when a Configuration object is created. This can be used to point different objects at different files.

If no topdir argument is passed to the constructor and WEST_CONFIG_LOCAL is not defined then the object does not point to any local file.

在 0.13.0 版本加入.

delete(option: str, configfile: ConfigFile | None = None) → None

Delete an option from the given file or files.

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

参数:

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: str | None = None, configfile: ConfigFile = ConfigFile.ALL) → str | None

Get a configuration option's value as a string.

参数:

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: 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.

参数:

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: float | None = None, configfile: ConfigFile = ConfigFile.ALL) → float | None

Get a configuration option's value as a float.

参数:

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: int | None = None, configfile: ConfigFile = ConfigFile.ALL) → int | None

Get a configuration option's value as an int.

参数:

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: ConfigFile = ConfigFile.ALL) → Iterable[tuple[str, Any]]: Iterator of option, value pairs.

set(option: str, value: Any, configfile: 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.

参数:

option -- option to set, in 'foo.bar' form
value -- value to set option to
configfile -- type of config file to set the value in

已弃用的 API

以下 API 也使用 west.configuration.ConfigFile，但默认操作保存当前工作区配置的全局对象。由于 west API 可用于多个工作区，这已被证明是不恰当的设计。这些 API 在 west v0.13.0 中被弃用。

这些 API 为兼容旧扩展而保留。如果新代码可以假定使用 west v0.13.0 或更高版本，就不应使用它们。

west.configuration.read_config(configfile: ConfigFile | None = None, config: ConfigParser = <configparser.ConfigParser object>, topdir: str | PathLike | None = 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.

参数:

configfile -- a west.configuration.ConfigFile
config -- configuration object to read into
topdir -- west workspace root to read local options from

在 0.8.0 版本发生变更: 已弃用的 read_config 参数被移除。

在 0.6.0 版本发生变更: 无法找到本地配置文件所导致的错误会被忽略。

west.configuration.update_config(section: str, key: str, value: Any, configfile: ConfigFile = ConfigFile.LOCAL, topdir: str | PathLike | None = None) → None

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

参数:

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: 用于当前配置的模块级全局 ConfigParser 实例。读取之前应使用 west.configuration.read_config() 初始化。

west.log（已弃用）

Deprecated due to its use of global state, which makes west harder to unit test. See:

https://github.com/zephyrproject-rtos/west/issues/149

Removal won't come until west v2.0.

In the future, commands should use equivalent WestCommand methods instead. For example, use WestCommand.dbg() instead of west.log.dbg(), and so forth.

Provides common methods for printing messages to display to the user which respect the color.ui configuration option and verbosity level. These were formerly encouraged for WestCommand instances.

控制输出详细程度

使用 set_verbosity() 设置全局输出详细程度。

west.log.set_verbosity(value)

Set the logging verbosity level.

参数:: value -- verbosity level to set, e.g. VERBOSE_VERY.

定义了以下详细程度级别。

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.

输出函数

主要函数为 dbg()、inf()、wrn()、err() 和 die()。还提供 inf() 的两个特殊形式 banner() 和 small_banner()，用于将输出分组为不同“章节”。

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

Print a verbose debug logging message.

参数:

args -- sequence of arguments to print.
level -- verbosity level to set, e.g. VERBOSE_VERY.

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

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

Print an informational message.

参数:

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.

参数:: 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().

参数:

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.

参数:

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.

主要类是 Manifest 和 Project，用于表示清单文件的内容。推荐使用 Manifest.from_topdir() 解析 west 清单。

常量与函数

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 = '1.2'

The latest manifest schema version supported by this west program.

This value will change whenever a new version of west includes new manifest file features not supported by earlier versions of west. (Its value changed to 1.0 following the release of west versions v1.0.x, so that users can say "I want schema version 1" instead of having to keep using '0.13', which was the previous version this changed.)

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.

参数:: data -- YAML manifest data as a string or object

在 0.13.0 版本发生变更: 返回经过验证、包含已解析 YAML 数据的字典。

清单及其子对象

The parsed contents of a west manifest file.

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 or manifest.project-filter; 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

参数:

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

在 0.7.0 版本发生变更: importer 和 import_flags 关键字参数。

在 0.13.0 版本发生变更: 所有参数改为仅限关键字传入。source_file 参数被移除，请改用 topdir。此函数不再抛出 WestNotFound。

在 0.13.0 版本加入: config 参数。

在 0.13.0 版本加入: abspath、posixpath、relative_path、yaml_path、repo_path、repo_posixpath 和 userdata 属性。

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.

参数:

topdir -- workspace top-level directory
config -- passed to Manifest()
importer -- passed to Manifest()
import_flags -- passed to Manifest()

在 0.13.0 版本加入.

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

参数:

source_file -- source file to load
importer -- passed to Manifest()
import_flags -- passed to Manifest()

在 0.7.0 版本发生变更: 新增 **kwargs。

在 0.8.0 版本发生变更: source_file、manifest_path 和 topdir 参数现在可以是任意 os.PathLike 对象。

在 0.13.0 版本发生变更: manifest_path 和 topdir 参数被移除。

static from_data(source_data: str | dict, importer: ~typing.Callable[[~west.manifest.Project, str], str | list[str] | None] | None = None, import_flags: ~west.manifest.ImportFlag = <ImportFlag.DEFAULT: 0>) → 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.

参数:

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

在 0.7.0 版本发生变更: 新增 **kwargs，且 source_data 可以是 str。

在 0.13.0 版本发生变更: The manifest_path and topdir arguments were removed.

以下辅助方法用于按名称或其他标识访问子对象：

get_projects(project_ids: Iterable[str | PathLike], allow_paths: bool = True, only_cloned: bool = False) → list[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.

参数:

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

在 0.8.0 版本发生变更: project_ids 序列现在可以包含任意 os.PathLike 对象。

在 0.6.1 版本加入.

其他方法：

as_dict(active_only: bool = False) → 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.

参数:: active_only -- Do not resolve inactive projects

在 1.4.0 版本加入: active_only 参数。

在 0.7.0 版本加入.

as_frozen_dict(active_only: bool = False) → 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.

参数:: active_only -- Do not freeze inactive projects

在 1.4.0 版本加入: The active_only argument.

as_yaml(active_only: bool = False, **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.

参数:

active_only -- Do not resolve inactive projects
kwargs -- passed to yaml.safe_dump()

在 1.4.0 版本加入: The active_only argument.

在 0.7.0 版本加入.

as_frozen_yaml(active_only: bool = False, **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.

参数:

active_only -- Do not freeze inactive projects
kwargs -- passed to yaml.safe_dump()

在 1.4.0 版本加入: The active_only argument.

在 0.7.0 版本加入.

is_active(project: Project, extra_filter: Iterable[str] | None = None) → bool

Is a project active?

If the manifest.project-filter configuration option is set, the return value determined by the option's value:

The elements of the manifest.project-filter value are checked against the project's name. If the regular expression in the element matches the project's name, then the project is active or inactive depending on if the element begins with + or - respectively.
If multiple elements have regular expressions matching the project's name, the last element which has a match determines the result.
This function returns True or False if the project is active or inactive according to these rules.

The manifest.project-filter value that was set at the time this Manifest object was constructed is used.

Otherwise, the return value depends on whether the project has any groups, and if so, whether they are enabled:

Projects with empty 'project.groups' lists are always active, and this function returns True for such projects.
If 'project.groups' is not empty, and any group in it is enabled by this manifest's 'group-filter:' list (and the 'manifest.group-filter' local configuration option, if we have a workspace), this 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, listing, resolving imports, etc.

参数:

project -- project to check
extra_filter -- an optional additional group filter

在 0.9.0 版本加入.

在 1.1.0 版本发生变更: 遵循 manifest.project-filter 配置选项，见内置配置选项。

class west.manifest.ImportFlag(*values)

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:"

Represents a project defined in a west manifest.

Attributes:

name: project's unique name
description: project's description
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

在 0.7.0 版本发生变更: remote 属性被移除。增加清单 import 键支持后，无法继续保持该属性的语义。

在 0.7.0 版本加入: remote_name 和 name_and_path 属性。

在 0.8.0 版本发生变更: west_commands 属性现在始终为列表；旧版中也可能为字符串或 None。

在 0.9.0 版本加入: group_filter 和 submodules 属性。

在 0.12.0 版本加入: userdata 属性。

在 1.2.0 版本加入: description 属性。

构造函数：

Project constructor.

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

参数:

name -- project's name: attribute in the manifest
description -- project's description or None
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.

在 0.8.0 版本发生变更: path 和 topdir 参数现在可以是任意 os.PathLike 对象。

在 0.7.0 版本发生变更: 参数相对于此前版本发生了不兼容变更。

方法：

as_dict() → dict: Return a representation of this object as a dict, as it would be parsed from an equivalent YAML manifest.

在 0.7.0 版本加入.

git(cmd: str | list[str], extra_args: Iterable[str] = (), capture_stdout: bool = False, capture_stderr: bool = False, check: bool = True, cwd: str | PathLike | None = None) → CompletedProcess

Run a git command in the project repository.

参数:

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)

在 0.6.1 版本发生变更: capture_stderr 关键字参数。

在 0.7.0 版本发生变更: 不再对参数调用现已移除的 Project.format 方法。

sha(rev: str, cwd: str | PathLike | None = None) → str

Get the SHA for a project revision.

参数:

rev -- git revision (HEAD, v2.0.0, etc.) as a string
cwd -- directory to run command in (default: self.abspath)

在 0.7.0 版本发生变更: 现在会捕获标准错误。

is_ancestor_of(rev1: str, rev2: str, cwd: str | PathLike | None = 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.

参数:

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)

在 0.8.0 版本发生变更: cwd 参数现在可以是任意 os.PathLike 对象。

is_cloned(cwd: str | PathLike | None = None) → bool

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

参数:: cwd -- directory to run command in (default: self.abspath)

在 0.8.0 版本发生变更: The cwd parameter can now be any os.PathLike.

在 0.6.1 版本加入.

is_up_to_date_with(rev: str, cwd: str | PathLike | None = 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).

参数:

rev -- base revision to check if project is up to date with.
cwd -- directory to run command in (default: self.abspath)

在 0.8.0 版本发生变更: The cwd parameter can now be any os.PathLike.

is_up_to_date(cwd: str | PathLike | None = 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).

参数:: cwd -- directory to run command in (default: self.abspath)

在 0.8.0 版本发生变更: The cwd parameter can now be any os.PathLike.

read_at(path: str | PathLike, rev: str | None = None, cwd: str | PathLike | None = None) → bytes

Read file contents in the project at a specific revision.

参数:

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)

在 0.8.0 版本发生变更: The cwd parameter can now be any os.PathLike.

在 0.7.0 版本加入.

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.

参数:

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')

在 0.8.0 版本发生变更: The cwd parameter can now be any os.PathLike.

在 0.7.0 版本加入.

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

仅支持 Project 方法的有限子集，调用其他方法的结果未作规定。

在 0.8.0 版本发生变更: url 属性现在为空字符串，而非 None。abspath 属性改用 os.path.abspath() 创建，而非 os.path.realpath()，以改善符号链接支持。

as_dict() → dict: Return a representation of this object as a dict, as it would be parsed from an equivalent YAML manifest.

在 0.6.0 版本加入.

class west.manifest.Submodule(path: str, name: str | None = None): Represents a Git submodule within a project.

在 0.9.0 版本加入.

Exceptions

class west.configuration.MalformedConfig

基类：Exception

The west configuration was malformed.

class west.manifest.MalformedManifest

基类：Exception

Manifest parsing failed due to invalid data.

class west.manifest.ManifestVersionError(version: str, file: str | PathLike | None = None)

基类：Exception

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

在 0.8.0 版本发生变更: file 参数现在可以是任意 os.PathLike 对象。

class west.manifest.ManifestImportFailed(project: Project | None, imp: Any)

基类：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

在 0.8.0 版本发生变更: filename 参数现在可以是任意 os.PathLike 对象。

在 0.13.0 版本发生变更: filename 参数改名为 imp，现在可以接受任意值。

west.util

Miscellaneous utilities.

函数

west.util.west_dir(start: str | PathLike | None = 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.

在 0.8.0 版本发生变更: start 参数可以是任意 os.PathLike 对象。

west.util.west_topdir(start: str | PathLike | None = 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

在 0.8.0 版本发生变更: The start parameter can be any os.PathLike.

Exceptions

class west.util.WestNotFound

基类：RuntimeError

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