Merging upstream version 0.11.0.

Signed-off-by: Daniel Baumann <daniel@debian.org>

docs/changelog.rst

@@ -2,8 +2,45 @@ Changelog
 =========
 
 
+Version 0.11.0
+--------------
+
+Released on
+
+New features:
+
+* Remove deprecated version and identifier parameters
+* Change some function names for consistency
+* Allow extra operands for special colors
+
+Contributors:
+
+* Guillaume Ayoub
+* Lucie Anglade
+
+Backers and sponsors:
+
+* Spacinov
+* Kobalt
+* Grip Angebotssoftware
+* Manuel Barkhau
+* SimonSoft
+* Menutech
+* KontextWork
+* Simon Sapin
+* René Fritz
+* TrainingSparkle
+* Healthchecks.io
+* Hammerbacher
+* Docraptor
+* Advance Insight
+* Yanal-Yvez Fargialla
+* Morntag
+* Xavid
+
+
 Version 0.10.0
--------------
+--------------
 
 Released on 2024-04-29.
 

docs/common_use_cases.rst

@@ -34,7 +34,7 @@ Draw rectangles and lines
    draw.rectangle(50, 50, 20, 40)
    draw.set_dash([], 0)
    draw.set_line_width(10)
-   draw.transform(1, 0, 0, 1, 80, 80)
+   draw.set_matrix(1, 0, 0, 1, 80, 80)
    draw.fill()
 
    # Add the stream with the two rectangles into the document
@@ -73,7 +73,7 @@ Add some color
    draw.rectangle(50, 50, 20, 40)
    draw.set_dash([], 0)
    draw.set_line_width(10)
-   draw.transform(1, 0, 0, 1, 80, 80)
+   draw.set_matrix(1, 0, 0, 1, 80, 80)
    draw.fill()
 
    document.add_object(draw)
@@ -113,7 +113,7 @@ Display image
 
    image = pydyf.Stream()
    image.push_state()
-   image.transform(100, 0, 0, 100, 100, 100)
+   image.set_matrix(100, 0, 0, 100, 100, 100)
    image.draw_x_object('Im1')
    image.pop_state()
    document.add_object(image)
@@ -159,7 +159,7 @@ Display text
   text = pydyf.Stream()
   text.begin_text()
   text.set_font_size('F1', 20)
-  text.text_matrix(1, 0, 0, 1, 10, 90)
+  text.set_text_matrix(1, 0, 0, 1, 10, 90)
   text.show_text(pydyf.String('Bœuf grillé & café'.encode('macroman')))
   text.end_text()
 
@@ -234,7 +234,7 @@ Display inline QR-code image
     stream.push_state()
     x = 0
     y = 0
-    stream.transform(width, 0, 0, height, x, y)
+    stream.set_matrix(width, 0, 0, height, x, y)
     # Add the 1-bit grayscale image inline in the PDF
     stream.inline_image(width, height, 'Gray', 1, raw_data)
     stream.pop_state()

pydyf/__init__.py

@@ -11,7 +11,7 @@ from hashlib import md5
 from math import ceil, log
 from warnings import warn
 
-VERSION = __version__ = '0.10.0'
+VERSION = __version__ = '0.11.0'
 
 
 def _to_bytes(item):
@@ -122,13 +122,9 @@ class Stream(Object):
         self.stream.append(b'h')
 
     def color_space(self, space, stroke=False):
-        """Set the nonstroking color space.
+        """color_space is deprecated, use set_color_space instead."""
-
+        warn(Stream.color_space.__doc__, DeprecationWarning)
-        If stroke is set to ``True``, set the stroking color space instead.
+        self.set_color_space(space, stroke)
-
-        """
-        self.stream.append(
-            b'/' + _to_bytes(space) + b' ' + (b'CS' if stroke else b'cs'))
 
     def curve_to(self, x1, y1, x2, y2, x3, y3):
         """Add cubic Bézier curve to current path.
@@ -248,6 +244,11 @@ class Stream(Object):
         self.stream.append(b' '.join((_to_bytes(x), _to_bytes(y), b'Td')))
 
     def shading(self, name):
+        """shading is deprecated, use paint_shading instead."""
+        warn(Stream.shading.__doc__, DeprecationWarning)
+        self.paint_shading(name)
+
+    def paint_shading(self, name):
         """Paint shape and color shading using shading dictionary ``name``."""
         self.stream.append(b'/' + _to_bytes(name) + b' sh')
 
@@ -281,14 +282,26 @@ class Stream(Object):
             _to_bytes(r), _to_bytes(g), _to_bytes(b),
             (b'RG' if stroke else b'rg'))))
 
-    def set_color_special(self, name, stroke=False):
+    def set_color_space(self, space, stroke=False):
-        """Set color for nonstroking operations.
+        """Set the nonstroking color space.
 
-        Set color for stroking operation if ``stroke`` is set to ``True``.
+        If stroke is set to ``True``, set the stroking color space instead.
 
         """
         self.stream.append(
-            b'/' + _to_bytes(name) + b' ' + (b'SCN' if stroke else b'scn'))
+            b'/' + _to_bytes(space) + b' ' + (b'CS' if stroke else b'cs'))
+
+    def set_color_special(self, name, stroke=False, *operands):
+        """Set special color for nonstroking operations.
+
+        Set special color for stroking operation if ``stroke`` is set to ``True``.
+
+        """
+        if name:
+            operands = (*operands, b'/' + _to_bytes(name))
+        self.stream.append(
+            b' '.join(_to_bytes(operand) for operand in operands) + b' ' +
+            (b'SCN' if stroke else b'scn'))
 
     def set_dash(self, dash_array, dash_phase):
         """Set dash line pattern.
@@ -327,6 +340,27 @@ class Stream(Object):
         """Set line width."""
         self.stream.append(_to_bytes(width) + b' w')
 
+    def set_matrix(self, a, b, c, d, e, f):
+        """Set current transformation matrix.
+
+        :param a: Top left number in the matrix.
+        :type a: :obj:`int` or :obj:`float`
+        :param b: Top middle number in the matrix.
+        :type b: :obj:`int` or :obj:`float`
+        :param c: Middle left number in the matrix.
+        :type c: :obj:`int` or :obj:`float`
+        :param d: Middle middle number in the matrix.
+        :type d: :obj:`int` or :obj:`float`
+        :param e: Bottom left number in the matrix.
+        :type e: :obj:`int` or :obj:`float`
+        :param f: Bottom middle number in the matrix.
+        :type f: :obj:`int` or :obj:`float`
+
+        """
+        self.stream.append(b' '.join((
+            _to_bytes(a), _to_bytes(b), _to_bytes(c),
+            _to_bytes(d), _to_bytes(e), _to_bytes(f), b'cm')))
+
     def set_miter_limit(self, miter_limit):
         """Set miter limit."""
         self.stream.append(_to_bytes(miter_limit) + b' M')
@@ -339,24 +373,8 @@ class Stream(Object):
         """
         self.stream.append(b'/' + _to_bytes(state_name) + b' gs')
 
-    def show_text(self, text):
+    def set_text_matrix(self, a, b, c, d, e, f):
-        """Show text strings with individual glyph positioning."""
+        """Set current text and text line transformation matrix.
-        self.stream.append(b'[' + _to_bytes(text) + b'] TJ')
-
-    def show_text_string(self, text):
-        """Show single text string."""
-        self.stream.append(String(text).data + b' Tj')
-
-    def stroke(self):
-        """Stroke path."""
-        self.stream.append(b'S')
-
-    def stroke_and_close(self):
-        """Stroke and close path."""
-        self.stream.append(b's')
-
-    def text_matrix(self, a, b, c, d, e, f):
-        """Set text matrix and text line matrix.
 
         :param a: Top left number in the matrix.
         :type a: :obj:`int` or :obj:`float`
@@ -376,26 +394,31 @@ class Stream(Object):
             _to_bytes(a), _to_bytes(b), _to_bytes(c),
             _to_bytes(d), _to_bytes(e), _to_bytes(f), b'Tm')))
 
+    def text_matrix(self, a, b, c, d, e, f):
+        """text_matrix is deprecated, use set_text_matrix instead."""
+        warn(Stream.text_matrix.__doc__, DeprecationWarning)
+        self.set_text_matrix(a, b, c, d, e, f)
+
     def transform(self, a, b, c, d, e, f):
-        """Modify current transformation matrix.
+        """transform is deprecated, use set_matrix instead."""
+        warn(Stream.transform.__doc__, DeprecationWarning)
+        self.set_matrix(a, b, c, d, e, f)
 
-        :param a: Top left number in the matrix.
+    def show_text(self, text):
-        :type a: :obj:`int` or :obj:`float`
+        """Show text strings with individual glyph positioning."""
-        :param b: Top middle number in the matrix.
+        self.stream.append(b'[' + _to_bytes(text) + b'] TJ')
-        :type b: :obj:`int` or :obj:`float`
-        :param c: Middle left number in the matrix.
-        :type c: :obj:`int` or :obj:`float`
-        :param d: Middle middle number in the matrix.
-        :type d: :obj:`int` or :obj:`float`
-        :param e: Bottom left number in the matrix.
-        :type e: :obj:`int` or :obj:`float`
-        :param f: Bottom middle number in the matrix.
-        :type f: :obj:`int` or :obj:`float`
 
-        """
+    def show_text_string(self, text):
-        self.stream.append(b' '.join((
+        """Show single text string."""
-            _to_bytes(a), _to_bytes(b), _to_bytes(c),
+        self.stream.append(String(text).data + b' Tj')
-            _to_bytes(d), _to_bytes(e), _to_bytes(f), b'cm')))
+
+    def stroke(self):
+        """Stroke path."""
+        self.stream.append(b'S')
+
+    def stroke_and_close(self):
+        """Stroke and close path."""
+        self.stream.append(b's')
 
     @property
     def data(self):
@@ -444,16 +467,8 @@ class Array(Object, list):
 
 class PDF:
     """PDF document."""
-    def __init__(self, version=None, identifier=None):
+    def __init__(self):
         """Create a PDF document."""
-        if version or identifier:  # to be removed in next version
-            warn(
-                "PDF objects don’t take version or identifier during initialization "
-                "anymore. These properties are now stored but ignored, and will be "
-                "removed and rejected in next version of pydyf. Please pass these "
-                "properties to the PDF.write() method instead.", DeprecationWarning)
-        self.version = _to_bytes(version) if version else b'1.7'  # to be removed
-        self.identifier = identifier  # to be removed
 
         #: Python :obj:`list` containing the PDF’s objects.
         self.objects = []

tests/test_pydyf.py

@@ -282,11 +282,11 @@ def test_curve_end_to():
     ''')
 
 
-def test_transform():
+def test_set_matrix():
     document = pydyf.PDF()
 
     draw = pydyf.Stream()
-    draw.transform(1, 0, 0, 1, 1, 1)
+    draw.set_matrix(1, 0, 0, 1, 1, 1)
     draw.move_to(2, 2)
     draw.set_line_width(2)
     draw.line_to(2, 5)
@@ -673,7 +673,7 @@ def test_text():
     draw = pydyf.Stream()
     draw.begin_text()
     draw.set_font_size('F1', 200)
-    draw.text_matrix(1, 0, 0, 1, -20, 5)
+    draw.set_text_matrix(1, 0, 0, 1, -20, 5)
     draw.show_text(pydyf.String('l'))
     draw.show_text(pydyf.String('É'))
     draw.end_text()