[PR] Extended syntax for filtering and accessing labels/annotations/patches/body parts

[kopf-archiver]

A pull request by nolar at 2020-03-11 10:22:06+00:00
Original URL: zalando-incubator/kopf#327
Merged by nolar at 2020-03-12 08:37:49+00:00

What do these changes do?

Extend the resource bodies, body-parts, and patches with properties making them easier to use, and add few handler kwargs for well-known and often-used fields (labels/annotations).

Description

Previously, it was quite common to use complicated Python structures to access the body/patch fields like this:

# OLD, as it was before:
@kopf.on.create(..., annotations={'some-marker': None})
def assign_ids(body, patch, **_):
    marker = body['metadata']['annotations']['some-marker']
    run_id = body.get('metadata', {}).get('labels', {}).get('run-id')
    field = body.get('spec', {}).get('field')
    patch.setdefault('status', {})['key'] = 'value'
    patch.setdefault('metadata', {}).setdefault('labels', {})['another-marker'] = 'value'

With this PR, well-known structures are exposed as body/patch properties, and are always behave as "live views" into their original dicts — i.e. every update on the dict is reflected in all views, all updates on the views is reflected in the original dict (similar to how KeysView, ValuesView, ItemsView work in Python itself).

# NEW, to be used:
@kopf.on.create(..., annotations={'some-marker': kopf.PRESENT})
def assign_ids(body, patch, labels, annotations, **_):
    marker = annotations['some-marker']
    run_id = labels.get('run-id')
    field = body.spec.get('field')
    patch.status['key'] = 'value'
    patch.meta.labels['another-marker'] = 'value'

Specifically:

• JSON-decoded objects/dicts/fields are now explicitly typed as "raw" to make their origin clear. These are the lighweight structures coming directly from K8s API.
• body kwarg is now always a "live view" to the original RawBody JSON-decoded dict, same as it already was for spec, meta, status kwargs before.
• labels & annotations kwargs are added to all resource-related handlers.
• body.spec|meta|status and body.meta.labels|annotations are the "live views" to a raw dict, persistent across multiple uses, and are exactly the same objects as provided in the kwargs (i.e. not re-created for every new handler).
• patch follows the same .spec|meta|status semantics with "mutable live views".

In addition, the labels/annotations filters are changed to deprecate None as an "any value" marker, as it was confusing ("some value is None" does not sound natural). Instead, kopf.PRESENT or kopf.ABSENT tokens should be used for labels/annotations filters.

Purpose: All of the above adds some conventional features now for the event-driven handlers, but is critically important for the upcoming daemons/timers, where the bodies are updated over time, while the handlers that use these bodies, run in a sequential execution flow (unlike short event handlers).

For the end users, there are no big changes except for the new kwargs and properties available.

Slightly breaking: body is now not a dict, but a custom class, therefore it is not JSON-serialisable. Use dict(body) to make it JSON-serialisable. But there were no expected usage patterns to JSON-serialise the whole body, and here is a quick solution — so, should be fine.

Issues/PRs

Issues: #19

Type of changes

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

Checklist

• The code addresses only the mentioned problem, and this problem only
• I think the code is well written
• Unit tests for the changes exist
• Documentation reflects the changes
• If you provide code modification, please add yourself to CONTRIBUTORS.txt