release v2.0.19

README.md

@@ -7,6 +7,8 @@
 [![Text Extraction : 88.6%](https://img.shields.io/badge/text%20extraction-88.6%25-orange)]()
 [![Public Method Documentation : 100%](https://img.shields.io/badge/public%20method%20documentation-100%25-green)]()
 
+[![Downloads](https://pepy.tech/badge/borb)](https://pepy.tech/project/borb)
+[![Downloads](https://pepy.tech/badge/borb/month)](https://pepy.tech/project/borb)
 
 `borb` is a library for creating and manipulating PDF files in python.
 
@@ -60,7 +62,7 @@ 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 import Document
+from borb.pdf.document.document import Document
 from borb.pdf.page.page import Page
 from borb.pdf.pdf import PDF
 

borb/io/read/reference/xref_transformer.py

@@ -15,7 +15,7 @@
 from borb.io.read.transformer import ReadTransformerState, Transformer
 from borb.io.read.types import AnyPDFType, Dictionary, Name
 from borb.pdf.canvas.event.event_listener import Event, EventListener
-from borb.pdf.document import Document
+from borb.pdf.document.document import Document
 from borb.pdf.xref.plaintext_xref import PlainTextXREF
 from borb.pdf.xref.stream_xref import StreamXREF
 from borb.pdf.xref.xref import XREF

borb/io/write/ascii_art/ascii_logo.txt

@@ -1,2 +1,2 @@
-borb version 2.0.18
+borb version 2.0.19
 Joris Schellekens

borb/io/write/document/document_transformer.py

@@ -11,7 +11,7 @@
 
 from borb.io.read.types import AnyPDFType, Dictionary, HexadecimalString, List, Name
 from borb.io.write.transformer import Transformer, WriteTransformerState
-from borb.pdf.document import Document
+from borb.pdf.document.document import Document
 
 logger = logging.getLogger(__name__)
 

borb/io/write/document/information_dictionary_transformer.py

@@ -18,7 +18,7 @@
 from borb.io.write.object.dictionary_transformer import DictionaryTransformer
 from borb.io.write.object.stream_transformer import StreamTransformer
 from borb.io.write.transformer import Transformer, WriteTransformerState
-from borb.pdf.document import Document
+from borb.pdf.document.document import Document
 from borb.pdf.trailer.document_info import XMPDocumentInfo
 
 logger = logging.getLogger(__name__)

borb/io/write/page/page_transformer.py

@@ -11,7 +11,7 @@
 from borb.io.read.types import AnyPDFType, Dictionary, Name
 from borb.io.write.object.dictionary_transformer import DictionaryTransformer
 from borb.io.write.transformer import WriteTransformerState
-from borb.pdf.document import Document
+from borb.pdf.document.document import Document
 
 logger = logging.getLogger(__name__)
 

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

@@ -0,0 +1,43 @@
+"""
+    This file is part of the borb (R) project.
+    Copyright (c) 2020-2040 borb Group NV
+    Authors: Joris Schellekens, et al.
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License version 3
+    as published by the Free Software Foundation with the addition of the
+    following permission added to Section 15 as permitted in Section 7(a):
+    FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+    BORB GROUP. BORB GROUP DISCLAIMS THE WARRANTY OF NON INFRINGEMENT
+    OF THIRD PARTY RIGHTS
+
+    This program is distributed in the hope that it will be useful, but
+    WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+    or FITNESS FOR A PARTICULAR PURPOSE.
+
+    See the GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program; if not, see http://www.gnu.org/licenses or write to
+    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+    Boston, MA, 02110-1301 USA.
+
+    The interactive user interfaces in modified source and object code versions
+    of this program must display Appropriate Legal Notices, as required under
+    Section 5 of the GNU Affero General Public License.
+    In accordance with Section 7(b) of the GNU Affero General Public License,
+    a covered work must retain the producer line in every PDF that is created
+    or manipulated using borb.
+
+    You can be released from the requirements of the license by purchasing
+    a commercial license. Buying such a license is mandatory as soon as you
+    develop commercial activities involving the borb software without
+    disclosing the source code of your own applications.
+
+    These activities include: offering paid services to customers as an ASP,
+    serving PDFs on the fly in a web application, shipping borb with a closed
+    source product.
+
+    For more information, please contact borb Software Corp. at this
+    address: [email protected]
+"""

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

@@ -0,0 +1,126 @@
+import datetime
+import typing
+from decimal import Decimal
+
+from borb.io.read.types import Dictionary, Name, List, Decimal as bDecimal, String
+from borb.pdf.canvas.color.color import Color
+from borb.pdf.canvas.geometry.rectangle import Rectangle
+
+
+class Annotation(Dictionary):
+    @staticmethod
+    def _timestamp_to_str() -> str:
+        timestamp_str = "D:"
+        now = datetime.datetime.now()
+        for n in [now.year, now.month, now.day, now.hour, now.minute, now.second]:
+            timestamp_str += "{0:02}".format(n)
+        timestamp_str += "Z00"
+        return timestamp_str
+
+    def __init__(
+        self,
+        bounding_box: Rectangle,
+        contents: typing.Optional[str] = None,
+        color: typing.Optional[Color] = None,
+        horizontal_corner_radius: typing.Optional[Decimal] = None,
+        vertical_corner_radius: typing.Optional[Decimal] = None,
+        border_width: typing.Optional[Decimal] = None,
+    ):
+        super(Annotation, self).__init__()
+
+        # (Optional) The type of PDF object that this dictionary describes; if
+        # present, shall be Annot for an annotation dictionary.
+        self[Name("Type")] = Name("Annot")
+
+        # (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["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()))
+        self["Rect"].append(bDecimal(bounding_box.get_y() + bounding_box.get_height()))
+
+        # (Optional) Text that shall be displayed for the annotation or, if this type of
+        # annotation does not display text, an alternate description of the
+        # annotation’s contents in human-readable form. In either case, this text is
+        # useful when extracting the document’s contents in support of
+        # accessibility to users with disabilities or for other purposes (see 14.9.3,
+        # “Alternate Descriptions”). See 12.5.6, “Annotation Types” for more
+        # details on the meaning of this entry for each annotation type.
+        if contents is not None:
+            self[Name("Contents")] = String(contents)
+
+        # (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
+        self[Name("NM")] = String("annotation-{0:03d}".format(len_annots))
+
+        # (Optional; PDF 1.1) The date and time when the annotation was most
+        # recently modified. The format should be a date string as described in
+        # 7.9.4, “Dates,” but conforming readers shall accept and display a string
+        # in any format.
+        self[Name("M")] = String(self._timestamp_to_str())
+
+        # (Optional; PDF 1.1) A set of flags specifying various characteristics of
+        # the annotation (see 12.5.3, “Annotation Flags”). Default value: 0.
+        self[Name("F")] = bDecimal(4)
+
+        # (Optional; PDF 1.2) An appearance dictionary specifying how the
+        # annotation shall be presented visually on the page (see 12.5.5,
+        # “Appearance Streams”). Individual annotation handlers may ignore this
+        # entry and provide their own appearances.
+        # self[Name("AP")] = None
+
+        # (Required if the appearance dictionary AP contains one or more
+        # subdictionaries; PDF 1.2) The annotation’s appearance state, which
+        # selects the applicable appearance stream from an appearance
+        # subdictionary (see Section 12.5.5, “Appearance Streams”).
+        # self[Name("AS")] = None
+
+        # Optional) An array specifying the characteristics of the annotation’s
+        # border, which shall be drawn as a rounded rectangle.
+        # (PDF 1.0) The array consists of three numbers defining the horizontal
+        # corner radius, vertical corner radius, and border width, all in default user
+        # space units. If the corner radii are 0, the border has square (not rounded)
+        # corners; if the border width is 0, no border is drawn.
+        # (PDF 1.1) The array may have a fourth element, an optional dash array
+        # defining a pattern of dashes and gaps that shall be used in drawing the
+        # border. The dash array shall be specified in the same format as in the
+        # line dash pattern parameter of the graphics state (see 8.4.3.6, “Line
+        # Dash Pattern”).
+        if (
+            horizontal_corner_radius is not None
+            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["Border"].append(bDecimal(horizontal_corner_radius))
+            self["Border"].append(bDecimal(vertical_corner_radius))
+            self["Border"].append(bDecimal(border_width))
+
+        # (Optional; PDF 1.1) An array of numbers in the range 0.0 to 1.0,
+        # representing a colour used for the following purposes:
+        # The background of the annotation’s icon when closed
+        # The title bar of the annotation’s pop-up window
+        # The border of a link annotation
+        # 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["C"].append(bDecimal(color.to_rgb().red))
+            self["C"].append(bDecimal(color.to_rgb().green))
+            self["C"].append(bDecimal(color.to_rgb().blue))
+
+        # (Required if the annotation is a structural content item; PDF 1.3) The
+        # integer key of the annotation’s entry in the structural parent tree (see
+        # 14.7.4.4, “Finding Structure Elements from Content Items”)
+        # self[Name("StructParent")] = None
+
+        # (Optional; PDF 1.5) An optional content group or optional content
+        # membership dictionary (see 8.11, “Optional Content”) specifying the
+        # optional content properties for the annotation. Before the annotation is
+        # drawn, its visibility shall be determined based on this entry as well as the
+        # annotation flags specified in the F entry (see 12.5.3, “Annotation Flags”).
+        # If it is determined to be invisible, the annotation shall be skipped, as if it
+        # were not in the document.
+        # self[Name("OC")] = None

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

@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+A caret annotation (PDF 1.5) is a visual symbol that indicates the presence of text edits. Table 180 lists the
+entries specific to caret annotations.
+"""
+from borb.pdf.canvas.layout.annotation.annotation import Annotation
+
+
+class CaretAnnotation(Annotation):
+    """
+    A caret annotation (PDF 1.5) is a visual symbol that indicates the presence of text edits. Table 180 lists the
+    entries specific to caret annotations.
+    """
+
+    def __init__(self):
+        super(CaretAnnotation, self).__init__()
+        # TODO

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

@@ -0,0 +1,83 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+Square and circle annotations (PDF 1.3) shall display, respectively, a rectangle or an ellipse on the page. When
+opened, they shall display a pop-up window containing the text of the associated note. The rectangle or ellipse
+shall be inscribed within the annotation rectangle defined by the annotation dictionary’s Rect entry (see
+Table 168).
+"""
+import typing
+from decimal import Decimal
+
+from borb.io.read.types import Name, List, Decimal as bDecimal
+from borb.pdf.canvas.color.color import Color
+from borb.pdf.canvas.geometry.rectangle import Rectangle
+from borb.pdf.canvas.layout.annotation.annotation import Annotation
+
+
+class CircleAnnotation(Annotation):
+    """
+    Square and circle annotations (PDF 1.3) shall display, respectively, a rectangle or an ellipse on the page. When
+    opened, they shall display a pop-up window containing the text of the associated note. The rectangle or ellipse
+    shall be inscribed within the annotation rectangle defined by the annotation dictionary’s Rect entry (see
+    Table 168).
+    """
+
+    def __init__(
+        self,
+        bounding_box: Rectangle,
+        fill_color: Color,
+        stroke_color: Color,
+        rectangle_difference: typing.Optional[
+            typing.Tuple[Decimal, Decimal, Decimal, Decimal]
+        ] = None,
+    ):
+        super(CircleAnnotation, self).__init__(
+            bounding_box=bounding_box, color=stroke_color
+        )
+
+        # (Required) The type of annotation that this dictionary describes; shall be
+        # Square or Circle for a square or circle annotation, respectively.
+        self[Name("Subtype")] = Name("Circle")
+
+        # (Optional) A border style dictionary (see Table 166) specifying the line
+        # width and dash pattern that shall be used in drawing the rectangle or
+        # ellipse.
+        # The annotation dictionary’s AP entry, if present, shall take precedence
+        # over the Rect and BS entries; see Table 168 and 12.5.5, “Appearance
+        # Streams.”
+        # self[Name("BS")] = None
+
+        # (Optional; PDF 1.4) An array of numbers that shall be in the range 0.0 to
+        # 1.0 and shall specify the interior color with which to fill the annotation’s
+        # 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["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))
+
+        # (Optional; PDF 1.5) A border effect dictionary describing an effect applied
+        # to the border described by the BS entry (see Table 167).
+        # self[Name("BE")] = None
+
+        # (Optional; PDF 1.5) A set of four numbers that shall describe the
+        # numerical differences between two rectangles: the Rect entry of the
+        # annotation and the actual boundaries of the underlying square or circle.
+        # Such a difference may occur in situations where a border effect
+        # (described by BE) causes the size of the Rect to increase beyond that of
+        # the square or circle.
+        # The four numbers shall correspond to the differences in default user
+        # space between the left, top, right, and bottom coordinates of Rect and
+        # those of the square or circle, respectively. Each value shall be greater
+        # than or equal to 0. The sum of the top and bottom differences shall be
+        # 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["RD"].append(bDecimal(rectangle_difference[0]))
+            self["RD"].append(bDecimal(rectangle_difference[1]))
+            self["RD"].append(bDecimal(rectangle_difference[2]))
+            self["RD"].append(bDecimal(rectangle_difference[3]))

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

@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+A file attachment annotation (PDF 1.3) contains a reference to a file, which typically shall be embedded in the
+PDF file (see 7.11.4, “Embedded File Streams”).
+"""
+from borb.pdf.canvas.layout.annotation.annotation import Annotation
+
+
+class FileAttachmentAnnotation(Annotation):
+    """
+    A file attachment annotation (PDF 1.3) contains a reference to a file, which typically shall be embedded in the
+    PDF file (see 7.11.4, “Embedded File Streams”).
+    """
+
+    def __init__(self):
+        super(FileAttachmentAnnotation, self).__init__()
+        # TODO