feat: allow invoice to be written to PDF file (#33)

Signed-off-by: Roald Nefs <info@roaldnefs.com>

Author: roaldnefs

CHANGELOG.md

@@ -7,5 +7,6 @@ All notable changes in **python-transip** are documented below.
 - The `transip.v6.objects.ApiTestService` service to allow calling the test resource to make sure everything is working.
 - The `transip.v6.objects.InvoiceItemService` service to allow listing all invoice items on a `transip.v6.objects.Invoice` object.
 - The `transip.mixins.ObjectUpdateMixin` mixin to allow calling `update()` on API object directly.
+- Allow an invoice to be written to a PDF file by calling the `pdf()` method on a `transip.v6.objects.Invoice` object.
 
 [Unreleased]: https://github.com/roaldnefs/python-transip/compare/v0.3.0...HEAD

tests/services/test_invoices.py

@@ -17,9 +17,11 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with python-transip.  If not, see <https://www.gnu.org/licenses/>.
 
-from typing import List, Tuple, Any, Dict
+from typing import List, Tuple, Any, Dict, Optional
 import responses  # type: ignore
 import unittest
+import tempfile
+import os
 
 from transip import TransIP
 from transip.v6.objects import Invoice, InvoiceItem
@@ -29,6 +31,7 @@ class InvoicesTest(unittest.TestCase):
     """Test the InvoiceService."""
 
     client: TransIP
+    tmp_dir: Optional[tempfile.TemporaryDirectory]
 
     @classmethod
     def setUpClass(cls) -> None:
@@ -65,3 +68,17 @@ def test_items_list(self) -> None:
         # Expect the get_id() method to return None as the invoice items don't
         # have a specific ID attribute.
         self.assertIsNone(items[0].get_id())  # type: ignore
+
+    @responses.activate
+    def test_pdf(self) -> None:
+        """
+        Check if the invoice can be written to a PDF file.
+        """
+        invoice_id = "F0000.1911.0000.0004"
+        invoice: Invoice = self.client.invoices.get(invoice_id)  # type: ignore
+
+        # Write the invoice to a PDF file in a temporary directory.
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            expected = os.path.join(tmp_dir, f"{invoice_id}.pdf")
+            actual = invoice.pdf(tmp_dir)
+            self.assertEqual(actual, expected)

transip/exceptions.py

@@ -50,3 +50,7 @@ def __str__(self) -> str:
 
 class TransIPParsingError(TransIPError):
     pass
+
+
+class TransIPIOError(TransIPError):
+    pass

transip/v6/objects.py

@@ -17,6 +17,9 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with python-transip.  If not, see <https://www.gnu.org/licenses/>.
 
+import os
+import base64
+
 from typing import Optional, Type
 
 from transip.base import ApiService, ApiObject
@@ -25,6 +28,7 @@
     ObjectDeleteMixin, ObjectUpdateMixin,
     CreateAttrsTuple, UpdateAttrsTuple
 )
+from transip.exceptions import TransIPIOError
 
 
 class ApiTestService(ApiService):
@@ -197,6 +201,44 @@ def items(self) -> InvoiceItemService:
             parent=self  # type: ignore
         )
 
+    def pdf(self, file_path: str) -> Optional[str]:
+        """
+        Write a invoice to a PDF file.
+
+        Args:
+            file_path (str): Path to PDF file, if the path is a directory to
+                PDF is saved using its invoice number.
+
+        Returns:
+            str: The absolute path to the saved PDF file.
+
+        Raises:
+            TransIPIOError: If the PDF data couldn't be written to file.
+        """
+        invoice_id = self.get_id()
+        if not invoice_id:
+            return None
+
+        # Retrieve the base64 encoded PDF data
+        encoded = self.service.client.get(f"/invoices/{invoice_id}/pdf")["pdf"]
+        data = base64.b64decode(encoded.encode('ascii'))
+
+        file_path = os.path.abspath(file_path)
+        if os.path.isdir(file_path):
+            file_path = os.path.join(file_path, f"{invoice_id}.pdf")
+        if os.path.exists(file_path):
+            raise TransIPIOError(f"File {file_path} already exists")
+
+        try:
+            with open(file_path, 'wb') as pdf_file:
+                pdf_file.write(data)
+        except OSError as exc:
+            raise TransIPIOError(
+                f"Unable to write PDF file {file_path}"
+            ) from exc
+
+        return file_path
+
 
 class InvoiceService(GetMixin, ListMixin, ApiService):