:orphan:

.. _west-apis: .. _west-apis-west:

West APIs #########

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

Contents:

.. contents:: :local:

.. NOTE: documentation authors:

keep these sorted by package/module name.
if you add a :ref: target here, add it to west-not-found.rst too.

.. _west-apis-commands:

west.commands

.. module:: west.commands

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

WestCommand

.. autoclass:: west.commands.WestCommand

Instance attributes:

.. py:attribute:: name

  As passed to the constructor.

.. py:attribute:: help

  As passed to the constructor. Required by built-in commands, ignored by
  extensions, see https://github.com/zephyrproject-rtos/west/issues/927

.. py:attribute:: description

  As passed to the constructor.

.. py:attribute:: accepts_unknown_args

  As passed to the constructor.

.. py:attribute:: requires_workspace

  As passed to the constructor.

.. versionadded:: 0.7.0

.. py:attribute:: parser

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

Instance properties:

.. py:attribute:: manifest

  A property which returns the :py:class:`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.

.. versionadded:: 0.6.1 .. versionchanged:: 0.7.0 This is now settable.

.. py:attribute:: has_manifest

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

.. py:attribute:: config

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

.. versionadded:: 0.13.0

.. py:attribute:: has_config

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

.. versionadded:: 0.13.0

.. py:attribute:: git_version_info

  A tuple of Git version information.

.. versionadded:: 0.11.0

.. py:attribute:: color_ui

  True if the west configuration permits colorized output,
  False otherwise.

.. versionadded:: 1.0.0

Constructor:

.. automethod:: init

.. versionadded:: 0.6.0 The requires_installation parameter (removed in v0.13.0). .. versionadded:: 0.7.0 The requires_workspace parameter. .. versionchanged:: 0.8.0 The topdir parameter can now be any os.PathLike. .. versionchanged:: 0.13.0 The deprecated requires_installation parameter was removed. .. versionadded:: 1.0.0 The verbosity parameter.

Methods:

.. automethod:: run

.. versionchanged:: 0.6.0 The topdir argument was added.

.. automethod:: add_parser

.. automethod:: add_pre_run_hook .. versionadded:: 1.0.0

.. NOTE: the following 'method' (not 'automethod') directives were added for expediency during the west v1.2 release time frame to work around a build failure in this zephyr documentation that could not be fixed without cutting a west point release. (The docstrings in west had some RST syntax errors).

  These should be reverted back to automethod calls at the next release.

.. method:: check_call(args, **kwargs)

  Runs ``subprocess.check_call(args, **kwargs)`` after
  logging the call at ``Verbosity.DBG_MORE`` level.

.. versionchanged:: 1.2.0 The cwd keyword argument was replaced with a catch-all **kwargs. .. versionchanged:: 0.11.0

.. method:: check_output(args, **kwargs)

  Runs ``subprocess.check_output(args, **kwargs)`` after
  logging the call at Verbosity.DBG_MORE level.

.. versionchanged:: 1.2.0 The cwd keyword argument was replaced with a catch-all **kwargs. .. versionchanged:: 0.11.0

.. method:: run_subprocess(args, **kwargs)

  Runs ``subprocess.run(args, **kwargs)`` after logging
  the call at Verbosity.DBG_MORE level.

.. versionadded:: 1.2.0

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

.. automethod:: do_add_parser

.. automethod:: do_run

The following methods should be used when the command needs to print output. These were introduced to enable a transition from the deprecated west.log module to a per-command interface that will allow for a global "quiet" mode for west commands in a future release:

.. automethod:: dbg .. versionchanged:: 1.2.0 The end argument. .. versionadded:: 1.0.0

.. automethod:: inf .. versionchanged:: 1.2.0 The end argument. .. versionadded:: 1.0.0

.. automethod:: wrn .. versionchanged:: 1.2.0 The end argument. .. versionadded:: 1.0.0

.. automethod:: err .. versionchanged:: 1.2.0 The end argument. .. versionadded:: 1.0.0

.. automethod:: die .. versionadded:: 1.0.0

.. automethod:: banner .. versionadded:: 1.0.0

.. automethod:: small_banner .. versionadded:: 1.0.0

.. _west-apis-commands-output:

Verbosity

Since west v1.0, west commands should print output using methods like west.commands.WestCommand.dbg(), west.commands.WestCommand.inf(), etc. (see above). This section documents a related enum used to declare verbosity levels.

.. autoclass:: west.commands.Verbosity

.. autoattribute:: QUIET .. autoattribute:: ERR .. autoattribute:: WRN .. autoattribute:: INF .. autoattribute:: DBG .. autoattribute:: DBG_MORE .. autoattribute:: DBG_EXTREME

.. versionadded:: 1.0.0

Exceptions

.. autoclass:: west.commands.CommandError :show-inheritance:

.. py:attribute:: returncode

  Recommended program exit code for this error.

.. autoclass:: west.commands.CommandContextError :show-inheritance:

.. _west-apis-configuration:

west.configuration

.. automodule:: west.configuration

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

Note that if you are writing a :ref:west extension <west-extensions>, you can access the current Configuration object as self.config. See :py:class:west.commands.WestCommand.

Configuration API

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

.. autoclass:: west.configuration.ConfigFile

.. autoclass:: west.configuration.Configuration :members:

.. versionadded:: 0.13.0

Deprecated APIs

The following APIs also use :py:class: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.

.. autofunction:: west.configuration.read_config

.. versionchanged:: 0.8.0 The deprecated read_config parameter was removed.

.. versionchanged:: 0.6.0 Errors due to an inability to find a local configuration file are ignored.

.. autofunction:: west.configuration.update_config

.. py:data:: west.configuration.config

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

.. _west-apis-log:

west.log (deprecated)

.. automodule:: west.log

Verbosity control

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

.. autofunction:: set_verbosity

These verbosity levels are defined.

.. autodata:: VERBOSE_NONE .. autodata:: VERBOSE_NORMAL .. autodata:: VERBOSE_VERY .. autodata:: VERBOSE_EXTREME

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

.. autofunction:: dbg .. autofunction:: inf .. autofunction:: wrn .. autofunction:: err .. autofunction:: die

.. autofunction:: banner .. autofunction:: small_banner

.. _west-apis-manifest:

west.manifest

.. automodule:: west.manifest

The main classes are :py:class:Manifest and :py:class:Project. These represent the contents of a :ref:manifest file <west-manifests>. The recommended method for parsing west manifests is :py:meth:Manifest.from_topdir.

Constants and functions

.. autodata:: MANIFEST_PROJECT_INDEX .. autodata:: MANIFEST_REV_BRANCH .. autodata:: QUAL_MANIFEST_REV_BRANCH .. autodata:: QUAL_REFS_WEST .. autodata:: SCHEMA_VERSION

.. autofunction:: west.manifest.manifest_path

.. autofunction:: west.manifest.validate

.. versionchanged:: 0.13.0 This returns the validated dict containing the parsed YAML data.

Manifest and sub-objects

.. autoclass:: west.manifest.Manifest

.. automethod:: init .. versionchanged:: 0.7.0 The importer and import_flags keyword arguments. .. versionchanged:: 0.13.0 All arguments were made keyword-only. The source_file argument was removed (use topdir instead). The function no longer raises WestNotFound. .. versionadded:: 0.13.0 The config argument. .. versionadded:: 0.13.0 The abspath, posixpath, relative_path, yaml_path, repo_path, repo_posixpath, and userdata attributes.

.. automethod:: from_topdir .. versionadded:: 0.13.0

.. automethod:: from_file .. versionchanged:: 0.7.0 **kwargs added. .. versionchanged:: 0.8.0 The source_file, manifest_path, and topdir arguments can now be any os.PathLike. .. versionchanged:: 0.13.0 The manifest_path and topdir arguments were removed.

.. automethod:: from_data .. versionchanged:: 0.7.0 **kwargs added, and source_data may be a str. .. versionchanged:: 0.13.0 The manifest_path and topdir arguments were removed.

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

.. automethod:: get_projects .. versionchanged:: 0.8.0 The project_ids sequence can now contain any os.PathLike. .. versionadded:: 0.6.1

Additional methods:

.. automethod:: as_dict .. versionadded:: 1.4.0 The active_only argument. .. versionadded:: 0.7.0 .. automethod:: as_frozen_dict .. versionadded:: 1.4.0 The active_only argument. .. automethod:: as_yaml .. versionadded:: 1.4.0 The active_only argument. .. versionadded:: 0.7.0 .. automethod:: as_frozen_yaml .. versionadded:: 1.4.0 The active_only argument. .. versionadded:: 0.7.0 .. automethod:: is_active .. versionadded:: 0.9.0 .. versionchanged:: 1.1.0 This respects the manifest.project-filter configuration option. See :ref:west-config-index.

.. autoclass:: west.manifest.ImportFlag :members: :member-order: bysource

.. autoclass:: west.manifest.Project

.. (note: attributes are part of the class docstring)

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

.. versionadded:: 0.7.0 The remote_name and name_and_path attributes.

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

.. versionadded:: 0.9.0 The group_filter and submodules attributes.

.. versionadded:: 0.12.0 The userdata attribute.

.. versionadded:: 1.2.0 The description attribute.

Constructor:

.. automethod:: init

.. versionchanged:: 0.8.0 The path and topdir parameters can now be any os.PathLike.

.. versionchanged:: 0.7.0 The parameters were incompatibly changed from previous versions.

Methods:

.. automethod:: as_dict .. versionadded:: 0.7.0

.. automethod:: git .. versionchanged:: 0.6.1 The capture_stderr kwarg. .. versionchanged:: 0.7.0 The (now removed) Project.format method is no longer called on arguments.

.. automethod:: sha .. versionchanged:: 0.7.0 Standard error is now captured.

.. automethod:: is_ancestor_of .. versionchanged:: 0.8.0 The cwd parameter can now be any os.PathLike.

.. automethod:: is_cloned .. versionchanged:: 0.8.0 The cwd parameter can now be any os.PathLike. .. versionadded:: 0.6.1

.. automethod:: is_up_to_date_with .. versionchanged:: 0.8.0 The cwd parameter can now be any os.PathLike.

.. automethod:: is_up_to_date .. versionchanged:: 0.8.0 The cwd parameter can now be any os.PathLike.

.. automethod:: read_at .. versionchanged:: 0.8.0 The cwd parameter can now be any os.PathLike. .. versionadded:: 0.7.0

.. automethod:: listdir_at .. versionchanged:: 0.8.0 The cwd parameter can now be any os.PathLike. .. versionadded:: 0.7.0

.. autoclass:: west.manifest.ManifestProject

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

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

.. automethod:: as_dict

.. versionadded:: 0.6.0

.. autoclass:: west.manifest.Submodule

.. versionadded:: 0.9.0

Exceptions

.. autoclass:: west.configuration.MalformedConfig :show-inheritance:

.. autoclass:: west.manifest.MalformedManifest :show-inheritance:

.. autoclass:: west.manifest.ManifestVersionError :show-inheritance:

.. versionchanged:: 0.8.0 The file argument can now be any os.PathLike.

.. autoclass:: west.manifest.ManifestImportFailed :show-inheritance:

.. versionchanged:: 0.8.0 The filename argument can now be any os.PathLike.

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

.. _west-apis-util:

west.util

.. canon_path(), escapes_directory(), etc. intentionally not documented here.

.. automodule:: west.util

Functions

.. autofunction:: west.util.west_dir

.. versionchanged:: 0.8.0 The start parameter can be any os.PathLike.

.. autofunction:: west.util.west_topdir

.. versionchanged:: 0.8.0 The start parameter can be any os.PathLike.

Exceptions

.. autoclass:: west.util.WestNotFound :show-inheritance: