Skip to content

feat(models): add type-safe field name references for Pydantic DTOs#108

Merged
HosseinNejatiJavaremi merged 1 commit intoSyntaxArc:masterfrom
miladmahmoodi:feat/type-safe-field-references
Feb 23, 2026
Merged

feat(models): add type-safe field name references for Pydantic DTOs#108
HosseinNejatiJavaremi merged 1 commit intoSyntaxArc:masterfrom
miladmahmoodi:feat/type-safe-field-references

Conversation

@miladmahmoodi
Copy link
Contributor

@miladmahmoodi miladmahmoodi commented Feb 22, 2026

Add FieldStr utility class and BaseMeta metaclass to BaseDTO so that all DTO subclasses automatically expose field names as type-safe class attributes (e.g., PaginationDTO.page returns FieldStr("page")).

This enables IDE autocompletion, refactoring support, and eliminates hardcoded field name strings. Instance attribute access is unaffected.

  • Add FieldStr(str) with slots for memory efficiency
  • Add BaseMeta(ModelMetaclass) that sets FieldStr attrs after class construction
  • Replace hardcoded field_name strings in range_dtos.py model validators
  • Add BDD feature file with 6 scenarios covering FieldStr behavior

Description

Hardcoded field name strings (e.g., "from_", "to") scattered across DTOs and validators are fragile — renaming a field won't cause a lint or type error, leading to silent runtime bugs.

This PR adds a FieldStr(str) utility and a BaseMeta(ModelMetaclass) metaclass to BaseDTO. After Pydantic's ModelMetaclass constructs the class and populates model_fields, BaseMeta overwrites the corresponding class attributes with FieldStr instances so that MyDTO.field_name returns a type-safe string equal to "field_name". Instance attribute access is unaffected because Python resolves instance __dict__ entries before class attributes.

How It Works

class UserDTO(BaseDTO):
    name: str
    email: str

Class-level access returns FieldStr (a str subclass)

UserDTO.name   # FieldStr("name") — type-safe reference
UserDTO.email  # FieldStr("email")

Instance-level access is unaffected

user = UserDTO(name="Alice", email="alice@example.com")
user.name   # "Alice" — actual value

Two hardcoded field name strings in range_dtos.py model validators have been replaced with type-safe FieldStr references as a demonstration.

Type of change

  • New feature (non-breaking change which adds functionality)

How Has This Been Tested?

  • 6 new BDD scenarios in features/base_dtos.feature covering: FieldStr class attributes exist, instance access returns actual values, FieldStr works as dict key, FieldStr works in string comparisons, inherited DTOs get FieldStr attributes, existing PaginationDTO has FieldStr attributes
  • Ran existing test suite (85 scenarios pass, 4 pre-existing datetime_utils failures unrelated to this change)
  • All pre-commit hooks pass (ruff, ruff-format, ty, codespell, trailing-whitespace, end-of-file-fixer, validate-pyproject)

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I have checked my code and corrected any misspellings

Additional context

The primary value of this feature is for downstream consumers of ArchiPy who define their own DTOs and can reference field names type-safely in their application code (queries, filters, serialization keys, etc.). Note that @field_validator("field_name") string arguments cannot be replaced because the decorator executes before the class (and thus the metaclass) is fully constructed — this is a Pydantic limitation.

Add FieldStr utility class and BaseMeta metaclass to BaseDTO so that
all DTO subclasses automatically expose field names as type-safe class
attributes (e.g., PaginationDTO.page returns FieldStr("page")).

This enables IDE autocompletion, refactoring support, and eliminates
hardcoded field name strings. Instance attribute access is unaffected.

- Add FieldStr(str) with __slots__ for memory efficiency
- Add BaseMeta(ModelMetaclass) that sets FieldStr attrs after class construction
- Replace hardcoded field_name strings in range_dtos.py model validators
- Add BDD feature file with 6 scenarios covering FieldStr behavior

Co-authored-by: Cursor <cursoragent@cursor.com>
@HosseinNejatiJavaremi HosseinNejatiJavaremi merged commit 747d93b into SyntaxArc:master Feb 23, 2026
4 of 5 checks passed
HosseinNejatiJavaremi added a commit that referenced this pull request Feb 23, 2026
Add comprehensive changelog entry for the type-safe field name references
feature merged in PR #108, including FieldStr utility and BaseMeta metaclass
implementation details.

Co-authored-by: Cursor <cursoragent@cursor.com>
HosseinNejatiJavaremi added a commit that referenced this pull request Feb 23, 2026
…ld-references"

This reverts commit 747d93b, reversing
changes made to d4e4922.
HosseinNejatiJavaremi added a commit that referenced this pull request Feb 23, 2026
- Add v4.3.3 section documenting reversion of type-safe field references feature
- Document removal of FieldStr utility class and BaseMeta metaclass
- Clarify that v4.3.3 supersedes the cancelled v4.3.2 release
- Feature is being reconsidered for future implementation with improved design

Co-authored-by: Cursor <cursoragent@cursor.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants