Part 1
요약·해설
West extension 개발에 필요한 WestCommand, Configuration, Manifest, Project, west.util API와 deprecated interface의 대체 경로를 설명합니다.
WestCommand · output · exceptions
system · global · local
Manifest · Project · imports
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
D0931A63A78D8EFCD0EE210B5450EBE2BC983B1D879181F9BBA03EA75F4142E0
: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:
Part 3
한국어 전문 번역
west.commands
이 페이지는 West가 제공하는 Python API와 Zephyr repository의 West extension이 사용하는 추가 API를 설명합니다.
west.commands의 모든 내장 command와 extension command는 여기 정의된 WestCommand의 subclass로 구현합니다. Command 실행 실패를 나타내는 exception type도 이 module에서 제공합니다.
WestCommand
class west.commands.WestCommand(name, help, description, accepts_unknown_args=False, requires_workspace=True, verbosity=Verbosity.INF)West command를 구현할 때 상속하는 abstract superclass입니다.
Instance attribute는 다음과 같습니다.
name,help,description,accepts_unknown_args,requires_workspace: constructor에 전달한 값입니다.requires_workspace는 0.7.0에서 추가됐습니다.parser:WestCommand.add_parser()가 만든 argument parser입니다.manifest: 현재 manifest file의west.manifest.Manifest를 반환하는 설정 가능한 property입니다. 값이 없으면 program을 중단하므로do_run()안에서만 안전합니다. 0.6.1에 추가되고 0.7.0부터 설정할 수 있습니다.has_manifest:manifest를 오류 없이 읽을 수 있으면True입니다.config:west.configuration.Configuration을 반환하는 설정 가능한 property입니다. 값이 없으면 중단하므로do_run()에서만 안전합니다.has_config:config를 오류 없이 읽을 수 있으면True입니다.config와 함께 0.13.0에 추가됐습니다.git_version_info: Git version 정보를 담은 tuple이며 0.11.0에 추가됐습니다.color_ui: West 설정이 색상 출력을 허용하면True입니다. 1.0.0에 추가됐습니다.
__init__name은 사용자가 입력하는 command 이름,help는 한 줄 도움말,description은 여러 줄 설명입니다.accepts_unknown_args가 참이면 임의의 미해석 인자를 받을 수 있고,requires_workspace가 참이면 workspace 밖에서 실행할 때 치명적 오류가 납니다.verbosity는 나중에도 바꿀 수 있는 출력 수준입니다.
Constructor의 일부 field가 argparse.ArgumentParser 인자와 겹치는 것은 의도된 설계입니다. argparse의 API 안정성 보장이 제한적이어서 미래 호환성을 위해 정보를 중복 보관합니다. 0.6.0의 requires_installation은 0.13.0에서 제거됐고, requires_workspace는 0.7.0, verbosity는 1.0.0에 추가됐습니다. 0.8.0부터 topdir은 모든 os.PathLike를 받습니다.
run(args, unknown, topdir, manifest=None, config=None)Command를 실행합니다.
args는 등록한 parser가 해석한 인자,unknown은 미해석 인자이며accepts_unknown_args가 거짓이면 비어 있어야 합니다.topdir,manifest,config는 각각do_run()에서self.topdir,self.manifest,self.config로 접근합니다. Context가 맞지 않으면CommandContextError를 일으킬 수 있습니다.
add_parser(parser_adder)argparse.ArgumentParser.add_subparsers()의 반환값에 이 command의 parser를 등록해 반환하고parserattribute에도 저장합니다.
add_pre_run_hook(hook)Command 실행 직전에 호출할 hook을 추가합니다. 1.0.0에서 추가됐습니다.
check_call(args, **kwargs)Verbosity.DBG_MORElevel로 호출을 기록한 뒤subprocess.check_call(args, **kwargs)을 실행합니다. 1.2.0부터cwd대신 모든 keyword를 받는**kwargs를 사용합니다.
check_output(args, **kwargs)Verbosity.DBG_MORElevel로 기록한 뒤subprocess.check_output(args, **kwargs)을 실행합니다. 1.2.0부터**kwargs를 받습니다.
run_subprocess(args, **kwargs)Verbosity.DBG_MORElevel로 기록한 뒤subprocess.run(args, **kwargs)을 실행합니다. 1.2.0에서 추가됐습니다.
모든 subclass는 다음 abstract method를 구현해야 합니다.
do_add_parser(parser_adder)parser_adder.add_parser()로 subcommand용ArgumentParser를 만들고 option과 argument를 추가한 뒤 최종 parser를 반환합니다.
do_run(args, unknown)args는 해석된argparse.Namespace,unknown은accepts_unknown_args가 참일 때 전달되는 미해석 문자열 sequence입니다. 실제 command 동작을 이 method에 구현합니다.
west.log의 global state를 command별 interface로 옮기고 향후 전역 quiet mode를 지원하기 위해 출력은 다음 method를 사용합니다.
dbg(*args, level=Verbosity.DBG, end='\n')self.verbosity가level이상일 때만 verbose debug message를 출력합니다.end는 1.2.0에 추가됐습니다.
inf(*args, colorize=False, end='\n')INF이상에서 정보 message를 출력합니다.colorize=True,color.ui가 미정 또는 참, stdout이 terminal이라는 세 조건이 맞으면 green으로 출력합니다.
wrn(*args, end='\n')WRN이상에서WARNING:prefix를 붙입니다. 색상 설정이 허용되고 stdout이 terminal이면 yellow로 출력합니다.
err(*args, fatal=False, end='\n')ERR이상에서 red error를 출력하지만 program을 중단하지는 않습니다.fatal이면FATAL ERROR:, 아니면ERROR:prefix를 사용합니다.
die(*args, exit_code=1)err()로 치명적 오류를 출력하고 지정한 return code로 program을 중단합니다.
banner(*args)inf()를 사용해 인자 앞에===를 붙이고 기본적으로 색상을 입힌 큰 banner를 출력합니다.
small_banner(*args)--를 붙이고 색상을 쓰지 않는 작은 banner를 출력합니다.
Verbosity
West 1.0부터 command 출력은 WestCommand.dbg(), inf(), wrn(), err() 같은 method를 사용합니다. west.commands.Verbosity enum은 다음 level을 선언합니다.
QUIET = 0:dbg(),inf()등을 호출해도 아무것도 출력하지 않습니다.ERR = 1: error만 출력합니다.WRN = 2: warning과 error를 출력합니다.INF = 3: 일반 정보, warning, error를 출력하는 기본 level입니다.DBG = 4: debug 정보를 추가합니다.DBG_MORE = 5: 더 상세한 debug 정보를 추가합니다.DBG_EXTREME = 6: 가장 상세한 debug 정보를 출력합니다.
Exception
west.commands.CommandError(returncode=1)Command 실행 오류의 base exception입니다.
returncode는 권장 program exit code입니다.
west.commands.CommandContextError(returncode=1)CommandError의 subclass로, context에 의존하는 command를 현재 context에서 실행할 수 없음을 뜻합니다.
west.configuration
West configuration file을 다룹니다. Git과 비슷하게 system, global, local 세 수준을 사용하며 뒤에서 읽은 더 구체적인 값이 앞의 값을 덮어씁니다. 따라서 local 우선순위가 가장 높고 system이 가장 낮습니다.
- System: Linux
/etc/westconfig, macOS/usr/local/etc/westconfig, Windows%PROGRAMDATA%\west\config. - Global: Linux
~/.westconfig또는$XDG_CONFIG_HOME/west/config, macOS~/.westconfig, Windows user home의.westconfig. - Local: 모든 OS에서
<workspace-topdir>/.west/config.
WEST_CONFIG_SYSTEM, WEST_CONFIG_GLOBAL, WEST_CONFIG_LOCAL 환경 변수로 각 file 위치를 덮어쓸 수 있습니다. West 0.13부터 읽기에는 Configuration class를 권장하며 extension에서는 현재 객체를 self.config로 접근합니다.
Configuration API
west.configuration.ConfigFileSYSTEM은 모든 user가 공유하는 system 수준,GLOBAL은 현재 user 전체,LOCAL은 workspace별,ALL은 적용 가능한 세 file 전부를 뜻하는 enum입니다.
west.configuration.Configuration(topdir=None)사용 가능한 option과 값을 나타내며 system, global, local file을 읽고 쓰고 지울 수 있습니다. 쓰기는 즉시 file에 반영되고 동시 접근 보호는 제공하지 않으므로 caller가 필요한 mutual exclusion을 해야 합니다.
WEST_CONFIG_*변수는 객체를 만들 때만 반영됩니다.topdir도WEST_CONFIG_LOCAL도 없으면 local file을 가리키지 않습니다.
Configuration.delete(option, configfile=None)foo.bar형식 option을 지웁니다.ALL이면 설정된 모든 file에서,None이면 가장 높은 우선순위 file에서만, 그 밖에는 지정한 file에서 지웁니다. 값이 없으면KeyError입니다.
Configuration.get(option, default=None, configfile=ConfigFile.ALL)지정한 file 범위에서 option을 문자열로 읽고, 없으면 default를 반환합니다.
Configuration.getboolean(option, default=False, configfile=ConfigFile.ALL)configparser의 boolean 변환을 적용합니다. 변환할 수 없는 값은ValueError를 일으킵니다.
Configuration.getfloat(option, default=None, configfile=ConfigFile.ALL)Option을 부동소수점 값으로 읽습니다.
Configuration.getint(option, default=None, configfile=ConfigFile.ALL)Option을 정수 값으로 읽습니다.
Configuration.items(configfile=ConfigFile.ALL)선택한 file의 option과 value pair iterator를 반환합니다.
Configuration.set(option, value, configfile=ConfigFile.LOCAL)Option을 즉시 file에 기록합니다. 객체를 만든 뒤 다른 process가 file을 바꿨을 수 있다면 새
Configuration을 만든 후 호출해야 중간 변경을 잃지 않습니다.
사용 중단 예정 API
다음 API는 현재 workspace 설정을 module-global object에 저장합니다. 여러 workspace의 API를 한 process에서 사용할 때 잘못된 상태를 공유할 수 있어 West 0.13.0에서 deprecated 됐습니다. 구형 extension 호환용으로 남아 있으며 새 code에서는 Configuration을 사용합니다.
west.configuration.read_config(configfile=None, config=..., topdir=None)선택한 configuration file을
ConfigParser에 읽습니다. 별도 객체가 없으면 globalwest.configuration.config를 사용합니다. Local option을 요청하면topdir/.west/config,WEST_CONFIG_LOCAL, file system에서 찾은 workspace local file 순으로 결정하며 찾지 못한 경우는 무시합니다.
west.configuration.update_config(section, key, value, configfile=ConfigFile.LOCAL, topdir=None)section.key를 지정한 file에 기록하고 section이 없으면 만듭니다.configfile은ALL일 수 없습니다. Local 목적지는topdir/.west/config,WEST_CONFIG_LOCAL, 탐색한 workspace file 순으로 결정하며 마지막 탐색도 실패하면WestNotFound입니다.
west.configuration.configread_config()로 초기화한 뒤 읽어야 하는 현재 configuration용 module-globalConfigParserinstance입니다.
west.log (deprecated)
west.log는 global state 때문에 West unit test를 어렵게 만들어 deprecated 됐으며 제거는 West 2.0 이전에는 하지 않습니다. 새 command는 같은 기능의 WestCommand method를 사용해야 합니다. 예를 들어 west.log.dbg() 대신 WestCommand.dbg()를 사용합니다.
Verbosity 제어
set_verbosity(value)Module-global verbosity level을 설정합니다.
VERBOSE_NONE: debug 출력 없음.VERBOSE_NORMAL: 일반 verbose 출력.VERBOSE_VERY: 더 자세한 출력.VERBOSE_EXTREME: 가장 상세한 출력.
출력 함수
주요 함수는 dbg(), inf(), wrn(), err(), die()입니다. banner()와 small_banner()는 inf()의 특별한 형태로 출력을 section별로 묶습니다. 각각의 동작은 앞의 WestCommand method와 같습니다.
west.manifest
West manifest의 parser와 abstract data type입니다. Manifest와 Project가 manifest file 내용을 나타내며, workspace manifest를 읽을 때는 Manifest.from_topdir()를 권장합니다.
상수와 함수
MANIFEST_PROJECT_INDEX = 0Manifest.projects에서 workspace의ManifestProject가 저장되는 index입니다.
MANIFEST_REV_BRANCH = 'manifest-rev'가장 최근
Projectupdate를 가리키는 Git revision입니다.
QUAL_MANIFEST_REV_BRANCH = 'refs/heads/manifest-rev'MANIFEST_REV_BRANCH의 fully qualified ref입니다.
QUAL_REFS_WEST = 'refs/west/'West 내부 용도로 쓰는 Git ref namespace입니다.
SCHEMA_VERSION = '1.2'현재 West가 지원하는 최신 manifest schema version입니다. 이전 West가 지원하지 못하는 manifest 기능이 추가될 때 바뀝니다.
manifest_path()manifest.path와manifest.file설정으로 현재 workspace manifest의 absolute path를 반환합니다. Workspace 밖이면WestNotFound,manifest.path가 없으면MalformedConfig, 실제 file이 없으면FileNotFoundError입니다.
validate(data)문자열 또는 객체인 YAML manifest data를 현재 West가 읽을 수 있는지 검증하고 parsed dictionary를 반환합니다. Import를 실제로 해결하는 단계에서는 별도 실패가 날 수 있습니다.
Manifest와 하위 객체
class west.manifest.Manifest해석이 끝난 manifest file을 나타냅니다.
abspath,posixpath,relative_path,yaml_path,repo_path,repo_abspath,repo_posixpath,topdir,projects,has_imports,group_filter같은 attribute를 제공합니다.
Manifest constructor에는 topdir 또는 source_data 중 정확히 하나만 줍니다. topdir은 workspace에서 읽고, source_data는 workspace 없이 YAML 문자열이나 dictionary를 읽습니다. 후자의 absolute project path는 None이며 import는 importer callback을 주거나 import_flags로 무시해야 합니다.
importer(project, file) callback은 빠진 manifest file의 내용을 문자열로, directory이면 문자열 list로 반환합니다. None이면 import를 무시합니다. 잘못된 data는 MalformedManifest, import 실패는 ManifestImportFailed, 너무 새 schema는 ManifestVersionError, file 문제는 OSError, 그 밖의 잘못된 인자는 ValueError입니다.
Manifest.from_topdir(topdir=None, config=None, importer=None, import_flags=ImportFlag.DEFAULT)Workspace topdir로 manifest를 만듭니다. 생략하면 현재 directory부터 workspace를 찾습니다.
Manifest.from_file(source_file=None, importer=None, import_flags=ImportFlag.DEFAULT)YAML file에서 manifest를 만듭니다. Workspace 안의 임의 Git repository에 있는 대체 manifest도 읽을 수 있어 두 manifest 비교에 유용합니다. File을 생략하면 현재 workspace manifest를 찾습니다.
Manifest.from_data(source_data, importer=None, import_flags=ImportFlag.DEFAULT)설정 file을 읽지 않고 YAML 문자열이나 parsed object로 manifest를 만듭니다. Relative path는 data를 따르고 absolute path는 모두 None입니다.
Manifest.get_projects(project_ids, allow_paths=True, only_cloned=False)이름이나 허용된 path로
Projectlist를 요청 순서대로 반환합니다. 빈 입력은self.projects복사본입니다. 알 수 없는 ID나only_cloned=True에서 복제되지 않은 project가 있으면ValueError입니다.
Manifest.as_dict() / as_yaml(**kwargs)모든 import를 한 file에 직접 정의한 것처럼 완전히 resolve한 dictionary 또는 YAML을 반환합니다. YAML keyword는 yaml.safe_dump()에 전달됩니다.
Manifest.as_frozen_dict() / as_frozen_yaml(**kwargs)QUAL_MANIFEST_REV_BRANCH가 가리키는 full SHA로 모든 project revision을 고정해 반환합니다. SHA를 resolve하지 못하면RuntimeError입니다.
Manifest.is_active(project, extra_filter=None)manifest.project-filter와 group filter를 적용해 project 활성 여부를 반환합니다. Project 이름에 여러 정규식이 맞으면 마지막 일치가 결정하고+는 활성,-는 비활성입니다. 1.1.0부터 project-filter 설정을 반영합니다.
west.manifest.ImportFlagManifest resolve 중 import 처리 방식을 제어하는 bit flag입니다.
IGNORE 또는 IGNORE_PROJECTS를 사용해도 import 안의 path-prefix는 해당 project 자체에 적용됩니다.
manifest:
projects:
- name: foo
import:
path-prefix: bar따라서 위 예에서 foo의 path는 import한 project를 무시해도 bar/foo입니다.
DEFAULT = 0:self: import:는 file system에서,projects: import:는 Git을 실행해 resolve합니다.IGNORE = 1:self:와projects:import로 추가되는 project를 모두 무시합니다.FORCE_PROJECTS = 2: project import를 항상 importer 또는 Git으로 resolve합니다.IGNORE_PROJECTS = 4:projects:import만 무시하고self:import는 처리합니다.
class west.manifest.ProjectManifest의 project 하나를 나타냅니다. 주요 attribute는
name,url,description,revision,path,submodules,clone_depth,west_commands,topdir,remote_name,groups,userdata,abspath,posixpath,name_and_path입니다. 0.7.0에서 remote가 제거되고 remote_name/name_and_path가 추가됐으며, 0.8.0부터 west_commands는 항상 list, 0.9.0부터 group_filter/submodules, 0.12.0부터 userdata, 1.2.0부터 description을 지원합니다.
Project.__init__(name, url, description=None, revision=None, path=None, ...)Manifest project의 URL, revision, workspace 상대 path, submodule, clone depth, extension command, group, user data와 topdir을 설정합니다. 0.8.0부터 path와 topdir은 모든 os.PathLike를 받습니다.
Project.as_dict()동일한 YAML manifest에서 parse했을 때의 모습과 같은 dictionary 표현을 반환합니다.
Project.git(cmd, extra_args=(), capture_stdout=False, capture_stderr=False, check=True, cwd=None)self.abspath또는cwd에서 Git command를 실행하고CompletedProcess를 반환합니다. stdout/stderr capture와 nonzero return code 검사 여부를 제어할 수 있습니다.
Project.sha(rev, cwd=None)HEAD, tag 등 Git revision을 full SHA로 resolve합니다.
Project.is_ancestor_of(rev1, rev2, cwd=None)rev1이rev2의 ancestor이면 참입니다. 같은 commit도 자기 자신의 ancestor로 봅니다.
Project.is_cloned(cwd=None)Directory가 Git repository top-level처럼 보이면 참입니다.
Project.is_up_to_date_with(rev, cwd=None)is_ancestor_of(rev, 'HEAD')와 같으며 HEAD가 지정 revision을 포함하면 참입니다.
Project.is_up_to_date(cwd=None)is_up_to_date_with(self.revision)와 같아 HEAD가 manifest revision에 맞게 최신인지 검사합니다.
Project.read_at(path, rev=None, cwd=None)특정 revision의 상대 file path 내용을 bytes로 읽습니다. 기본 revision은 self.revision입니다.
Project.listdir_at(path, rev=None, cwd=None, encoding=None)특정 revision의 directory 안 file과 subdirectory 이름 list를 반환합니다. 기본 encoding은 UTF-8입니다.
class west.manifest.ManifestProjectManifest repository를
Project처럼 나타냅니다. 이름은manifest, revision은HEAD, URL은 빈 문자열, clone_depth는 None, groups는 빈 list입니다.topdir,path,abspath,posixpath,west_commands,userdata가 의미 있는 attribute이며 Project method 일부만 지원합니다.
ManifestProject.as_dict()동등한 YAML manifest에서 parse한 것과 같은 dictionary를 반환합니다.
class west.manifest.Submodule(path, name=None)Project 안의 Git submodule 하나를 나타냅니다. 0.9.0에 추가됐습니다.
Exception
west.configuration.MalformedConfigWest configuration data가 잘못됐음을 뜻합니다.
west.manifest.MalformedManifest잘못된 data 때문에 manifest parsing이 실패했음을 뜻합니다.
west.manifest.ManifestVersionError(version, file=None)Manifest가 현재 설치된 것보다 새로운 West version을 요구합니다. 0.8.0부터 file은 os.PathLike를 받을 수 있습니다.
west.manifest.ManifestImportFailed(project, imp)project는 빠진 data가 있는 Project이며self: import:이면 None입니다.imp는 import를 요청한 parsed YAML data입니다. 0.13.0에서 filename 인자가 imp로 바뀌고 임의 값을 받을 수 있게 됐습니다.
west.util
Workspace 위치 탐색 같은 기타 utility를 제공합니다.
함수
west.util.west_dir(start=None)시작 directory부터 parent 방향으로
.west를 찾아 absolute path를 반환합니다. 시작점을 생략하면 현재 directory를 사용하며 찾지 못하면WestNotFound입니다. 0.8.0부터 start는 os.PathLike를 받습니다.
west.util.west_topdir(start=None)시작 directory부터 parent 방향으로 workspace를 찾아 top-level absolute path를 반환합니다. 시작점을 생략하면 현재 directory를 사용하며 찾지 못하면
WestNotFound입니다. 0.8.0부터 start는 os.PathLike를 받습니다.
Exception
west.util.WestNotFound현재 위치나 지정한 시작점에서 West workspace를 찾지 못했음을 뜻합니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.