Add HTML to PDF support (anvilco#6)

aalmazan · web-flow · commit 0883631172fc · 2021-05-05T20:45:39.000-07:00
* Add HTML-to-PDF support

* Update docs

* Bump version

* More validations, tests
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,7 +1,10 @@
-# 0.1.1 (2021-02-16)
+# 0.2.0 (2021-05-05)
+
+- Add support for HTML to PDF on `generate_pdf`
 
-* Fix for REST API calls failing
+# 0.1.1 (2021-02-16)
 
+- Fix for REST API calls failing
 
 # 0.1.0 (2021-01-30)
 
diff --git a/docs/api_usage.md b/docs/api_usage.md
@@ -37,6 +37,28 @@ response = anvil.fill_pdf("some_template", data)
 Anvil allows you to dynamically generate new PDFs using JSON data you provide via the /api/v1/generate-pdf REST
 endpoint. Useful for agreements, invoices, disclosures, or any other text-heavy documents.
 
+By default, `generate_pdf` will format data assuming it's in [Markdown](https://daringfireball.net/projects/markdown/).
+
+HTML is another supported input type. This can be used by providing
+`"type": "html"` in the payload and making the `data` field a dict containing
+keys `"html"` and an optional `"css"`. Example below:
+
+```python 
+anvil = Anvil(api_key="MY KEY")
+data = {
+    "type": "html",
+    "title": "Some Title",
+    "data": {
+      "html": "<h2>HTML Heading</h2>"
+      "css": "h2 { color: red }"
+    }
+}
+response = anvil.generate_pdf(data)
+```
+
+See the official [Anvil Docs on HTML to PDF](https://www.useanvil.com/docs/api/generate-pdf#html--css-to-pdf)
+for more details.
+
 <strong>payload: Union[dict, AnyStr, GeneratePDFPayload]</strong>
 
 Data to embed into the PDF. Supported `payload` types are:
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,7 +1,7 @@
 [tool.poetry]
 
 name = "python_anvil"
-version = "0.1.1"
+version = "0.2.0"
 description = "Anvil API"
 
 license = "MIT"
diff --git a/python_anvil/api.py b/python_anvil/api.py
@@ -85,6 +85,27 @@ def generate_pdf(self, payload: Union[AnyStr, Dict]):
         else:
             raise ValueError("`payload` must be a valid JSON string or a dict")
 
+        # `dataclasses_json` doesn't seem to validate the `type` field here,
+        # so double-check that.
+        if data.type and data.type.lower() not in ["html", "markdown"]:
+            raise ValueError("`type` must be either 'html' or 'markdown'")
+
+        # For HTML-type payloads, data must be a dict (or JSON object).
+        if data.type == "html":
+            if not isinstance(data.data, dict):
+                raise ValueError(
+                    "`payload` data must be a dict when generating a PDF from HTML"
+                )
+            if "html" not in data.data:
+                raise ValueError(
+                    "`payload` data must have 'html' if using the 'html' type"
+                )
+        elif data.type == 'markdown' and not isinstance(data.data, list):
+            raise ValueError(
+                "`payload` data must be a list of dicts when generating a PDF "
+                "from markdown (this is the default)"
+            )
+
         # Any data errors would come from here..
         api = RestRequest(client=self.client)
         return api.post("generate-pdf", data=remove_empty_items(data.to_dict()))
diff --git a/python_anvil/api_resources/payload.py b/python_anvil/api_resources/payload.py
@@ -31,9 +31,10 @@ class FillPDFPayload(DataClassJsonMixin):
 @dataclass_json(letter_case=LetterCase.CAMEL)
 @dataclass
 class GeneratePDFPayload(DataClassJsonMixin):
-    data: List[Dict[str, Any]]
+    data: Union[List[Dict[str, Any]], Dict[str, Any]]
     logo: Optional[EmbeddedLogo] = None
     title: Optional[str] = None
+    type: Optional[str] = "markdown"  # or html
 
 
 @dataclass_json(letter_case=LetterCase.CAMEL)
diff --git a/python_anvil/tests/test_api.py b/python_anvil/tests/test_api.py
@@ -52,17 +52,61 @@ def describe_generate_pdf():
         def test_dict_payload(m_request_post, anvil):
             anvil.generate_pdf({"data": [{"d1": "data"}]})
             m_request_post.assert_called_once_with(
-                "generate-pdf", data={'data': [{'d1': 'data'}]}
+                # Defaults to 'markdown'
+                "generate-pdf",
+                data={'data': [{'d1': 'data'}], 'type': 'markdown'},
             )
 
         @mock.patch('python_anvil.api.RestRequest.post')
         def test_json_payload(m_request_post, anvil):
             payload = """{ "data": [{ "d1": "data" }] }"""
             anvil.generate_pdf(payload)
             m_request_post.assert_called_once_with(
-                "generate-pdf", data={'data': [{'d1': 'data'}]}
+                "generate-pdf", data={"data": [{"d1": "data"}], "type": "markdown"}
             )
 
+        @mock.patch('python_anvil.api.RestRequest.post')
+        def test_payload_html_type(m_request_post, anvil):
+            anvil.generate_pdf({"data": {"html": "<h1>Hello</h1>"}, "type": "html"})
+            m_request_post.assert_called_once_with(
+                "generate-pdf",
+                data={"data": {"html": "<h1>Hello</h1>"}, "type": "html"},
+            )
+
+        @mock.patch('python_anvil.api.RestRequest.post')
+        def test_invalid_payload_html_payload(m_request_post, anvil):
+            with pytest.raises(ValueError):
+                anvil.generate_pdf({"data": {"no_html_here": "Nope"}, "type": "html"})
+
+        @mock.patch('python_anvil.api.RestRequest.post')
+        def test_payload_invalid_type(m_request_post, anvil):
+            with pytest.raises(ValueError):
+                anvil.generate_pdf(
+                    {"data": [{"d1": "data"}], "type": "something_invalid"}
+                )
+
+        @mock.patch('python_anvil.api.RestRequest.post')
+        def test_invalid_data_for_html(m_request_post, anvil):
+            with pytest.raises(ValueError):
+                anvil.generate_pdf(
+                    {
+                        # This should be a plain dict, not a list
+                        "data": [{"d1": "data"}],
+                        "type": "html",
+                    }
+                )
+
+        @mock.patch('python_anvil.api.RestRequest.post')
+        def test_invalid_data_for_markdown(m_request_post, anvil):
+            with pytest.raises(ValueError):
+                anvil.generate_pdf(
+                    {
+                        # This should be a plain dict, not a list
+                        "data": {"d1": "data"},
+                        "type": "markdown",
+                    }
+                )
+
     def describe_current_user_query():
         @mock.patch('python_anvil.api.GraphqlRequest.post')
         def test_get_current_user(m_request_post, anvil):
