I'm trying to generate API documentation, which requires several steps: 1. Run the Python app to export the schema: create a PEX file, and run it via

experimental_shell_command

capturing the schema as a file 2. Run the doc generator on the schema to create a .html file: install (via NPM) the doc generator and run it on the output of above, all via

experimental_shell_command

3. Package the .html file into an archive:

relocated_files

+

archive

This mostly works, except I'm finding step 1 is... weird. The targets I'm using are, something like:

# path/to/dir/BUILD
pex_binary(name="print-schema", ...)
experimental_shell_command(
    name="schema",
    command="../../../path.to.dir/print-schema.pex > schema.graphql",
    dependencies=[":print-schema"],
    tools=["python3.9", "bash"],
    outputs=["schema.graphql"],
)

Questions: 1. Is it possible to have

experiemental_shell_command

run an in-repo Python file directly, pulling in appropriate internal and external dependencies? It'd be nifty to not need to set up the PEX file if we didn't need to 2. Is

tools=["python3.9", ...]

the right way to pull in Python to run the PEX? I have a feeling that it'll just be just pulling in whatever

python3.9

executable happens to be on PATH (if there is one), rather than the interpreter Pants has gone to great efforts to choose for 'normal' `run`/`test` etc. of Python targets? 3. Is there a better way to refer to the root of the repo/find the dependency pulled into the

experiemental_shell_command

, beyond just

..

the right number of times?

Good questions! I’m hoping to take a closer look at

experimental_shell_command

so this is a helpful use-case

The equivalent script (with a venv and node modules set up “normally”, e.g. via poetry and npm) would be something like:

python script/print-schema.py > schema.graphql # step 1
npx spectaql config.yaml # step 2
zip … # step 3

A (codegen?) plug-in sounds like it might indeed handle step 1 smoothly, but I'm not sure I could sell my team (or even myself) on replacing a single one-off line of shell with dozens-to-hundreds of lines of Python. Based on https://www.pantsbuild.org/docs/plugins-overview, we might also be signing up for additional maintenance/upgrade burden due to lack of stability (which, to be clear, I totally support: stable and powerful APIs are nice as a consumer but a pain as a maintainer 😅 ).

Yeah, this sounds like a good use case for

experimental_shell_command

I'm being a squeaky wheel (thanks for tolerating it!) and filed issues about those questions: 1/2 https://github.com/pantsbuild/pants/issues/17405 (arguably should be separate, but seems somewhat related) 3 https://github.com/pantsbuild/pants/issues/17404 I found

{chroot}

is substituted (🎉)

Thanks for filing these!