-
-
Notifications
You must be signed in to change notification settings - Fork 902
Expand file tree
/
Copy pathbcfxml.py
More file actions
298 lines (244 loc) · 10.9 KB
/
bcfxml.py
File metadata and controls
298 lines (244 loc) · 10.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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
53
54
55
56
57
58
59
60
61
62
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
89
90
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
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
"""BCF XML V3 handlers."""
from __future__ import annotations
import uuid
import warnings
import zipfile
from pathlib import Path
from typing import Any, NoReturn, Optional, TypeVar
import bcf.v3.model as mdl
from bcf.inmemory_zipfile import InMemoryZipFile, ZipFileInterface
from bcf.v3.document import DocumentsHandler
from bcf.v3.topic import TopicHandler
from bcf.xml_parser import AbstractXmlParserSerializer, XmlParserSerializer
T = TypeVar("T")
class BcfXml:
"""BCF XML handler."""
def __init__(
self, filename: Optional[Path] = None, xml_handler: Optional[AbstractXmlParserSerializer] = None
) -> None:
self._filename = filename
self._xml_handler = xml_handler or XmlParserSerializer()
self._version: Optional[mdl.Version] = None
self._project_info: Optional[mdl.ProjectInfo] = None
self._extensions: Optional[mdl.Extensions] = None
self._topics: Optional[dict[str, TopicHandler]] = None
self._documents: Optional[DocumentsHandler] = None
self._zip_file = self._load_zip_file()
def __enter__(self) -> BcfXml:
return self
def __exit__(self, *args: Any) -> None:
self.close()
def __del__(self) -> None:
self.close()
def close(self) -> None:
if self._zip_file:
self._zip_file.close()
def _load_zip_file(self) -> Optional[zipfile.ZipFile]:
return zipfile.ZipFile(self._filename) if self._filename else None
@property
def version(self) -> mdl.Version:
"""Bcf Version."""
if not self._version:
self._version = (
self._xml_handler.parse(self._zip_file.read("bcf.version"), mdl.Version)
if self._zip_file
else mdl.Version(version_id="3.0")
)
return self._version
@version.setter
def version(self, value: mdl.Version) -> None:
self._version = value
@property
def project_info(self) -> Optional[mdl.ProjectInfo]:
"""BCF project information."""
if not self._project_info and self._zip_file and zipfile.Path(self._zip_file, "project.bcfp").exists():
self._project_info = self._xml_handler.parse(self._zip_file.read("project.bcfp"), mdl.ProjectInfo)
return self._project_info
@project_info.setter
def project_info(self, value: Optional[mdl.ProjectInfo]) -> None:
self._project_info = value
@property
def project(self) -> Optional[mdl.Project]:
"""BCF project."""
return self.project_info.project if self.project_info else None
@property
def extensions(self) -> Optional[mdl.Extensions]:
"""BCF extensions."""
if not self._extensions and self._zip_file:
self._extensions = self._xml_handler.parse(self._zip_file.read("extensions.xml"), mdl.Extensions)
return self._extensions
@extensions.setter
def extensions(self, value: Optional[mdl.Extensions]) -> None:
self._extensions = value
@property
def topics(self) -> dict[str, TopicHandler]:
"""BCF topics."""
if self._topics is None:
self._topics = self._load_topics()
return self._topics
def _load_topics(self) -> dict[str, TopicHandler]:
topics = {}
if self._zip_file is None:
return topics
for topic_dir in zipfile.Path(self._zip_file).iterdir():
if not topic_dir.is_dir():
continue
markup_path = topic_dir.joinpath("markup.bcf")
if not markup_path.exists():
continue
topics[topic_dir.name] = TopicHandler(topic_dir, self._xml_handler)
return topics
@property
def documents(self) -> Optional[DocumentsHandler]:
"""Documents stored in the BCF file."""
if not self._documents and self._zip_file:
self._documents = DocumentsHandler.load(self._zip_file, self._xml_handler)
return self._documents
@classmethod
def load(cls, filename: Path, xml_handler: Optional[AbstractXmlParserSerializer] = None) -> Optional[BcfXml]:
"""
Create a BcfXml object from a file.
Args:
filename: Path to the file.
xml_handler: XML parser and serializer.
Returns:
A BcfXml object with the file contents.
Raises:
ValueError: If the file name is null or empty
"""
if not filename:
raise ValueError("filename is required")
xml_handler = xml_handler or XmlParserSerializer()
return cls(xml_handler=xml_handler, filename=filename)
@classmethod
def create_new(
cls,
project_name: Optional[str] = None,
extensions: Optional[mdl.Extensions] = None,
xml_handler: Optional[AbstractXmlParserSerializer] = None,
) -> BcfXml:
"""
Create a new BcfXml object.
Args:
project_name: The name of the project.
extensions: The Extension XML object. Defaults to an empty one.
xml_handler: XML parser and serializer.
Returns:
A new BcfXml object.
"""
instance = cls(xml_handler=xml_handler or XmlParserSerializer())
instance.project_info = mdl.ProjectInfo(project=mdl.Project(name=project_name, project_id=str(uuid.uuid4())))
instance.extensions = extensions or mdl.Extensions()
return instance
def save(self, filename: Optional[Path] = None, keep_open: bool = False) -> None:
"""Save the BCF file to the given filename."""
if not filename and not self._filename:
raise ValueError("No file name specified, cannot save BCF file.")
if filename:
self._filename = filename
with InMemoryZipFile(self._filename) as bcf_zip:
self._save_project(bcf_zip)
self._save_version(bcf_zip)
self._save_extensions(bcf_zip)
self._save_documents(bcf_zip)
self._save_topics(bcf_zip)
if keep_open:
self._zip_file = self._load_zip_file()
def _save_project(self, destination_zip: ZipFileInterface) -> None:
self._smart_save_xml(destination_zip, self._project_info, "project.bcfp")
def _save_version(self, destination_zip: ZipFileInterface) -> None:
if not self._version and self._zip_file:
destination_zip.writestr("bcf.version", self._zip_file.read("bcf.version"))
else:
self._save_xml(destination_zip, "bcf.version", self.version)
def _save_extensions(self, destination_zip: ZipFileInterface) -> None:
self._smart_save_xml(destination_zip, self._extensions, "extensions.xml")
def _smart_save_xml(self, destination_zip: ZipFileInterface, item: Any, target: str) -> None:
if item:
self._save_xml(destination_zip, target, item)
elif self._zip_file and zipfile.Path(self._zip_file, target).exists():
destination_zip.writestr(target, self._zip_file.read(target))
def _save_xml(self, destination_zip: ZipFileInterface, inner_file: str, xml_obj: Any) -> None:
destination_zip.writestr(inner_file, self._xml_handler.serialize(xml_obj))
def _save_documents(self, bcf_zip: ZipFileInterface) -> None:
if self.documents:
self.documents.save(bcf_zip)
def _save_topics(self, destination_zip: ZipFileInterface) -> None:
for topic_handler in self.topics.values():
topic_handler.save(destination_zip)
def add_topic(
self, title: str, description: str, author: str, topic_type: str = "", topic_status: str = ""
) -> TopicHandler:
"""
Add a new topic to the BCF.
Args:
title: The title of the topic.
description: The description of the topic.
author: The author of the topic.
topic_type: The type of the topic.
topic_status: The status of the topic.
Returns:
The newly created topic wrapped inside a TopicHandler object.
"""
topic_handler = TopicHandler.create_new(
title,
description,
author,
topic_type=topic_type,
topic_status=topic_status,
xml_handler=self._xml_handler,
)
self.topics[topic_handler.guid] = topic_handler
return topic_handler
def __eq__(self, other: object) -> bool | NoReturn:
return (
self.version == other.version
and self.project_info == other.project_info
and self.extensions == other.extensions
if isinstance(other, BcfXml)
else NotImplemented
)
# region Deprecated methods
def new_project(self) -> BcfXml:
"""Deprecated method."""
warnings.warn("new_project is deprecated, use create_new instead.", DeprecationWarning)
return self.create_new()
def get_project(self, _filepath: Optional[str] = None) -> Optional[mdl.Project]:
"""Deprecated method."""
warnings.warn("get_project is deprecated, use project_info.project instead.", DeprecationWarning)
return self.project
def edit_project(self) -> None:
"""Deprecated method."""
warnings.warn("edit_project is deprecated, there's no need to use it.", DeprecationWarning)
def save_project(self, filepath: Path) -> None:
"""Deprecated method."""
warnings.warn("save_project is deprecated, use save instead.", DeprecationWarning)
self.save(filepath)
def get_version(self) -> str:
warnings.warn("get_version is deprecated, use version.version_id instead.", DeprecationWarning)
return self.version.version_id
def edit_version(self) -> None:
"""Deprecated method."""
warnings.warn("edit_version is deprecated, there's no need to use it.", DeprecationWarning)
def get_topics(self) -> dict[str, TopicHandler]:
"""Deprecated method."""
warnings.warn("get_topics is deprecated, use topics instead.", DeprecationWarning)
return self.topics
def get_topic(self, guid: str) -> TopicHandler:
"""Return a topic by its GUID."""
warnings.warn("get_topic is deprecated, use topics[guid] instead", DeprecationWarning)
return self.topics[guid]
def get_header(self, guid: str) -> Optional[mdl.Header]:
"""Return the header of a Topic by its GUID."""
return self.topics[guid].header
def edit_topic(self) -> None:
"""Deprecated method."""
warnings.warn("edit_topic is deprecated, there's no need to use it.", DeprecationWarning)
def add_comment(self, _topic: mdl.Topic, _comment: Optional[mdl.Comment] = None) -> None:
"""Deprecated method."""
warnings.warn("add_comment is deprecated, use topics methods instead.", DeprecationWarning)
def edit_comment(self) -> None:
"""Deprecated method."""
warnings.warn("edit_comment is deprecated, there's no need to use it.", DeprecationWarning)
# TODO: deprecate other methods
# endregion