src/pypdf/xmp.py
1"""
2Anything related to Extensible Metadata Platform (XMP) metadata.
3
4https://en.wikipedia.org/wiki/Extensible_Metadata_Platform
5"""
6
7import datetime
8import decimal
9import re
10from collections.abc import Callable, Iterator
11from string import hexdigits
12from typing import (
13 Any,
14 NoReturn,
15 TypeVar,
16 cast,
17)
18from xml.dom.expatbuilder import ExpatBuilderNS
19from xml.dom.minidom import Document, ProcessingInstruction
20from xml.dom.minidom import Element as XmlElement
21from xml.dom.xmlbuilder import Options
22from xml.parsers.expat import ExpatError, XMLParserType
23
24from ._configuration import get_configuration
25from ._utils import StreamType, deprecation_with_replacement
26from .errors import LimitReachedError, PdfReadError, XmpDocumentError
27from .generic import ContentStream, PdfObject, StreamObject
28
29XMP_MAX_INPUT_LENGTH = 5_000_000 # DEPRECATED: Use pypdf.Configuration.
30XMP_MAX_ELEMENT_COUNT = 100_000 # DEPRECATED: Use pypdf.Configuration.
31
32RDF_NAMESPACE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
33DC_NAMESPACE = "http://purl.org/dc/elements/1.1/"
34XMP_NAMESPACE = "http://ns.adobe.com/xap/1.0/"
35PDF_NAMESPACE = "http://ns.adobe.com/pdf/1.3/"
36XMPMM_NAMESPACE = "http://ns.adobe.com/xap/1.0/mm/"
37
38# What is the PDFX namespace, you might ask?
39# It's documented here: https://github.com/adobe/xmp-docs/raw/master/XMPSpecifications/XMPSpecificationPart3.pdf
40# This namespace is used to place "custom metadata"
41# properties, which are arbitrary metadata properties with no semantic or
42# documented meaning.
43#
44# Elements in the namespace are key/value-style storage,
45# where the element name is the key and the content is the value. The keys
46# are transformed into valid XML identifiers by substituting an invalid
47# identifier character with \u2182 followed by the unicode hex ID of the
48# original character. A key like "my car" is therefore "my\u21820020car".
49#
50# \u2182 is the unicode character \u{ROMAN NUMERAL TEN THOUSAND}
51#
52# The pdfx namespace should be avoided.
53# A custom data schema and sensical XML elements could be used instead, as is
54# suggested by Adobe's own documentation on XMP under "Extensibility of
55# Schemas".
56PDFX_NAMESPACE = "http://ns.adobe.com/pdfx/1.3/"
57
58# PDF/A
59PDFAID_NAMESPACE = "http://www.aiim.org/pdfa/ns/id/"
60
61# Internal mapping of namespace URI → prefix
62_NAMESPACE_PREFIX_MAP = {
63 DC_NAMESPACE: "dc",
64 XMP_NAMESPACE: "xmp",
65 PDF_NAMESPACE: "pdf",
66 XMPMM_NAMESPACE: "xmpMM",
67 PDFAID_NAMESPACE: "pdfaid",
68 PDFX_NAMESPACE: "pdfx",
69}
70
71iso8601 = re.compile(
72 """
73 (?P<year>[0-9]{4})
74 (-
75 (?P<month>[0-9]{2})
76 (-
77 (?P<day>[0-9]+)
78 (T
79 (?P<hour>[0-9]{2}):
80 (?P<minute>[0-9]{2})
81 (:(?P<second>[0-9]{2}(.[0-9]+)?))?
82 (?P<tzd>Z|[-+][0-9]{2}:[0-9]{2})
83 )?
84 )?
85 )?
86 """,
87 re.VERBOSE,
88)
89
90
91K = TypeVar("K")
92
93# Minimal XMP template
94_MINIMAL_XMP = f"""<?xpacket begin="\ufeff" id="W5M0MpCehiHzreSzNTczkc9d"?>
95<x:xmpmeta xmlns:x="adobe:ns:meta/" x:xmptk="pypdf">
96 <rdf:RDF xmlns:rdf="{RDF_NAMESPACE}">
97 <rdf:Description rdf:about=""
98 xmlns:dc="{DC_NAMESPACE}"
99 xmlns:xmp="{XMP_NAMESPACE}"
100 xmlns:pdf="{PDF_NAMESPACE}"
101 xmlns:xmpMM="{XMPMM_NAMESPACE}"
102 xmlns:pdfaid="{PDFAID_NAMESPACE}"
103 xmlns:pdfx="{PDFX_NAMESPACE}">
104 </rdf:Description>
105 </rdf:RDF>
106</x:xmpmeta>
107<?xpacket end="r"?>"""
108
109
110def _identity(value: K) -> K:
111 return value
112
113
114def _converter_date(value: str) -> datetime.datetime:
115 matches = iso8601.match(value)
116 if matches is None:
117 raise ValueError(f"Invalid date format: {value}")
118 year = int(matches.group("year"))
119 month = int(matches.group("month") or "1")
120 day = int(matches.group("day") or "1")
121 hour = int(matches.group("hour") or "0")
122 minute = int(matches.group("minute") or "0")
123 second = decimal.Decimal(matches.group("second") or "0")
124 seconds_dec = second.to_integral(decimal.ROUND_FLOOR)
125 milliseconds_dec = (second - seconds_dec) * 1_000_000
126
127 seconds = int(seconds_dec)
128 milliseconds = int(milliseconds_dec)
129
130 tzd = matches.group("tzd") or "Z"
131 try:
132 dt = datetime.datetime(year, month, day, hour, minute, seconds, milliseconds)
133 except ValueError as exc:
134 raise ValueError(f"Invalid date {value!r}: {exc}") from exc
135 if tzd != "Z":
136 tzd_hours, tzd_minutes = (int(x) for x in tzd[1:].split(":"))
137 offset = datetime.timedelta(hours=tzd_hours, minutes=tzd_minutes)
138 dt = dt - offset if tzd.startswith("+") else dt + offset
139 return dt
140
141
142def _format_datetime_utc(value: datetime.datetime) -> str:
143 """Format a datetime as UTC with trailing 'Z'.
144
145 - If the input is timezone-aware, convert to UTC first.
146 - If naive, assume UTC.
147 """
148 if value.tzinfo is not None and value.utcoffset() is not None:
149 value = value.astimezone(datetime.timezone.utc)
150
151 value = value.replace(tzinfo=None)
152 return value.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
153
154
155def _generic_get(
156 element: XmlElement, self: "XmpInformation", list_type: str, converter: Callable[[Any], Any] = _identity
157) -> list[str] | None:
158 containers = element.getElementsByTagNameNS(RDF_NAMESPACE, list_type)
159 retval: list[Any] = []
160 if len(containers):
161 for container in containers:
162 for item in container.getElementsByTagNameNS(RDF_NAMESPACE, "li"):
163 value = self._get_text(item)
164 value = converter(value)
165 retval.append(value)
166 return retval
167 return None
168
169
170class _XmpBuilder(ExpatBuilderNS):
171 """
172 Custom XML parser denying all entity declarations.
173
174 This is a stripped down and typed version inspired by what *defusedxml* does.
175
176 Why do we need this? The default limits of *libexpat* used by Python only block exponential entity expansion,
177 but not cases like quadratic entity expansion which can still cause quite some memory usage.
178 """
179
180 def __init__(self, options: Options | None = None) -> None:
181 super().__init__(options=options)
182 self._element_count = 0
183 self._configuration = get_configuration()
184
185 def custom_entity_declaration_handler(
186 self,
187 entity_name: str,
188 # expat passes an int here rather than a bool, but typeshed declares
189 # the handler with a bool, so the annotation follows typeshed.
190 is_parameter_entity: bool,
191 value: str | None,
192 base: str | None,
193 system_id: str,
194 public_id: str | None,
195 notation_name: str | None,
196 ) -> None:
197 raise ExpatError(f"Forbidden entities: {entity_name!r}")
198
199 def start_element_handler(self, name: str, attributes: list[str]) -> None:
200 self._element_count += 1
201 if self._element_count > self._configuration.xmp_maximum_element_count:
202 raise LimitReachedError(
203 f"XMP metadata exceeds limit of {self._configuration.xmp_maximum_element_count} elements."
204 )
205 super().start_element_handler(name=name, attributes=attributes)
206
207 def install(self, parser: XMLParserType) -> None:
208 super().install(parser)
209
210 parser.EntityDeclHandler = self.custom_entity_declaration_handler
211 parser.StartElementHandler = self.start_element_handler
212
213
214class XmpInformation(PdfObject):
215 """
216 An object that represents Extensible Metadata Platform (XMP) metadata.
217 Usually accessed by :py:attr:`xmp_metadata()<pypdf.PdfReader.xmp_metadata>`.
218
219 Raises:
220 PdfReadError: if XML is invalid
221
222 """
223
224 def __init__(self, stream: StreamObject) -> None:
225 self.stream = stream
226 try:
227 data = self.stream.get_data()
228 configuration = get_configuration()
229 if (length := len(data)) > configuration.xmp_maximum_input_length:
230 raise LimitReachedError(
231 f"XMP stream size {length} exceeds limit of {configuration.xmp_maximum_input_length}."
232 )
233 doc_root: Document = _XmpBuilder().parseString(data)
234 except (AttributeError, ExpatError) as exception:
235 raise PdfReadError(f"XML in XmpInformation was invalid: {exception}") from exception
236 rdf_roots = doc_root.getElementsByTagNameNS(RDF_NAMESPACE, "RDF")
237 if not rdf_roots:
238 raise PdfReadError(
239 "XML in XmpInformation was invalid: Missing rdf:RDF root element"
240 )
241 self.rdf_root: XmlElement = rdf_roots[0]
242 self.cache: dict[Any, Any] = {}
243
244 @classmethod
245 def create(cls) -> "XmpInformation":
246 """
247 Create a new XmpInformation object with minimal structure.
248
249 Returns:
250 A new XmpInformation instance with empty metadata fields.
251 """
252 stream = ContentStream(None, None)
253 stream.set_data(_MINIMAL_XMP.encode("utf-8"))
254 return cls(stream)
255
256 def write_to_stream(self, stream: StreamType) -> NoReturn:
257 deprecation_with_replacement(
258 "XmpInformation.write_to_stream",
259 "PdfWriter.xmp_metadata",
260 "6.0.0"
261 )
262
263 def get_element(self, about_uri: str, namespace: str, name: str) -> Iterator[Any]:
264 for desc in self.rdf_root.getElementsByTagNameNS(RDF_NAMESPACE, "Description"):
265 if desc.getAttributeNS(RDF_NAMESPACE, "about") == about_uri:
266 attr = desc.getAttributeNodeNS(namespace, name)
267 if attr is not None:
268 yield attr
269 yield from desc.getElementsByTagNameNS(namespace, name)
270
271 def get_nodes_in_namespace(self, about_uri: str, namespace: str) -> Iterator[Any]:
272 for desc in self.rdf_root.getElementsByTagNameNS(RDF_NAMESPACE, "Description"):
273 if desc.getAttributeNS(RDF_NAMESPACE, "about") == about_uri:
274 for i in range(desc.attributes.length):
275 attr = desc.attributes.item(i)
276 if attr and attr.namespaceURI == namespace:
277 yield attr
278 for child in desc.childNodes:
279 if child.namespaceURI == namespace:
280 yield child
281
282 def _get_text(self, element: XmlElement) -> str:
283 text = ""
284 for child in element.childNodes:
285 if child.nodeType == child.TEXT_NODE:
286 text += child.data
287 return text
288
289 def _get_single_value(
290 self,
291 namespace: str,
292 name: str,
293 converter: Callable[[str], Any] = _identity,
294 ) -> Any | None:
295 cached = self.cache.get(namespace, {}).get(name)
296 if cached:
297 return cached
298 value = None
299 for element in self.get_element("", namespace, name):
300 if element.nodeType == element.ATTRIBUTE_NODE:
301 value = element.nodeValue
302 else:
303 value = self._get_text(element)
304 break
305 if value is not None:
306 value = converter(value)
307 ns_cache = self.cache.setdefault(namespace, {})
308 ns_cache[name] = value
309 return value
310
311 def _getter_bag(self, namespace: str, name: str) -> list[str] | None:
312 cached = self.cache.get(namespace, {}).get(name)
313 if cached:
314 return cast(list[str], cached)
315 retval: list[str] = []
316 for element in self.get_element("", namespace, name):
317 if (bags := _generic_get(element, self, list_type="Bag")) is not None:
318 retval.extend(bags)
319 else:
320 value = self._get_text(element)
321 retval.append(value)
322 ns_cache = self.cache.setdefault(namespace, {})
323 ns_cache[name] = retval
324 return retval
325
326 def _get_seq_values(
327 self,
328 namespace: str,
329 name: str,
330 converter: Callable[[Any], Any] = _identity,
331 ) -> list[Any] | None:
332 cached = self.cache.get(namespace, {}).get(name)
333 if cached:
334 return cast(list[Any], cached)
335 retval: list[Any] = []
336 for element in self.get_element("", namespace, name):
337 if (seqs := _generic_get(element, self, list_type="Seq", converter=converter)) is not None:
338 retval.extend(seqs)
339 elif (bags := _generic_get(element, self, list_type="Bag")) is not None:
340 # See issue at https://github.com/py-pdf/pypdf/issues/3324
341 # Some applications violate the XMP metadata standard regarding `dc:creator` which should
342 # be an "ordered array" and thus a sequence, but use an unordered array (bag) instead.
343 # This seems to stem from the fact that the original Dublin Core specification does indeed
344 # use bags or direct values, while PDFs are expected to follow the XMP standard and ignore
345 # the plain Dublin Core variant. For this reason, add a fallback here to deal with such
346 # issues accordingly.
347 retval.extend(bags)
348 else:
349 value = converter(self._get_text(element))
350 retval.append(value)
351 ns_cache = self.cache.setdefault(namespace, {})
352 ns_cache[name] = retval
353 return retval
354
355 def _get_langalt_values(self, namespace: str, name: str) -> dict[Any, Any] | None:
356 cached = self.cache.get(namespace, {}).get(name)
357 if cached:
358 return cast(dict[Any, Any], cached)
359 retval: dict[Any, Any] = {}
360 for element in self.get_element("", namespace, name):
361 alts = element.getElementsByTagNameNS(RDF_NAMESPACE, "Alt")
362 if len(alts):
363 for alt in alts:
364 for item in alt.getElementsByTagNameNS(RDF_NAMESPACE, "li"):
365 value = self._get_text(item)
366 retval[item.getAttribute("xml:lang")] = value
367 else:
368 retval["x-default"] = self._get_text(element)
369 ns_cache = self.cache.setdefault(namespace, {})
370 ns_cache[name] = retval
371 return retval
372
373 @property
374 def dc_contributor(self) -> list[str] | None:
375 """Contributors to the resource (other than the authors)."""
376 return self._getter_bag(DC_NAMESPACE, "contributor")
377
378 @dc_contributor.setter
379 def dc_contributor(self, values: list[str] | None) -> None:
380 self._set_bag_values(DC_NAMESPACE, "contributor", values)
381
382 @property
383 def dc_coverage(self) -> str | None:
384 """Text describing the extent or scope of the resource."""
385 return self._get_single_value(DC_NAMESPACE, "coverage")
386
387 @dc_coverage.setter
388 def dc_coverage(self, value: str | None) -> None:
389 self._set_single_value(DC_NAMESPACE, "coverage", value)
390
391 @property
392 def dc_creator(self) -> list[str] | None:
393 """A sorted array of names of the authors of the resource, listed in order of precedence."""
394 return self._get_seq_values(DC_NAMESPACE, "creator")
395
396 @dc_creator.setter
397 def dc_creator(self, values: list[str] | None) -> None:
398 self._set_seq_values(DC_NAMESPACE, "creator", values)
399
400 @property
401 def dc_date(self) -> list[datetime.datetime] | None:
402 """A sorted array of dates of significance to the resource. The dates and times are in UTC."""
403 return self._get_seq_values(DC_NAMESPACE, "date", _converter_date)
404
405 @dc_date.setter
406 def dc_date(self, values: list[str | datetime.datetime] | None) -> None:
407 if values is None:
408 self._set_seq_values(DC_NAMESPACE, "date", None)
409 else:
410 date_strings = []
411 for value in values:
412 if isinstance(value, datetime.datetime):
413 date_strings.append(_format_datetime_utc(value))
414 else:
415 date_strings.append(str(value))
416 self._set_seq_values(DC_NAMESPACE, "date", date_strings)
417
418 @property
419 def dc_description(self) -> dict[str, str] | None:
420 """A language-keyed dictionary of textual descriptions of the content of the resource."""
421 return self._get_langalt_values(DC_NAMESPACE, "description")
422
423 @dc_description.setter
424 def dc_description(self, values: dict[str, str] | None) -> None:
425 self._set_langalt_values(DC_NAMESPACE, "description", values)
426
427 @property
428 def dc_format(self) -> str | None:
429 """The mime-type of the resource."""
430 return self._get_single_value(DC_NAMESPACE, "format")
431
432 @dc_format.setter
433 def dc_format(self, value: str | None) -> None:
434 self._set_single_value(DC_NAMESPACE, "format", value)
435
436 @property
437 def dc_identifier(self) -> str | None:
438 """Unique identifier of the resource."""
439 return self._get_single_value(DC_NAMESPACE, "identifier")
440
441 @dc_identifier.setter
442 def dc_identifier(self, value: str | None) -> None:
443 self._set_single_value(DC_NAMESPACE, "identifier", value)
444
445 @property
446 def dc_language(self) -> list[str] | None:
447 """An unordered array specifying the languages used in the resource."""
448 return self._getter_bag(DC_NAMESPACE, "language")
449
450 @dc_language.setter
451 def dc_language(self, values: list[str] | None) -> None:
452 self._set_bag_values(DC_NAMESPACE, "language", values)
453
454 @property
455 def dc_publisher(self) -> list[str] | None:
456 """An unordered array of publisher names."""
457 return self._getter_bag(DC_NAMESPACE, "publisher")
458
459 @dc_publisher.setter
460 def dc_publisher(self, values: list[str] | None) -> None:
461 self._set_bag_values(DC_NAMESPACE, "publisher", values)
462
463 @property
464 def dc_relation(self) -> list[str] | None:
465 """An unordered array of text descriptions of relationships to other documents."""
466 return self._getter_bag(DC_NAMESPACE, "relation")
467
468 @dc_relation.setter
469 def dc_relation(self, values: list[str] | None) -> None:
470 self._set_bag_values(DC_NAMESPACE, "relation", values)
471
472 @property
473 def dc_rights(self) -> dict[str, str] | None:
474 """A language-keyed dictionary of textual descriptions of the rights the user has to this resource."""
475 return self._get_langalt_values(DC_NAMESPACE, "rights")
476
477 @dc_rights.setter
478 def dc_rights(self, values: dict[str, str] | None) -> None:
479 self._set_langalt_values(DC_NAMESPACE, "rights", values)
480
481 @property
482 def dc_source(self) -> str | None:
483 """Unique identifier of the work from which this resource was derived."""
484 return self._get_single_value(DC_NAMESPACE, "source")
485
486 @dc_source.setter
487 def dc_source(self, value: str | None) -> None:
488 self._set_single_value(DC_NAMESPACE, "source", value)
489
490 @property
491 def dc_subject(self) -> list[str] | None:
492 """An unordered array of descriptive phrases or keywords that specify the topic of the content."""
493 return self._getter_bag(DC_NAMESPACE, "subject")
494
495 @dc_subject.setter
496 def dc_subject(self, values: list[str] | None) -> None:
497 self._set_bag_values(DC_NAMESPACE, "subject", values)
498
499 @property
500 def dc_title(self) -> dict[str, str] | None:
501 """A language-keyed dictionary of the title of the resource."""
502 return self._get_langalt_values(DC_NAMESPACE, "title")
503
504 @dc_title.setter
505 def dc_title(self, values: dict[str, str] | None) -> None:
506 self._set_langalt_values(DC_NAMESPACE, "title", values)
507
508 @property
509 def dc_type(self) -> list[str] | None:
510 """An unordered array of textual descriptions of the document type."""
511 return self._getter_bag(DC_NAMESPACE, "type")
512
513 @dc_type.setter
514 def dc_type(self, values: list[str] | None) -> None:
515 self._set_bag_values(DC_NAMESPACE, "type", values)
516
517 @property
518 def pdf_keywords(self) -> str | None:
519 """An unformatted text string representing document keywords."""
520 return self._get_single_value(PDF_NAMESPACE, "Keywords")
521
522 @pdf_keywords.setter
523 def pdf_keywords(self, value: str | None) -> None:
524 self._set_single_value(PDF_NAMESPACE, "Keywords", value)
525
526 @property
527 def pdf_pdfversion(self) -> str | None:
528 """The PDF file version, for example 1.0 or 1.3."""
529 return self._get_single_value(PDF_NAMESPACE, "PDFVersion")
530
531 @pdf_pdfversion.setter
532 def pdf_pdfversion(self, value: str | None) -> None:
533 self._set_single_value(PDF_NAMESPACE, "PDFVersion", value)
534
535 @property
536 def pdf_producer(self) -> str | None:
537 """The name of the tool that saved the document as a PDF."""
538 return self._get_single_value(PDF_NAMESPACE, "Producer")
539
540 @pdf_producer.setter
541 def pdf_producer(self, value: str | None) -> None:
542 self._set_single_value(PDF_NAMESPACE, "Producer", value)
543
544 @property
545 def xmp_create_date(self) -> datetime.datetime | None:
546 """The date and time the resource was originally created. Returned as a UTC datetime object."""
547 return self._get_single_value(XMP_NAMESPACE, "CreateDate", _converter_date)
548
549 @xmp_create_date.setter
550 def xmp_create_date(self, value: datetime.datetime | None) -> None:
551 if value:
552 date_str = _format_datetime_utc(value)
553 self._set_single_value(XMP_NAMESPACE, "CreateDate", date_str)
554 else:
555 self._set_single_value(XMP_NAMESPACE, "CreateDate", None)
556
557 @property
558 def xmp_modify_date(self) -> datetime.datetime | None:
559 """The date and time the resource was last modified. Returned as a UTC datetime object."""
560 return self._get_single_value(XMP_NAMESPACE, "ModifyDate", _converter_date)
561
562 @xmp_modify_date.setter
563 def xmp_modify_date(self, value: datetime.datetime | None) -> None:
564 if value:
565 date_str = _format_datetime_utc(value)
566 self._set_single_value(XMP_NAMESPACE, "ModifyDate", date_str)
567 else:
568 self._set_single_value(XMP_NAMESPACE, "ModifyDate", None)
569
570 @property
571 def xmp_metadata_date(self) -> datetime.datetime | None:
572 """The date and time that any metadata for this resource was last changed. Returned as a UTC datetime object."""
573 return self._get_single_value(XMP_NAMESPACE, "MetadataDate", _converter_date)
574
575 @xmp_metadata_date.setter
576 def xmp_metadata_date(self, value: datetime.datetime | None) -> None:
577 if value:
578 date_str = _format_datetime_utc(value)
579 self._set_single_value(XMP_NAMESPACE, "MetadataDate", date_str)
580 else:
581 self._set_single_value(XMP_NAMESPACE, "MetadataDate", None)
582
583 @property
584 def xmp_creator_tool(self) -> str | None:
585 """The name of the first known tool used to create the resource."""
586 return self._get_single_value(XMP_NAMESPACE, "CreatorTool")
587
588 @xmp_creator_tool.setter
589 def xmp_creator_tool(self, value: str | None) -> None:
590 self._set_single_value(XMP_NAMESPACE, "CreatorTool", value)
591
592 @property
593 def xmpmm_document_id(self) -> str | None:
594 """The common identifier for all versions and renditions of this resource."""
595 return self._get_single_value(XMPMM_NAMESPACE, "DocumentID")
596
597 @xmpmm_document_id.setter
598 def xmpmm_document_id(self, value: str | None) -> None:
599 self._set_single_value(XMPMM_NAMESPACE, "DocumentID", value)
600
601 @property
602 def xmpmm_instance_id(self) -> str | None:
603 """An identifier for a specific incarnation of a document, updated each time a file is saved."""
604 return self._get_single_value(XMPMM_NAMESPACE, "InstanceID")
605
606 @xmpmm_instance_id.setter
607 def xmpmm_instance_id(self, value: str | None) -> None:
608 self._set_single_value(XMPMM_NAMESPACE, "InstanceID", value)
609
610 @property
611 def pdfaid_part(self) -> str | None:
612 """The part of the PDF/A standard that the document conforms to (e.g., 1, 2, 3)."""
613 return self._get_single_value(PDFAID_NAMESPACE, "part")
614
615 @pdfaid_part.setter
616 def pdfaid_part(self, value: str | None) -> None:
617 self._set_single_value(PDFAID_NAMESPACE, "part", value)
618
619 @property
620 def pdfaid_conformance(self) -> str | None:
621 """The conformance level within the PDF/A standard (e.g., 'A', 'B', 'U')."""
622 return self._get_single_value(PDFAID_NAMESPACE, "conformance")
623
624 @pdfaid_conformance.setter
625 def pdfaid_conformance(self, value: str | None) -> None:
626 self._set_single_value(PDFAID_NAMESPACE, "conformance", value)
627
628 @property
629 def custom_properties(self) -> dict[Any, Any]:
630 """
631 Retrieve custom metadata properties defined in the undocumented pdfx
632 metadata schema.
633
634 Returns:
635 A dictionary of key/value items for custom metadata properties.
636
637 """
638 if not hasattr(self, "_custom_properties"):
639 self._custom_properties = {}
640 for node in self.get_nodes_in_namespace("", PDFX_NAMESPACE):
641 key = node.localName
642 start = 0
643 while True:
644 # see documentation about PDFX_NAMESPACE earlier in file
645 idx = key.find("\u2182", start)
646 if idx == -1:
647 break
648 hex_id = key[idx + 1 : idx + 5]
649 if len(hex_id) != 4 or not all(c in hexdigits for c in hex_id):
650 # Not a well-formed escape; leave the marker untouched
651 # and continue past it instead of crashing.
652 start = idx + 1
653 continue
654 key = key[:idx] + chr(int(hex_id, base=16)) + key[idx + 5 :]
655 start = idx + 1
656 if node.nodeType == node.ATTRIBUTE_NODE:
657 value = node.nodeValue
658 else:
659 value = self._get_text(node)
660 self._custom_properties[key] = value
661 return self._custom_properties
662
663 def _get_or_create_description(self, about_uri: str = "") -> XmlElement:
664 """Get or create an rdf:Description element with the given about URI."""
665 for desc in self.rdf_root.getElementsByTagNameNS(RDF_NAMESPACE, "Description"):
666 if desc.getAttributeNS(RDF_NAMESPACE, "about") == about_uri:
667 return desc
668
669 doc = self.rdf_root.ownerDocument
670 if doc is None:
671 raise XmpDocumentError("XMP Document is None")
672 desc = doc.createElementNS(RDF_NAMESPACE, "rdf:Description")
673 desc.setAttributeNS(RDF_NAMESPACE, "rdf:about", about_uri)
674 self.rdf_root.appendChild(desc)
675 return desc
676
677 def _clear_cache_entry(self, namespace: str, name: str) -> None:
678 """Remove a cached value for a given namespace/name if present."""
679 ns_cache = self.cache.get(namespace)
680 if ns_cache and name in ns_cache:
681 del ns_cache[name]
682
683 def _set_single_value(self, namespace: str, name: str, value: str | None) -> None:
684 """Set or remove a single metadata value."""
685 self._clear_cache_entry(namespace, name)
686 desc = self._get_or_create_description()
687
688 existing_elements = list(desc.getElementsByTagNameNS(namespace, name))
689 for elem in existing_elements:
690 desc.removeChild(elem)
691
692 if existing_attr := desc.getAttributeNodeNS(namespace, name):
693 desc.removeAttributeNode(existing_attr)
694
695 if value is not None:
696 doc = self.rdf_root.ownerDocument
697 if doc is None:
698 raise XmpDocumentError("XMP Document is None")
699 prefix = self._get_namespace_prefix(namespace)
700 elem = doc.createElementNS(namespace, f"{prefix}:{name}")
701 text_node = doc.createTextNode(str(value))
702 elem.appendChild(text_node)
703 desc.appendChild(elem)
704
705 self._update_stream()
706
707 def _set_bag_values(self, namespace: str, name: str, values: list[str] | None) -> None:
708 """Set or remove bag values (unordered array)."""
709 self._clear_cache_entry(namespace, name)
710 desc = self._get_or_create_description()
711
712 existing_elements = list(desc.getElementsByTagNameNS(namespace, name))
713 for elem in existing_elements:
714 desc.removeChild(elem)
715
716 if values:
717 doc = self.rdf_root.ownerDocument
718 if doc is None:
719 raise XmpDocumentError("XMP Document is None")
720 prefix = self._get_namespace_prefix(namespace)
721 elem = doc.createElementNS(namespace, f"{prefix}:{name}")
722 bag = doc.createElementNS(RDF_NAMESPACE, "rdf:Bag")
723
724 for value in values:
725 li = doc.createElementNS(RDF_NAMESPACE, "rdf:li")
726 text_node = doc.createTextNode(str(value))
727 li.appendChild(text_node)
728 bag.appendChild(li)
729
730 elem.appendChild(bag)
731 desc.appendChild(elem)
732
733 self._update_stream()
734
735 def _set_seq_values(self, namespace: str, name: str, values: list[str] | None) -> None:
736 """Set or remove sequence values (ordered array)."""
737 self._clear_cache_entry(namespace, name)
738 desc = self._get_or_create_description()
739
740 existing_elements = list(desc.getElementsByTagNameNS(namespace, name))
741 for elem in existing_elements:
742 desc.removeChild(elem)
743
744 if values:
745 doc = self.rdf_root.ownerDocument
746 if doc is None:
747 raise XmpDocumentError("XMP Document is None")
748 prefix = self._get_namespace_prefix(namespace)
749 elem = doc.createElementNS(namespace, f"{prefix}:{name}")
750 seq = doc.createElementNS(RDF_NAMESPACE, "rdf:Seq")
751
752 for value in values:
753 li = doc.createElementNS(RDF_NAMESPACE, "rdf:li")
754 text_node = doc.createTextNode(str(value))
755 li.appendChild(text_node)
756 seq.appendChild(li)
757
758 elem.appendChild(seq)
759 desc.appendChild(elem)
760
761 self._update_stream()
762
763 def _set_langalt_values(self, namespace: str, name: str, values: dict[str, str] | None) -> None:
764 """Set or remove language alternative values."""
765 self._clear_cache_entry(namespace, name)
766 desc = self._get_or_create_description()
767
768 existing_elements = list(desc.getElementsByTagNameNS(namespace, name))
769 for elem in existing_elements:
770 desc.removeChild(elem)
771
772 if values:
773 doc = self.rdf_root.ownerDocument
774 if doc is None:
775 raise XmpDocumentError("XMP Document is None")
776 prefix = self._get_namespace_prefix(namespace)
777 elem = doc.createElementNS(namespace, f"{prefix}:{name}")
778 alt = doc.createElementNS(RDF_NAMESPACE, "rdf:Alt")
779
780 for lang, value in values.items():
781 li = doc.createElementNS(RDF_NAMESPACE, "rdf:li")
782 li.setAttribute("xml:lang", lang)
783 text_node = doc.createTextNode(str(value))
784 li.appendChild(text_node)
785 alt.appendChild(li)
786
787 elem.appendChild(alt)
788 desc.appendChild(elem)
789
790 self._update_stream()
791
792 def _get_namespace_prefix(self, namespace: str) -> str:
793 """Get the appropriate namespace prefix for a given namespace URI."""
794 return _NAMESPACE_PREFIX_MAP.get(namespace, "unknown")
795
796 def _update_stream(self) -> None:
797 """Update the stream with the current XML content."""
798 doc = self.rdf_root.ownerDocument
799 if doc is None:
800 raise XmpDocumentError("XMP Document is None")
801
802 # Serialize the top-level nodes one by one instead of the whole document:
803 # this omits the XML declaration (PDF 2.0, Annex H.2) while preserving
804 # the <?xpacket?> wrapper and other processing instructions.
805 parts = []
806 for node in doc.childNodes:
807 if (
808 isinstance(node, ProcessingInstruction)
809 and node.target == "xpacket"
810 and re.fullmatch(r"""end\s*=\s*(['"])[rw]\1\s*""", node.data)
811 ):
812 # No padding is written, so the packet cannot be updated in place.
813 node.data = 'end="r"'
814 parts.append(node.toxml(encoding="utf-8"))
815 self.stream.set_data(b"".join(parts))