[codemageddon]

Summary

One object that fails validation (typically a custom resource stored before its CRD schema changed) currently fails a whole list() and ends a watch(). Reconnecting doesn't help because the same object comes back. This adds an opt-in mode that keeps such objects instead of raising.

pods = await api.list(invalid=InvalidObjects.INCLUDE)   # ListWithInvalid[Pod]
pods.items      # objects that fit the model
pods.invalid    # InvalidObject(raw, error, metadata) for the rest

async for ev in api.watch(invalid=InvalidObjects.INCLUDE):  # keeps streaming past bad objects
    if ev.is_initial_events_end: ...   # end bookmark of a send_initial_events watch
    ev.object.metadata.name            # works on WatchEvent and InvalidWatchEvent

Changes

• InvalidObjects enum (RAISE default, INCLUDE) in kubex.core.params; the strings "raise"/"include" are accepted too, matching VersionMatch and friends. Overloads on Api.list()/Api.watch() pick the return type, so existing callers' types are unchanged.
• InvalidObject (raw, error, parsed metadata) and ListWithInvalid (a ListEntity subclass with invalid, which is not serialized) in the new kubex.core.invalid_object.
• InvalidWatchEvent: has type and object.metadata like WatchEvent, so code that tracks names or resume points works on both.
• What still raises with INCLUDE: ERROR events, bookmarks that don't parse, lines that aren't JSON, and objects whose metadata has no name (they can't be identified, e.g. to drop from a cache).
• WatchEvent.is_initial_events_end for the k8s.io/initial-events-end bookmark.
• MetadataAccessor.watch is unchanged: PartialObjectMetadata has only optional fields.
• Docs: watch page (new section, plus where to resume after initial events), list section, API reference, CHANGELOG, CLAUDE.md.

Not in this PR

• get/delete/patch/replace still parse with the model, so on a bad object they raise ValidationError, the last three after the server has applied the change. Documented, with api.metadata as the workaround.
• The default mode still raises pydantic's ValidationError unwrapped; wrapping it in a kubex exception would be a breaking change.

Testing

• 36 unit tests (test/test_invalid_objects.py): parsing rules, Api.list/Api.watch via the stub client, is_initial_events_end, and assert_type checks of the overloads.
• 4 e2e tests against K3S (test/e2e/test_invalid_objects.py): a CRD object the model rejects, through watch and list (including a DELETED event for it), and resuming from the end bookmark's resource version.
• Full suite locally: 2725 passed, 63 skipped. mypy strict, ruff, pre-commit and mkdocs build --strict are clean.

🤖 Generated with Claude Code

[github-actions]

Test PyPI packages published

The following packages have been published to Test PyPI:

• kubex 0.1.0b3.dev601
• kubex-core 0.1.0b3.dev601
• kubex-k8s-1-32 0.1.0b3.dev601
• kubex-k8s-1-33 0.1.0b3.dev601
• kubex-k8s-1-34 0.1.0b3.dev601
• kubex-k8s-1-35 0.1.0b3.dev601
• kubex-k8s-1-36 0.1.0b3.dev601
• kubex-k8s-1-37 0.1.0b1.dev601
• kubex-k8s-1-38 0.1.0a1.dev601

Install with:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ kubex==0.1.0b3.dev601

[github-actions]

Test PyPI packages published

The following packages have been published to Test PyPI:

• kubex 0.1.0b3.dev611
• kubex-core 0.1.0b3.dev611
• kubex-k8s-1-32 0.1.0b3.dev611
• kubex-k8s-1-33 0.1.0b3.dev611
• kubex-k8s-1-34 0.1.0b3.dev611
• kubex-k8s-1-35 0.1.0b3.dev611
• kubex-k8s-1-36 0.1.0b3.dev611
• kubex-k8s-1-37 0.1.0b1.dev611
• kubex-k8s-1-38 0.1.0a1.dev611

Install with:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ kubex==0.1.0b3.dev611