574 lines
14 KiB
ReStructuredText
574 lines
14 KiB
ReStructuredText
: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:
|
|
|
|
1. keep these sorted by package/module name.
|
|
2. 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.
|
|
|
|
.. 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:: 0.7.0
|
|
.. automethod:: as_frozen_dict
|
|
.. automethod:: as_yaml
|
|
.. versionadded:: 0.7.0
|
|
.. automethod:: as_frozen_yaml
|
|
.. 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:
|