Lines Matching +full:python +full:- +full:tests
1 .. _module-pw_build-python:
4 Python GN Templates
6 .. pigweed-module-subpage::
9 The Python build is implemented with GN templates defined in
10 ``pw_build/python.gni``. See the .gni file for complete usage documentation.
14 - :bdg-ref-primary-line:`docs-python-build` for an overview on how Python in
16 - The :bdg-ref-primary-line:`module-pw_build` docs for other GN templates
19 .. _module-pw_build-python-base-templates:
21 ---------------------
22 Python Base Templates
23 ---------------------
24 The core subset of templates where you can create Python packages, actions,
27 - :ref:`module-pw_build-pw_python_package`
28 - :ref:`module-pw_build-pw_python_action`
29 - :ref:`module-pw_build-pw_python_script`
30 - :ref:`module-pw_build-pw_python_group`
32 .. _module-pw_build-pw_python_package:
36 The main Python template is ``pw_python_package``. Each ``pw_python_package``
37 target represents a Python package. As described in
38 :ref:`module-pw_build-python-target`, each ``pw_python_package`` expands to
41 - ``<name>`` - Represents the files themselves
42 - ``<name>.lint`` - Runs static analysis
43 - ``<name>.tests`` - Runs all tests for this package
44 - ``<name>.install`` - Installs the package
45 - ``<name>.wheel`` - Builds a Python wheel
48 name (e.g. ``//foo`` for ``//foo:foo``). For consistency with this, Python
52 .. code-block::
54 //path/to/my_python_package:my_python_package.tests
55 //path/to/my_python_package:tests
59 multi-toolchain builds. This toolchain can be set with the
61 ``$dir_pw_build/python_toolchain:python``.
65 By default, ``<name>.lint`` and ``<name>.tests`` will transitively test and
72 ---------
73 - ``setup`` - List of setup file paths (setup.cfg and pyproject.toml), which
75 - ``generate_setup``: As an alternative to ``setup``, generate setup files with
81 .. code-block::
93 - ``sources`` - Python sources files in the package.
94 - ``tests`` - Test files for this Python package.
99 file. That could cause your tests to be included within the package
100 distributions (See :ref:`module-pw_build-pw_python_distribution`). For
101 example pip installed into the bootstrapped Python virtual environment or
102 as part of a Python wheel.
104 If you need to nest your test source files under a sub-folder exclude it in
107 .. code-block:: cfg
112 # Exclude the tests and test_scripts folders.
115 tests
118 - ``python_deps`` - Dependencies on other pw_python_packages in the GN build.
119 - ``python_test_deps`` - Test-only pw_python_package dependencies.
120 - ``other_deps`` - Dependencies on GN targets that are not pw_python_packages.
121 - ``inputs`` - Other files to track, such as package_data.
122 - ``proto_library`` - A pw_proto_library target to embed in this Python package.
124 :ref:`module-pw_protobuf_compiler-add-to-python-package`.
125 - ``static_analysis`` List of static analysis tools to run; ``"*"`` (default)
127 - ``pylintrc`` - Optional path to a pylintrc configuration file to use. If not
131 - ``mypy_ini`` - Optional path to a mypy configuration file to use. If not
137 -------
138 This is an example Python package declaration for a ``pw_my_module`` module.
140 .. code-block::
144 import("$dir_pw_build/python.gni")
157 tests = [
163 ":some_protos.python",
169 .. _module-pw_build-pw_python_action:
175 for running Python scripts. See
176 :bdg-ref-primary-line:`module-pw_build-python-action` in the ``pw_build``
179 .. _module-pw_build-pw_python_script:
183 A ``pw_python_script`` represents a set of standalone Python scripts and/or
184 tests. These files support all of the arguments of ``pw_python_package`` except
189 :ref:`pw_python_action <module-pw_build-python-action>` associated with the
197 - The embedded action target bridges the gap between actions and Python targets.
198 A Python script can be expressed in a single, concise GN target, rather than
200 - The action automatically depends on the ``pw_python_script``. This ensures
204 - Using a ``pw_python_script`` with an embedded action is a simple way to check
205 an existing action's script with Pylint or Mypy or to add tests.
207 .. _module-pw_build-pw_python_group:
215 .. code-block::
232 ----------------------------
233 Python Environment Templates
234 ----------------------------
235 Templates that manage the Python build and bootstrap environment are listed
238 - :ref:`module-pw_build-pw_python_venv`
239 - :ref:`module-pw_build-pw_python_pip_install`
241 .. _module-pw_build-pw_python_venv:
245 Defines and creates a Python virtualenv. This template is used by Pigweed in
247 virtualenv for use within the GN build that all Python actions will run in.
250 -------
251 .. code-block::
252 :caption: Example of a typical Python venv definition in a top level
267 path = "$root_build_dir/python-build-venv"
279 ---------
280 - ``path``: The directory where the virtualenv will be created. This is relative
284 - ``constraints``: A list of constraint files used when performing pip install
288 - ``requirements``: A list of requirements files to install into this virtualenv
296 :ref:`docs-python-build-python-gn-requirements-files`
298 - ``pip_generate_hashes``: (Default: false) Use ``--generate-hashes`` When
299 running `pip-compile <A list of requirements files to install into this
302 - ``source_packages``: A list of in-tree
303 :ref:`module-pw_build-pw_python_package` or targets that will be checked for
315 - ``output_logs``: (Default: true) If this is true then the virtual environment will output to logs.
317 .. _module-pw_build-pw_python_pip_install:
325 -------
326 .. code-block::
327 :caption: Example of a typical Python venv definition in a top level
338 ---------
340 - ``packages``: A list of :ref:`module-pw_build-pw_python_package` targets to be
342 install`` command with a ``--constraint`` argument for each constraint file in
345 - ``editable``: If true, --editable is passed to the pip install command.
347 - ``force_reinstall``: If true, ``--force-reinstall`` is passed to the pip
350 .. _module-pw_build-python-dist:
352 ------------------------------
353 Python Distributable Templates
354 ------------------------------
355 Pigweed also provides some templates to make it easier to bundle Python packages
358 - :ref:`module-pw_build-pw_python_wheels`
359 - :ref:`module-pw_build-pw_python_zip_with_setup`
360 - :ref:`module-pw_build-pw_python_distribution`
362 .. _module-pw_build-pw_python_wheels:
366 Collects Python wheels for one or more ``pw_python_package`` targets, plus any
368 Note that this does not include Python dependencies that come from outside the
373 ---------
374 - ``packages`` - List of ``pw_python_package`` targets whose wheels should be
376 - ``directory`` - Output directory for the collected wheels. Defaults to
380 -------------------------------
382 (``.whl``) for the Python package. The ``pw_python_wheels`` template figures
388 .. _module-pw_build-pw_python_zip_with_setup:
393 developer environment. The generated ``.zip`` contains Python wheels
400 MacOS, and Windows. The setup scripts automatically create a Python virtual
405 and usage instructions for the distributable. A simple ready-to-use README file
409 ---------
410 - ``packages`` - A list of `pw_python_package` targets whose wheels should be
412 - ``inputs`` - An optional list of extra files to include in the generated
415 - ``dirs`` - An optional list of directories to include in the generated
420 -------
422 .. code-block::
433 .. _module-pw_build-pw_python_distribution:
437 Generates a directory of Python packages from source files suitable for
440 useful for bundling multiple Python packages up into a single package for
444 ---------
446 - ``packages`` - A list of :ref:`module-pw_build-pw_python_package` targets to be installed into
449 - ``include_tests`` - If true, copy Python package tests to a ``tests`` subdir.
451 - ``extra_files`` - A list of extra files that should be included in the output.
454 .. code-block:: text
458 - Source and destination file should be separated by ``>``.
460 - The source file should be a GN target label (starting with ``//``).
462 - The destination file will be relative to the generated output
466 - ``generate_setup_cfg`` - If included, create a merged ``setup.cfg`` for all
467 python Packages using either a ``common_config_file`` as a base or ``name``
474 - ``append_git_sha_to_version = true``: Append the current git SHA to the
477 - ``append_date_to_version = true``: Append the current date to the package
480 - ``include_default_pyproject_file = true``: Include a standard
483 - ``include_extra_files_in_package_data = true``: Add any ``extra_files``
487 - ``auto_create_package_data_init_py_files = true``: (Default: true) Create
491 .. code-block::
503 .. code-block::
514 Using this template will create an additional target for and building a Python
518 - ``awesome`` - This will create the merged package with all source files in
520 - ``awesome.wheel`` - This builds a Python wheel from the above source files
524 -------
526 .. code-block::
552 .. code-block:: text
553 :caption: :octicon:`file-directory;1em`
564 │ └── tests
571 └── tests