1:orphan:
2
3.. _west-apis:
4.. _west-apis-west:
5
6West APIs
7#########
8
9This page documents the Python APIs provided by :ref:`west <west>`, as well as
10some additional APIs used by the :ref:`west extensions <west-extensions>` in
11the zephyr repository.
12
13.. warning::
14
15   These APIs should be considered unstable until west version 1.0 (see `west
16   #38`_).
17
18.. _west #38:
19   https://github.com/zephyrproject-rtos/west/issues/38
20
21**Contents**:
22
23.. contents::
24   :local:
25
26.. NOTE: documentation authors:
27
28   1. keep these sorted by package/module name.
29   2. if you add a :ref: target here, add it to west-not-found.rst too.
30
31.. _west-apis-commands:
32
33west.commands
34*************
35
36.. module:: west.commands
37
38All built-in and extension commands are implemented as subclasses of the
39:py:class:`WestCommand` class defined here. Some exception types are also
40provided.
41
42WestCommand
43===========
44
45.. py:class:: west.commands.WestCommand
46
47   Instance attributes:
48
49   .. py:attribute:: name
50
51      As passed to the constructor.
52
53   .. py:attribute:: help
54
55      As passed to the constructor.
56
57   .. py:attribute:: description
58
59      As passed to the constructor.
60
61   .. py:attribute:: accepts_unknown_args
62
63      As passed to the constructor.
64
65   .. py:attribute:: requires_workspace
66
67      As passed to the constructor.
68
69   .. versionadded:: 0.7.0
70
71   .. py:attribute:: parser
72
73      The argument parser created by calling ``WestCommand.add_parser()``.
74
75   Instance properties:
76
77   .. py:attribute:: manifest
78
79      A property which returns the :py:class:`west.manifest.Manifest`
80      instance for the current manifest file or aborts the program if one was
81      not provided. This is only safe to use from the ``do_run()`` method.
82
83   .. versionadded:: 0.6.1
84   .. versionchanged:: 0.7.0
85      This is now settable.
86
87   .. py:attribute:: has_manifest
88
89      True if reading the manifest property will succeed instead of erroring
90      out.
91
92   .. py:attribute:: git_version_info
93
94      A tuple of Git version information.
95
96   .. versionadded:: 0.11.0
97
98   Constructor:
99
100   .. automethod:: __init__
101
102   .. versionchanged:: 0.8.0
103      The *topdir* parameter can now be any ``os.PathLike``.
104   .. versionadded:: 0.6.0
105      The *requires_installation* parameter.
106   .. versionadded:: 0.7.0
107      The *requires_workspace* parameter.
108
109   Methods:
110
111   .. automethod:: run
112
113   .. versionchanged:: 0.6.0
114      The *topdir* argument was added.
115
116   .. automethod:: add_parser
117
118   .. automethod:: check_call
119
120   .. versionchanged:: 0.11.0
121
122   .. automethod:: check_output
123
124   .. versionchanged:: 0.11.0
125
126   All subclasses must provide the following abstract methods, which are used
127   to implement the above:
128
129   .. automethod:: do_add_parser
130
131   .. automethod:: do_run
132
133Exceptions
134==========
135
136.. autoclass:: west.commands.CommandError
137   :show-inheritance:
138
139   .. py:attribute:: returncode
140
141      Recommended program exit code for this error.
142
143.. autoclass:: west.commands.CommandContextError
144   :show-inheritance:
145
146.. _west-apis-configuration:
147
148west.configuration
149******************
150
151.. automodule:: west.configuration
152
153This provides API access to west configuration files and data.
154
155Reading and writing options
156===========================
157
158.. autofunction:: west.configuration.read_config
159
160.. versionchanged:: 0.8.0
161   The deprecated *read_config* parameter was removed.
162
163.. versionchanged:: 0.6.0
164   Errors due to an inability to find a local configuration file are ignored.
165
166.. autofunction:: west.configuration.update_config
167
168.. autoclass:: west.configuration.ConfigFile
169
170Global configuration instance
171=============================
172
173.. py:data:: west.configuration.config
174
175   Module-global ConfigParser instance for the current configuration. This
176   should be initialized with :py:func:`west.configuration.read_config` before
177   being read.
178
179.. _west-apis-log:
180
181west.log
182********
183
184.. automodule:: west.log
185
186This module's functions are used whenever a running west command needs to print
187to standard out or error streams.
188
189This is safe to use from extension commands if you want output that mirrors
190that of west itself.
191
192Verbosity control
193=================
194
195To set the global verbosity level, use ``set_verbosity()``.
196
197.. autofunction:: set_verbosity
198
199These verbosity levels are defined.
200
201.. autodata:: VERBOSE_NONE
202.. autodata:: VERBOSE_NORMAL
203.. autodata:: VERBOSE_VERY
204.. autodata:: VERBOSE_EXTREME
205
206Output functions
207================
208
209The main functions are ``dbg()``, ``inf()``, ``wrn()``, ``err()``, and
210``die()``. Two special cases of ``inf()``, ``banner()`` and ``small_banner()``,
211are also available for grouping output into "sections".
212
213.. autofunction:: dbg
214.. autofunction:: inf
215.. autofunction:: wrn
216.. autofunction:: err
217.. autofunction:: die
218
219.. autofunction:: banner
220.. autofunction:: small_banner
221
222.. _west-apis-manifest:
223
224west.manifest
225*************
226
227.. automodule:: west.manifest
228
229The main classes are `Manifest` and `Project`. These represent the contents of
230a :ref:`manifest file <west-manifests>`. The recommended methods for parsing
231west manifests are `Manifest.from_file` and `Manifest.from_data`.
232
233Constants and functions
234=======================
235
236.. autodata:: MANIFEST_PROJECT_INDEX
237.. autodata:: MANIFEST_REV_BRANCH
238.. autodata:: QUAL_MANIFEST_REV_BRANCH
239.. autodata:: QUAL_REFS_WEST
240.. autodata:: SCHEMA_VERSION
241
242.. autofunction:: west.manifest.manifest_path
243
244.. autofunction:: west.manifest.validate
245
246Manifest and sub-objects
247========================
248
249.. autoclass:: west.manifest.Manifest
250
251   .. automethod:: __init__
252   .. versionchanged:: 0.7.0
253      The *importer* and *import_flags* keyword arguments.
254
255   .. automethod:: from_file
256   .. versionchanged:: 0.8.0
257      The *source_file*, *manifest_path*, and *topdir* arguments
258      can now be any ``os.PathLike``.
259   .. versionchanged:: 0.7.0
260      ``**kwargs`` added.
261
262   .. automethod:: from_data
263   .. versionchanged:: 0.7.0
264      ``**kwargs`` added, and *source_data* may be a ``str``.
265
266   Conveniences for accessing sub-objects by name or other identifier:
267
268   .. automethod:: get_projects
269   .. versionchanged:: 0.8.0
270      The *project_ids* sequence can now contain any ``os.PathLike``.
271   .. versionadded:: 0.6.1
272
273   Additional methods:
274
275   .. automethod:: as_dict
276   .. versionadded:: 0.7.0
277   .. automethod:: as_frozen_dict
278   .. automethod:: as_yaml
279   .. versionadded:: 0.7.0
280   .. automethod:: as_frozen_yaml
281   .. versionadded:: 0.7.0
282   .. automethod:: is_active
283   .. versionadded:: 0.9.0
284
285.. autoclass:: west.manifest.ImportFlag
286   :members:
287   :member-order: bysource
288
289.. autoclass:: west.manifest.Project
290
291   .. (note: attributes are part of the class docstring)
292
293   .. versionchanged:: 0.8.0
294      The *west_commands* attribute is now always a list. In previous
295      releases, it could be a string or ``None``.
296
297   .. versionchanged:: 0.7.0
298      The *remote* attribute was removed. Its semantics could no longer
299      be preserved when support for manifest ``import`` keys was added.
300
301   .. versionadded:: 0.7.0
302      The *remote_name* and *name_and_path* attributes.
303
304   .. versionadded:: 0.9.0
305      The *group_filter* and *submodules* attributes.
306
307   Constructor:
308
309   .. automethod:: __init__
310
311   .. versionchanged:: 0.8.0
312      The *path* and *topdir* parameters can now be any ``os.PathLike``.
313
314   .. versionchanged:: 0.7.0
315      The parameters were incompatibly changed from previous versions.
316
317   Methods:
318
319   .. automethod:: as_dict
320   .. versionadded:: 0.7.0
321
322   .. automethod:: git
323   .. versionchanged:: 0.6.1
324      The *capture_stderr* kwarg.
325   .. versionchanged:: 0.7.0
326      The (now removed) ``Project.format`` method is no longer called on
327      arguments.
328
329   .. automethod:: sha
330   .. versionchanged:: 0.7.0
331      Standard error is now captured.
332
333   .. automethod:: is_ancestor_of
334   .. versionchanged:: 0.8.0
335      The *cwd* parameter can now be any ``os.PathLike``.
336
337   .. automethod:: is_cloned
338   .. versionchanged:: 0.8.0
339      The *cwd* parameter can now be any ``os.PathLike``.
340   .. versionadded:: 0.6.1
341
342   .. automethod:: is_up_to_date_with
343   .. versionchanged:: 0.8.0
344      The *cwd* parameter can now be any ``os.PathLike``.
345
346   .. automethod:: is_up_to_date
347   .. versionchanged:: 0.8.0
348      The *cwd* parameter can now be any ``os.PathLike``.
349
350   .. automethod:: read_at
351   .. versionchanged:: 0.8.0
352      The *cwd* parameter can now be any ``os.PathLike``.
353   .. versionadded:: 0.7.0
354
355   .. automethod:: listdir_at
356   .. versionchanged:: 0.8.0
357      The *cwd* parameter can now be any ``os.PathLike``.
358   .. versionadded:: 0.7.0
359
360.. autoclass:: west.manifest.ManifestProject
361
362   A limited subset of Project methods is supported.
363   Results for calling others are not specified.
364
365   .. versionchanged:: 0.8.0
366      The *url* attribute is now the empty string instead of ``None``.
367      The *abspath* attribute is created using ``os.path.abspath()``
368      instead of ``os.path.realpath()``, improving support for symbolic links.
369
370   .. automethod:: as_dict
371
372.. versionadded:: 0.6.0
373
374.. autoclass:: west.manifest.Submodule
375
376.. versionadded:: 0.9.0
377
378Exceptions
379==========
380
381.. autoclass:: west.manifest.MalformedManifest
382   :show-inheritance:
383
384.. autoclass:: west.manifest.MalformedConfig
385   :show-inheritance:
386
387.. autoclass:: west.manifest.ManifestVersionError
388   :show-inheritance:
389
390   .. versionchanged:: 0.8.0
391      The *file* argument can now be any ``os.PathLike``.
392
393.. autoclass:: west.manifest.ManifestImportFailed
394   :show-inheritance:
395
396   .. versionchanged:: 0.8.0
397      The *filename* argument can now be any ``os.PathLike``.
398
399.. _west-apis-util:
400
401west.util
402*********
403
404.. canon_path(), escapes_directory(), etc. intentionally not documented here.
405
406.. automodule:: west.util
407
408Functions
409=========
410
411.. autofunction:: west.util.west_dir
412
413   .. versionchanged:: 0.8.0
414      The *start* parameter can be any ``os.PathLike``.
415
416.. autofunction:: west.util.west_topdir
417
418   .. versionchanged:: 0.8.0
419      The *start* parameter can be any ``os.PathLike``.
420
421Exceptions
422==========
423
424.. autoclass:: west.util.WestNotFound
425   :show-inheritance:
426