@bitter-ability-32190 there's a new subsystem

preamble

which isn't yet used it seems. 🧵

It's certainly used. We're using it to stamp and to check for copyright headers. (Try it, remove one and run lint or fmt)

Right. How is it possible that you pass a string when it's expecting a dict? :/

Also, don't forget that an invalid config will make pants error (unless told otherwise) so we can be pretty sure it's valid 😉

The

"@…

is significant here…

Yeah sorry, I was replying while rocking my son 😅

ah I am doing such a terrible job explaining what is it that concerns me! 😄 I am familiar with the

@

notation; that's what's used in the https://www.pantsbuild.org/docs/reference-regex-lint as well. It's the type of the option as seen by the Pants

help-all

goal:

{
          "choices": null,
          "comma_separated_choices": null,
          "comma_separated_display_args": "--preamble-template-by-globs=\"{'key1': val1, 'key2': val2, ...}\"",
          "config_key": "template_by_globs",
          "default": {},
          "deprecated_message": null,
          "deprecation_active": false,
          "display_args": [
            "--preamble-template-by-globs=\"{'key1': val1, 'key2': val2, ...}\""
          ],
          "env_var": "PANTS_PREAMBLE_TEMPLATE_BY_GLOBS",
          "help": "Which preamble template to use based on the path globs (relative to the build root).\n\nExample:\n\n    {\n        '*.rs': '// Copyright (c) $year\n// Line 2 '\n        '*.py:!__init__.py': '# Copyright (c) $year\n# Line 2 ',\n    }\n\nIt might be helpful to load this config from a JSON or YAML file. To do that, set `[preamble].config = '@path/to/config.yaml'`, for example.",
          "removal_hint": null,
          "removal_version": null,
          "scoped_cmd_line_args": [
            "--preamble-template-by-globs"
          ],
          "target_field_name": null,
          "typ": "dict",
          "unscoped_cmd_line_args": [
            "--template-by-globs"
          ],

As far as JSON schema concerned, the property is supposed to be an object (the Python

dict

). But clearly it can also be a string (with the

@

) that will load the data from a file turning it into a

dict

at runtime

Ah… yes, seems the

fromfile

property of this option is not reflected here, as not all options support it we can’t even assume that is an option for all.. er, options 😉

right, but is there anything in the source code that can tell us (so that we could mark an option somehow in the

all-help

output) that an option could be of multiple types (a dict and a string in this case)? 😕

This case is special. I believe it's just dict options with fromfile that also allows strings 🤔

there’s a way to include the support for fromfile syntax in the all-help info output…

right, I see a handful of these e.g. https://github.com/pantsbuild/pants/blob/3bdbb7d496b347418b8b1e77e55cf80d6e15a7c3/src/python/pants/backend/docker/subsystems/docker_options.py#L79-L118

--preamble-template-by-globs="{'key1': val1, 'key2': val2, ...}"
  PANTS_PREAMBLE_TEMPLATE_BY_GLOBS
  template_by_globs
      default: {}
      current value: {
          "**/*.py:!**/__init__.py:**/BUILD:**/BUILD.*": "# Copyright $year Pants project contributors (see CONTRIBUTORS.md).\n# Licensed under the Apache License, Version 2.0 (see LICENSE).\n",
          "**/*.rs": "// Copyright $year Pants project contributors (see CONTRIBUTORS.md).\n// Licensed under the Apache License, Version 2.0 (see LICENSE).\n"
      } (from pants.toml)
-- FROMFILE: True
      Which preamble template to use based on the path globs (relative to the build root).

      Example:

diff --git a/src/python/pants/help/help_formatter.py b/src/python/pants/help/help_formatter.py
index 699a7bb2d..70a38f80b 100644
--- a/src/python/pants/help/help_formatter.py
+++ b/src/python/pants/help/help_formatter.py
@@ -148,6 +148,7 @@ class HelpFormatter(MaybeColor):
             *default_lines,
             *curr_value_lines,
             *value_derivation_lines,
+            f"-- FROMFILE: {ohi.fromfile}",
             *deprecated_lines,
             *description_lines,
         ]
diff --git a/src/python/pants/help/help_info_extracter.py b/src/python/pants/help/help_info_extracter.py
index e5a235a41..da386d90c 100644
--- a/src/python/pants/help/help_info_extracter.py
+++ b/src/python/pants/help/help_info_extracter.py
@@ -115,7 +115,7 @@ class OptionHelpInfo:
     choices: tuple[str, ...] | None
     comma_separated_choices: str | None
     value_history: OptionValueHistory | None
-
+    fromfile: bool

 @dataclass(frozen=True)
 class OptionScopeHelpInfo:
@@ -974,6 +974,8 @@ class HelpInfoExtracter:
         target_field_name = f"{self._scope_prefix}_{option_field_name_for(args)}".replace("-", "_")
         environment_aware = kwargs.get("environment_aware") is True

+        fromfile = kwargs.get("fromfile", False)
+
         ret = OptionHelpInfo(
             display_args=tuple(display_args),
             comma_separated_display_args=", ".join(display_args),
@@ -992,5 +994,6 @@ class HelpInfoExtracter:
             choices=choices,
             comma_separated_choices=None if choices is None else ", ".join(choices),
             value_history=None,
+            fromfile=fromfile,
         )
         return ret

Oh although lists and dicta also allow the +/- prefix

yes, indeed! • The special Pants only

.add

syntax as in:

extra_requirements.add = [
  "mypy-typing-asserts",
  "strawberry-graphql>=0.95.1,<0.96",
]

is considered a violation:

{"add":["mypy-typing-asserts","strawberry-graphql>=0.95.1,<0.96"]} is not of type "array"

So using .add isn't a toml violation, we just need the schema to be smarter

sorry, I meant schema violation, not TOML specs 🙂