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**Contents**:
14
15.. contents::
16   :local:
17
18.. NOTE: documentation authors:
19
20   1. keep these sorted by package/module name.
21   2. if you add a :ref: target here, add it to west-not-found.rst too.
22
23.. _west-apis-commands:
24
25west.commands
26*************
27
28.. module:: west.commands
29
30All built-in and extension commands are implemented as subclasses of the
31:py:class:`WestCommand` class defined here. Some exception types are also
32provided.
33
34WestCommand
35===========
36
37.. autoclass:: west.commands.WestCommand
38
39   Instance attributes:
40
41   .. py:attribute:: name
42
43      As passed to the constructor.
44
45   .. py:attribute:: help
46
47      As passed to the constructor.
48
49   .. py:attribute:: description
50
51      As passed to the constructor.
52
53   .. py:attribute:: accepts_unknown_args
54
55      As passed to the constructor.
56
57   .. py:attribute:: requires_workspace
58
59      As passed to the constructor.
60
61   .. versionadded:: 0.7.0
62
63   .. py:attribute:: parser
64
65      The argument parser created by calling ``WestCommand.add_parser()``.
66
67   Instance properties:
68
69   .. py:attribute:: manifest
70
71      A property which returns the :py:class:`west.manifest.Manifest`
72      instance for the current manifest file or aborts the program if one was
73      not provided. This is only safe to use from the ``do_run()`` method.
74
75   .. versionadded:: 0.6.1
76   .. versionchanged:: 0.7.0
77      This is now settable.
78
79   .. py:attribute:: has_manifest
80
81      True if reading the manifest property will succeed instead of erroring
82      out.
83
84   .. py:attribute:: config
85
86      A settable property which returns the
87      :py:class:`west.configuration.Configuration` instance or aborts the
88      program if one was not provided. This is only safe to use from the
89      ``do_run()`` method.
90
91   .. versionadded:: 0.13.0
92
93   .. py:attribute:: has_config
94
95      True if reading the config property will succeed instead of erroring
96      out.
97
98   .. versionadded:: 0.13.0
99
100   .. py:attribute:: git_version_info
101
102      A tuple of Git version information.
103
104   .. versionadded:: 0.11.0
105
106   .. py:attribute:: color_ui
107
108      True if the west configuration permits colorized output,
109      False otherwise.
110
111   .. versionadded:: 1.0.0
112
113   Constructor:
114
115   .. automethod:: __init__
116
117   .. versionadded:: 0.6.0
118      The *requires_installation* parameter (removed in v0.13.0).
119   .. versionadded:: 0.7.0
120      The *requires_workspace* parameter.
121   .. versionchanged:: 0.8.0
122      The *topdir* parameter can now be any ``os.PathLike``.
123   .. versionchanged:: 0.13.0
124      The deprecated *requires_installation* parameter was removed.
125   .. versionadded:: 1.0.0
126      The *verbosity* parameter.
127
128   Methods:
129
130   .. automethod:: run
131
132   .. versionchanged:: 0.6.0
133      The *topdir* argument was added.
134
135   .. automethod:: add_parser
136
137   .. automethod:: add_pre_run_hook
138   .. versionadded:: 1.0.0
139
140   .. NOTE: the following 'method' (not 'automethod') directives were added for
141      expediency during the west v1.2 release time frame to work around a build
142      failure in this zephyr documentation that could not be fixed without
143      cutting a west point release. (The docstrings in west had some RST syntax
144      errors).
145
146      These should be reverted back to automethod calls at the next release.
147
148   .. method:: check_call(args, **kwargs)
149
150      Runs ``subprocess.check_call(args, **kwargs)`` after
151      logging the call at ``Verbosity.DBG_MORE`` level.
152
153   .. versionchanged:: 1.2.0
154      The *cwd* keyword argument was replaced with a catch-all ``**kwargs``.
155   .. versionchanged:: 0.11.0
156
157   .. method:: check_output(args, **kwargs)
158
159      Runs ``subprocess.check_output(args, **kwargs)`` after
160      logging the call at Verbosity.DBG_MORE level.
161
162   .. versionchanged:: 1.2.0
163      The *cwd* keyword argument was replaced with a catch-all ``**kwargs``.
164   .. versionchanged:: 0.11.0
165
166   .. method:: run_subprocess(args, **kwargs)
167
168      Runs ``subprocess.run(args, **kwargs)`` after logging
169      the call at Verbosity.DBG_MORE level.
170
171   .. versionadded:: 1.2.0
172
173   All subclasses must provide the following abstract methods, which are used
174   to implement the above:
175
176   .. automethod:: do_add_parser
177
178   .. automethod:: do_run
179
180   The following methods should be used when the command needs to print output.
181   These were introduced to enable a transition from the deprecated
182   ``west.log`` module to a per-command interface that will allow for a global
183   "quiet" mode for west commands in a future release:
184
185   .. automethod:: dbg
186   .. versionchanged:: 1.2.0
187      The *end* argument.
188   .. versionadded:: 1.0.0
189
190   .. automethod:: inf
191   .. versionchanged:: 1.2.0
192      The *end* argument.
193   .. versionadded:: 1.0.0
194
195   .. automethod:: wrn
196   .. versionchanged:: 1.2.0
197      The *end* argument.
198   .. versionadded:: 1.0.0
199
200   .. automethod:: err
201   .. versionchanged:: 1.2.0
202      The *end* argument.
203   .. versionadded:: 1.0.0
204
205   .. automethod:: die
206   .. versionadded:: 1.0.0
207
208   .. automethod:: banner
209   .. versionadded:: 1.0.0
210
211   .. automethod:: small_banner
212   .. versionadded:: 1.0.0
213
214.. _west-apis-commands-output:
215
216Verbosity
217=========
218
219Since west v1.0, west commands should print output using methods like
220west.commands.WestCommand.dbg(), west.commands.WestCommand.inf(), etc. (see
221above). This section documents a related enum used to declare verbosity levels.
222
223.. autoclass:: west.commands.Verbosity
224
225   .. autoattribute:: QUIET
226   .. autoattribute:: ERR
227   .. autoattribute:: WRN
228   .. autoattribute:: INF
229   .. autoattribute:: DBG
230   .. autoattribute:: DBG_MORE
231   .. autoattribute:: DBG_EXTREME
232
233.. versionadded:: 1.0.0
234
235Exceptions
236==========
237
238.. autoclass:: west.commands.CommandError
239   :show-inheritance:
240
241   .. py:attribute:: returncode
242
243      Recommended program exit code for this error.
244
245.. autoclass:: west.commands.CommandContextError
246   :show-inheritance:
247
248.. _west-apis-configuration:
249
250west.configuration
251******************
252
253.. automodule:: west.configuration
254
255Since west v0.13, the recommended class for reading this is
256:py:class:`west.configuration.Configuration`.
257
258Note that if you are writing a :ref:`west extension <west-extensions>`, you can
259access the current ``Configuration`` object as ``self.config``. See
260:py:class:`west.commands.WestCommand`.
261
262Configuration API
263=================
264
265This is the recommended API to use since west v0.13.
266
267.. autoclass:: west.configuration.ConfigFile
268
269.. autoclass:: west.configuration.Configuration
270   :members:
271
272   .. versionadded:: 0.13.0
273
274Deprecated APIs
275===============
276
277The following APIs also use :py:class:`west.configuration.ConfigFile`, but they
278operate by default on a global object which stores the current workspace
279configuration. This has proven to be a bad design decision since west's APIs
280can be used from multiple workspaces. They were deprecated in west v0.13.0.
281
282These APIs are preserved for compatibility with older extensions. They should
283not be used in new code when west v0.13.0 or later may be assumed.
284
285.. autofunction:: west.configuration.read_config
286
287.. versionchanged:: 0.8.0
288   The deprecated *read_config* parameter was removed.
289
290.. versionchanged:: 0.6.0
291   Errors due to an inability to find a local configuration file are ignored.
292
293.. autofunction:: west.configuration.update_config
294
295.. py:data:: west.configuration.config
296
297   Module-global ConfigParser instance for the current configuration. This
298   should be initialized with :py:func:`west.configuration.read_config` before
299   being read.
300
301.. _west-apis-log:
302
303west.log (deprecated)
304*********************
305
306.. automodule:: west.log
307
308Verbosity control
309=================
310
311To set the global verbosity level, use ``set_verbosity()``.
312
313.. autofunction:: set_verbosity
314
315These verbosity levels are defined.
316
317.. autodata:: VERBOSE_NONE
318.. autodata:: VERBOSE_NORMAL
319.. autodata:: VERBOSE_VERY
320.. autodata:: VERBOSE_EXTREME
321
322Output functions
323================
324
325The main functions are ``dbg()``, ``inf()``, ``wrn()``, ``err()``, and
326``die()``. Two special cases of ``inf()``, ``banner()`` and ``small_banner()``,
327are also available for grouping output into "sections".
328
329.. autofunction:: dbg
330.. autofunction:: inf
331.. autofunction:: wrn
332.. autofunction:: err
333.. autofunction:: die
334
335.. autofunction:: banner
336.. autofunction:: small_banner
337
338.. _west-apis-manifest:
339
340west.manifest
341*************
342
343.. automodule:: west.manifest
344
345The main classes are :py:class:`Manifest` and :py:class:`Project`. These
346represent the contents of a :ref:`manifest file <west-manifests>`. The
347recommended method for parsing west manifests is
348:py:meth:`Manifest.from_topdir`.
349
350Constants and functions
351=======================
352
353.. autodata:: MANIFEST_PROJECT_INDEX
354.. autodata:: MANIFEST_REV_BRANCH
355.. autodata:: QUAL_MANIFEST_REV_BRANCH
356.. autodata:: QUAL_REFS_WEST
357.. autodata:: SCHEMA_VERSION
358
359.. autofunction:: west.manifest.manifest_path
360
361.. autofunction:: west.manifest.validate
362
363.. versionchanged:: 0.13.0
364   This returns the validated dict containing the parsed YAML data.
365
366Manifest and sub-objects
367========================
368
369.. autoclass:: west.manifest.Manifest
370
371   .. automethod:: __init__
372   .. versionchanged:: 0.7.0
373      The *importer* and *import_flags* keyword arguments.
374   .. versionchanged:: 0.13.0
375      All arguments were made keyword-only. The *source_file* argument was
376      removed (use *topdir* instead). The function no longer raises
377      ``WestNotFound``.
378   .. versionadded:: 0.13.0
379      The *config* argument.
380   .. versionadded:: 0.13.0
381      The *abspath*, *posixpath*, *relative_path*, *yaml_path*, *repo_path*,
382      *repo_posixpath*, and *userdata* attributes.
383
384   .. automethod:: from_topdir
385   .. versionadded:: 0.13.0
386
387   .. automethod:: from_file
388   .. versionchanged:: 0.7.0
389      ``**kwargs`` added.
390   .. versionchanged:: 0.8.0
391      The *source_file*, *manifest_path*, and *topdir* arguments
392      can now be any ``os.PathLike``.
393   .. versionchanged:: 0.13.0
394      The *manifest_path* and *topdir* arguments were removed.
395
396   .. automethod:: from_data
397   .. versionchanged:: 0.7.0
398      ``**kwargs`` added, and *source_data* may be a ``str``.
399   .. versionchanged:: 0.13.0
400      The *manifest_path* and *topdir* arguments were removed.
401
402   Conveniences for accessing sub-objects by name or other identifier:
403
404   .. automethod:: get_projects
405   .. versionchanged:: 0.8.0
406      The *project_ids* sequence can now contain any ``os.PathLike``.
407   .. versionadded:: 0.6.1
408
409   Additional methods:
410
411   .. automethod:: as_dict
412   .. versionadded:: 0.7.0
413   .. automethod:: as_frozen_dict
414   .. automethod:: as_yaml
415   .. versionadded:: 0.7.0
416   .. automethod:: as_frozen_yaml
417   .. versionadded:: 0.7.0
418   .. automethod:: is_active
419   .. versionadded:: 0.9.0
420   .. versionchanged:: 1.1.0
421      This respects the ``manifest.project-filter`` configuration
422      option. See :ref:`west-config-index`.
423
424.. autoclass:: west.manifest.ImportFlag
425   :members:
426   :member-order: bysource
427
428.. autoclass:: west.manifest.Project
429
430   .. (note: attributes are part of the class docstring)
431
432   .. versionchanged:: 0.7.0
433      The *remote* attribute was removed. Its semantics could no longer
434      be preserved when support for manifest ``import`` keys was added.
435
436   .. versionadded:: 0.7.0
437      The *remote_name* and *name_and_path* attributes.
438
439   .. versionchanged:: 0.8.0
440      The *west_commands* attribute is now always a list. In previous
441      releases, it could be a string or ``None``.
442
443   .. versionadded:: 0.9.0
444      The *group_filter* and *submodules* attributes.
445
446   .. versionadded:: 0.12.0
447      The *userdata* attribute.
448
449   .. versionadded:: 1.2.0
450      The *description* attribute.
451
452   Constructor:
453
454   .. automethod:: __init__
455
456   .. versionchanged:: 0.8.0
457      The *path* and *topdir* parameters can now be any ``os.PathLike``.
458
459   .. versionchanged:: 0.7.0
460      The parameters were incompatibly changed from previous versions.
461
462   Methods:
463
464   .. automethod:: as_dict
465   .. versionadded:: 0.7.0
466
467   .. automethod:: git
468   .. versionchanged:: 0.6.1
469      The *capture_stderr* kwarg.
470   .. versionchanged:: 0.7.0
471      The (now removed) ``Project.format`` method is no longer called on
472      arguments.
473
474   .. automethod:: sha
475   .. versionchanged:: 0.7.0
476      Standard error is now captured.
477
478   .. automethod:: is_ancestor_of
479   .. versionchanged:: 0.8.0
480      The *cwd* parameter can now be any ``os.PathLike``.
481
482   .. automethod:: is_cloned
483   .. versionchanged:: 0.8.0
484      The *cwd* parameter can now be any ``os.PathLike``.
485   .. versionadded:: 0.6.1
486
487   .. automethod:: is_up_to_date_with
488   .. versionchanged:: 0.8.0
489      The *cwd* parameter can now be any ``os.PathLike``.
490
491   .. automethod:: is_up_to_date
492   .. versionchanged:: 0.8.0
493      The *cwd* parameter can now be any ``os.PathLike``.
494
495   .. automethod:: read_at
496   .. versionchanged:: 0.8.0
497      The *cwd* parameter can now be any ``os.PathLike``.
498   .. versionadded:: 0.7.0
499
500   .. automethod:: listdir_at
501   .. versionchanged:: 0.8.0
502      The *cwd* parameter can now be any ``os.PathLike``.
503   .. versionadded:: 0.7.0
504
505.. autoclass:: west.manifest.ManifestProject
506
507   A limited subset of Project methods is supported.
508   Results for calling others are not specified.
509
510   .. versionchanged:: 0.8.0
511      The *url* attribute is now the empty string instead of ``None``.
512      The *abspath* attribute is created using ``os.path.abspath()``
513      instead of ``os.path.realpath()``, improving support for symbolic links.
514
515   .. automethod:: as_dict
516
517.. versionadded:: 0.6.0
518
519.. autoclass:: west.manifest.Submodule
520
521.. versionadded:: 0.9.0
522
523Exceptions
524==========
525
526.. autoclass:: west.configuration.MalformedConfig
527   :show-inheritance:
528
529.. autoclass:: west.manifest.MalformedManifest
530   :show-inheritance:
531
532.. autoclass:: west.manifest.ManifestVersionError
533   :show-inheritance:
534
535   .. versionchanged:: 0.8.0
536      The *file* argument can now be any ``os.PathLike``.
537
538.. autoclass:: west.manifest.ManifestImportFailed
539   :show-inheritance:
540
541   .. versionchanged:: 0.8.0
542      The *filename* argument can now be any ``os.PathLike``.
543
544   .. versionchanged:: 0.13.0
545      The *filename* argument was renamed *imp*, and can now take any value.
546
547.. _west-apis-util:
548
549west.util
550*********
551
552.. canon_path(), escapes_directory(), etc. intentionally not documented here.
553
554.. automodule:: west.util
555
556Functions
557=========
558
559.. autofunction:: west.util.west_dir
560
561   .. versionchanged:: 0.8.0
562      The *start* parameter can be any ``os.PathLike``.
563
564.. autofunction:: west.util.west_topdir
565
566   .. versionchanged:: 0.8.0
567      The *start* parameter can be any ``os.PathLike``.
568
569Exceptions
570==========
571
572.. autoclass:: west.util.WestNotFound
573   :show-inheritance:
574