release v2.0.22

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: BUG
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behaviour:
+
+```python
+# please enter a concise, complete and self-contained code sample
+# that reproduces the bug
+```
+
+**Expected behaviour**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - borb version [e.g. 22]
+- input PDF (if applicable)
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

README.md

@@ -60,11 +60,11 @@ this is the classic `Hello World` example, in `borb`:
 ```python
 from pathlib import Path
 
-from borb.pdf.canvas.layout.page_layout.multi_column_layout import SingleColumnLayout
-from borb.pdf.canvas.layout.text.paragraph import Paragraph
-from borb.pdf.document.document import Document
-from borb.pdf.page.page import Page
-from borb.pdf.pdf import PDF
+from borb.pdf import Document
+from borb.pdf import Page
+from borb.pdf import SingleColumnLayout
+from borb.pdf import Paragraph
+from borb.pdf import PDF
 
 # create an empty Document
 pdf = Document()

borb/io/read/types.py

@@ -153,34 +153,34 @@ def get_reference(self) -> typing.Optional["Reference"]:
             setattr(self, "_reference", None)
         return self._reference
 
-    # set_can_be_referenced
-    def set_can_be_referenced(self, a_flag: bool):
+    # set_is_inline
+    def set_is_inline(self, a_flag: bool):
         """
-        This function sets whether or not this Object can be referenced.
-        When an object can not be referenced, it is always embedded immediately in the PDF byte stream.
+        This function sets whether or not this Object is written inline.
+        When an object is inline, it is always embedded immediately in the PDF byte stream.
         """
-        if "_can_be_referenced" not in vars(self):
-            setattr(self, "_can_be_referenced", None)
-        self._can_be_referenced = a_flag
+        if "_is_inline" not in vars(self):
+            setattr(self, "_is_inline", None)
+        self._is_inline = a_flag
         return self
 
-    # can_be_referenced
-    def can_be_referenced(self) -> bool:
+    # is_inline
+    def get_is_inline(self) -> bool:
         """
         This function returns whether or not this Object can be referenced.
         When an object can not be referenced, it is always embedded immediately in the PDF byte stream.
         """
-        if "_can_be_referenced" not in vars(self):
-            setattr(self, "_can_be_referenced", True)
-        return self._can_be_referenced
+        if "_is_inline" not in vars(self):
+            setattr(self, "_is_inline", False)
+        return self._is_inline
 
     object.set_parent = types.MethodType(set_parent, object)
     object.get_parent = types.MethodType(get_parent, object)
     object.get_root = types.MethodType(get_root, object)
     object.set_reference = types.MethodType(set_reference, object)
     object.get_reference = types.MethodType(get_reference, object)
-    object.set_can_be_referenced = types.MethodType(set_can_be_referenced, object)
-    object.can_be_referenced = types.MethodType(can_be_referenced, object)
+    object.set_is_inline = types.MethodType(set_is_inline, object)
+    object.is_inline = types.MethodType(get_is_inline, object)
     object.to_json_serializable = types.MethodType(to_json_serializable, object)
     if isinstance(object, Image):
         object.__deepcopy__ = types.MethodType(deepcopy_mod, object)

borb/io/write/ascii_art/ascii_logo.txt

@@ -1,2 +1,2 @@
-borb version 2.0.21
+borb version 2.0.22
 Joris Schellekens

borb/io/write/conformance_level.py

@@ -25,6 +25,10 @@ class ConformanceLevel(enum.Enum):
     PDFA_3U = 19
 
     def get_standard(self) -> int:
+        """
+        This function returns the standard (the numeric part) of this ConformanceLevel
+        :return:    the numeric part of this ConformanceLevel (1, 2, 3)
+        """
         if self in [ConformanceLevel.PDFA_1A, ConformanceLevel.PDFA_1B]:
             return 1
         if self in [
@@ -42,6 +46,10 @@ def get_standard(self) -> int:
         assert False
 
     def get_conformance_level(self) -> str:
+        """
+        This function returns the conformance-level (non-numeric part) of this ConformanceLevel
+        :return:    the non-numeric part of this ConformanceLevel (A, B, U)
+        """
         if self in [ConformanceLevel.PDFA_1A, ConformanceLevel.PDFA_2A]:
             return "A"
         if self in [

borb/io/write/document/document_transformer.py

@@ -61,13 +61,13 @@ def transform(
         random_id = HexadecimalString("%032x" % random.randrange(16 ** 32))
         if "ID" not in object_to_transform["XRef"]["Trailer"]:
             # fmt: off
-            object_to_transform["XRef"]["Trailer"][Name("ID")] = List().set_can_be_referenced(False) # type: ignore [attr-defined]
+            object_to_transform["XRef"]["Trailer"][Name("ID")] = List().set_is_inline(True) # type: ignore [attr-defined]
             object_to_transform["XRef"]["Trailer"]["ID"].append(random_id)
             object_to_transform["XRef"]["Trailer"]["ID"].append(random_id)
             # fmt: on
         else:
             object_to_transform["XRef"]["Trailer"]["ID"][1] = random_id
-        object_to_transform["XRef"]["Trailer"]["ID"].set_can_be_referenced(False)
+        object_to_transform["XRef"]["Trailer"]["ID"].set_is_inline(True)
 
         # /Info
         self._build_empty_document_info_dictionary(object_to_transform)

borb/io/write/object/array_transformer.py

@@ -64,7 +64,7 @@ def transform(
                 or isinstance(v, List)
                 or isinstance(v, Stream)
                 or isinstance(v, Image)
-            ) and v.can_be_referenced():  # type: ignore [union-attr]
+            ) and not v.is_inline():  # type: ignore [union-attr]
                 out_value.append(self.get_reference(v, context))
                 queue.append(v)
             else:
@@ -86,7 +86,12 @@ def transform(
             self.get_root_transformer().transform(v, context)
             if i != N - 1:
                 context.destination.write(bytes(" ", "latin1"))
-        context.destination.write(bytes("]\n", "latin1"))
+
+        # write newline if the object is not inline
+        if object_to_transform.is_inline():
+            context.destination.write(bytes("]", "latin1"))
+        else:
+            context.destination.write(bytes("]\n", "latin1"))
 
         # end object if needed
         if started_object:

borb/io/write/object/dictionary_transformer.py

@@ -65,7 +65,7 @@ def transform(
                 or isinstance(v, Stream)
                 or isinstance(v, Image)
                 or isinstance(v, Element)
-            ) and v.can_be_referenced():  # type: ignore [union-attr]
+            ) and not v.is_inline():  # type: ignore [union-attr]
                 out_value[k] = self.get_reference(v, context)
                 queue.append(v)
             else:
@@ -89,7 +89,12 @@ def transform(
             self.get_root_transformer().transform(v, context)
             if i != N - 1:
                 context.destination.write(bytes(" ", "latin1"))
-        context.destination.write(bytes(">>\n", "latin1"))
+
+        # write newline if the object is not inline
+        if object_to_transform.is_inline():
+            context.destination.write(bytes(">>", "latin1"))
+        else:
+            context.destination.write(bytes(">>\n", "latin1"))
 
         # end object if needed
         if started_object:

borb/io/write/object/stream_transformer.py

@@ -74,7 +74,7 @@ def transform(
                 isinstance(v, Dictionary)
                 or isinstance(v, List)
                 or isinstance(v, Stream)
-            ) and v.can_be_referenced():  # type: ignore [union-attr]
+            ) and not v.is_inline():  # type: ignore [union-attr]
                 stream_dictionary[k] = self.get_reference(v, context)
                 queue.append(v)
             else:

borb/io/write/page/page_transformer.py

@@ -51,7 +51,7 @@ def transform(
         # mark some keys as non-referencable
         for k in ["ArtBox", "BleedBox", "CropBox", "MediaBox", "TrimBox"]:
             if k in object_to_transform:
-                object_to_transform[k].set_can_be_referenced(False)  # type: ignore [attr-defined]
+                object_to_transform[k].set_is_inline(True)  # type: ignore [attr-defined]
 
         # delegate to super
         super(PageTransformer, self).transform(object_to_transform, context)

borb/io/write/page/pages_transformer.py

@@ -42,7 +42,7 @@ def transform(
         ), "A WriteTransformerState must be defined in order to write Pages Dictionary objects."
 
         # /Kids can be written immediately
-        object_to_transform[Name("Kids")].set_can_be_referenced(False)  # type: ignore [attr-defined]
+        object_to_transform[Name("Kids")].set_is_inline(True)  # type: ignore [attr-defined]
 
         # queue writing of /Page objects
         queue: typing.List[AnyPDFType] = []

borb/pdf/__init__.py

@@ -41,3 +41,51 @@
     For more information, please contact borb Software Corp. at this
     address: [email protected]
 """
+
+# Document, Page, PDF
+from .document.document import Document
+from .page.page import Page
+from .pdf import PDF
+
+# PageLayout
+from .canvas.layout.page_layout.page_layout import PageLayout
+from .canvas.layout.page_layout.multi_column_layout import SingleColumnLayout
+from .canvas.layout.page_layout.multi_column_layout import MultiColumnLayout
+
+# Paragraph
+from .canvas.layout.text.paragraph import Paragraph
+from .canvas.layout.text.heading import Heading
+
+# Image
+from .canvas.layout.image.image import Image
+from .canvas.layout.image.chart import Chart
+from .canvas.layout.image.barcode import Barcode
+from .canvas.layout.image.barcode import BarcodeType
+
+# Shape
+from .canvas.layout.shape.shape import Shape
+from .canvas.layout.shape.disjoint_shape import DisjointShape
+
+# Table
+from .canvas.layout.table.table import Table, TableCell
+from .canvas.layout.table.fixed_column_width_table import FixedColumnWidthTable
+from .canvas.layout.table.flexible_column_width_table import FlexibleColumnWidthTable
+
+# List
+from .canvas.layout.list.list import List
+from .canvas.layout.list.ordered_list import OrderedList
+from .canvas.layout.list.unordered_list import UnorderedList
+from .canvas.layout.list.roman_list import RomanNumeralOrderedList
+
+# Color
+from .canvas.color.color import (
+    Color,
+    RGBColor,
+    CMYKColor,
+    GrayColor,
+    HSVColor,
+    HexColor,
+    HSVColor,
+    X11Color,
+)
+from .canvas.color.pantone import Pantone

borb/pdf/canvas/font/font.py

@@ -370,7 +370,7 @@ def _copy_font_descriptor(self, font_descriptor_to_copy: Dictionary) -> Dictiona
             f1[Name("FontWeight")] = f0["FontWeight"]
         f1[Name("Flags")] = f0["Flags"]
         if "FontBBox" in f0 and False:  # TODO
-            f1[Name("FontBBox")] = List().set_can_be_referenced(False)  # type: ignore [attr-defined]
+            f1[Name("FontBBox")] = List().set_is_inline(True)  # type: ignore [attr-defined]
             for i in range(0, len(f0["FontBBox"])):
                 f1["FontBBox"].append(f0["FontBBox"][i])
         f1[Name("ItalicAngle")] = f0["ItalicAngle"]

borb/pdf/canvas/font/simple_font/true_type_font.py

@@ -163,7 +163,7 @@ def _get_font_descriptor(ttf_font_file: TTFont) -> Dictionary:
         if cap_height is None:
             cap_height = bDecimal(840)
 
-        font_descriptor[Name("FontBBox")] = List().set_can_be_referenced(False)  # type: ignore[attr-defined]
+        font_descriptor[Name("FontBBox")] = List().set_is_inline(True)  # type: ignore[attr-defined]
         font_descriptor["FontBBox"].append(bDecimal(min_x))
         font_descriptor["FontBBox"].append(bDecimal(min_y))
         font_descriptor["FontBBox"].append(bDecimal(max_x))

borb/pdf/canvas/layout/annotation/annotation.py

@@ -48,7 +48,7 @@ def __init__(
 
         # (Required) The annotation rectangle, defining the location of the
         # annotation on the page in default user space units.
-        self[Name("Rect")] = List().set_can_be_referenced(False)  # type: ignore [attr-defined]
+        self[Name("Rect")] = List().set_is_inline(True)  # type: ignore [attr-defined]
         self["Rect"].append(bDecimal(bounding_box.get_x()))
         self["Rect"].append(bDecimal(bounding_box.get_y()))
         self["Rect"].append(bDecimal(bounding_box.get_x() + bounding_box.get_width()))
@@ -66,7 +66,7 @@ def __init__(
 
         # (Optional; PDF 1.4) The annotation name, a text string uniquely
         # identifying it among all the annotations on its page.
-        len_annots = len(self["Annots"]) if "Annots" in self else 0
+        len_annots: int = 0
         self[Name("NM")] = String("annotation-{0:03d}".format(len_annots))
 
         # (Optional; PDF 1.1) The date and time when the annotation was most
@@ -107,7 +107,7 @@ def __init__(
             and vertical_corner_radius is not None
             and border_width is not None
         ):
-            self[Name("Border")] = List().set_can_be_referenced(False)  # type: ignore [attr-defined]
+            self[Name("Border")] = List().set_is_inline(True)  # type: ignore [attr-defined]
             self["Border"].append(bDecimal(horizontal_corner_radius))
             self["Border"].append(bDecimal(vertical_corner_radius))
             self["Border"].append(bDecimal(border_width))
@@ -120,7 +120,7 @@ def __init__(
         # The number of array elements determines the colour space in which the
         # colour shall be defined
         if color is not None:
-            self[Name("C")] = List().set_can_be_referenced(False)  # type: ignore [attr-defined]
+            self[Name("C")] = List().set_is_inline(True)  # type: ignore [attr-defined]
             self["C"].append(bDecimal(color.to_rgb().red))
             self["C"].append(bDecimal(color.to_rgb().green))
             self["C"].append(bDecimal(color.to_rgb().blue))

borb/pdf/canvas/layout/annotation/circle_annotation.py

@@ -54,7 +54,7 @@ def __init__(
         # rectangle or ellipse. The number of array elements determines the colour
         # space in which the colour shall be defined
         if fill_color is not None:
-            self[Name("IC")] = List().set_can_be_referenced(False)  # type: ignore [attr-defined]
+            self[Name("IC")] = List().set_is_inline(True)  # type: ignore [attr-defined]
             self["IC"].append(bDecimal(fill_color.to_rgb().red))
             self["IC"].append(bDecimal(fill_color.to_rgb().green))
             self["IC"].append(bDecimal(fill_color.to_rgb().blue))
@@ -76,7 +76,7 @@ def __init__(
         # less than the height of Rect, and the sum of the left and right differences
         # shall be less than the width of Rect.
         if rectangle_difference is not None:
-            self[Name("RD")] = List().set_can_be_referenced(False)  # type: ignore [attr-defined]
+            self[Name("RD")] = List().set_is_inline(True)  # type: ignore [attr-defined]
             self["RD"].append(bDecimal(rectangle_difference[0]))
             self["RD"].append(bDecimal(rectangle_difference[1]))
             self["RD"].append(bDecimal(rectangle_difference[2]))

borb/pdf/canvas/layout/annotation/highlight_annotation.py

@@ -39,7 +39,7 @@ def __init__(self, bounding_box: Rectangle, color: Color = HexColor("faed27")):
         # underlying the annotation. The coordinates for each quadrilateral shall
         # be given in the order
         # x1 y1 x2 y2 x3 y3 x4 y4
-        self[Name("QuadPoints")] = List().set_can_be_referenced(False)  # type: ignore [attr-defined]
+        self[Name("QuadPoints")] = List().set_is_inline(True)  # type: ignore [attr-defined]
         # x1, y1
         self["QuadPoints"].append(bDecimal(bounding_box.get_x()))
         self["QuadPoints"].append(bDecimal(bounding_box.get_y()))
@@ -62,7 +62,7 @@ def __init__(self, bounding_box: Rectangle, color: Color = HexColor("faed27")):
         )
 
         # border
-        self[Name("Border")] = List().set_can_be_referenced(False)  # type: ignore [attr-defined]
+        self[Name("Border")] = List().set_is_inline(True)  # type: ignore [attr-defined]
         self["Border"].append(bDecimal(0))
         self["Border"].append(bDecimal(0))
         self["Border"].append(bDecimal(1))