module documentation

Parser for Nebius field mask strings.

This module tokenizes and parses the compact mask syntax into a nebius.base.fieldmask.Mask tree. It supports dotted paths, comma separation, nested sub-masks using parentheses, and the wildcard *.

Grammar overview

  • Paths are dot-separated (spec.max_size_bytes).
  • Multiple paths are comma-separated.
  • Parentheses group a sub-mask (spec.(a,b)).
  • * denotes a wildcard branch at the current level.

Examples

Parse a simple mask:

from nebius.base.fieldmask_parser import parse

mask = parse("spec.max_size_bytes,labels")
assert mask.marshal() == "labels,spec.max_size_bytes"

Parse a nested mask:

mask = parse("spec.(limits,max_size_bytes)")
assert mask.marshal() == "spec.(limits,max_size_bytes)"
Class Level Parser helper tracking mask branches within a parenthesized level.
Class Lexer Tokenizer for the field mask grammar.
Class State Parser state machine states.
Class Token Single token with type, string value, and source position.
Class TokenType Token kinds produced by Lexer.
Exception ContextedParseError Parse error that includes source context.
Exception ParseError Raised when parsing fails.
Exception TooComplexError Raised when a mask needs more steps than parse permits.
Function parse Parse a mask string into a Mask tree.
Variable context_back Number of characters to show before the error position.
Variable error_mark Combining enclosing square to mark error position in context.
Variable max_context Maximum length of context to show in error messages.
Variable simple_string_token Regex for full simple (unquoted) token strings.
Variable simple_string_token_set Regex for simple (unquoted) token strings.
Variable simple_string_token_start Regex for the start of simple (unquoted) token strings.
Variable space_chars Whitespace characters recognized by the lexer.
Variable space_set Set of whitespace characters recognized by the lexer.
Function _context_around Build a human-friendly context string around a parse error.
Function _groups_before_dot Find the groups that a dot follows.
Function _parse Parse a mask string with an explicit limit for the number of steps.
Function _possible_ellipsis Return a truncated string with an ellipsis when needed.
Variable _parse_steps_per_char Number of steps that parse permits for each character of the input.
def parse(source: str) -> Mask: (source)

Parse a mask string into a Mask tree.

The parser limits its work, because a sequence of groups multiplies the number of fields. For example, (a,b).(c,d).(e,f) contains 14 fields. The parser does one step for each active mask when it applies a key, a wildcard, a comma or a closing parenthesis. It permits 8 steps for each character of the input. The number of fields in the result is thus not more than 8 times the length of the input.

The limit has no effect on a mask in which no dot follows a group. Such a mask needs one step for each token at most. Mask.marshal writes only such masks.

Parameters
source:strMask string to parse.
Returns
MaskParsed Mask. Empty or whitespace-only strings yield an empty mask.
Raises
TooComplexErrorIf the mask needs more steps than the limit.
ParseErrorIf the input is malformed.
context_back: int = (source)

Number of characters to show before the error position.

error_mark: str = (source)

Combining enclosing square to mark error position in context.

max_context: int = (source)

Maximum length of context to show in error messages.

simple_string_token = (source)

Regex for full simple (unquoted) token strings.

simple_string_token_set: str = (source)

Regex for simple (unquoted) token strings.

simple_string_token_start = (source)

Regex for the start of simple (unquoted) token strings.

space_chars: str = (source)

Whitespace characters recognized by the lexer.

space_set = (source)

Set of whitespace characters recognized by the lexer.

def _context_around(s: str, pos: int) -> str: (source)

Build a human-friendly context string around a parse error.

Parameters
s:strSource string.
pos:intError position within s.
Returns
strContext string with an error mark.
def _groups_before_dot(tokens: list[Token]) -> list[bool]: (source)

Find the groups that a dot follows.

Parameters
tokens:list[Token]Tokens of the mask.
Returns
list[bool]One value for each token. The value is true for the opening parenthesis of such a group.
def _parse(source: str, max_steps: int) -> Mask: (source)

Parse a mask string with an explicit limit for the number of steps.

Parameters
source:strMask string to parse.
max_steps:intMaximum number of steps.
Returns
MaskParsed Mask.
Raises
ParseErrorIf the input is malformed or needs too many steps.
def _possible_ellipsis(s: str, max_context: int) -> str: (source)

Return a truncated string with an ellipsis when needed.

Parameters
s:strSource string.
max_context:intMaximum length to return.
Returns
strPossibly truncated string.
_parse_steps_per_char: int = (source)

Number of steps that parse permits for each character of the input.