nebius.base.fieldmask.Mask

class documentation

class Mask: (source)

Constructors: Mask.unmarshal(source), Mask(any, field_parts)

Tree representation of a field mask.

A mask contains named field parts and an optional wildcard branch (any). Masks can be merged, intersected, or subtracted to build more complex partial update expressions.

Example

Build a mask with a wildcard and a specific field:

mask = Mask(any=FieldPath(["spec"]).to_mask())
mask += FieldPath(["labels"]).to_mask()
serialized = mask.marshal()

Parameters
any	Wildcard sub-mask or `None`.
field_parts	Mapping of field names to nested masks.
Raises
`ValueError`	If inputs are not valid mask structures.

Class Method	`unmarshal`	Parse a marshaled mask string into a `Mask`.
Method	`__add__`	Return a merged copy of this mask and another.
Method	`__and__`	Alias for `intersect_reset_mask`.
Method	`__eq__`	Return True when another mask is structurally equal.
Method	`__iadd__`	Merge another mask or field path into this mask.
Method	`__imul__`	In-place simple intersection with another mask.
Method	`__init__`	Create a mask from an optional wildcard and field mapping.
Method	`__isub__`	In-place reset-mask subtraction.
Method	`__itruediv__`	In-place simple subtraction from another mask.
Method	`__mul__`	Return a copy intersected with another mask.
Method	`__repr__`	Return a debug representation of the mask.
Method	`__sub__`	Return a copy with reset-mask subtraction applied.
Method	`__truediv__`	Return a copy with simple subtraction applied.
Method	`copy`	Return a deep copy of the mask tree.
Method	`intersect_dumb`	Return a simple intersection (no wildcard promotion).
Method	`intersect_reset_mask`	Return the reset-mask intersection with another mask.
Method	`is_empty`	Return True if the mask has no wildcard and no field parts.
Method	`is_field_path`	Return True if the mask can be represented as a single path.
Method	`marshal`	Serialize the mask to a string.
Method	`sub_mask`	Return a sub-mask for the provided field path or key.
Method	`subtract_dumb`	Remove paths from the mask without wildcard promotion.
Method	`subtract_reset_mask`	Remove paths using reset-mask semantics.
Method	`to_field_path`	Convert a single-path mask to a `FieldPath`.
Instance Variable	`any`	Wildcard sub-mask or `None`.
Instance Variable	`field_parts`	Mapping of field names to nested masks.
Method	`_marshal`	Return a tuple of (segment count, marshaled string).

@classmethod
def unmarshal(cls, source: str) -> Mask: (source) ¶

Parse a marshaled mask string into a Mask.

Parameters
source:`str`	Mask string.
Returns
`Mask`	Parsed mask tree.
Raises
`Error`	When parsing fails.

def __add__(self, other: Mask | FieldPath | None) -> Mask: (source) ¶

Return a merged copy of this mask and another.

Parameters
other:`Mask \| FieldPath \| None`	Mask or path to merge in.
Returns
`Mask`	New merged `Mask`.

def __and__(self, other: Mask | None) -> Mask | None: (source) ¶

Alias for intersect_reset_mask.

Parameters
other:`Mask \| None`	Mask to intersect with.
Returns
`Mask \| None`	Intersected `Mask` or `None`.

def __eq__(self, value: object) -> bool: (source) ¶

Return True when another mask is structurally equal.

Parameters
value:`object`	Object to compare.
Returns
`bool`	`True` if equal, otherwise `False`.

def __iadd__(self, other: Mask | FieldPath | None) -> Mask: (source) ¶

Merge another mask or field path into this mask.

Parameters
other:`Mask \| FieldPath \| None`	Mask or path to merge in.
Returns
`Mask`	This mask instance.

def __imul__(self, other: Mask) -> Mask: (source) ¶

In-place simple intersection with another mask.

Parameters
other:`Mask`	Mask to intersect with.
Returns
`Mask`	This mask instance.
Raises
`ValueError`	If `other` is not a `Mask`.

def __init__(self, any: Mask | None = None, field_parts: Mapping[FieldKey | str, Mask] | None = None): (source) ¶

Create a mask from an optional wildcard and field mapping.

def __isub__(self, other: Mask | None) -> Mask: (source) ¶

In-place reset-mask subtraction.

Parameters
other:`Mask \| None`	Mask to subtract.
Returns
`Mask`	This mask instance.

def __itruediv__(self, other: Mask) -> Mask: (source) ¶

In-place simple subtraction from another mask.

Parameters
other:`Mask`	Mask to subtract.
Returns
`Mask`	This mask instance.
Raises
`ValueError`	If `other` is not a `Mask`.

def __mul__(self, other: Mask) -> Mask: (source) ¶

Return a copy intersected with another mask.

Parameters
other:`Mask`	Mask to intersect with.
Returns
`Mask`	New intersected `Mask`.

def __repr__(self) -> str: (source) ¶

Return a debug representation of the mask.

def __sub__(self, other: Mask | None) -> Mask: (source) ¶

Return a copy with reset-mask subtraction applied.

Parameters
other:`Mask \| None`	Mask to subtract.
Returns
`Mask`	New `Mask` with subtraction applied.

def __truediv__(self, other: Mask) -> Mask: (source) ¶

Return a copy with simple subtraction applied.

Parameters
other:`Mask`	Mask to subtract.
Returns
`Mask`	New `Mask` with subtraction applied.

def copy(self) -> Mask: (source) ¶

Return a deep copy of the mask tree.

Returns
`Mask`	New `Mask` instance.

def intersect_dumb(self, other: Mask | None) -> Mask | None: (source) ¶

Return a simple intersection (no wildcard promotion).

Parameters
other:`Mask \| None`	Mask to intersect with.
Returns
`Mask \| None`	Intersected `Mask` or `None` when `other` is invalid.

def intersect_reset_mask(self, other: Mask | None) -> Mask | None: (source) ¶

Return the reset-mask intersection with another mask.

Parameters
other:`Mask \| None`	Mask to intersect with.
Returns
`Mask \| None`	Intersected `Mask` or `None` when `other` is invalid.

def is_empty(self) -> bool: (source) ¶

Return True if the mask has no wildcard and no field parts.

Returns
`bool`	`True` if empty, otherwise `False`.

def is_field_path(self) -> bool: (source) ¶

Return True if the mask can be represented as a single path.

Returns
`bool`	`True` if convertible to a `FieldPath`.

def marshal(self) -> str: (source) ¶

Serialize the mask to a string.

Returns
`str`	Marshaled mask string.

def sub_mask(self, path: FieldPath | FieldKey) -> Mask | None: (source) ¶

Return a sub-mask for the provided field path or key.

Parameters
path:`FieldPath \| FieldKey`	A `FieldKey` or `FieldPath`.
Returns
`Mask \| None`	The sub-mask, wildcard mask, or `None` if absent.

def subtract_dumb(self, other: Mask | None): (source) ¶

Remove paths from the mask without wildcard promotion.

Parameters
other:`Mask \| None`	Mask to subtract.

def subtract_reset_mask(self, other: Mask | None): (source) ¶

Remove paths using reset-mask semantics.

Parameters
other:`Mask \| None`	Mask to subtract.

def to_field_path(self) -> FieldPath | None: (source) ¶

Convert a single-path mask to a FieldPath.

Returns
`FieldPath \| None`	The field path or `None` when the mask is empty.
Raises
`Error`	If the mask uses wildcards or contains multiple paths.

any: Mask | None = (source) ¶

Wildcard sub-mask or None.

field_parts = (source) ¶

Mapping of field names to nested masks.

def _marshal(self) -> tuple[int, str]: (source) ¶

Return a tuple of (segment count, marshaled string).

Returns
`tuple[int, str]`	`(count, serialized)` where `count` is the number of top-level segments.