21374897774

Committed 26 Jan 2026 09:37PM UTC coverage: 80.008% (-0.3%) from 80.269%

Build # 21374897774

Build Type

Pull #23037

github

Committed by

web-flow

Commit Message

Merge 4023b9eee into 09b8ecaa1

Pull Request Pull Request #23037: Enable publish without package 2

Run Details

105 of 178 new or added lines in 11 files covered. (58.99%)

238 existing lines in 14 files now uncovered.

78628 of 98275 relevant lines covered (80.01%)

3.35 hits per line

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

93.75

/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.package_types import DockerPushOnPackageBehavior
from pants.backend.docker.registries import DockerRegistries
from pants.core.util_rules.search_paths import ExecutableSearchPathsOptionMixin
from pants.option.option_types import (
    BoolOption,
    DictOption,
    EnumOption,
    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,
    )

    push_on_package = EnumOption(
        default=DockerPushOnPackageBehavior.WARN,
        help=softwrap(
            """
            The behavior when a docker_image target would push to a registry during packaging
            (e.g., when output has push=true or type=registry).

            Options:
            - allow: Allow pushes during packaging
            - warn: Log a warning but continue with the push (default)
            - ignore: Skip building images that would push
            - error: Raise an error if an image would push
            """
        ),
    )

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

pantsbuild / pants / 21374897774

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