Token¶
Token-level annotations
module-attribute
¶
ConstraintExpr = Union[
AnnotationConstraint,
IntegerRangeConstraint,
FunctionConstraint,
NotConstraint,
BoolConstraint,
]
Discriminated union of token-level constraint expressions.
Represents any constraint that can appear in a token query [...]:
- AnnotationConstraint: annotation comparison (e.g., word="man")
- IntegerRangeConstraint: integer range (e.g., confidence=in[50,100])
- FunctionConstraint: function call (e.g., pos_confidence(...))
- NotConstraint: negation (e.g., !(pos="noun"))
- BoolConstraint: AND/OR/implication (e.g., pos="noun" | pos="verb")
Bases: BCQLNode
A quoted string value inside a BCQL query.
Handles regular strings, literal strings (prefixed with l), and
sensitivity flags ((?-i) for sensitive, (?i) for insensitive).
Attributes:
| Name | Type | Description |
|---|---|---|
value |
str
|
The raw string content (without surrounding quotes). |
is_literal |
bool
|
|
sensitivity |
Literal['default', 'sensitive', 'insensitive']
|
|
Example::
StringValue(value="(?-i)Panama").to_bcql()
# '"(?-i)Panama"'
Return this string value in BCQL syntax.
View source on GitHub: src/bcql_py/models/token.py lines 58–62
Bases: BCQLNode
A single annotation comparison: annotation op "value".
Typically between an identifier, an operator, and a string value.
Note that the identifier is not semantically specified here! It fully depends
on the corpus which attributes (like word, lemma, pos) are available. So here
annotation is underspecified as just a string.
Example: word="man" or pos != "noun".
Attributes:
| Name | Type | Description |
|---|---|---|
annotation |
str
|
The annotation name (e.g. |
operator |
Literal['=', '!=', '<', '<=', '>', '>=']
|
|
value |
StringValue
|
The value being compared against. |
Return this annotation constraint in BCQL syntax.
View source on GitHub: src/bcql_py/models/token.py lines 89–91
Bases: BCQLNode
An integer range constraint, such as a parser's confidence: confidence=in[min,max].
Example: pos_confidence=in[50,100].
Note that we require both min and max vals to be given. No implicit "infinite" or "zero" bounds.
Attributes:
| Name | Type | Description |
|---|---|---|
annotation |
str
|
The annotation name. |
min_val |
int
|
Inclusive lower bound. |
max_val |
int
|
Inclusive upper bound. |
Return this integer range constraint in BCQL syntax.
View source on GitHub: src/bcql_py/models/token.py lines 112–114
Bases: BCQLNode
A function-call constraint inside token brackets.
TODO: check for predefined functions in blacklab?
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The function / pseudo-annotation name. |
args |
list[StringValue]
|
The string arguments to the function. |
Return this function constraint in BCQL syntax.
View source on GitHub: src/bcql_py/models/token.py lines 131–134
Bases: BCQLNode
Logical NOT on a token-level constraint: !expr.
Typically for a capture group: !(pos="noun" | pos="verb").
Attributes:
| Name | Type | Description |
|---|---|---|
operand |
ConstraintExpr
|
The constraint being negated. |
Return this negated token constraint in BCQL syntax.
View source on GitHub: src/bcql_py/models/token.py lines 149–155
Bases: BCQLNode
Boolean combination of token-level constraints: left op right.
The operator is & (AND), | (OR), or -> (implication). Per the BCQL spec / Bcql.g4,
all three share identical precedence and are left-associative. See the booleanOperator rule
in Bcql.g4. Naming-wise calling it "boolean" might be somewhat confusing for the implication case though
Not to be confused with sequence-level boolean operators (also &, |, and ->) which
combine whole sub-queries instead of token constraints. See sequence.SequenceBoolNode for those.
Attributes:
| Name | Type | Description |
|---|---|---|
operator |
Literal['&', '|', '->']
|
|
left |
ConstraintExpr
|
Left operand. |
right |
ConstraintExpr
|
Right operand. |
Return this boolean token constraint in BCQL syntax.
View source on GitHub: src/bcql_py/models/token.py lines 181–183
Bases: BCQLNode
A single token query: [...], "string" shorthand, or [].
Attributes:
| Name | Type | Description |
|---|---|---|
constraint |
ConstraintExpr | None
|
The constraint expression inside the brackets, or
|
negated |
bool
|
|
shorthand |
StringValue | None
|
When the query was written as a bare string like
|
Return this token query in BCQL syntax.
View source on GitHub: src/bcql_py/models/token.py lines 236–244