Update API for consistency

- text_matrix is replaced by set_text_matrix,
- color_space is replaced by set_color_space,
- transform is replaced by set_matrix,
- shading is replaced by paint_shading.

Old functions are marked as deprecated until next version.

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

@@ -122,13 +122,9 @@ def close(self):
         self.stream.append(b'h')
 
     def color_space(self, space, stroke=False):
-        """Set the nonstroking color space.
-
-        If stroke is set to ``True``, set the stroking color space instead.
-
-        """
-        self.stream.append(
-            b'/' + _to_bytes(space) + b' ' + (b'CS' if stroke else b'cs'))
+        """color_space is deprecated, use set_color_space instead."""
+        warn(Stream.color_space.__doc__, DeprecationWarning)
+        self.set_color_space(space, stroke)
 
     def curve_to(self, x1, y1, x2, y2, x3, y3):
         """Add cubic Bézier curve to current path.
@@ -248,6 +244,11 @@ def move_text_to(self, x, y):
         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,6 +282,15 @@ def set_color_rgb(self, r, g, b, stroke=False):
             _to_bytes(r), _to_bytes(g), _to_bytes(b),
             (b'RG' if stroke else b'rg'))))
 
+    def set_color_space(self, space, stroke=False):
+        """Set the nonstroking color space.
+
+        If stroke is set to ``True``, set the stroking color space instead.
+
+        """
+        self.stream.append(
+            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.
 
@@ -330,36 +340,8 @@ def set_line_width(self, width):
         """Set line width."""
         self.stream.append(_to_bytes(width) + b' w')
 
-    def set_miter_limit(self, miter_limit):
-        """Set miter limit."""
-        self.stream.append(_to_bytes(miter_limit) + b' M')
-
-    def set_state(self, state_name):
-        """Set specified parameters in graphic state.
-
-        :param state_name: Name of the graphic state.
-
-        """
-        self.stream.append(b'/' + _to_bytes(state_name) + b' gs')
-
-    def show_text(self, text):
-        """Show text strings with individual glyph positioning."""
-        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.
+    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`
@@ -377,10 +359,22 @@ def text_matrix(self, a, b, c, d, e, f):
         """
         self.stream.append(b' '.join((
             _to_bytes(a), _to_bytes(b), _to_bytes(c),
-            _to_bytes(d), _to_bytes(e), _to_bytes(f), b'Tm')))
+            _to_bytes(d), _to_bytes(e), _to_bytes(f), b'cm')))
 
-    def transform(self, a, b, c, d, e, f):
-        """Modify current transformation matrix.
+    def set_miter_limit(self, miter_limit):
+        """Set miter limit."""
+        self.stream.append(_to_bytes(miter_limit) + b' M')
+
+    def set_state(self, state_name):
+        """Set specified parameters in graphic state.
+
+        :param state_name: Name of the graphic state.
+
+        """
+        self.stream.append(b'/' + _to_bytes(state_name) + b' gs')
+
+    def set_text_matrix(self, a, b, c, d, e, f):
+        """Set current text and text line transformation matrix.
 
         :param a: Top left number in the matrix.
         :type a: :obj:`int` or :obj:`float`
@@ -398,7 +392,33 @@ def transform(self, a, b, c, d, e, f):
         """
         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')))
+            _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):
+        """transform is deprecated, use set_matrix instead."""
+        warn(Stream.transform.__doc__, DeprecationWarning)
+        self.set_matrix(a, b, c, d, e, f)
+
+    def show_text(self, text):
+        """Show text strings with individual glyph positioning."""
+        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')
 
     @property
     def data(self):

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()