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 | |
Parser helper tracking mask branches within a parenthesized level. |
| Class | |
Tokenizer for the field mask grammar. |
| Class | |
Parser state machine states. |
| Class | |
Single token with type, string value, and source position. |
| Class | |
Token kinds produced by Lexer. |
| Exception | |
Parse error that includes source context. |
| Exception | |
Raised when parsing fails. |
| Exception | |
Raised when a mask needs more steps than parse permits. |
| Function | parse |
Parse a mask string into a Mask tree. |
| Variable | context |
Number of characters to show before the error position. |
| Variable | error |
Combining enclosing square to mark error position in context. |
| Variable | max |
Maximum length of context to show in error messages. |
| Variable | simple |
Regex for full simple (unquoted) token strings. |
| Variable | simple |
Regex for simple (unquoted) token strings. |
| Variable | simple |
Regex for the start of simple (unquoted) token strings. |
| Variable | space |
Whitespace characters recognized by the lexer. |
| Variable | space |
Set of whitespace characters recognized by the lexer. |
| Function | _context |
Build a human-friendly context string around a parse error. |
| Function | _groups |
Find the groups that a dot follows. |
| Function | _parse |
Parse a mask string with an explicit limit for the number of steps. |
| Function | _possible |
Return a truncated string with an ellipsis when needed. |
| Variable | _parse |
Number of steps that parse permits for each character of the input. |
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:str | Mask string to parse. |
| Returns | |
Mask | Parsed Mask. Empty or whitespace-only strings yield an
empty mask. |
| Raises | |
TooComplexError | If the mask needs more steps than the limit. |
ParseError | If the input is malformed. |
Parse a mask string with an explicit limit for the number of steps.
| Parameters | |
source:str | Mask string to parse. |
maxint | Maximum number of steps. |
| Returns | |
Mask | Parsed Mask. |
| Raises | |
ParseError | If the input is malformed or needs too many steps. |