Skip to content

Add usethis-python-enum agent skill and dict comprehensiveness test #1492

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nathanjmcdougall merged 2 commits into from
Mar 25, 2026
Merged

Add usethis-python-enum agent skill and dict comprehensiveness test #1492

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2c0c0c1
Initial plan
Copilot Mar 25, 2026
2b5f023
Add usethis-python-enum skill and dict comprehensiveness test for _ST…
Copilot Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions .agents/skills/usethis-python-enum/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
name: usethis-python-enum
description: Style and testing conventions for working with Python enums
compatibility: usethis, Python, pytest, enums
license: MIT
metadata:
version: "1.0"
---

# Working with Enums

## Exhaustiveness via `assert_never`

When handling all cases of an enum in `if`/`elif` chains, always include a final `else` branch that calls `assert_never` from `typing_extensions`. This ensures the type checker will flag any unhandled enum members if the enum is extended in the future.

```python
from typing_extensions import assert_never

from usethis._types.backend import BackendEnum

def handle_backend(backend: BackendEnum) -> str:
if backend is BackendEnum.uv:
return "uv"
elif backend is BackendEnum.none:
return "none"
else:
assert_never(backend)
```

## Dicts with enum keys must have comprehensiveness tests

When a module-level dict uses an enum's members as its keys, add a unit test that asserts the dict's keys exactly match the set of all enum members. This prevents the dict from silently becoming incomplete when new members are added to the enum.

### Example test

```python
from usethis._core.status import _STATUS_TO_CLASSIFIER_MAP
from usethis._types.status import DevelopmentStatusEnum

class TestStatusToClassifierMap:
def test_keys_match_enum(self):
assert set(_STATUS_TO_CLASSIFIER_MAP.keys()) == set(DevelopmentStatusEnum)
```

### Why this matters

Type checkers can catch missing cases in `if`/`elif` chains when `assert_never` is used, but they **cannot** catch missing keys in a dict literal. A dedicated unit test is the only reliable way to ensure that all enum members are represented.
7 changes: 6 additions & 1 deletion tests/usethis/_core/test_status.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,17 @@
import pytest
from pydantic import TypeAdapter

from usethis._core.status import use_development_status
from usethis._core.status import _STATUS_TO_CLASSIFIER_MAP, use_development_status
from usethis._file.pyproject_toml.io_ import PyprojectTOMLManager
from usethis._test import change_cwd
from usethis._types.status import DevelopmentStatusEnum


class TestStatusToClassifierMap:
def test_keys_match_enum(self):
assert set(_STATUS_TO_CLASSIFIER_MAP.keys()) == set(DevelopmentStatusEnum)


class TestUseDevelopmentStatus:
def test_planning(self, uv_init_dir: Path, capfd: pytest.CaptureFixture[str]):
# Arrange
Expand Down
Loading