Neops Worker SDK for Python

Build network automation as small, typed Python units — function blocks — that the neops platform orchestrates, schedules, and scales for you.

@register_function_block(Registration(name="show_version", run_on="device", ...))
class ShowVersion(FunctionBlock[ShowVersionParams, ShowVersionResult]):
    async def run(self, params, context):
        async with ConnectionProxy.connect(context.device) as conn:
            output = await conn.send_command("show version")
        return FunctionBlockResult(success=True, data=ShowVersionResult(output=output))

Full Documentation — Getting started, function blocks, device connections, testing, deployment.

Installation

For users (pip):

pip install neops-worker-sdk

For contributors (uv):

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository and install dependencies
uv sync --group dev --extra test

Use a .env file (with python-dotenv):

cp .env.test .env
python -m dotenv -f .env run -- uv run neops_worker

Run the Worker

To run the worker locally:

uv run neops_worker

If installed via pip, run it from your virtual environment:

neops_worker

You can also use the module form:

python -m neops_worker_sdk.cli.neops_worker

Development Tools

This project uses a modern Python toolchain for development:

Tool	Purpose	Documentation
uv	Fast Python package and project manager	Getting Started
ruff	Extremely fast Python linter and formatter	Configuration
pyrefly	Fast type checker for Python	Documentation

Common Commands

Action	Command
Install dependencies	`uv sync`
Install with dev deps	`uv sync --group dev`
Install with all groups	`uv sync --group dev --extra test`
Add a package	`uv add <pkg>`
Add dev package	`uv add --group dev <pkg>`
Run a command	`uv run <cmd>`
Run the worker	`uv run neops_worker`
Build wheel	`uv build`
Publish package	`uv publish`

Code Quality Commands

Action	Command
Format code	`uv run ruff format .`
Check formatting	`uv run ruff format --check .`
Lint code	`uv run ruff check .`
Fix lint issues	`uv run ruff check --fix .`
Type check	`uv run pyrefly check`

Testing

Tests are organized in tiers using pytest markers. By default, only fast unit tests run — integration and example tests are excluded to keep local iteration quick.

Command	What runs
`uv run pytest`	Unit tests only (default)
`make test`	Same as above
`make test-examples`	Example function block tests (no lab required)
`make test-function-blocks`	Function block + remote lab integration tests
`make test-all`	Everything

Remote lab tests require REMOTE_LAB_URL to be set:

export REMOTE_LAB_URL=http://<remote-lab-host>:8000
make test-all

Marker	Applied by	Purpose
`function_block`	`@fb_test_case`	Local function block lifecycle tests
`remote_lab`	`@fb_test_case_with_lab`	Tests requiring a provisioned lab topology
`examples`	Auto (conftest.py)	All tests collected from `examples/`

Make Targets

# Run linting (format check + lint check)
make lint

# Auto-format code
make format

# Run type checking (pyrefly)
make typeCheck

# Run tests
make test               # unit tests (default)
make test-examples      # example tests
make test-function-blocks   # function block + remote lab tests
make test-all           # everything

Code Style

Type Checking

We enforce strict typing for all Python files. The codebase is checked with pyrefly:

uv run pyrefly check

Formatting and Linting

Code formatting and linting are enforced by ruff:

# Check formatting
uv run ruff format --check ./neops_worker_sdk ./examples

# Auto-format
uv run ruff format ./neops_worker_sdk ./examples

# Lint
uv run ruff check ./neops_worker_sdk ./examples

# Lint and auto-fix
uv run ruff check --fix ./neops_worker_sdk ./examples

Docker

Build and run with Docker:

# Build the image
docker build -t neops-worker-sdk .

# Run the worker
docker run neops-worker-sdk

# Run linting (CI target)
docker build --target linter -t neops-worker-sdk:lint .

# Run tests (CI target)
docker build --target test -t neops-worker-sdk:test .