18517631058

Committed 15 Oct 2025 04:18AM UTC coverage: 69.207% (-11.1%) from 80.267%

Build # 18517631058

Build Type

Pull #22745

github

Committed by

web-flow

Commit Message

Merge 642a76ca1 into 99919310e

Pull Request Pull Request #22745: [windows] Add windows support in the stdio crate.

Run Details

53815 of 77759 relevant lines covered (69.21%)

2.42 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

89.13

/src/python/pants/backend/docker/subsystems/docker_options.py

# Copyright 2021 Pants project contributors (see CONTRIBUTORS.md).
# Licensed under the Apache License, Version 2.0 (see LICENSE).

from __future__ import annotations

import sys
from typing import Any

from pants.backend.docker.registries import DockerRegistries
from pants.core.util_rules.search_paths import ExecutableSearchPathsOptionMixin
from pants.option.option_types import (
    BoolOption,
    DictOption,
    ShellStrListOption,
    StrListOption,
    StrOption,
    WorkspacePathOption,
)
from pants.option.subsystem import Subsystem
from pants.util.docutil import bin_name
from pants.util.memo import memoized_method
from pants.util.strutil import bullet_list, softwrap

doc_links = {
    "docker_env_vars": (
        "https://docs.docker.com/engine/reference/commandline/cli/#environment-variables"
    ),
}


class DockerOptions(Subsystem):
    options_scope = "docker"
    help = "Options for interacting with Docker."

    class EnvironmentAware(ExecutableSearchPathsOptionMixin, Subsystem.EnvironmentAware):
        _env_vars = ShellStrListOption(
            help=softwrap(
                """
                Environment variables to set for `docker` invocations.

                Entries are either strings in the form `ENV_VAR=value` to set an explicit value;
                or just `ENV_VAR` to copy the value from Pants's own environment.
                """
            ),
            advanced=True,
        )
        executable_search_paths_help = softwrap(
            """
            The PATH value that will be used to find the Docker client and any tools required.
            """
        )

        @property
        def env_vars(self) -> tuple[str, ...]:
            return tuple(sorted(set(self._env_vars)))

    _registries = DictOption[Any](
        help=softwrap(
            """
            Configure Docker registries. The schema for a registry entry is as follows:

                {
                    "registry-alias": {
                        "address": "registry-domain:port",
                        "default": bool,
                        "extra_image_tags": [],
                        "skip_push": bool,
                        "repository": str,
                        "use_local_alias": bool,
                    },
                    ...
                }

            If no registries are provided in a `docker_image` target, then all default
            addresses will be used, if any.

            The `docker_image.registries` may be provided with a list of registry addresses
            and registry aliases prefixed with `@` to be used instead of the defaults.

            A configured registry is marked as default either by setting `default = true`
            or with an alias of `"default"`.

            A `docker_image` may be pushed to a subset of registries using the per registry
            `skip_push` option rather then the all or nothing toggle of the field option `skip_push`
            on the `docker_image` target.

            Any image tags that should only be added for specific registries may be provided as the
            `extra_image_tags` option. The tags may use value formatting the same as for the
            `image_tags` field of the `docker_image` target.

            When a registry provides a `repository` value, it will be used instead of the
            `docker_image.repository` or the default repository. Using the placeholders
            `{target_repository}` or `{default_repository}` those overridden values may be
            incorporated into the registry specific repository value.

            If `use_local_alias` is true, a built image is additionally tagged locally using the
            registry alias as the value for repository (i.e. the additional image tag is not pushed)
            and will be used for any `pants run` requests.
            """
        ),
        fromfile=True,
    )
    default_repository = StrOption(
        help=softwrap(
            f"""
            Configure the default repository name used in the Docker image tag.

            The value is formatted and may reference these variables (in addition to the normal
            placeholders derived from the Dockerfile and build args etc):

            {bullet_list(["name", "directory", "parent_directory", "full_directory", "target_repository"])}

            Example: `--default-repository="{{directory}}/{{name}}"`.

            The `name` variable is the `docker_image`'s target name.

            With the directory variables available, given a sample repository path of `baz/foo/bar/BUILD`,
            then `directory` is `bar`, `parent_directory` is `foo` and `full_directory` will be `baz/foo/bar`.

            Use the `repository` field to set this value directly on a `docker_image` target.

            Registries may override the repository value for a specific registry.

            Any registries or tags are added to the image name as required, and should
            not be part of the repository name.
            """
        ),
        default="{name}",
    )
    default_context_root = WorkspacePathOption(
        default="",
        help=softwrap(
            """
            Provide a default Docker build context root path for `docker_image` targets that
            does not specify their own `context_root` field.

            The context root is relative to the build root by default, but may be prefixed
            with `./` to be relative to the directory of the BUILD file of the `docker_image`.

            Examples:

                --default-context-root=src/docker
                --default-context-root=./relative_to_the_build_file
            """
        ),
    )
    use_buildx = BoolOption(
        default=False,
        help=softwrap(
            """
            Use [buildx](https://github.com/docker/buildx#buildx) (and BuildKit) for builds.
            """
        ),
    )

    _build_args = ShellStrListOption(
        help=softwrap(
            f"""
            Global build arguments (for Docker `--build-arg` options) to use for all
            `docker build` invocations.

            Entries are either strings in the form `ARG_NAME=value` to set an explicit value;
            or just `ARG_NAME` to copy the value from Pants's own environment.

            Example:

                [{options_scope}]
                build_args = ["VAR1=value", "VAR2"]


            Use the `extra_build_args` field on a `docker_image` target for additional
            image specific build arguments.
            """
        ),
    )
    build_target_stage = StrOption(
        default=None,
        help=softwrap(
            """
            Global default value for `target_stage` on `docker_image` targets, overriding
            the field value on the targets, if there is a matching stage in the `Dockerfile`.

            This is useful to provide from the command line, to specify the target stage to
            build for at execution time.
            """
        ),
    )
    build_hosts = DictOption[str](
        default={},
        help=softwrap(
            f"""
            Hosts entries to be added to the `/etc/hosts` file in all built images.

            Example:

                [{options_scope}]
                build_hosts = {{"docker": "10.180.0.1", "docker2": "10.180.0.2"}}

            Use the `extra_build_hosts` field on a `docker_image` target for additional
            image specific host entries.
            """
        ),
    )
    build_no_cache = BoolOption(
        default=False,
        help="Do not use the Docker cache when building images.",
    )
    build_verbose = BoolOption(
        default=False,
        help="Whether to log the Docker output to the console. If false, only the image ID is logged.",
    )
    run_args = ShellStrListOption(
        default=["--interactive", "--tty"] if sys.stdout.isatty() else [],
        help=softwrap(
            f"""
            Additional arguments to use for `docker run` invocations.

            Example:

                $ {bin_name()} run --{options_scope}-run-args="-p 127.0.0.1:80:8080/tcp\
                    --name demo" src/example:image -- [image entrypoint args]

            To provide the top-level options to the `docker` client, use
            `[{options_scope}].env_vars` to configure the
            [Environment variables]({doc_links["docker_env_vars"]}) as appropriate.

            The arguments for the image entrypoint may be passed on the command line after a
            double dash (`--`), or using the `--run-args` option.

            Defaults to `--interactive --tty` when stdout is connected to a terminal.
            """
        ),
    )
    publish_noninteractively = BoolOption(
        default=False,
        help=softwrap(
            """
            If true, publish images non-interactively. This allows for pushes to be parallelized, but requires
            docker to be pre-authenticated to the registries to which it is pushing.
            """
        ),
    )
    _tools = StrListOption(
        default=[],
        help=softwrap(
            """
            List any additional executable tools required for Docker to work. The paths to
            these tools will be included in the PATH used in the execution sandbox, so that
            they may be used by the Docker client.
            """
        ),
        advanced=True,
    )

    _optional_tools = StrListOption(
        help=softwrap(
            """
            List any additional executables which are not mandatory for Docker to work, but which
            should be included if available. The paths to these tools will be included in the
            PATH used in the execution sandbox, so that they may be used by the Docker client.
            """
        ),
        advanced=True,
    )

    tailor = BoolOption(
        default=True,
        help="If true, add `docker_image` targets with the `tailor` goal.",
        advanced=True,
    )

    suggest_renames = BoolOption(
        default=True,
        help=softwrap(
            """
            When true and, the `docker_image` build fails, enrich the logs with suggestions
            for renaming source file COPY instructions where possible.
            """
        ),
        advanced=True,
    )

    @property
    def build_args(self) -> tuple[str, ...]:
        return tuple(sorted(set(self._build_args)))

    @property
    def tools(self) -> tuple[str, ...]:
        return tuple(sorted(set(self._tools)))

    @property
    def optional_tools(self) -> tuple[str, ...]:
        return tuple(sorted(set(self._optional_tools)))

    @memoized_method
    def registries(self) -> DockerRegistries:
        return DockerRegistries.from_dict(self._registries)

1	# Copyright 2021 Pants project contributors (see CONTRIBUTORS.md).
2	# Licensed under the Apache License, Version 2.0 (see LICENSE).
3
4	from __future__ import annotations	6✔
5
6	import sys	6✔
7	from typing import Any	6✔
8
9	from pants.backend.docker.registries import DockerRegistries	6✔
10	from pants.core.util_rules.search_paths import ExecutableSearchPathsOptionMixin	6✔
11	from pants.option.option_types import (	6✔
12	BoolOption,
13	DictOption,
14	ShellStrListOption,
15	StrListOption,
16	StrOption,
17	WorkspacePathOption,
18	)
19	from pants.option.subsystem import Subsystem	6✔
20	from pants.util.docutil import bin_name	6✔
21	from pants.util.memo import memoized_method	6✔
22	from pants.util.strutil import bullet_list, softwrap	6✔
23
24	doc_links = {	6✔
25	"docker_env_vars": (
26	"https://docs.docker.com/engine/reference/commandline/cli/#environment-variables"
27	),
28	}
29
30
31	class DockerOptions(Subsystem):	6✔
32	options_scope = "docker"	6✔
33	help = "Options for interacting with Docker."	6✔
34
35	class EnvironmentAware(ExecutableSearchPathsOptionMixin, Subsystem.EnvironmentAware):	6✔
36	_env_vars = ShellStrListOption(	6✔
37	help=softwrap(
38	"""
39	Environment variables to set for `docker` invocations.
40
41	Entries are either strings in the form `ENV_VAR=value` to set an explicit value;
42	or just `ENV_VAR` to copy the value from Pants's own environment.
43	"""
44	),
45	advanced=True,
46	)
47	executable_search_paths_help = softwrap(	6✔
48	"""
49	The PATH value that will be used to find the Docker client and any tools required.
50	"""
51	)
52
53	@property	6✔
54	def env_vars(self) -> tuple[str, ...]:	6✔
55	return tuple(sorted(set(self._env_vars)))	×
56
57	_registries = DictOption[Any](
58	help=softwrap(
59	"""
60	Configure Docker registries. The schema for a registry entry is as follows:
61
62	{
63	"registry-alias": {
64	"address": "registry-domain:port",
65	"default": bool,
66	"extra_image_tags": [],
67	"skip_push": bool,
68	"repository": str,
69	"use_local_alias": bool,
70	},
71	...
72	}
73
74	If no registries are provided in a `docker_image` target, then all default
75	addresses will be used, if any.
76
77	The `docker_image.registries` may be provided with a list of registry addresses
78	and registry aliases prefixed with `@` to be used instead of the defaults.
79
80	A configured registry is marked as default either by setting `default = true`
81	or with an alias of `"default"`.
82
83	A `docker_image` may be pushed to a subset of registries using the per registry
84	`skip_push` option rather then the all or nothing toggle of the field option `skip_push`
85	on the `docker_image` target.
86
87	Any image tags that should only be added for specific registries may be provided as the
88	`extra_image_tags` option. The tags may use value formatting the same as for the
89	`image_tags` field of the `docker_image` target.
90
91	When a registry provides a `repository` value, it will be used instead of the
92	`docker_image.repository` or the default repository. Using the placeholders
93	`{target_repository}` or `{default_repository}` those overridden values may be
94	incorporated into the registry specific repository value.
95
96	If `use_local_alias` is true, a built image is additionally tagged locally using the
97	registry alias as the value for repository (i.e. the additional image tag is not pushed)
98	and will be used for any `pants run` requests.
99	"""
100	),
101	fromfile=True,
102	)
103	default_repository = StrOption(	6✔
104	help=softwrap(
105	f"""
106	Configure the default repository name used in the Docker image tag.
107
108	The value is formatted and may reference these variables (in addition to the normal
109	placeholders derived from the Dockerfile and build args etc):
110
111	{bullet_list(["name", "directory", "parent_directory", "full_directory", "target_repository"])}
112
113	Example: `--default-repository="{{directory}}/{{name}}"`.
114
115	The `name` variable is the `docker_image`'s target name.
116
117	With the directory variables available, given a sample repository path of `baz/foo/bar/BUILD`,
118	then `directory` is `bar`, `parent_directory` is `foo` and `full_directory` will be `baz/foo/bar`.
119
120	Use the `repository` field to set this value directly on a `docker_image` target.
121
122	Registries may override the repository value for a specific registry.
123
124	Any registries or tags are added to the image name as required, and should
125	not be part of the repository name.
126	"""
127	),
128	default="{name}",
129	)
130	default_context_root = WorkspacePathOption(	6✔
131	default="",
132	help=softwrap(
133	"""
134	Provide a default Docker build context root path for `docker_image` targets that
135	does not specify their own `context_root` field.
136
137	The context root is relative to the build root by default, but may be prefixed
138	with `./` to be relative to the directory of the BUILD file of the `docker_image`.
139
140	Examples:
141
142	--default-context-root=src/docker
143	--default-context-root=./relative_to_the_build_file
144	"""
145	),
146	)
147	use_buildx = BoolOption(	6✔
148	default=False,
149	help=softwrap(
150	"""
151	Use [buildx](https://github.com/docker/buildx#buildx) (and BuildKit) for builds.
152	"""
153	),
154	)
155
156	_build_args = ShellStrListOption(	6✔
157	help=softwrap(
158	f"""
159	Global build arguments (for Docker `--build-arg` options) to use for all
160	`docker build` invocations.
161
162	Entries are either strings in the form `ARG_NAME=value` to set an explicit value;
163	or just `ARG_NAME` to copy the value from Pants's own environment.
164
165	Example:
166
167	[{options_scope}]
168	build_args = ["VAR1=value", "VAR2"]
169
170
171	Use the `extra_build_args` field on a `docker_image` target for additional
172	image specific build arguments.
173	"""
174	),
175	)
176	build_target_stage = StrOption(	6✔
177	default=None,
178	help=softwrap(
179	"""
180	Global default value for `target_stage` on `docker_image` targets, overriding
181	the field value on the targets, if there is a matching stage in the `Dockerfile`.
182
183	This is useful to provide from the command line, to specify the target stage to
184	build for at execution time.
185	"""
186	),
187	)
188	build_hosts = DictOption[str](	6✔
189	default={},
190	help=softwrap(
191	f"""
192	Hosts entries to be added to the `/etc/hosts` file in all built images.
193
194	Example:
195
196	[{options_scope}]
197	build_hosts = {{"docker": "10.180.0.1", "docker2": "10.180.0.2"}}
198
199	Use the `extra_build_hosts` field on a `docker_image` target for additional
200	image specific host entries.
201	"""
202	),
203	)
204	build_no_cache = BoolOption(	6✔
205	default=False,
206	help="Do not use the Docker cache when building images.",
207	)
208	build_verbose = BoolOption(	6✔
209	default=False,
210	help="Whether to log the Docker output to the console. If false, only the image ID is logged.",
211	)
212	run_args = ShellStrListOption(	6✔
213	default=["--interactive", "--tty"] if sys.stdout.isatty() else [],
214	help=softwrap(
215	f"""
216	Additional arguments to use for `docker run` invocations.
217
218	Example:
219
220	$ {bin_name()} run --{options_scope}-run-args="-p 127.0.0.1:80:8080/tcp\
221	--name demo" src/example:image -- [image entrypoint args]
222
223	To provide the top-level options to the `docker` client, use
224	`[{options_scope}].env_vars` to configure the
225	[Environment variables]({doc_links["docker_env_vars"]}) as appropriate.
226
227	The arguments for the image entrypoint may be passed on the command line after a
228	double dash (`--`), or using the `--run-args` option.
229
230	Defaults to `--interactive --tty` when stdout is connected to a terminal.
231	"""
232	),
233	)
234	publish_noninteractively = BoolOption(	6✔
235	default=False,
236	help=softwrap(
237	"""
238	If true, publish images non-interactively. This allows for pushes to be parallelized, but requires
239	docker to be pre-authenticated to the registries to which it is pushing.
240	"""
241	),
242	)
243	_tools = StrListOption(	6✔
244	default=[],
245	help=softwrap(
246	"""
247	List any additional executable tools required for Docker to work. The paths to
248	these tools will be included in the PATH used in the execution sandbox, so that
249	they may be used by the Docker client.
250	"""
251	),
252	advanced=True,
253	)
254
255	_optional_tools = StrListOption(	6✔
256	help=softwrap(
257	"""
258	List any additional executables which are not mandatory for Docker to work, but which
259	should be included if available. The paths to these tools will be included in the
260	PATH used in the execution sandbox, so that they may be used by the Docker client.
261	"""
262	),
263	advanced=True,
264	)
265
266	tailor = BoolOption(	6✔
267	default=True,
268	help="If true, add `docker_image` targets with the `tailor` goal.",
269	advanced=True,
270	)
271
272	suggest_renames = BoolOption(	6✔
273	default=True,
274	help=softwrap(
275	"""
276	When true and, the `docker_image` build fails, enrich the logs with suggestions
277	for renaming source file COPY instructions where possible.
278	"""
279	),
280	advanced=True,
281	)
282
283	@property	6✔
284	def build_args(self) -> tuple[str, ...]:	6✔
285	return tuple(sorted(set(self._build_args)))	×
286
287	@property	6✔
288	def tools(self) -> tuple[str, ...]:	6✔
289	return tuple(sorted(set(self._tools)))	×
290
291	@property	6✔
292	def optional_tools(self) -> tuple[str, ...]:	6✔
293	return tuple(sorted(set(self._optional_tools)))	×
294
295	@memoized_method	6✔
296	def registries(self) -> DockerRegistries:	6✔
297	return DockerRegistries.from_dict(self._registries)	×

pantsbuild / pants / 18517631058

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous