We are currently solving the following issue within our repository. Here is the issue text:
--- BEGIN ISSUE ---
docs: `adhoc_tool` example field values swapped
              When looking at the rendered docs it was much easier to spot that the example field values here are swapped (files vs directories). 👀

_Originally posted by @kaos in https://github.com/pantsbuild/pants/pull/18237#discussion_r1184219518_
            

--- END ISSUE ---

Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
--- BEGIN FILES ---
Path: `src/python/pants/backend/adhoc/target_types.py`
Content:
```
1 # Copyright 2023 Pants project contributors (see CONTRIBUTORS.md).
2 # Licensed under the Apache License, Version 2.0 (see LICENSE).
3 
4 from __future__ import annotations
5 
6 from typing import ClassVar
7 
8 from pants.core.util_rules.environments import EnvironmentField
9 from pants.engine.target import (
10     COMMON_TARGET_FIELDS,
11     BoolField,
12     Dependencies,
13     IntField,
14     MultipleSourcesField,
15     SpecialCasedDependencies,
16     StringField,
17     StringSequenceField,
18     Target,
19     ValidNumbers,
20 )
21 from pants.util.strutil import help_text
22 
23 
24 class AdhocToolDependenciesField(Dependencies):
25     pass
26 
27 
28 class AdhocToolRunnableField(StringField):
29     alias: ClassVar[str] = "runnable"
30     required = True
31     help = help_text(
32         lambda: f"""
33         Address to a target that can be invoked by the `run` goal (and does not set
34         `run_in_sandbox_behavior=NOT_SUPPORTED`). This will be executed along with any arguments
35         specified by `{AdhocToolArgumentsField.alias}`, in a sandbox with that target's transitive
36         dependencies, along with the transitive dependencies specified by
37         `{AdhocToolExecutionDependenciesField.alias}`.
38         """
39     )
40 
41 
42 class AdhocToolOutputFilesField(StringSequenceField):
43     alias: ClassVar[str] = "output_files"
44     required = False
45     default = ()
46     help = help_text(
47         lambda: f"""
48         Specify the output files to capture, relative to the value of
49         `{AdhocToolWorkdirField.alias}`.
50 
51         For directories, use `{AdhocToolOutputDirectoriesField.alias}`. At least one of
52         `{AdhocToolOutputFilesField.alias}` and`{AdhocToolOutputDirectoriesField.alias}` must be
53         specified.
54 
55         Relative paths (including `..`) may be used, as long as the path does not ascend further
56         than the build root.
57         """
58     )
59 
60 
61 class AdhocToolOutputDirectoriesField(StringSequenceField):
62     alias: ClassVar[str] = "output_directories"
63     required = False
64     default = ()
65     help = help_text(
66         lambda: f"""
67         Specify full directories (including recursive descendants) of output to capture, relative
68         to the value of `{AdhocToolWorkdirField.alias}`.
69 
70         For individual files, use `{AdhocToolOutputFilesField.alias}`. At least one of
71         `{AdhocToolOutputFilesField.alias}` and`{AdhocToolOutputDirectoriesField.alias}` must be
72         specified.
73 
74         Relative paths (including `..`) may be used, as long as the path does not ascend further
75         than the build root.
76         """
77     )
78 
79 
80 class AdhocToolOutputDependenciesField(AdhocToolDependenciesField):
81     supports_transitive_excludes = True
82     alias: ClassVar[str] = "output_dependencies"
83 
84     help = help_text(
85         lambda: """
86         Any dependencies that need to be present (as transitive dependencies) whenever the outputs
87         of this target are consumed (including as dependencies).
88         """
89     )
90 
91 
92 class AdhocToolExecutionDependenciesField(SpecialCasedDependencies):
93     alias: ClassVar[str] = "execution_dependencies"
94     required = False
95     default = None
96 
97     help = help_text(
98         lambda: f"""
99         The execution dependencies for this command.
100 
101         Dependencies specified here are those required to make the command complete successfully
102         (e.g. file inputs, packages compiled from other targets, etc), but NOT required to make
103         the outputs of the command useful. Dependencies that are required to use the outputs
104         produced by this command should be specified using the
105         `{AdhocToolOutputDependenciesField.alias}` field.
106 
107         If this field is specified, dependencies from `{AdhocToolOutputDependenciesField.alias}`
108         will not be added to the execution sandbox.
109         """
110     )
111 
112 
113 class AdhocToolRunnableDependenciesField(SpecialCasedDependencies):
114     alias: ClassVar[str] = "runnable_dependencies"
115     required = False
116     default = None
117 
118     help = help_text(
119         lambda: f"""
120         The execution dependencies for this command.
121 
122         Dependencies specified here are those required to exist on the `PATH` to make the command
123         complete successfully (interpreters specified in a `#!` command, etc). Note that these
124         dependencies will be made available on the `PATH` with the name of the target.
125 
126         See also `{AdhocToolOutputDependenciesField.alias}` and
127         `{AdhocToolExecutionDependenciesField.alias}.
128         """
129     )
130 
131 
132 class AdhocToolSourcesField(MultipleSourcesField):
133     # We solely register this field for codegen to work.
134     alias: ClassVar[str] = "_sources"
135     uses_source_roots = False
136     expected_num_files = 0
137 
138 
139 class AdhocToolArgumentsField(StringSequenceField):
140     alias: ClassVar[str] = "args"
141     default = ()
142     help = help_text(
143         lambda: f"Extra arguments to pass into the `{AdhocToolRunnableField.alias}` field."
144     )
145 
146 
147 class AdhocToolStdoutFilenameField(StringField):
148     alias: ClassVar[str] = "stdout"
149     default = None
150     help = help_text(
151         lambda: f"""
152         A filename to capture the contents of `stdout` to. Relative paths are
153         relative to the value of `{AdhocToolWorkdirField.alias}`, absolute paths
154         start at the build root.
155         """
156     )
157 
158 
159 class AdhocToolStderrFilenameField(StringField):
160     alias: ClassVar[str] = "stderr"
161     default = None
162     help = help_text(
163         lambda: f"""
164         A filename to capture the contents of `stderr` to. Relative paths are
165         relative to the value of `{AdhocToolWorkdirField.alias}`, absolute paths
166         start at the build root.
167         """
168     )
169 
170 
171 class AdhocToolTimeoutField(IntField):
172     alias: ClassVar[str] = "timeout"
173     default = 30
174     help = "Command execution timeout (in seconds)."
175     valid_numbers = ValidNumbers.positive_only
176 
177 
178 class AdhocToolExtraEnvVarsField(StringSequenceField):
179     alias: ClassVar[str] = "extra_env_vars"
180     help = help_text(
181         """
182         Additional environment variables to provide to the process.
183 
184         Entries are strings in the form `ENV_VAR=value` to use explicitly; or just
185         `ENV_VAR` to copy the value of a variable in Pants's own environment.
186         """
187     )
188 
189 
190 class AdhocToolLogOutputField(BoolField):
191     alias: ClassVar[str] = "log_output"
192     default = False
193     help = "Set to true if you want the output logged to the console."
194 
195 
196 class AdhocToolWorkdirField(StringField):
197     alias: ClassVar[str] = "workdir"
198     default = "."
199     help = help_text(
200         """
201         Sets the working directory for the process.
202 
203         Values are relative to the build root, except in the following cases:
204 
205         * `.` specifies the location of the `BUILD` file.
206         * Values beginning with `./` are relative to the location of the `BUILD` file.
207         * `/` or the empty string specifies the build root.
208         * Values beginning with `/` are also relative to the build root.
209         """
210     )
211 
212 
213 class AdhocToolOutputRootDirField(StringField):
214     alias: ClassVar[str] = "root_output_directory"
215     default = "/"
216     help = help_text(
217         """Adjusts the location of files output by this target, when consumed as a dependency.
218 
219         Values are relative to the build root, except in the following cases:
220 
221         * `.` specifies the location of the `BUILD` file.
222         * Values beginning with `./` are relative to the location of the `BUILD` file.
223         * `/` or the empty string specifies the build root.
224         * Values beginning with `/` are also relative to the build root.
225         """
226     )
227 
228 
229 class AdhocToolTarget(Target):
230     alias: ClassVar[str] = "adhoc_tool"
231     core_fields = (
232         *COMMON_TARGET_FIELDS,
233         AdhocToolRunnableField,
234         AdhocToolArgumentsField,
235         AdhocToolExecutionDependenciesField,
236         AdhocToolOutputDependenciesField,
237         AdhocToolRunnableDependenciesField,
238         AdhocToolLogOutputField,
239         AdhocToolOutputFilesField,
240         AdhocToolOutputDirectoriesField,
241         AdhocToolSourcesField,
242         AdhocToolTimeoutField,
243         AdhocToolExtraEnvVarsField,
244         AdhocToolWorkdirField,
245         AdhocToolOutputRootDirField,
246         AdhocToolStdoutFilenameField,
247         AdhocToolStderrFilenameField,
248         EnvironmentField,
249     )
250     help = help_text(
251         lambda: f"""
252         Execute any runnable target for its side effects.
253 
254         Example BUILD file:
255 
256             {AdhocToolTarget.alias}(
257                 {AdhocToolRunnableField.alias}=":python_source",
258                 {AdhocToolArgumentsField.alias}=[""],
259                 {AdhocToolExecutionDependenciesField.alias}=[":scripts"],
260                 {AdhocToolOutputDirectoriesField.alias}=["logs/my-script.log"],
261                 {AdhocToolOutputFilesField.alias}=["results/"],
262             )
263 
264             shell_sources(name="scripts")
265         """
266     )
267 
268 
269 # ---
270 # `system_binary` target
271 # ---
272 
273 
274 class SystemBinaryNameField(StringField):
275     alias: ClassVar[str] = "binary_name"
276     required = True
277     help = "The name of the binary to find."
278 
279 
280 class SystemBinaryExtraSearchPathsField(StringSequenceField):
281     alias: ClassVar[str] = "extra_search_paths"
282     default = ()
283     help = help_text(
284         """
285         Extra search paths to look for the binary. These take priority over Pants' default
286         search paths.
287         """
288     )
289 
290 
291 class SystemBinaryFingerprintPattern(StringField):
292     alias: ClassVar[str] = "fingerprint"
293     required = False
294     default = None
295     help = help_text(
296         """
297         A regular expression which will be used to match the fingerprint outputs from
298         candidate binaries found during the search process.
299         """
300     )
301 
302 
303 class SystemBinaryFingerprintArgsField(StringSequenceField):
304     alias: ClassVar[str] = "fingerprint_args"
305     default = ()
306     help = help_text(
307         "Specifies arguments that will be used to run the binary during the search process."
308     )
309 
310 
311 class SystemBinaryFingerprintDependenciesField(AdhocToolRunnableDependenciesField):
312     alias: ClassVar[str] = "fingerprint_dependencies"
313     help = help_text(
314         """
315         Specifies any runnable dependencies that need to be available on the `PATH` when the binary
316         is run, so that the search process may complete successfully. The name of the target must
317         be the name of the runnable dependency that is called by this binary.
318         """
319     )
320 
321 
322 class SystemBinaryTarget(Target):
323     alias: ClassVar[str] = "system_binary"
324     core_fields = (
325         *COMMON_TARGET_FIELDS,
326         SystemBinaryNameField,
327         SystemBinaryExtraSearchPathsField,
328         SystemBinaryFingerprintPattern,
329         SystemBinaryFingerprintArgsField,
330         SystemBinaryFingerprintDependenciesField,
331     )
332     help = help_text(
333         lambda: f"""
334         A system binary that can be run with `pants run` or consumed by `{AdhocToolTarget.alias}`.
335 
336         Pants will search for binaries with name `{SystemBinaryNameField.alias}` in the search
337         paths provided, as well as default search paths. If
338         `{SystemBinaryFingerprintPattern.alias}` is specified, each binary that is located will be
339         executed with the arguments from `{SystemBinaryFingerprintArgsField.alias}`. Any binaries
340         whose output does not match the pattern will be excluded.
341 
342         The first non-excluded binary will be the one that is resolved.
343         """
344     )
345
```
--- END FILES ---

Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.

Here is an example:

```diff
diff --git a/examples/server_async.py b/examples/server_async.py
--- a/examples/server_async.py
+++ b/examples/server_async.py
@@ -313,4 +313,4 @@
 
 
 if __name__ == "__main__":
-    asyncio.run(run_async_server("."), debug=True)
+    asyncio.run(run_async_server(), debug=True)
diff --git a/examples/server_sync.py b/examples/server_sync.py
--- a/examples/server_sync.py
+++ b/examples/server_sync.py
@@ -313,5 +313,5 @@
 
 
 if __name__ == "__main__":
-    server = run_sync_server(".")
+    server = run_sync_server()
     server.shutdown()

```

diff --git a/src/python/pants/backend/adhoc/target_types.py b/src/python/pants/backend/adhoc/target_types.py
--- a/src/python/pants/backend/adhoc/target_types.py
+++ b/src/python/pants/backend/adhoc/target_types.py
@@ -257,8 +257,8 @@
                 {AdhocToolRunnableField.alias}=":python_source",
                 {AdhocToolArgumentsField.alias}=[""],
                 {AdhocToolExecutionDependenciesField.alias}=[":scripts"],
-                {AdhocToolOutputDirectoriesField.alias}=["logs/my-script.log"],
-                {AdhocToolOutputFilesField.alias}=["results/"],
+                {AdhocToolOutputDirectoriesField.alias}=["results/"],
+                {AdhocToolOutputFilesField.alias}=["logs/my-script.log"],
             )
 
             shell_sources(name="scripts")

{"golden_diff": "diff --git a/src/python/pants/backend/adhoc/target_types.py b/src/python/pants/backend/adhoc/target_types.py\n--- a/src/python/pants/backend/adhoc/target_types.py\n+++ b/src/python/pants/backend/adhoc/target_types.py\n@@ -257,8 +257,8 @@\n                 {AdhocToolRunnableField.alias}=\":python_source\",\n                 {AdhocToolArgumentsField.alias}=[\"\"],\n                 {AdhocToolExecutionDependenciesField.alias}=[\":scripts\"],\n-                {AdhocToolOutputDirectoriesField.alias}=[\"logs/my-script.log\"],\n-                {AdhocToolOutputFilesField.alias}=[\"results/\"],\n+                {AdhocToolOutputDirectoriesField.alias}=[\"results/\"],\n+                {AdhocToolOutputFilesField.alias}=[\"logs/my-script.log\"],\n             )\n \n             shell_sources(name=\"scripts\")\n", "issue": "docs: `adhoc_tool` example field values swapped\n              When looking at the rendered docs it was much easier to spot that the example field values here are swapped (files vs directories). \ud83d\udc40\r\n\r\n_Originally posted by @kaos in https://github.com/pantsbuild/pants/pull/18237#discussion_r1184219518_\r\n            \n", "before_files": [{"content": "# Copyright 2023 Pants project contributors (see CONTRIBUTORS.md).\n# Licensed under the Apache License, Version 2.0 (see LICENSE).\n\nfrom __future__ import annotations\n\nfrom typing import ClassVar\n\nfrom pants.core.util_rules.environments import EnvironmentField\nfrom pants.engine.target import (\n    COMMON_TARGET_FIELDS,\n    BoolField,\n    Dependencies,\n    IntField,\n    MultipleSourcesField,\n    SpecialCasedDependencies,\n    StringField,\n    StringSequenceField,\n    Target,\n    ValidNumbers,\n)\nfrom pants.util.strutil import help_text\n\n\nclass AdhocToolDependenciesField(Dependencies):\n    pass\n\n\nclass AdhocToolRunnableField(StringField):\n    alias: ClassVar[str] = \"runnable\"\n    required = True\n    help = help_text(\n        lambda: f\"\"\"\n        Address to a target that can be invoked by the `run` goal (and does not set\n        `run_in_sandbox_behavior=NOT_SUPPORTED`). This will be executed along with any arguments\n        specified by `{AdhocToolArgumentsField.alias}`, in a sandbox with that target's transitive\n        dependencies, along with the transitive dependencies specified by\n        `{AdhocToolExecutionDependenciesField.alias}`.\n        \"\"\"\n    )\n\n\nclass AdhocToolOutputFilesField(StringSequenceField):\n    alias: ClassVar[str] = \"output_files\"\n    required = False\n    default = ()\n    help = help_text(\n        lambda: f\"\"\"\n        Specify the output files to capture, relative to the value of\n        `{AdhocToolWorkdirField.alias}`.\n\n        For directories, use `{AdhocToolOutputDirectoriesField.alias}`. At least one of\n        `{AdhocToolOutputFilesField.alias}` and`{AdhocToolOutputDirectoriesField.alias}` must be\n        specified.\n\n        Relative paths (including `..`) may be used, as long as the path does not ascend further\n        than the build root.\n        \"\"\"\n    )\n\n\nclass AdhocToolOutputDirectoriesField(StringSequenceField):\n    alias: ClassVar[str] = \"output_directories\"\n    required = False\n    default = ()\n    help = help_text(\n        lambda: f\"\"\"\n        Specify full directories (including recursive descendants) of output to capture, relative\n        to the value of `{AdhocToolWorkdirField.alias}`.\n\n        For individual files, use `{AdhocToolOutputFilesField.alias}`. At least one of\n        `{AdhocToolOutputFilesField.alias}` and`{AdhocToolOutputDirectoriesField.alias}` must be\n        specified.\n\n        Relative paths (including `..`) may be used, as long as the path does not ascend further\n        than the build root.\n        \"\"\"\n    )\n\n\nclass AdhocToolOutputDependenciesField(AdhocToolDependenciesField):\n    supports_transitive_excludes = True\n    alias: ClassVar[str] = \"output_dependencies\"\n\n    help = help_text(\n        lambda: \"\"\"\n        Any dependencies that need to be present (as transitive dependencies) whenever the outputs\n        of this target are consumed (including as dependencies).\n        \"\"\"\n    )\n\n\nclass AdhocToolExecutionDependenciesField(SpecialCasedDependencies):\n    alias: ClassVar[str] = \"execution_dependencies\"\n    required = False\n    default = None\n\n    help = help_text(\n        lambda: f\"\"\"\n        The execution dependencies for this command.\n\n        Dependencies specified here are those required to make the command complete successfully\n        (e.g. file inputs, packages compiled from other targets, etc), but NOT required to make\n        the outputs of the command useful. Dependencies that are required to use the outputs\n        produced by this command should be specified using the\n        `{AdhocToolOutputDependenciesField.alias}` field.\n\n        If this field is specified, dependencies from `{AdhocToolOutputDependenciesField.alias}`\n        will not be added to the execution sandbox.\n        \"\"\"\n    )\n\n\nclass AdhocToolRunnableDependenciesField(SpecialCasedDependencies):\n    alias: ClassVar[str] = \"runnable_dependencies\"\n    required = False\n    default = None\n\n    help = help_text(\n        lambda: f\"\"\"\n        The execution dependencies for this command.\n\n        Dependencies specified here are those required to exist on the `PATH` to make the command\n        complete successfully (interpreters specified in a `#!` command, etc). Note that these\n        dependencies will be made available on the `PATH` with the name of the target.\n\n        See also `{AdhocToolOutputDependenciesField.alias}` and\n        `{AdhocToolExecutionDependenciesField.alias}.\n        \"\"\"\n    )\n\n\nclass AdhocToolSourcesField(MultipleSourcesField):\n    # We solely register this field for codegen to work.\n    alias: ClassVar[str] = \"_sources\"\n    uses_source_roots = False\n    expected_num_files = 0\n\n\nclass AdhocToolArgumentsField(StringSequenceField):\n    alias: ClassVar[str] = \"args\"\n    default = ()\n    help = help_text(\n        lambda: f\"Extra arguments to pass into the `{AdhocToolRunnableField.alias}` field.\"\n    )\n\n\nclass AdhocToolStdoutFilenameField(StringField):\n    alias: ClassVar[str] = \"stdout\"\n    default = None\n    help = help_text(\n        lambda: f\"\"\"\n        A filename to capture the contents of `stdout` to. Relative paths are\n        relative to the value of `{AdhocToolWorkdirField.alias}`, absolute paths\n        start at the build root.\n        \"\"\"\n    )\n\n\nclass AdhocToolStderrFilenameField(StringField):\n    alias: ClassVar[str] = \"stderr\"\n    default = None\n    help = help_text(\n        lambda: f\"\"\"\n        A filename to capture the contents of `stderr` to. Relative paths are\n        relative to the value of `{AdhocToolWorkdirField.alias}`, absolute paths\n        start at the build root.\n        \"\"\"\n    )\n\n\nclass AdhocToolTimeoutField(IntField):\n    alias: ClassVar[str] = \"timeout\"\n    default = 30\n    help = \"Command execution timeout (in seconds).\"\n    valid_numbers = ValidNumbers.positive_only\n\n\nclass AdhocToolExtraEnvVarsField(StringSequenceField):\n    alias: ClassVar[str] = \"extra_env_vars\"\n    help = help_text(\n        \"\"\"\n        Additional environment variables to provide to the process.\n\n        Entries are strings in the form `ENV_VAR=value` to use explicitly; or just\n        `ENV_VAR` to copy the value of a variable in Pants's own environment.\n        \"\"\"\n    )\n\n\nclass AdhocToolLogOutputField(BoolField):\n    alias: ClassVar[str] = \"log_output\"\n    default = False\n    help = \"Set to true if you want the output logged to the console.\"\n\n\nclass AdhocToolWorkdirField(StringField):\n    alias: ClassVar[str] = \"workdir\"\n    default = \".\"\n    help = help_text(\n        \"\"\"\n        Sets the working directory for the process.\n\n        Values are relative to the build root, except in the following cases:\n\n        * `.` specifies the location of the `BUILD` file.\n        * Values beginning with `./` are relative to the location of the `BUILD` file.\n        * `/` or the empty string specifies the build root.\n        * Values beginning with `/` are also relative to the build root.\n        \"\"\"\n    )\n\n\nclass AdhocToolOutputRootDirField(StringField):\n    alias: ClassVar[str] = \"root_output_directory\"\n    default = \"/\"\n    help = help_text(\n        \"\"\"Adjusts the location of files output by this target, when consumed as a dependency.\n\n        Values are relative to the build root, except in the following cases:\n\n        * `.` specifies the location of the `BUILD` file.\n        * Values beginning with `./` are relative to the location of the `BUILD` file.\n        * `/` or the empty string specifies the build root.\n        * Values beginning with `/` are also relative to the build root.\n        \"\"\"\n    )\n\n\nclass AdhocToolTarget(Target):\n    alias: ClassVar[str] = \"adhoc_tool\"\n    core_fields = (\n        *COMMON_TARGET_FIELDS,\n        AdhocToolRunnableField,\n        AdhocToolArgumentsField,\n        AdhocToolExecutionDependenciesField,\n        AdhocToolOutputDependenciesField,\n        AdhocToolRunnableDependenciesField,\n        AdhocToolLogOutputField,\n        AdhocToolOutputFilesField,\n        AdhocToolOutputDirectoriesField,\n        AdhocToolSourcesField,\n        AdhocToolTimeoutField,\n        AdhocToolExtraEnvVarsField,\n        AdhocToolWorkdirField,\n        AdhocToolOutputRootDirField,\n        AdhocToolStdoutFilenameField,\n        AdhocToolStderrFilenameField,\n        EnvironmentField,\n    )\n    help = help_text(\n        lambda: f\"\"\"\n        Execute any runnable target for its side effects.\n\n        Example BUILD file:\n\n            {AdhocToolTarget.alias}(\n                {AdhocToolRunnableField.alias}=\":python_source\",\n                {AdhocToolArgumentsField.alias}=[\"\"],\n                {AdhocToolExecutionDependenciesField.alias}=[\":scripts\"],\n                {AdhocToolOutputDirectoriesField.alias}=[\"logs/my-script.log\"],\n                {AdhocToolOutputFilesField.alias}=[\"results/\"],\n            )\n\n            shell_sources(name=\"scripts\")\n        \"\"\"\n    )\n\n\n# ---\n# `system_binary` target\n# ---\n\n\nclass SystemBinaryNameField(StringField):\n    alias: ClassVar[str] = \"binary_name\"\n    required = True\n    help = \"The name of the binary to find.\"\n\n\nclass SystemBinaryExtraSearchPathsField(StringSequenceField):\n    alias: ClassVar[str] = \"extra_search_paths\"\n    default = ()\n    help = help_text(\n        \"\"\"\n        Extra search paths to look for the binary. These take priority over Pants' default\n        search paths.\n        \"\"\"\n    )\n\n\nclass SystemBinaryFingerprintPattern(StringField):\n    alias: ClassVar[str] = \"fingerprint\"\n    required = False\n    default = None\n    help = help_text(\n        \"\"\"\n        A regular expression which will be used to match the fingerprint outputs from\n        candidate binaries found during the search process.\n        \"\"\"\n    )\n\n\nclass SystemBinaryFingerprintArgsField(StringSequenceField):\n    alias: ClassVar[str] = \"fingerprint_args\"\n    default = ()\n    help = help_text(\n        \"Specifies arguments that will be used to run the binary during the search process.\"\n    )\n\n\nclass SystemBinaryFingerprintDependenciesField(AdhocToolRunnableDependenciesField):\n    alias: ClassVar[str] = \"fingerprint_dependencies\"\n    help = help_text(\n        \"\"\"\n        Specifies any runnable dependencies that need to be available on the `PATH` when the binary\n        is run, so that the search process may complete successfully. The name of the target must\n        be the name of the runnable dependency that is called by this binary.\n        \"\"\"\n    )\n\n\nclass SystemBinaryTarget(Target):\n    alias: ClassVar[str] = \"system_binary\"\n    core_fields = (\n        *COMMON_TARGET_FIELDS,\n        SystemBinaryNameField,\n        SystemBinaryExtraSearchPathsField,\n        SystemBinaryFingerprintPattern,\n        SystemBinaryFingerprintArgsField,\n        SystemBinaryFingerprintDependenciesField,\n    )\n    help = help_text(\n        lambda: f\"\"\"\n        A system binary that can be run with `pants run` or consumed by `{AdhocToolTarget.alias}`.\n\n        Pants will search for binaries with name `{SystemBinaryNameField.alias}` in the search\n        paths provided, as well as default search paths. If\n        `{SystemBinaryFingerprintPattern.alias}` is specified, each binary that is located will be\n        executed with the arguments from `{SystemBinaryFingerprintArgsField.alias}`. Any binaries\n        whose output does not match the pattern will be excluded.\n\n        The first non-excluded binary will be the one that is resolved.\n        \"\"\"\n    )\n", "path": "src/python/pants/backend/adhoc/target_types.py"}], "after_files": [{"content": "# Copyright 2023 Pants project contributors (see CONTRIBUTORS.md).\n# Licensed under the Apache License, Version 2.0 (see LICENSE).\n\nfrom __future__ import annotations\n\nfrom typing import ClassVar\n\nfrom pants.core.util_rules.environments import EnvironmentField\nfrom pants.engine.target import (\n    COMMON_TARGET_FIELDS,\n    BoolField,\n    Dependencies,\n    IntField,\n    MultipleSourcesField,\n    SpecialCasedDependencies,\n    StringField,\n    StringSequenceField,\n    Target,\n    ValidNumbers,\n)\nfrom pants.util.strutil import help_text\n\n\nclass AdhocToolDependenciesField(Dependencies):\n    pass\n\n\nclass AdhocToolRunnableField(StringField):\n    alias: ClassVar[str] = \"runnable\"\n    required = True\n    help = help_text(\n        lambda: f\"\"\"\n        Address to a target that can be invoked by the `run` goal (and does not set\n        `run_in_sandbox_behavior=NOT_SUPPORTED`). This will be executed along with any arguments\n        specified by `{AdhocToolArgumentsField.alias}`, in a sandbox with that target's transitive\n        dependencies, along with the transitive dependencies specified by\n        `{AdhocToolExecutionDependenciesField.alias}`.\n        \"\"\"\n    )\n\n\nclass AdhocToolOutputFilesField(StringSequenceField):\n    alias: ClassVar[str] = \"output_files\"\n    required = False\n    default = ()\n    help = help_text(\n        lambda: f\"\"\"\n        Specify the output files to capture, relative to the value of\n        `{AdhocToolWorkdirField.alias}`.\n\n        For directories, use `{AdhocToolOutputDirectoriesField.alias}`. At least one of\n        `{AdhocToolOutputFilesField.alias}` and`{AdhocToolOutputDirectoriesField.alias}` must be\n        specified.\n\n        Relative paths (including `..`) may be used, as long as the path does not ascend further\n        than the build root.\n        \"\"\"\n    )\n\n\nclass AdhocToolOutputDirectoriesField(StringSequenceField):\n    alias: ClassVar[str] = \"output_directories\"\n    required = False\n    default = ()\n    help = help_text(\n        lambda: f\"\"\"\n        Specify full directories (including recursive descendants) of output to capture, relative\n        to the value of `{AdhocToolWorkdirField.alias}`.\n\n        For individual files, use `{AdhocToolOutputFilesField.alias}`. At least one of\n        `{AdhocToolOutputFilesField.alias}` and`{AdhocToolOutputDirectoriesField.alias}` must be\n        specified.\n\n        Relative paths (including `..`) may be used, as long as the path does not ascend further\n        than the build root.\n        \"\"\"\n    )\n\n\nclass AdhocToolOutputDependenciesField(AdhocToolDependenciesField):\n    supports_transitive_excludes = True\n    alias: ClassVar[str] = \"output_dependencies\"\n\n    help = help_text(\n        lambda: \"\"\"\n        Any dependencies that need to be present (as transitive dependencies) whenever the outputs\n        of this target are consumed (including as dependencies).\n        \"\"\"\n    )\n\n\nclass AdhocToolExecutionDependenciesField(SpecialCasedDependencies):\n    alias: ClassVar[str] = \"execution_dependencies\"\n    required = False\n    default = None\n\n    help = help_text(\n        lambda: f\"\"\"\n        The execution dependencies for this command.\n\n        Dependencies specified here are those required to make the command complete successfully\n        (e.g. file inputs, packages compiled from other targets, etc), but NOT required to make\n        the outputs of the command useful. Dependencies that are required to use the outputs\n        produced by this command should be specified using the\n        `{AdhocToolOutputDependenciesField.alias}` field.\n\n        If this field is specified, dependencies from `{AdhocToolOutputDependenciesField.alias}`\n        will not be added to the execution sandbox.\n        \"\"\"\n    )\n\n\nclass AdhocToolRunnableDependenciesField(SpecialCasedDependencies):\n    alias: ClassVar[str] = \"runnable_dependencies\"\n    required = False\n    default = None\n\n    help = help_text(\n        lambda: f\"\"\"\n        The execution dependencies for this command.\n\n        Dependencies specified here are those required to exist on the `PATH` to make the command\n        complete successfully (interpreters specified in a `#!` command, etc). Note that these\n        dependencies will be made available on the `PATH` with the name of the target.\n\n        See also `{AdhocToolOutputDependenciesField.alias}` and\n        `{AdhocToolExecutionDependenciesField.alias}.\n        \"\"\"\n    )\n\n\nclass AdhocToolSourcesField(MultipleSourcesField):\n    # We solely register this field for codegen to work.\n    alias: ClassVar[str] = \"_sources\"\n    uses_source_roots = False\n    expected_num_files = 0\n\n\nclass AdhocToolArgumentsField(StringSequenceField):\n    alias: ClassVar[str] = \"args\"\n    default = ()\n    help = help_text(\n        lambda: f\"Extra arguments to pass into the `{AdhocToolRunnableField.alias}` field.\"\n    )\n\n\nclass AdhocToolStdoutFilenameField(StringField):\n    alias: ClassVar[str] = \"stdout\"\n    default = None\n    help = help_text(\n        lambda: f\"\"\"\n        A filename to capture the contents of `stdout` to. Relative paths are\n        relative to the value of `{AdhocToolWorkdirField.alias}`, absolute paths\n        start at the build root.\n        \"\"\"\n    )\n\n\nclass AdhocToolStderrFilenameField(StringField):\n    alias: ClassVar[str] = \"stderr\"\n    default = None\n    help = help_text(\n        lambda: f\"\"\"\n        A filename to capture the contents of `stderr` to. Relative paths are\n        relative to the value of `{AdhocToolWorkdirField.alias}`, absolute paths\n        start at the build root.\n        \"\"\"\n    )\n\n\nclass AdhocToolTimeoutField(IntField):\n    alias: ClassVar[str] = \"timeout\"\n    default = 30\n    help = \"Command execution timeout (in seconds).\"\n    valid_numbers = ValidNumbers.positive_only\n\n\nclass AdhocToolExtraEnvVarsField(StringSequenceField):\n    alias: ClassVar[str] = \"extra_env_vars\"\n    help = help_text(\n        \"\"\"\n        Additional environment variables to provide to the process.\n\n        Entries are strings in the form `ENV_VAR=value` to use explicitly; or just\n        `ENV_VAR` to copy the value of a variable in Pants's own environment.\n        \"\"\"\n    )\n\n\nclass AdhocToolLogOutputField(BoolField):\n    alias: ClassVar[str] = \"log_output\"\n    default = False\n    help = \"Set to true if you want the output logged to the console.\"\n\n\nclass AdhocToolWorkdirField(StringField):\n    alias: ClassVar[str] = \"workdir\"\n    default = \".\"\n    help = help_text(\n        \"\"\"\n        Sets the working directory for the process.\n\n        Values are relative to the build root, except in the following cases:\n\n        * `.` specifies the location of the `BUILD` file.\n        * Values beginning with `./` are relative to the location of the `BUILD` file.\n        * `/` or the empty string specifies the build root.\n        * Values beginning with `/` are also relative to the build root.\n        \"\"\"\n    )\n\n\nclass AdhocToolOutputRootDirField(StringField):\n    alias: ClassVar[str] = \"root_output_directory\"\n    default = \"/\"\n    help = help_text(\n        \"\"\"Adjusts the location of files output by this target, when consumed as a dependency.\n\n        Values are relative to the build root, except in the following cases:\n\n        * `.` specifies the location of the `BUILD` file.\n        * Values beginning with `./` are relative to the location of the `BUILD` file.\n        * `/` or the empty string specifies the build root.\n        * Values beginning with `/` are also relative to the build root.\n        \"\"\"\n    )\n\n\nclass AdhocToolTarget(Target):\n    alias: ClassVar[str] = \"adhoc_tool\"\n    core_fields = (\n        *COMMON_TARGET_FIELDS,\n        AdhocToolRunnableField,\n        AdhocToolArgumentsField,\n        AdhocToolExecutionDependenciesField,\n        AdhocToolOutputDependenciesField,\n        AdhocToolRunnableDependenciesField,\n        AdhocToolLogOutputField,\n        AdhocToolOutputFilesField,\n        AdhocToolOutputDirectoriesField,\n        AdhocToolSourcesField,\n        AdhocToolTimeoutField,\n        AdhocToolExtraEnvVarsField,\n        AdhocToolWorkdirField,\n        AdhocToolOutputRootDirField,\n        AdhocToolStdoutFilenameField,\n        AdhocToolStderrFilenameField,\n        EnvironmentField,\n    )\n    help = help_text(\n        lambda: f\"\"\"\n        Execute any runnable target for its side effects.\n\n        Example BUILD file:\n\n            {AdhocToolTarget.alias}(\n                {AdhocToolRunnableField.alias}=\":python_source\",\n                {AdhocToolArgumentsField.alias}=[\"\"],\n                {AdhocToolExecutionDependenciesField.alias}=[\":scripts\"],\n                {AdhocToolOutputDirectoriesField.alias}=[\"results/\"],\n                {AdhocToolOutputFilesField.alias}=[\"logs/my-script.log\"],\n            )\n\n            shell_sources(name=\"scripts\")\n        \"\"\"\n    )\n\n\n# ---\n# `system_binary` target\n# ---\n\n\nclass SystemBinaryNameField(StringField):\n    alias: ClassVar[str] = \"binary_name\"\n    required = True\n    help = \"The name of the binary to find.\"\n\n\nclass SystemBinaryExtraSearchPathsField(StringSequenceField):\n    alias: ClassVar[str] = \"extra_search_paths\"\n    default = ()\n    help = help_text(\n        \"\"\"\n        Extra search paths to look for the binary. These take priority over Pants' default\n        search paths.\n        \"\"\"\n    )\n\n\nclass SystemBinaryFingerprintPattern(StringField):\n    alias: ClassVar[str] = \"fingerprint\"\n    required = False\n    default = None\n    help = help_text(\n        \"\"\"\n        A regular expression which will be used to match the fingerprint outputs from\n        candidate binaries found during the search process.\n        \"\"\"\n    )\n\n\nclass SystemBinaryFingerprintArgsField(StringSequenceField):\n    alias: ClassVar[str] = \"fingerprint_args\"\n    default = ()\n    help = help_text(\n        \"Specifies arguments that will be used to run the binary during the search process.\"\n    )\n\n\nclass SystemBinaryFingerprintDependenciesField(AdhocToolRunnableDependenciesField):\n    alias: ClassVar[str] = \"fingerprint_dependencies\"\n    help = help_text(\n        \"\"\"\n        Specifies any runnable dependencies that need to be available on the `PATH` when the binary\n        is run, so that the search process may complete successfully. The name of the target must\n        be the name of the runnable dependency that is called by this binary.\n        \"\"\"\n    )\n\n\nclass SystemBinaryTarget(Target):\n    alias: ClassVar[str] = \"system_binary\"\n    core_fields = (\n        *COMMON_TARGET_FIELDS,\n        SystemBinaryNameField,\n        SystemBinaryExtraSearchPathsField,\n        SystemBinaryFingerprintPattern,\n        SystemBinaryFingerprintArgsField,\n        SystemBinaryFingerprintDependenciesField,\n    )\n    help = help_text(\n        lambda: f\"\"\"\n        A system binary that can be run with `pants run` or consumed by `{AdhocToolTarget.alias}`.\n\n        Pants will search for binaries with name `{SystemBinaryNameField.alias}` in the search\n        paths provided, as well as default search paths. If\n        `{SystemBinaryFingerprintPattern.alias}` is specified, each binary that is located will be\n        executed with the arguments from `{SystemBinaryFingerprintArgsField.alias}`. Any binaries\n        whose output does not match the pattern will be excluded.\n\n        The first non-excluded binary will be the one that is resolved.\n        \"\"\"\n    )\n", "path": "src/python/pants/backend/adhoc/target_types.py"}]}