A lightweight, dependency-free tool to manage your scripts directly from pyproject.toml
Project description
Tomlscript
A lightweight, dependency-free tool to manage your scripts directly from pyproject.toml
Usage
# alias tom = "uvx tomlscript"
# List commands
tom
# Run a command
tom dev --port 8000
tom publish
tom pyi
Example Configuration
# pyproject.toml
[tool.tomlscript]
# Start dev server (default on port 5001)
dev = "uv run uvicorn --port {port:5001} superapp.main:app --reload"
# Publish to PyPI
publish = "rm -rf dist && uv build && uvx twine upload dist/*"
# Generate pyi stubs (python function)
pyi = "mypackage.typing:generate_pyi"
Installation
pip install tomlscript
uv add --dev tomlscript
Running Commands
Directly
# alias tom = "uvx tomlscript"
tom
tom function
tom function arg1 --k2 v2
Using uv / uvx
uvx tomlscript
uvx tomlscript function arg1 --k2 v2
uv run tom
uv run tom function arg1 --k2 v2
Configuration
Basic
Commands are defined in the [tool.tomlscript]
section of the pyproject.toml
file.
The comment above a command serves as its documentation.
[tool.tomlscript]
# Linter check <= this line is the documentation for `lint` command
lint = "uv run ruff check"
Commands can be multi-line scripts:
[tool.tomlscript]
# Lint and test
test = """
uv run ruff check
uv run pytest
"""
You can define commands with arguments using the {arg}
or {arg:default}
syntax:
[tool.tomlscript]
# Start dev server (default on port 5001)
dev = "uv run uvicorn --port {port:5001} superapp.main:app --reload"
The above command can be used as
tom dev # run on port 5001
tom dev --port 8000 # run on port 8000
You can also define commands as Python functions using the module:function
syntax:
[tool.tomlscript]
# Run python function run2 from [tests.myscript module](./tests/myscript.py)
py_example = "tests.myscript:run2"
Arguments can be passed to Python functions:
tom py_example --name Paul
For complex shell scripts, you can use the [tool.tomlscript.source]
section. Functions defined here can be reused across multiple commands:
[tool.tomlscript]
build = "clean && uv build"
source = """
# Clean up
clean() {
say_ "Cleaning up..."
rm -rf dist .eggs *.egg-info build
}
# Functions ending with _ are hidden from the command list
say_() {
echo "$1"
}
"""
Full example
For real world examples, see pyproject.toml file.
[tool.tomlscript]
# This line is the documentation for `hello` function
hello = 'say_ "Hello world"'
# Run python function run2 from tests.myscript module
run2 = "tests.myscript:run2"
# A command with arguments and default values
dev = "uv run uvicorn --port {port:5001} superapp.main:app"
# Lint and test
test = """
uv run ruff check
uv run pytest --inline-snapshot=review
"""
# Define multiple functions in the `[tool.tomlscript.source]` sections
source = """
# Documentation for `doc` function
doc() {
say_ "Rendering documentation..."
}
# Functions ending with _ are hidden from the command list
say_() {
echo "$1"
}
"""
Development
# Install dependencies
uv sync
alias tom="uv run tom"
# List the commands
tom
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for tomlscript-0.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d76059987048e0e68a1b3d08701874a3b1432dee41055a025224be1466a23b0c |
|
MD5 | 133a8af61e33f1a2bad305699d253177 |
|
BLAKE2b-256 | 7dd1360083a6a727e91078b8f08d0c888336e373c02013febf5ebe10b45454d2 |