Contributing
Thank you for your interest in contributing to pyvergeos!
Development Setup
Clone the repository:
git clone https://github.com/verge-io/pyvergeos.git cd pyvergeos
Install dependencies with uv:
uv syncRun tests:
uv run pytest tests/unit
Code Style
We use ruff for linting and formatting:
# Lint and auto-fix
uv run ruff check --fix .
# Format
uv run ruff format .
# Type check
uv run mypy pyvergeos
Guidelines
Line length: 100 characters maximum
Docstrings: Google style for all public classes and methods
Type hints: Required for all public APIs
Tests: Required for new features and bug fixes
Adding a Resource Accessor
A field the server has to compute – a traversal like
machine#status#running as running or an aggregate like
count(members) as member_count – is not part of fields=all. It
arrives only if the manager asked for it by name.
Declare the accessor and the projection entry behind it together, with
Projected, so the two cannot drift apart:
from pyvergeos.resources.base import Projected
class Network(ResourceObject):
is_running = Projected[bool](
"machine#status#running as running",
bool,
default=False,
doc="Check if network is powered on.",
)
The manager then derives its projection from the declarations rather than restating them:
DEFAULT_NETWORK_FIELDS = [*_NETWORK_COLUMNS, *Network.projected_entries()]
Adding the accessor is therefore all that is needed; its field joins every query that reads it.
Do not write the accessor by hand:
# wrong: nothing ties this to the manager's field list, and it cannot
# tell a stopped network from one whose 'running' was never fetched
@property
def is_running(self) -> bool:
return bool(self.get("running", False))
A test enforces this: no @property may call require_projected.
Arguments
The read happens in a fixed order, which is what lets Projected
reproduce the hand-written accessors it replaced:
require_projected(alias, default)fallback– re-read from a plain field when the value is falsyfalsy– substitute for any falsy value, thex or 0idiomnull– return this, uncoerced, when the value is Nonecoerce, thentransform
default answers the case where the field was requested but the server
omitted it, which happens when a traversal passes through a null
polymorphic reference. If the field was never requested at all, the
accessor raises FieldNotProjectedError rather than guessing.
Note that coerce receives a null value unless null is given. That is
deliberate – it is what the accessors being replaced did.
transform covers display maps and unit conversions:
from pyvergeos.resources.base import display_map, epoch_utc
status = Projected[str](
"status#status as status", str, default="",
transform=display_map(STATUS_DISPLAY),
)
started_at = Projected["datetime | None"](
"machine#status#started as started",
falsy=None, null=None, transform=epoch_utc,
)
Write a union parameter as a string – Projected["str | None"] – because
the subscript is evaluated at runtime and str | None is a TypeError
on Python 3.9, which is still supported.
Plain columns are different: read them with self.get() as usual. all
already covers them, so there is nothing to keep in step.
References
Some columns hold a "table/key" reference such as "vms/39", and a key
is not always numeric – recipes are keyed by name. Use
reference_key()/reference_table() rather than int():
from pyvergeos.resources.base import reference_key
@property
def owner_key(self) -> str | int | None:
return reference_key(self.get("owner"))
Running Tests
# Unit tests only
uv run pytest tests/unit
# With coverage
uv run pytest tests/unit --cov=pyvergeos
# Specific test file
uv run pytest tests/unit/test_vms.py
# Pattern matching
uv run pytest -k "test_vm"
Pull Request Process
Create a feature branch from
mainMake your changes with tests
Ensure all tests pass and linting is clean
Submit a pull request with a clear description
Commit Messages
We use conventional commits with emoji:
feat:New featurefix:Bug fixdocs:Documentation changestest:Test additions or fixesrefactor:Code refactoring
Example:
feat: add VM migration support
- Add migrate() method to VM class
- Add integration tests for live migration