Minor edits to PDF/A tutorial (#1390)

Author: Lucas-C

CHANGELOG.md

@@ -18,16 +18,16 @@ This can also be enabled programmatically with `warnings.simplefilter('default',
 
 ## [2.8.3] - Not released yet
 ### Added
-* added tutorial "tuto7" (in [English](https://py-pdf.github.io/fpdf2/Tutorial.html#tuto-7-creating-pdfa-documents) and [German](https://py-pdf.github.io/fpdf2/Tutorial-de.html#tuto-7-ein-pdfa-dokument-erstellen)) with documentation to create PDF/A files with fpdf2
-* support for [Output Intents](https://py-pdf.github.io/fpdf2/Images.html#output-intents) on document level
+* added tutorial "tuto7" (in [English](https://py-pdf.github.io/fpdf2/Tutorial.html#tuto-7-creating-pdfa-documents) and [German](https://py-pdf.github.io/fpdf2/Tutorial-de.html#tuto-7-ein-pdfa-dokument-erstellen)) with documentation to create PDF/A files with fpdf2 - thanks to @lka
+* support for [Output Intents](https://py-pdf.github.io/fpdf2/Images.html#output-intents) on document level - thanks to @lka
 * support for [shading patterns (gradients)](https://py-pdf.github.io/fpdf2/Patterns.html) - thanks to @andersonhc - [PR #1334](https://github.com/py-pdf/fpdf2/pull/1334)
 * support for [setting a minimal row height in tables](https://py-pdf.github.io/fpdf2/Tables.html#setting-row-height)
 * support for [`v_align` at the row level in tables](https://py-pdf.github.io/fpdf2/Tables.html#setting-vertical-alignment-of-text-in-cells)
 * new optional `reset_page_indices` parameter for [`insert_toc_placeholder()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.insert_toc_placeholder)
 * support for <s>strikethrough text</s>
 * new [ViewerPreferences.print_scaling](https://py-pdf.github.io/fpdf2/fpdf/prefs.html#fpdf.prefs.ViewerPreferences.print_scaling)
 * documentation on [verifying provenance of `fpdf2` releases](https://py-pdf.github.io/fpdf2/#verifying-provenance)
-* documentation on [`fpdf2` internals](https://py-pdf.github.io/fpdf2/Internals.html)### Added
+* documentation on [`fpdf2` internals](https://py-pdf.github.io/fpdf2/Internals.html)
 * added Slovenian translation of the tutorial: [Vodič](https://py-pdf.github.io/fpdf2/Tutorial-sl.html) - thanks to @DeepBlackHole
 * support for adding TrueType fonts that are missing the `.notdef` glyph - [issue #1161](https://github.com/py-pdf/fpdf2/issues/1161) - thanks to @spacegaori
 * improved SVG image speed by 50% to 70% - thanks to @petri-lipponen-movesense - [PR #1350](https://github.com/py-pdf/fpdf2/pull/1350)

docs/Metadata.md

@@ -7,15 +7,15 @@ The PDF 2.0 specification removes the `DocumentInformation` dictionary.
 Currently, the following methods on `fpdf.FPDF` allow to set metadata information
 in the `DocumentInformation` dictionary:
 
-- `set_title`
-- `set_lang`
-- `set_subject`
-- `set_author`
-- `set_keywords`
-- `set_producer`
-- `set_creator`
-- `set_creation_date`
-- `set_xmp_metadata`, that requires you to craft the necessary XML string
+- [`set_title()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_title)
+- [`set_lang()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_lang)
+- [`set_subject()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_subject)
+- [`set_author()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_author)
+- [`set_keywords()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_keywords)
+- [`set_producer()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_producer)
+- [`set_creator()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_creator)
+- [`set_creation_date()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_creation_date)
+- [`set_xmp_metadata()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.set_xmp_metadata), that requires you to craft the necessary XML string
 
 For a more user-friendly API to set metadata,
 we recommend using [`pikepdf`](https://github.com/pikepdf/pikepdf/) that will set both XMP & `DocumentInformation` metadata:

docs/Tutorial-de.md

@@ -236,6 +236,6 @@ pdf.create_pdf_with_metadata(
 
 Dabei benutzen wir pikepdf um die nötigen Metadata zu erzeugen und den Typen auf PDF/A-3B zu setzen.
 
-In der Funktion `create_pdf_with_metadata` setzen wir 'language' und 'subject' ausserhalb der Metadata bevor wir pikepdf aufrufen um, die Konformität zu erreichen.
+In der Funktion `create_pdf_with_metadata` setzen wir `language` und `subject` ausserhalb der Metadata bevor wir pikepdf aufrufen um, die Konformität zu erreichen.
 
 Bitte benutzen Sie ein Programm, wie z.B. [VeraPDF](https://verapdf.org/), um die Konformität des erstellten PDF zu sicherzustellen.

docs/Tutorial.md

@@ -266,22 +266,12 @@ Then, we add the ICC profile object to the output intents array using the
 [add_output_intent()](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.add_output_intent)
 method.
 
-After adding first page, using the embedded font, writing some text, we'll create the pdf:
-```python
-pdf.create_pdf_with_metadata(
-    filename="tuto7.pdf",
-    language="en-US",
-    title="Tutorial7",
-    subject="Example for PDFA",
-    creator=["John Dow", "Jane Dow"],
-    description="this is my description of this file",
-    keywords="Example Tutorial7"
-)
-```
-
-Here we use [pikepdf](https://pypi.org/project/pikepdf/) to create the necessary metadata and set the type to PDF/A-3B.
+After adding some pages, using the embedded fonts, and writing some text,
+we create the pdf by calling `create_pdf_with_metadata()`,
+that uses [pikepdf](https://pypi.org/project/pikepdf/)
+to create the necessary metadata and set the type to PDF/A-3B.
 
-In the function `create_pdf_with_metadata` we need to set 'language' and 'subject' outside the metadata before we use `pikepdf` to achieve conformance.
+For information on PDF metadata, check the dedicated documentation page: [Metadata](Metadata.md).
 
 Note that instead of using a function, you could also subclass `FPDF.output()` to ensure that all your documents are PDF-A compliant, as done in [test/pdf-a/test_pdf_a.py](https://github.com/py-pdf/fpdf2/blob/master/test/pdf-a/test_pdf_a.py).
 

fpdf/fpdf.py

@@ -127,7 +127,7 @@ class Image:
     PDFPageLabel,
     ResourceCatalog,
     stream_content_for_raster_image,
-    PDFICCProfileObject,
+    PDFICCProfile,
     OutputIntentDictionary,
 )
 from .recorder import FPDFRecorder
@@ -487,7 +487,7 @@ def add_output_intent(
         output_condition_identifier: str = None,
         output_condition: str = None,
         registry_name: str = None,
-        dest_output_profile: PDFICCProfileObject = None,
+        dest_output_profile: PDFICCProfile = None,
         info: str = None,
     ):
         """
@@ -500,8 +500,8 @@ def add_output_intent(
             output_condition (str, optional): see the Definition in
                 https://www.color.org/registry.xalter
             registry_name (str, optional): "https://www.color.org"
-            dest_output_profile (PDFICCProfileObject, required/optional):
-                PDFICCProfileObject | None # (required  if
+            dest_output_profile (PDFICCProfile, required/optional):
+                PDFICCProfile | None # (required  if
                 output_condition_identifier does not specify a standard
                 production condition; optional otherwise)
             info (str, required/optional see dest_output_profile): human

fpdf/output.py

@@ -216,7 +216,7 @@ def __init__(
         self.s_mask = None
 
 
-class PDFICCProfileObject(PDFContentStream):
+class PDFICCProfile(PDFContentStream):
     """holds values for ICC Profile Stream
     Args:
         contents (str): stream content
@@ -463,8 +463,8 @@ class OutputIntentDictionary:
         output_condition (str, optional): see the Definition in
             https://www.color.org/registry.xalter
         registry_name (str, optional): "https://www.color.org"
-        dest_output_profile (PDFICCProfileObject, required/optional):
-            PDFICCProfileObject | None # (required if
+        dest_output_profile (PDFICCProfile, required/optional):
+            PDFICCProfile | None # (required if
             output_condition_identifier does not specify a standard
             production condition; optional otherwise)
         info (str, required/optional see dest_output_profile): human
@@ -487,7 +487,7 @@ def __init__(
         output_condition_identifier: str,
         output_condition: str = None,
         registry_name: str = None,
-        dest_output_profile: PDFICCProfileObject = None,
+        dest_output_profile: PDFICCProfile = None,
         info: str = None,
     ):
         self.type = Name("OutputIntent")
@@ -503,8 +503,7 @@ def __init__(
         self.registry_name = PDFString(registry_name) if registry_name else None
         self.dest_output_profile = (
             dest_output_profile
-            if dest_output_profile
-            and isinstance(dest_output_profile, PDFICCProfileObject)
+            if dest_output_profile and isinstance(dest_output_profile, PDFICCProfile)
             else None
         )
         self.info = PDFString(info) if info else None
@@ -967,7 +966,7 @@ def _ensure_iccp(self, img_info):
                 break
         assert iccp_content is not None
         # Note: n should be 4 if the profile ColorSpace is CMYK
-        iccp_obj = PDFICCProfileObject(
+        iccp_obj = PDFICCProfile(
             contents=iccp_content, n=img_info["dpn"], alternate=img_info["cs"]
         )
         iccp_pdf_i = self._add_pdf_obj(iccp_obj, "iccp")

test/output_intents/test_output_intents.py

@@ -2,7 +2,7 @@
 
 from fpdf import FPDF
 from fpdf.enums import OutputIntentSubType
-from fpdf.output import PDFICCProfileObject, OutputIntentDictionary
+from fpdf.output import PDFICCProfile, OutputIntentDictionary
 
 import pytest
 from test.conftest import assert_pdf_equal
@@ -50,7 +50,7 @@ def test_output_intents(tmp_path):
     """
     doc = FPDF()
     with open(HERE / "sRGB2014.icc", "rb") as iccp_file:
-        icc_profile = PDFICCProfileObject(
+        icc_profile = PDFICCProfile(
             contents=iccp_file.read(), n=3, alternate="DeviceRGB"
         )
 
@@ -110,7 +110,7 @@ def test_two_output_intents(tmp_path):
     """
     doc = FPDF()
     with open(HERE / "sRGB2014.icc", "rb") as iccp_file:
-        icc_profile = PDFICCProfileObject(
+        icc_profile = PDFICCProfile(
             contents=iccp_file.read(), n=3, alternate="DeviceRGB"
         )
     doc.add_output_intent(
@@ -148,7 +148,7 @@ def test_two_equal_output_intents_raises():
     """
     doc = FPDF()
     with open(HERE / "sRGB2014.icc", "rb") as iccp_file:
-        icc_profile = PDFICCProfileObject(
+        icc_profile = PDFICCProfile(
             contents=iccp_file.read(), n=3, alternate="DeviceRGB"
         )
     doc.add_output_intent(

test/pdf-a/README.md

@@ -5,7 +5,3 @@ by calling those scripts from the repository root directory:
 
     scripts/install-verapdf.sh
     scripts/check-PDF-A-with-verapdf.sh
-
-`pikepdf` also checks if the PDF **claims** to be conformant:
-https://pikepdf.readthedocs.io/en/latest/topics/metadata.html#checking-pdf-a-conformance
-It is used in unit tests by checking PDF metadata `.pdfa_status`.

test/pdf-a/test_pdf_a.py

@@ -3,7 +3,7 @@
 
 from fpdf import FPDF
 from fpdf.enums import OutputIntentSubType
-from fpdf.output import PDFICCProfileObject
+from fpdf.output import PDFICCProfile
 from fpdf import FPDF_VERSION
 import pikepdf
 
@@ -35,7 +35,7 @@ def output(self, name: str, *args, **kwargs):
         if self.subject:
             self.set_subject(self.subject)
         super().output(name, *args, **kwargs)
-        if hasattr(name, "name"):  # => io.BufferedWriter
+        if hasattr(name, "name"):  # => io.BufferedWriter from assert_pdf_equal()
             name.close()  # closing buffer before opening file with pikepdf (required on Windows)
             name = name.name
         with pikepdf.open(name, allow_overwriting_input=True) as pdf:
@@ -53,7 +53,6 @@ def output(self, name: str, *args, **kwargs):
                 # meta["xmp:CreateDate"] = already done by assert_pdf_equal()
                 meta["pdfaid:part"] = "3"
                 meta["pdfaid:conformance"] = "B"
-            assert meta.pdfa_status == "3B"
             pdf.save(deterministic_id=True)
 
 
@@ -83,7 +82,7 @@ def test_basic_pdfa(tmp_path):
     pdf.set_font(style="I")
     pdf.write(text="Example text in italics")
     with open(TUTORIAL / "sRGB2014.icc", "rb") as iccp_file:
-        icc_profile = PDFICCProfileObject(
+        icc_profile = PDFICCProfile(
             contents=iccp_file.read(), n=3, alternate="DeviceRGB"
         )
     pdf.add_output_intent(

tutorial/tuto7.py

@@ -3,7 +3,7 @@
 
 from fpdf import FPDF
 from fpdf.enums import OutputIntentSubType
-from fpdf.output import PDFICCProfileObject
+from fpdf.output import PDFICCProfile
 from fpdf import FPDF_VERSION
 import pikepdf
 
@@ -43,7 +43,7 @@ def create_pdf_with_metadata(
             meta["xmp:CreateDate"] = datetime.now(timezone.utc).isoformat()
             meta["pdfaid:part"] = "3"
             meta["pdfaid:conformance"] = "B"
-        pike_pdf.save()
+        pike_pdf.save(deterministic_id=True)
 
 
 pdf = FPDF()
@@ -62,9 +62,7 @@ def create_pdf_with_metadata(
 
 # set Output Intents
 with open(DIR / "sRGB2014.icc", "rb") as iccp_file:
-    icc_profile = PDFICCProfileObject(
-        contents=iccp_file.read(), n=3, alternate="DeviceRGB"
-    )
+    icc_profile = PDFICCProfile(contents=iccp_file.read(), n=3, alternate="DeviceRGB")
 pdf.add_output_intent(
     OutputIntentSubType.PDFA,
     "sRGB",