Skip to content

feat(attributes): add default_for_new attribute for model fields and update related documentation - #553

Open
marvelefe wants to merge 4 commits into
ferrumio:mainfrom
marvelefe:main
Open

marvelefe wants to merge 4 commits into
ferrumio:mainfrom
marvelefe:main

Conversation

@marvelefe

Copy link
Copy Markdown

Summary

Adds a default_for_new attribute option. New models use it when the field is omitted. Stored items that lack the field still use default.

class User(Model):
    model_config = ModelConfig(table="users")

    pk = StringAttribute(partition_key=True)
    recommendations_enabled = BooleanAttribute(
        default=False,  # Stored items that lack the field
        default_for_new=True,  # New models that omit the field
    )


User(pk="USER#new").recommendations_enabled  # True
User.from_dict({"pk": "USER#old"}).recommendations_enabled  # False

Closes #487

Behavior

  • Direct construction uses default_for_new when the field is omitted. Otherwise default applies, as before.
  • Loading (from_dict, get, query, scan, batch and index reads) always uses default. Partial projections never get a creation default.
  • Explicit values win, including False, 0, and None. default_for_new=None means no creation default, so required still applies.
  • Models that only use default behave as before.

Persistence

  • A value filled in on load is not tracked as a change. A smart save does not send it.
  • Setting the field explicitly on a loaded item marks it changed, even if it equals the read default.
  • Full-item writes send every field, including fallback values. This covers new items, save(full_replace=True), and loaded items with no changes.

Changes

  • attributes/base.py: new option and UNSET sentinel.
  • attributes/{primitives,special,compressed,decimal,s3,vector}.py: constructors that take default accept default_for_new.
  • _internal/_model/_base.py: default selection in the constructor and auto-generate handling. A ContextVar marks the loading path in from_dict.
  • docs/guides/attributes.md and docs/examples/models/default_for_new.py: guide section and example.
  • tests/unit/test_default_for_new.py: 22 new tests.

Testing

  • Unit tests (uv run pytest tests/unit/): 1129 passed.
  • Lint, format, and type checks (ruff, ty): pass.
  • Integration tests (uv run pytest tests/integration/): 867 passed, 8 skipped, 1 failed.
    • The failure is test_distributed_lock.py::test_native_short_retry_recovery[0.05], which raises Lock request timed out. It fails when run alone, and the lock code does not import any module this PR changes. It's a pre-existing failure
    • Run with DOCKER_HOST pointing at the Docker Desktop socket and TESTCONTAINERS_RYUK_DISABLED=true.

@leandrodamascena

Copy link
Copy Markdown
Member

Thanks, Efe! The existing tests and examples passed. I found two cases we should fix before merging:

  • _apply_auto_generate() always selects the creation default. With default_for_new=AutoGenerate.UUID4, loading an old item, changing only its name and saving also writes a new UUID. I reproduced this with LocalStack in both sync and async.
  • _loading_stored also affects other models created inside a custom constructor. Those are new objects, but they receive read defaults. Tasks started there inherit that loading state too, even after from_dict() returns.

Could you adjust the default selection on save, keep the loading state specific to the object being loaded, and add Python regression tests for these cases? Thanks for working on this 🙂

@pull-request-size pull-request-size Bot added size/XL and removed size/L labels Nov 1, 2026
@sonarqubecloud

sonarqubecloud Bot commented Nov 1, 2026

Copy link
Copy Markdown

@marvelefe

Copy link
Copy Markdown
Author

@leandrodamascena Fixed both now with regression tests, and the integration suite passes

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE] Add separate defaults for new and loaded models

2 participants