StrictDoc Documentation
strictdoc/backend/sdoc/models/document.py
Source file coverage
Path:
strictdoc/backend/sdoc/models/document.py
Lines:
375
Non-empty lines:
308
Non-empty lines covered with requirements:
308 / 308 (100.0%)
Functions:
32
Functions covered by requirements:
32 / 32 (100.0%)
1
"""
2
@relation(SDOC-SRS-98, SDOC-SRS-109, scope=file)
3
"""
4
 
5
from collections import defaultdict
6
from dataclasses import dataclass
7
from typing import DefaultDict, Dict, Generator, List, Optional, Set, Tuple
8
 
9
from strictdoc.backend.sdoc.document_reference import DocumentReference
10
from strictdoc.backend.sdoc.models.document_config import DocumentConfig
11
from strictdoc.backend.sdoc.models.document_grammar import (
12
    DocumentGrammar,
13
)
14
from strictdoc.backend.sdoc.models.document_view import DocumentView
15
from strictdoc.backend.sdoc.models.grammar_element import (
16
    GrammarElement,
17
    GrammarElementField,
18
    GrammarElementFieldMultipleChoice,
19
    GrammarElementFieldSingleChoice,
20
    GrammarElementFieldTag,
21
)
22
from strictdoc.backend.sdoc.models.model import (
23
    SDocDocumentFromFileIF,
24
    SDocDocumentIF,
25
    SDocElementIF,
26
    SDocNodeIF,
27
)
28
from strictdoc.backend.sdoc.models.node import (
29
    SDocNode,
30
    SDocNodeContext,
31
    SDocNodeField,
32
)
33
from strictdoc.core.document_meta import DocumentMeta
34
from strictdoc.helpers.auto_described import auto_described
35
from strictdoc.helpers.cast import assert_cast
36
from strictdoc.helpers.mid import MID
37
from strictdoc.helpers.ordered_set import OrderedSet
38
from strictdoc.helpers.string import tokenize
39
 
40
 
41
@dataclass
42
class SDocDocumentSearchIndex:
43
    document_index: DefaultDict[str, Set[str]]
44
    map_nodes_by_mid: Dict[str, Dict[str, str]]
45
 
46
    @classmethod
47
    def create_empty(cls) -> "SDocDocumentSearchIndex":
48
        return SDocDocumentSearchIndex(
49
            document_index=defaultdict(set), map_nodes_by_mid={}
50
        )
51
 
52
 
53
@auto_described
54
class SDocDocument(SDocDocumentIF):
55
    def __init__(
56
        self,
57
        mid: Optional[str],
58
        title: str,
59
        config: Optional[DocumentConfig],
60
        view: Optional[DocumentView],
61
        grammar: Optional[DocumentGrammar],
62
        section_contents: List[SDocElementIF],
63
        is_bundle_document: bool = False,
64
        autogen: bool = False,
65
    ) -> None:
66
        self.title: str = title
67
        self.reserved_title: str = title
68
        self.config: DocumentConfig = (
69
            config
70
            if config is not None
71
            else DocumentConfig.default_config(self)
72
        )
73
        self.view: DocumentView = (
74
            view if view is not None else DocumentView.create_default(self)
75
        )
76
        self.grammar: Optional[DocumentGrammar] = grammar
77
        self.section_contents: List[SDocElementIF] = section_contents
78
 
79
        self.is_bundle_document: bool = is_bundle_document
80
 
81
        self.fragments_from_files: List[SDocDocumentFromFileIF] = []
82
 
83
        self.ng_has_requirements = False
84
 
85
        self.meta: Optional[DocumentMeta] = None
86
 
87
        self.reserved_mid: MID = MID(mid) if mid is not None else MID.create()
88
        self.mid_permanent: bool = mid is not None
89
        self.included_documents: List[SDocDocumentIF] = []
90
        self.context: SDocNodeContext = SDocNodeContext()
91
 
92
        self.ng_including_document_reference: Optional[DocumentReference] = None
93
        self.ng_including_document_from_file: Optional[
94
            SDocDocumentFromFileIF
95
        ] = None
96
 
97
        self.search_index = SDocDocumentSearchIndex.create_empty()
98
        self.ng_source_content: Optional[str] = None
99
        self.ng_markdown_meta_style: Optional[str] = None
100
 
101
        # Specifies whether a node is created from text or autogenerated, e.g.,
102
        # from a JUnit XML test report or from reading source file comments.
103
        # The SDoc writer uses this property to decide whether it shall write
104
        # autogenerated code to disk.
105
        self.autogen: bool = autogen
106
 
107
    def get_total_size(self) -> Tuple[int, int, int]:
108
        """
109
        Calculate the how many nodes a given document contains.
110
 
111
        The returned value is a tuple:
112
        (total nodes, normative nodes, non-normative nodes)
113
        """
114
        if self.section_contents is None or len(self.section_contents) == 0:
115
            return 0, 0, 0
116
        total_size = 0, 0, 0
117
        for node_ in self.section_contents:
118
            if isinstance(node_, SDocNode):
119
                node_total_size = node_.get_total_size()
120
                total_size = (
121
                    total_size[0] + node_total_size[0],
122
                    total_size[1] + node_total_size[1],
123
                    total_size[2] + node_total_size[2],
124
                )
125
        return total_size
126
 
127
    def iterate_nodes(
128
        self, element_type: Optional[str] = None
129
    ) -> Generator[SDocNodeIF, None, None]:
130
        """
131
        Iterate over all non-[TEXT] nodes in the document.
132
 
133
        If element_type is given, then only nodes of type `element_type` are
134
        returned. Otherwise, all element types are returned.
135
        """
136
        task_list: List[SDocElementIF] = list(self.section_contents)
137
        while task_list:
138
            node = task_list.pop(0)
139
 
140
            if isinstance(node, SDocDocumentFromFileIF):
141
                yield from node.iterate_nodes(element_type)
142
 
143
            if isinstance(node, SDocNodeIF):
144
                if node.node_type != "TEXT":
145
                    if element_type is None or node.node_type == element_type:
146
                        yield node
147
 
148
            task_list.extend(node.section_contents)
149
 
150
    def has_any_requirements(self) -> bool:
151
        return any(True for _ in self.iterate_nodes())
152
 
153
    def collect_options_for_tag(
154
        self, element_type: str, field_name: str
155
    ) -> List[str]:
156
        """
157
        Returns the list of existing options for a tag field in this document.
158
        """
159
        option_set: OrderedSet[str] = OrderedSet()
160
 
161
        for nodeif in self.iterate_nodes(element_type):
162
            node = assert_cast(nodeif, SDocNode)
163
            if field_name in node.ordered_fields_lookup:
164
                node_field = node.ordered_fields_lookup[field_name][0]
165
                field_value = node_field.get_text_value()
166
                if field_value:
167
                    options = [
168
                        option.strip()
169
                        for option in field_value.split(",")
170
                        if option.strip()
171
                    ]
172
                    for option in options:
173
                        option_set.add(option)
174
 
175
        return list(option_set)
176
 
177
    @property
178
    def uid(self) -> Optional[str]:
179
        return self.config.uid
180
 
181
    @property
182
    def is_root_included_document(self) -> bool:
183
        return self.document_is_included()
184
 
185
    def is_requirement(self) -> bool:
186
        return False
187
 
188
    def is_document(self) -> bool:
189
        return True
190
 
191
    def get_display_node_type(self) -> str:
192
        return "Document"
193
 
194
    def get_node_type_string(self) -> Optional[str]:
195
        return None
196
 
197
    def get_type_string(self) -> str:
198
        return "document" if not self.document_is_included() else "section"
199
 
200
    def get_debug_info(self) -> str:
201
        debug_components: List[str] = [f"TITLE = '{self.title}'"]
202
        if self.meta is not None:
203
            debug_components.append(
204
                f" ({self.meta.input_doc_rel_path.relative_path})"
205
            )
206
        return f"Document({', '.join(debug_components)})"
207
 
208
    def document_is_included(self) -> bool:
209
        if self.ng_including_document_reference is None:
210
            return False
211
        return self.ng_including_document_reference.get_document() is not None
212
 
213
    def get_including_document(self) -> Optional["SDocDocumentIF"]:
214
        if self.ng_including_document_reference is None:
215
            return None
216
        return self.ng_including_document_reference.get_document()
217
 
218
    def iterate_included_documents_depth_first(
219
        self,
220
    ) -> Generator["SDocDocumentIF", None, None]:
221
        for included_document_ in self.included_documents:
222
            yield included_document_
223
            yield from included_document_.iterate_included_documents_depth_first()
224
 
225
    @property
226
    def reserved_uid(self) -> Optional[str]:
227
        return self.config.uid
228
 
229
    def assign_meta(self, meta: DocumentMeta) -> None:
230
        assert isinstance(meta, DocumentMeta)
231
        self.meta = meta
232
 
233
    def has_any_nodes(self) -> bool:
234
        return len(self.section_contents) > 0
235
 
236
    def get_display_title(
237
        self,
238
        include_toc_number: bool = True,  # noqa: ARG002
239
    ) -> str:
240
        return self.title
241
 
242
    @property
243
    def ng_resolved_custom_level(self) -> Optional[str]:
244
        return None
245
 
246
    @property
247
    def requirement_prefix(self) -> str:
248
        return self.get_prefix()
249
 
250
    def get_prefix(self) -> str:
251
        return self.config.get_prefix()
252
 
253
    def get_prefix_for_new_node(self, node_type: str) -> Optional[str]:
254
        assert isinstance(node_type, str) and len(node_type), node_type
255
 
256
        grammar: DocumentGrammar = assert_cast(self.grammar, DocumentGrammar)
257
        element: GrammarElement = grammar.elements_by_type[node_type]
258
        if (element_prefix := element.property_prefix) is not None:
259
            if element_prefix == "None":
260
                return None
261
            return element_prefix
262
 
263
        return self.get_prefix()
264
 
265
    def enumerate_table_meta_field_titles(self) -> Generator[str, None, None]:
266
        assert self.grammar is not None
267
        assert self.grammar.elements is not None
268
        seen: Set[str] = set()
269
        for element in self.grammar.elements:
270
            for title in element.enumerate_table_meta_field_titles():
271
                if title not in seen:
272
                    seen.add(title)
273
                    yield title
274
 
275
    def enumerate_table_non_reserved_content_field_titles(
276
        self,
277
    ) -> Generator[str, None, None]:
278
        assert self.grammar is not None
279
        assert self.grammar.elements is not None
280
        seen: Set[str] = set()
281
        for element in self.grammar.elements:
282
            for (
283
                title
284
            ) in element.enumerate_table_non_reserved_content_field_titles():
285
                if title not in seen:
286
                    seen.add(title)
287
                    yield title
288
 
289
    def get_grammar_element_field_for(
290
        self, element_type: str, field_name: str
291
    ) -> GrammarElementField:
292
        """
293
        Returns the GrammarElementField for a field of a [element_type] in this document.
294
        """
295
        grammar: DocumentGrammar = assert_cast(self.grammar, DocumentGrammar)
296
        element: GrammarElement = grammar.elements_by_type[element_type]
297
        field: GrammarElementField = element.fields_map[field_name]
298
        return field
299
 
300
    def get_options_for_field(
301
        self, element_type: str, field_name: str
302
    ) -> List[str]:
303
        """
304
        Returns the list of valid options for a Single/MultiChoice field in this document.
305
        """
306
        field: GrammarElementField = self.get_grammar_element_field_for(
307
            element_type, field_name
308
        )
309
 
310
        if isinstance(field, GrammarElementFieldSingleChoice) or isinstance(
311
            field, GrammarElementFieldMultipleChoice
312
        ):
313
            return field.options
314
 
315
        if isinstance(field, GrammarElementFieldTag):
316
            return self.collect_options_for_tag(element_type, field_name)
317
 
318
        raise AssertionError(f"Must not reach here: {field}")
319
 
320
    def build_search_index(self) -> None:
321
        """
322
        Build a static search index for this document.
323
 
324
        @relation(SDOC-SRS-155, scope=function)
325
        """
326
 
327
        document_index = defaultdict(set)
328
        map_nodes_by_mid = {}
329
 
330
        from strictdoc.core.document_iterator import (  # noqa: PLC0415
331
            SDocDocumentIterator,
332
        )
333
 
334
        document_iterator = SDocDocumentIterator(self)
335
 
336
        for node, _ in document_iterator.all_content(
337
            print_fragments=False,
338
        ):
339
            if not isinstance(node, SDocNode):
340
                continue
341
 
342
            node_dict = {}
343
 
344
            node_dict["MID"] = node.reserved_mid.get_string_value()
345
            map_nodes_by_mid[node.reserved_mid.get_string_value()] = node_dict
346
 
347
            for (
348
                field_name_,
349
                field_values_,
350
            ) in node.ordered_fields_lookup.items():
351
                requirement_field: SDocNodeField = field_values_[0]
352
                requirement_field_value = requirement_field.get_text_value()
353
 
354
                node_dict[field_name_] = requirement_field_value
355
 
356
                tokens = set(tokenize(requirement_field_value))
357
                for token in tokens:
358
                    if len(token) > 1:
359
                        document_index[token].add(
360
                            node.reserved_mid.get_string_value()
361
                        )
362
 
363
                        for i in range(0, len(token)):
364
                            token_incremental = token[: i + 1]
365
                            document_index[token_incremental].add(
366
                                node.reserved_mid
367
                            )
368
                            token_deincremental = token[i:]
369
                            document_index[token_deincremental].add(
370
                                node.reserved_mid
371
                            )
372
 
373
        self.search_index = SDocDocumentSearchIndex(
374
            document_index, map_nodes_by_mid
375
        )
1 - 375 | entire file