AS Acquisition Library

This library is used by other repositories as a source of devices, plans, and tools.

Development

Setup

To create a virtual environment with the minimal set of dependencies

$ uv sync

or, to include dev dependencies like pytest, include the minimum requirements for testing the core parts of the library (which doesn't include scientific or plotting modules):

$ uv sync --extra dev

To exercise and test the complete functionality of this library, including that which depends on the scientific and plotting modules, you should include those too:

$ uv sync --extra dev --extra scientific_packages --extra matplotlib

Unit Testing

Basics

To run unit tests

$ pytest

or

$ uv run pytest

or if you want a really fast feedback cycle, you can exclude slower "integration" tests that run bluesky plans

$ uv run pytest -m "not integration"

Snapshot Tests

We also have snapshot tests (via the https://pypi.org/project/syrupy/ package) such as "test_generic_scan_models_serialisation".

These are useful for tests where you just want to assert that the output of something has not changed, rather than assert on specific conditions.

If these fail, pytest will throw an error explaining that the snapshot has failed. You can add -vv switches to pytest to show the diff between the current output and the expected output.

$ uv run pytest -vv

If the current output looks fine, run pytest with the --snapshot-update switch to update the snapshots and then commit them to source control.

$ uv run pytest --snapshot-update

Code Quality

To run formatting/linting

$ uv run ruff format            # Formatting only
$ uv run ruff check --fix       # Linting only

Building

To build an installable sdist tarball and wheel

$ uv build

Pydantic

There is a custom Pydantic model base class called ASBaseModel which is a drop in replacement for the default Pydantic base model. It has stricter options than the defaults. If you find that these stricter defaults are causing issues you can override them on a case by case basis.

See as_base_model.py for more info.

# Example usage
class SomeModel(ASBaseModel):
    a: str

Pre-commit Hooks

To automatically run ruff linting/formatting when you commit, you can install pre-commit hooks

$ uv run pre-commit install

Then every time you make a commit, you'll get automatic checks.

You can also run all the pre-commit hooks manually

$ uv run pre-commit run -a