playground/AGENTS.md

• Every script is self contained.

• Do not be chatty, do not summarize the code afterwards.

• Use #!/usr/bin/env -S uv run --script as the shebang line.

• Add dependencies under the shebang line as

# /// script
# dependencies = [list of external dependencies as json array]
# ///

and keep them updated as the code changes.

• Keep comments to minimum
• Use uv for package management.
• Use logging instead of print statements. Use logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s: %(message)s") for configuration.
• Use argparse for command-line arguments, keep argument parsing in a func called parse_args() -> argparse.Namespace, which gets called from main. Use argparse.ArgumentDefaultsHelpFormatter for the formatter class.
• Use pathlib.Path for file operations. When the CLI args include a path, set its type=Path
• Place imports at the top of the file.
• Use httpx for HTTP requests. Do not use async.
• Always add type annotations to function signatures, prefer built-in types, e.g. list[str] over typing module types when possible.
• Prefer kwargs calling style for function calls, e.g. func(arg1=value1, arg2=value2) instead of func(value1, value2).
• Use Path.cwd() for the current working directory.
• Prefer os.getenv over os.environ.get for environment variables.
• Use subprocess.run for running shell commands, prefer check=True to raise an error on failure.
• Use tempfile.TemporaryDirectory() for temporary directories.
• Do not shorten parameter names unnecessarily, unless it's an idiomatic abbreviation.
• Use f-strings for string formatting.
• When calling an external command, use the long form of the arguments, e.g. --output instead of -o.

Testing

• Use pytest for tests and name test files <script_name>_test.py.
• Make test scripts self contained like docker_refresh_test.py: use the same uv shebang, declare pytest and all required external dependencies in inline script metadata, and run pytest.main(args=[str(Path(__file__).resolve()), *sys.argv[1:]]) via sys.exit under the __main__ guard so pytest CLI arguments are forwarded.