blob: 306cef813e8b672fe77b3eef0bef960e16330d75 [file] [log] [blame]
: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: