Feat model validation

[Poofjunior]

Basic validation for a device spec entry.
Let's merge: #10 first.

[patricklatimer]

I don't think public repos can run on self-hosted runners. Also we don't actually need any features of the self-hosted (like being in the network), so I think it's probably best to use a gh-provided one like windows-latest

Also then you don't need to do the env stuff to point to AIBS_MPE

[Poofjunior]

This is 100% cruft from a very old template starting point. If you have recs on an updated version, I'll gladly take it!

[patricklatimer]

I like to keep my actual tool invocations in a makefile, then just call them from the CI like so:

name: Lint and run tests

on:
  pull_request:
    branches:
      - main

jobs:
  test-lint-type:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [ '3.10', '3.11', '3.12', '3.13', '3.14' ]
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
    - name: Install UV - python version set to ${{ matrix.python-version }} 
      uses: astral-sh/setup-uv@v5
      with:
        python-version: ${{ matrix.python-version }} 
    - name: Lint
      run: make lint
    - name: Test
      run: make test

Makefile:

lint:
	uvx ruff check

lint-fix:
	uvx ruff check --fix

test:
	uv run pytest
	

That way its easy to locally run the exact same commands as the CI, and you can just update the makefile rather than having to hunt in the CI.

[patricklatimer]

These mutable default arguments are gonna cause some problems:
https://docs.python-guide.org/writing/gotchas/#mutable-default-arguments
https://florimond.dev/en/posts/2018/08/python-mutable-defaults-are-the-source-of-all-evil

Tangentially though, you can provide mutable defaults to pydantic models! https://pydantic.dev/docs/validation/latest/concepts/fields/#mutable-default-values

[Poofjunior]

I would totally agree except these aren't input arguments. ;) They're entirely constructed internally.

[patricklatimer]

Oh whoops didn't read closely, sorry!

[patricklatimer]

Maybe add a docstring about the module_name/class_name/factory options. Also might be a good use case for some doctests!

I turned your unit tests into doctests, maybe it's a bit much to have all the error cases in a docstring, but I think it's definitely handy to have an example or two of how I'm supposed to use it, especially since there's special validation logic.

    """
    Examples
    --------
    >>> data = {'module': 'builtins', 'class': 'dict', 'kwds': {'key0': 'MyVal'}}
    >>> DeviceSpec.model_validate(data).model_dump(exclude_none=True)
    {'module_name': 'builtins', 'class_name': 'dict', 'kwds': {'key0': 'MyVal'}}
    
    >>> data = {'module': '', 'class': 'dict', 'kwds': {'key0': 'MyVal'}}
    >>> DeviceSpec.model_validate(data) # doctest: +ELLIPSIS
    Traceback (most recent call last):
        ...
    pydantic_core._pydantic_core.ValidationError: ...

    >>> data = {'class': 'dict', 'kwds': {'key0': 'MyVal'}}
    >>> DeviceSpec.model_validate(data) # doctest: +ELLIPSIS
    Traceback (most recent call last):
        ...
    pydantic_core._pydantic_core.ValidationError: ...

    >>> data = {'class': 'builtins.dict', 'factory': 'builtins.dict', 'kwds': {'key0': 'MyVal'}}
    >>> DeviceSpec.model_validate(data) # doctest: +ELLIPSIS
    Traceback (most recent call last):
        ...
    pydantic_core._pydantic_core.ValidationError: ...

    >>> data = {'kwds': {'key0': 'MyVal'}}
    >>> DeviceSpec.model_validate(data) # doctest: +ELLIPSIS
    Traceback (most recent call last):
        ...
    pydantic_core._pydantic_core.ValidationError: ...
    """

Also, you can configure pytest in the pyproject.toml to run doctests

[tool.pytest.ini_options]
addopts = "--doctest-modules"

https://docs.pytest.org/en/7.1.x/how-to/doctest.html

[Poofjunior]

I like it! This looks handy from the point of view of generating docs, but pytest is useful from the point of view of being able to run one function at at time, so I'll probs keep both.

It also looks like doctest autoruns the examples folder, so I cleaned those up and made an omission where needed.

[patricklatimer]

Yeah, there's definitely a balance to be found with doctests, they're definitely not like, the place to put all your unit tests, but they're very handy to have a few examples and basic usage tests.

[patricklatimer]

Pretty sure this import is a tab-complete-gone-wrong situation

[Poofjunior]

oof; my editor taking my tab too far.

[patricklatimer]

This is cool, I haven't used this before!

[Poofjunior]

yeah; I thought that was cool too for an anonymous-ish field!

[patricklatimer]

Should this spec_trees be typed as a DeviceTrees? Or if it's easier to keep it a dict, would this function be a good place to run the validation?

DeviceTrees.model_validate(**spec_trees)

[Poofjunior]

This is actually the resulting dict of instances that device-spinner will buid, not the input. But you're right that I should totally let the create_devices_from_specs take a DeviceTrees as input or do a model validate.