1import json
2from importlib import resources
3from typing import Dict, Any, List
4
5resource_package = __name__
6
7
[docs]
8class ThreatrMappingLoader:
9 """
10 Loads and provides access to the Threatr to Colander mapping data.
11
12 This class is responsible for loading the mapping configuration from a JSON file
13 that defines how Threatr entities, events, and relations should be converted to
14 their Colander equivalents. The mapping data includes field mappings, type
15 conversions, and relationship definitions.
16
17 Note:
18 The mapping data is loaded once during initialization and cached for
19 subsequent use.
20
21 Attributes:
22 mapping_data (List[Dict[str, Any]]): The loaded mapping data
23
24 Example:
25 >>> loader = ThreatrMappingLoader()
26 >>> mappings = loader.mapping_data
27 >>> isinstance(mappings, list)
28 True
29 """
30
[docs]
31 def __init__(self):
32 """
33 Initialize the mapping loader and load the mapping data.
34
35 Raises:
36 ValueError: If the mapping file cannot be found or parsed
37 """
38 self.mapping_data = self._load_mapping_data()
39
40 @staticmethod
41 def _load_mapping_data() -> List[Dict[str, Any]]:
42 """
43 Load the mapping data from the JSON file.
44
45 This method reads the mapping configuration from the JSON file located at
46 ``data/threatr_colander_mapping.json`` relative to this module's package.
47
48 Returns:
49 List[Dict[str, Any]]: The mapping data loaded from the JSON file
50
51 Raises:
52 ValueError: If the file cannot be found or contains invalid JSON
53 FileNotFoundError: If the mapping file does not exist
54 json.JSONDecodeError: If the mapping file contains malformed JSON
55
56 Important:
57 The JSON file must contain a root object with a "mapping" key that holds
58 an array of mapping definitions.
59 """
60 json_file = resources.files(resource_package).joinpath("data").joinpath("threatr_colander_mapping.json")
61 try:
62 with json_file.open() as f:
63 return json.load(f).get("mapping")
64 except (FileNotFoundError, json.JSONDecodeError) as e:
65 raise ValueError(f"Failed to load mapping data: {e}")
66
67
[docs]
68class ThreatrMapper:
69 """
70 Base class for mapping between Threatr and Colander data using the mapping file.
71
72 This abstract base class provides common functionality for all Threatr to Colander
73 mappers. It initializes the mapping loader and provides access to the mapping
74 data that defines how different data formats should be converted between the
75 two systems.
76
77 Attributes:
78 mapping_loader (ThreatrMappingLoader): Instance of ThreatrMappingLoader for accessing mapping data
79
80 Note:
81 This is a base class that should be subclassed by specific mapper
82 implementations. The mapping data is loaded once and shared across
83 all mapper instances.
84
85 Example:
86 >>> class CustomMapper(ThreatrMapper):
87 ... def __init__(self):
88 ... super().__init__()
89 ...
90 >>> mapper = CustomMapper()
91 >>> hasattr(mapper, 'mapping_loader')
92 True
93 """
94
[docs]
95 def __init__(self):
96 """
97 Initialize the mapper with the mapping loader.
98
99 Creates an instance of ThreatrMappingLoader to provide access to the
100 mapping configuration data. This data will be used by subclasses to
101 perform the actual conversion between Threatr and Colander formats.
102 """
103 self.mapping_loader = ThreatrMappingLoader()