Documentation Index
Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
Use this file to discover all available pages before exploring further.
Python SDK
RBS provides first-class Python support with hermetic toolchains, automatic dependency resolution, test coverage enforcement, and linting — all without requiring pip, venv, or any system-installed Python.
Setup
Register a Python toolchain in your WORKSPACE.rbs. RBS automatically downloads and manages the interpreter.
load("@rbs//python/toolchain.rbs", "python_toolchain")
python_toolchain(name = "python3", version = "3.12")
Dependencies
Define external packages using py_repository. RBS resolves and caches them hermetically.
load("@rbs//python/dependencies.rbs", "py_repository")
py_repository(name = "django_repo", package = "django", version = "5.0.1")
py_repository(name = "requests_repo", package = "requests", version = "2.32.4")
py_repository(name = "gunicorn_repo", package = "gunicorn", version = "23.0.0")
Linting
Register Python linters (Black, isort, Flake8, Ruff) for workspace-wide use:
load("@rbs//python/lint.rbs", "register_python_linters")
register_python_linters()
Rules
py_library
Creates a reusable Python library that other targets can depend on.
load("@rbs//python/rules.rbs", "py_library")
py_library(
name = "calculator",
srcs = ["src/calculator.py"],
)
py_library(
name = "string_utils",
srcs = ["src/string_utils.py"],
)
| Attribute | Type | Description |
|---|
name | string | Unique target name (required). |
srcs | list | Python source files. |
deps | list | Dependencies (local targets or @external:// references). |
py_binary
Creates an executable Python application with all dependencies bundled.
load("@rbs//python/rules.rbs", "py_binary")
py_binary(
name = "app",
srcs = ["src/main.py"],
main = "src/main.py",
deps = [":calculator", ":string_utils"],
)
| Attribute | Type | Description |
|---|
name | string | Unique target name (required). |
srcs | list | Python source files. |
main | string | Entry point file (required). |
deps | list | Dependencies. |
args | list | Default arguments passed to the binary. |
env | dict | Environment variables. |
py_test
Runs Python tests with optional coverage thresholds. Pytest is auto-included — no manual dependency needed.
load("@rbs//python/rules.rbs", "py_test")
# Basic test
py_test(
name = "calculator_test",
srcs = ["tests/test_calculator.py"],
deps = [":calculator"],
)
# Test with coverage enforcement — FAILS if below threshold
py_test(
name = "calculator_coverage_test",
srcs = ["tests/test_calculator.py"],
deps = [":calculator"],
min_line_coverage = 85,
min_branch_coverage = 75,
min_function_coverage = 80,
size = "small",
timeout = 60,
)
| Attribute | Type | Description |
|---|
name | string | Unique target name (required). |
srcs | list | Test source files. |
deps | list | Dependencies (libraries under test). |
test_runner | string | "pytest" (default) or "unittest". |
min_line_coverage | int | Minimum line coverage percentage. Test fails if below. |
min_branch_coverage | int | Minimum branch coverage percentage. |
min_function_coverage | int | Minimum function coverage percentage. |
size | string | Test size ("small", "medium", "large"). |
timeout | int | Timeout in seconds. |
py_lint
Runs linters (Black + isort by default) on Python source files.
load("@rbs//python/lint.rbs", "py_lint")
py_lint(
name = "lint",
srcs = glob(["**/*.py"], exclude = [".rbs/**", "__pycache__/**"]),
)
# Auto-fix mode
py_lint(
name = "lint_fix",
srcs = glob(["**/*.py"], exclude = [".rbs/**", "__pycache__/**"]),
fix = True,
)
| Attribute | Type | Description |
|---|
name | string | Unique target name (required). |
srcs | list | Source files to lint. |
fix | bool | Auto-fix lint issues (default False). |
Example: Django Blog
A complete Django application with development/production servers, management commands, and linting.
WORKSPACE.rbs
BUILD.rbs
Commands
load("@rbs//python/toolchain.rbs", "python_toolchain")
load("@rbs//python/lint.rbs", "register_python_linters")
load("@rbs//python/dependencies.rbs", "py_repository")
python_toolchain(name = "python3", version = "3.12")
register_python_linters()
py_repository(name = "django_repo", package = "django", version = "5.0.1")
py_repository(name = "gunicorn_repo", package = "gunicorn", version = "23.0.0")
py_repository(name = "whitenoise_repo", package = "whitenoise", version = "6.6.0")
py_repository(name = "pillow_repo", package = "pillow", version = "10.2.0")
py_repository(name = "requests_repo", package = "requests", version = "2.32.4")
load("@rbs//python/rules.rbs", "py_binary", "py_library")
load("@rbs//python/lint.rbs", "py_lint")
py_library(
name = "blog_app",
srcs = glob(["blog/*.py"]),
deps = [":django_repo", ":pillow_repo"],
)
py_library(
name = "django_config",
srcs = glob(["django_blog/*.py"]),
deps = [":django_repo", ":whitenoise_repo", ":requests_repo"],
)
# Development server
py_binary(
name = "dev_server",
srcs = ["manage.py"],
main = "manage.py",
args = ["runserver", "8001"],
deps = [":blog_app", ":django_config", ":django_repo"],
env = {"DJANGO_SETTINGS_MODULE": "django_blog.settings", "DEBUG": "True"},
)
# Production server (Gunicorn)
py_binary(
name = "prod_server",
srcs = ["gunicorn_config.py"],
main = "gunicorn_config.py",
deps = [":blog_app", ":django_config", ":django_repo", ":gunicorn_repo", ":whitenoise_repo"],
env = {"DJANGO_SETTINGS_MODULE": "django_blog.settings", "DEBUG": "False"},
)
# Database migrations
py_binary(
name = "migrate",
srcs = ["manage.py"],
main = "manage.py",
args = ["migrate"],
deps = [":blog_app", ":django_config", ":django_repo"],
env = {"DJANGO_SETTINGS_MODULE": "django_blog.settings"},
)
# Lint
py_lint(
name = "lint",
srcs = glob(["**/*.py"], exclude = [".rbs/**", "venv/**", "__pycache__/**"]),
)
rbs run dev_server # Start development server
rbs run prod_server # Start production server
rbs run migrate # Run database migrations
rbs build lint # Check code style
Commands
rbs build app # Build binary
rbs run dev_server # Run development server
rbs test calculator_test # Run tests
rbs test calculator_coverage_test # Run tests with coverage enforcement
rbs coverage calculator_test # Generate coverage report
rbs build lint # Run linter
