Span

bcql_py.models.span

XML span models

SpanQuery

Bases: BCQLNode

A span (XML tag) query.

Three forms exist per Bcql.g4's tag rule: - Whole span: <s/> or <ne type="PERS"/> - Start tag: <s> - End tag: </s>

The tag name can be a plain identifier (s, ne) or a quoted string for regex patterns (<"person|location"/>).

Attributes:

Name	Type	Description
tag_name	str | StringValue	The tag name as a plain string or StringValue for regex.
position	Literal['whole', 'start', 'end']	"whole" for <s/>, "start" for <s>, "end" for </s>.
attributes	dict[str, StringValue]	XML attributes as name: StringValue pairs (e.g. type="PERS").

PositionFilterNode

Bases: BCQLNode

A position-filter operator: within, containing, or overlap.

Example: "baker" within <person/> means find "baker" inside a <person/> span.

These operators are right-associative, so A within B within C is parsed as A within (B within C).

Attributes:

Name	Type	Description
operator	Literal['within', 'containing', 'overlap']	One of "within", "containing", "overlap".
left	BCQLNodeUnion	The query whose hits are filtered.
right	BCQLNodeUnion	The span/query that defines the positional constraint.