Python Tools Scripts

Common errors

• ModuleNotFoundError: No module named 'ptscripts'

  cause The `ptscripts` module was not found. This typically happens if `python-tools-scripts` was not installed, or if the import statement is incorrect (e.g., trying to use `python_tools_scripts`).
  fix Ensure the library is installed with `pip install python-tools-scripts`. Verify that the import statement is `from ptscripts import ...`.

• Error: No such command 'my_command_group'

  cause The `tools` CLI could not find the specified command group or command. This usually means the script defining the command was not correctly placed in the `<repo-root>/tools` directory, or it wasn't imported in `tools/__init__.py`.
  fix Check that your `tools` directory is at the repository root, contains an `__init__.py` file, and that your script file (e.g., `my_script.py`) is imported within `tools/__init__.py`. Also, ensure the `@command_group` decorator has the correct `name` argument matching the command you're trying to execute.

Warnings

• gotcha The PyPI package name is `python-tools-scripts`, but the Python import name for its modules is `ptscripts`. Attempting to import directly from `python_tools_scripts` will fail.
  Fix: Always use `from ptscripts import ...` for imports after installing `python-tools-scripts`.
• gotcha For scripts to be discoverable by the `tools` CLI, they must reside within a Python package named `tools` at the root of your repository (e.g., `<repo-root>/tools/__init__.py`, `<repo-root>/tools/your_script.py`). Furthermore, the individual script files must be imported within `tools/__init__.py` to be loaded.
  Fix: Create a `tools` directory at your project root. Add an empty `__init__.py` file to make it a package. For each script `my_script.py` in `tools/`, add `from . import my_script` to `tools/__init__.py`.

Install

• pip install python-tools-scripts Install with pip

Imports

• Context

  from ptscripts import Context

• command_group

  from ptscripts import command_group

• command
  wrong:

  import python_tools_scripts

  correct:

  from ptscripts import command

  The installed package is `python-tools-scripts`, but the actual import module is `ptscripts`. Importing `python_tools_scripts` directly will not provide the intended API.

Quickstart

To use `python-tools-scripts`, create a `tools` directory in your repository's root and ensure it's a Python package (contains `__init__.py`). Define your CLI commands within Python files inside this `tools` package using `@command_group` and `@command` decorators from `ptscripts`. These scripts will then be discoverable and executable via the `tools` command-line utility. Ensure you import your script files into `tools/__init__.py` for them to be picked up.

import os
from ptscripts import command_group, Context, command

# --- File: <repo-root>/tools/__init__.py ---
# This file makes the 'tools' directory a Python package.
# No specific content is required here for basic discovery, but it can import other scripts.

# --- File: <repo-root>/tools/my_scripts.py ---
# Define a command group
my_group = command_group(name="hello", help="Basic greeting commands")

@my_group.command(
    arguments={
        "name": {"help": "The name to greet", "default": "World"}
    }
)
def greet(ctx: Context, name: str):
    """Greets the specified name."""
    print(f"Hello, {name} from {ctx.command_path}!")

@my_group.command()
def goodbye(ctx: Context):
    """Says goodbye."""
    print(f"Goodbye from {ctx.command_path}!")

# To make 'my_scripts.py' discoverable by the 'tools' CLI,
# ensure it's imported in '<repo-root>/tools/__init__.py'.
# E.g., 'from . import my_scripts'

# --- How to run (from your repository root) ---
# Make sure to run 'pip install python-tools-scripts' first.
# > tools hello greet --name Alice
# > tools hello goodbye