Skip to content

Types

cifflow.types

Core types shared across all cifflow layers.

CifVersion

Bases: Enum

CIF specification version indicated by the #\CIF_x.x magic header.

Attributes:

Name Type Description
CIF_1_1

CIF 1.1 specification.
CIF_2_0

CIF 2.0 specification.
Source code in src/cifflow/types.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
class CifVersion(Enum):
    r"""CIF specification version indicated by the ``#\CIF_x.x`` magic header.

    Attributes
    ----------
    CIF_1_1
        CIF 1.1 specification.
    CIF_2_0
        CIF 2.0 specification.
    """

    CIF_1_1 = "1.1"
    CIF_2_0 = "2.0"

ValueType

Bases: Enum

Lexer-assigned encoding category for a CIF value.

Assigned by the lexer only; never modified downstream.

Attributes:

Name Type Description
MULTILINE_STRING

Semicolon-delimited multi-line text field.
TRIPLE_DOUBLE_QUOTED

Triple double-quoted string (CIF 2.0).
TRIPLE_SINGLE_QUOTED

Triple single-quoted string (CIF 2.0).
DOUBLE_QUOTED

Double-quoted string.
SINGLE_QUOTED

Single-quoted string.
STRING

Bare (unquoted) string.
PLACEHOLDER

Bare . (inapplicable) or ? (unknown).
Source code in src/cifflow/types.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
class ValueType(Enum):
    """Lexer-assigned encoding category for a CIF value.

    Assigned by the lexer only; never modified downstream.

    Attributes
    ----------
    MULTILINE_STRING
        Semicolon-delimited multi-line text field.
    TRIPLE_DOUBLE_QUOTED
        Triple double-quoted string (CIF 2.0).
    TRIPLE_SINGLE_QUOTED
        Triple single-quoted string (CIF 2.0).
    DOUBLE_QUOTED
        Double-quoted string.
    SINGLE_QUOTED
        Single-quoted string.
    STRING
        Bare (unquoted) string.
    PLACEHOLDER
        Bare ``.`` (inapplicable) or ``?`` (unknown).
    """

    MULTILINE_STRING     = "multiline_string"
    TRIPLE_DOUBLE_QUOTED = "triple_double_quoted"
    TRIPLE_SINGLE_QUOTED = "triple_single_quoted"
    DOUBLE_QUOTED        = "double_quoted"
    SINGLE_QUOTED        = "single_quoted"
    STRING               = "string"
    PLACEHOLDER          = "placeholder"

TokenType

Bases: Enum

Lexer token classification used in parser trace events.

Source code in src/cifflow/types.py 
55
56
57
58
59
60
class TokenType(Enum):
    """Lexer token classification used in parser trace events."""

    TAG     = "tag"
    KEYWORD = "keyword"
    VALUE   = "value"

ParseError dataclass

Parse error event emitted when the parser encounters malformed input.

Attributes:

Name Type Description
error_type Literal['lexical', 'syntactic', 'semantic']

Category of error: "lexical", "syntactic", or "semantic".
message str

Human-readable description of the error.
line int

1-based line number where the error was detected.
column int

1-based column number where the error was detected.
context str

Raw source text surrounding the error location.
recovery_action str

Description of how the parser recovered and continued.
Source code in src/cifflow/types.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
@dataclass
class ParseError:
    """Parse error event emitted when the parser encounters malformed input.

    Attributes
    ----------
    error_type
        Category of error: ``"lexical"``, ``"syntactic"``, or ``"semantic"``.
    message
        Human-readable description of the error.
    line
        1-based line number where the error was detected.
    column
        1-based column number where the error was detected.
    context
        Raw source text surrounding the error location.
    recovery_action
        Description of how the parser recovered and continued.
    """

    error_type:      Literal["lexical", "syntactic", "semantic"]
    message:         str
    line:            int
    column:          int
    context:         str
    recovery_action: str

CifParserEvents

Bases: Protocol

Protocol that a CIF event handler must implement.

The parser calls these methods in file order as tokens are consumed. Implement this protocol to accumulate CIF content from a stream of events.

Source code in src/cifflow/types.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
class CifParserEvents(Protocol):
    """Protocol that a CIF event handler must implement.

    The parser calls these methods in file order as tokens are consumed.
    Implement this protocol to accumulate CIF content from a stream of events.
    """

    def on_data_block(self, name: str) -> None:
        """Begin a new data block.

        Parameters
        ----------
        name
            The data block name (without the ``data_`` prefix).
        """
        ...

    def on_save_frame_start(self, name: str) -> None:
        """Begin a save frame.

        Parameters
        ----------
        name
            The save frame name (without the ``save_`` prefix).
        """
        ...

    def on_save_frame_end(self) -> None:
        """Close the current save frame."""
        ...

    def add_tag(self, tag_name: str) -> None:
        """Register a tag name; the next ``add_value`` call supplies its value.

        Parameters
        ----------
        tag_name
            Fully qualified CIF tag, e.g. ``_cell.length_a``.
        """
        ...

    def add_value(self, value: str, value_type: ValueType) -> None:
        """Supply the value for the most recently registered tag.

        Parameters
        ----------
        value
            Raw string value exactly as it appeared in the source file.
        value_type
            Lexer-assigned encoding category for the value.
        """
        ...

    def on_list_start(self) -> None:
        """Begin a CIF 2.0 list value."""
        ...

    def on_list_end(self) -> None:
        """Close the current CIF 2.0 list value."""
        ...

    def on_table_start(self) -> None:
        """Begin a CIF 2.0 table value."""
        ...

    def on_table_end(self) -> None:
        """Close the current CIF 2.0 table value."""
        ...

    def on_table_key(self, key: str, value_type: ValueType) -> None:
        """Supply the current table key; the next ``add_value`` call is its value.

        Parameters
        ----------
        key
            Raw key string as it appeared in the source file.
        value_type
            Lexer-assigned encoding category for the key.
        """
        ...

    def on_loop_start(self, tags: List[str]) -> None:
        """Begin a loop with the given ordered tag names.

        Parameters
        ----------
        tags
            Ordered list of fully qualified tag names in the loop header.
        """
        ...

    def on_loop_end(self) -> None:
        """Close the current loop."""
        ...

    def on_error(self, error: ParseError) -> None:
        """Deliver a parse error; the parser continues after recovery.

        Parameters
        ----------
        error
            Details of the error and the recovery action taken.
        """
        ...

on_data_block(name)

Begin a new data block.

Parameters:

Name Type Description Default
name str

The data block name (without the data_ prefix).

 required
Source code in src/cifflow/types.py 
 98
 99
100
101
102
103
104
105
106
def on_data_block(self, name: str) -> None:
    """Begin a new data block.

    Parameters
    ----------
    name
        The data block name (without the ``data_`` prefix).
    """
    ...

on_save_frame_start(name)

Begin a save frame.

Parameters:

Name Type Description Default
name str

The save frame name (without the save_ prefix).

 required
Source code in src/cifflow/types.py 
108
109
110
111
112
113
114
115
116
def on_save_frame_start(self, name: str) -> None:
    """Begin a save frame.

    Parameters
    ----------
    name
        The save frame name (without the ``save_`` prefix).
    """
    ...

on_save_frame_end()

Close the current save frame.

Source code in src/cifflow/types.py 
118
119
120
def on_save_frame_end(self) -> None:
    """Close the current save frame."""
    ...

add_tag(tag_name)

Register a tag name; the next add_value call supplies its value.

Parameters:

Name Type Description Default
tag_name str

Fully qualified CIF tag, e.g. _cell.length_a.

 required
Source code in src/cifflow/types.py 
122
123
124
125
126
127
128
129
130
def add_tag(self, tag_name: str) -> None:
    """Register a tag name; the next ``add_value`` call supplies its value.

    Parameters
    ----------
    tag_name
        Fully qualified CIF tag, e.g. ``_cell.length_a``.
    """
    ...

add_value(value, value_type)

Supply the value for the most recently registered tag.

Parameters:

Name Type Description Default
value str

Raw string value exactly as it appeared in the source file.

 required
value_type ValueType

Lexer-assigned encoding category for the value.

 required
Source code in src/cifflow/types.py 
132
133
134
135
136
137
138
139
140
141
142
def add_value(self, value: str, value_type: ValueType) -> None:
    """Supply the value for the most recently registered tag.

    Parameters
    ----------
    value
        Raw string value exactly as it appeared in the source file.
    value_type
        Lexer-assigned encoding category for the value.
    """
    ...

on_list_start()

Begin a CIF 2.0 list value.

Source code in src/cifflow/types.py 
144
145
146
def on_list_start(self) -> None:
    """Begin a CIF 2.0 list value."""
    ...

on_list_end()

Close the current CIF 2.0 list value.

Source code in src/cifflow/types.py 
148
149
150
def on_list_end(self) -> None:
    """Close the current CIF 2.0 list value."""
    ...

on_table_start()

Begin a CIF 2.0 table value.

Source code in src/cifflow/types.py 
152
153
154
def on_table_start(self) -> None:
    """Begin a CIF 2.0 table value."""
    ...

on_table_end()

Close the current CIF 2.0 table value.

Source code in src/cifflow/types.py 
156
157
158
def on_table_end(self) -> None:
    """Close the current CIF 2.0 table value."""
    ...

on_table_key(key, value_type)

Supply the current table key; the next add_value call is its value.

Parameters:

Name Type Description Default
key str

Raw key string as it appeared in the source file.

 required
value_type ValueType

Lexer-assigned encoding category for the key.

 required
Source code in src/cifflow/types.py 
160
161
162
163
164
165
166
167
168
169
170
def on_table_key(self, key: str, value_type: ValueType) -> None:
    """Supply the current table key; the next ``add_value`` call is its value.

    Parameters
    ----------
    key
        Raw key string as it appeared in the source file.
    value_type
        Lexer-assigned encoding category for the key.
    """
    ...

on_loop_start(tags)

Begin a loop with the given ordered tag names.

Parameters:

Name Type Description Default
tags List[str]

Ordered list of fully qualified tag names in the loop header.

 required
Source code in src/cifflow/types.py 
172
173
174
175
176
177
178
179
180
def on_loop_start(self, tags: List[str]) -> None:
    """Begin a loop with the given ordered tag names.

    Parameters
    ----------
    tags
        Ordered list of fully qualified tag names in the loop header.
    """
    ...

on_loop_end()

Close the current loop.

Source code in src/cifflow/types.py 
182
183
184
def on_loop_end(self) -> None:
    """Close the current loop."""
    ...

on_error(error)

Deliver a parse error; the parser continues after recovery.

Parameters:

Name Type Description Default
error ParseError

Details of the error and the recovery action taken.

 required
Source code in src/cifflow/types.py 
186
187
188
189
190
191
192
193
194
def on_error(self, error: ParseError) -> None:
    """Deliver a parse error; the parser continues after recovery.

    Parameters
    ----------
    error
        Details of the error and the recovery action taken.
    """
    ...