Support version number in PDF fills (anvilco#40)

aalmazan · web-flow · commit e3aae80ae3ac · 2022-09-09T14:45:05.000-07:00
* Fix changelog typo

* Support params in POST requests

* Add `version_number` support in fill_pdf method

* Add version-related constants, Update example

* Update docs

* Bump version

* Update tests, fix from tests

* Typo
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,8 @@
-# 1.5.0 (2022-09-07)
+# 1.7.0 (2022-09-09)
+
+- Added support for `version_number` in PDF Fill requests.
+
+# 1.6.0 (2022-09-07)
 
 - Added support for HTML/CSS and Markdown in `CreateEtchPacket`. [See examples here](https://www.useanvil.com/docs/api/e-signatures#generating-a-pdf-from-html-and-css).
 
diff --git a/docs/api_usage.md b/docs/api_usage.md
@@ -34,6 +34,13 @@ Data to embed into the PDF. Supported `payload` types are:
   sure all required data is set.
 * `FillPDFPayload` - dataclass (see: [Data Types](#data-types))
 
+**version_number: Optional[int]**
+
+Version of the PDF template to use. By default, the request will use the latest published version.
+
+You can also use the constants `Anvil.VERSION_LATEST_PUBLISHED` and `Anvil.VERSION_LATEST`
+instead of providing a specific version number.
+
 Example:
 
 ```python
@@ -46,6 +53,14 @@ data = {
     "data": {"textField": "Some data"}
 }
 response = anvil.fill_pdf("some_template", data)
+
+# A version number can also be passed in. This will retrieve a specific
+# version of the PDF to be filled if you don't want the current version
+# to be used.
+# You can also use the constant `Anvil.VERSION_LATEST` to fill a PDF that has not
+# been published yet. Use this if you'd like to fill out a draft version of
+# your template/PDF.
+response = anvil.fill_pdf("some_template", data, version_number=Anvil.VERSION_LATEST)
 ```
 
 ### Anvil.generate_pdf
diff --git a/examples/fill_pdf.py b/examples/fill_pdf.py
@@ -34,6 +34,15 @@ def main():
     # to a file.
     res = anvil.fill_pdf('abc123', data)
 
+    # A version number can also be passed in. This will retrieve a specific
+    # version of the PDF to be filled if you don't want the current version
+    # to be used.
+    # You can also use the constant `Anvil.VERSION_LATEST` to fill a PDF that has not
+    # been published yet. Use this if you'd like to fill out a draft version of
+    # your template/PDF.
+    #
+    # res = anvil.fill_pdf('abc123', data, version_number=Anvil.VERSION_LATEST)
+
     # Write the bytes to disk
     with open('./file.pdf', 'wb') as f:
         f.write(res)
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,7 +1,7 @@
 [tool.poetry]
 
 name = "python_anvil"
-version = "1.6.0"
+version = "1.7.0"
 description = "Anvil API"
 
 license = "MIT"
diff --git a/python_anvil/api.py b/python_anvil/api.py
@@ -35,6 +35,12 @@ class Anvil:
         >> pdf_data = anvil.fill_pdf("the_template_id", payload)
     """
 
+    # Version number to use for latest versions (usually drafts)
+    VERSION_LATEST = -1
+    # Version number to use for the latest published version.
+    # This is the default when a version is not provided.
+    VERSION_LATEST_PUBLISHED = -2
+
     def __init__(self, api_key=None, environment='dev'):
         self.client = HTTPClient(api_key=api_key, environment=environment)
 
@@ -63,10 +69,13 @@ def fill_pdf(
         Use the casts graphql query to get a list of available templates you
         can use for this request.
 
-        :param template_id: eid of an existing template/cast.
+        :param template_id: eid of an existing template/cast
         :type template_id: str
         :param payload: payload in the form of a dict or JSON data
         :type payload: dict|str
+        :param kwargs.version_number: specific template version number to use. If
+            not provided, the latest _published_ version will be used.
+        :type kwargs.version_number: int
         """
         try:
             if isinstance(payload, dict):
@@ -86,6 +95,10 @@ def fill_pdf(
                 "fields are set. "
             ) from e
 
+        version_number = kwargs.pop("version_number", None)
+        if version_number:
+            kwargs["params"] = dict(versionNumber=version_number)
+
         api = RestRequest(client=self.client)
         return api.post(
             f"fill/{template_id}.pdf",
diff --git a/python_anvil/api_resources/requests.py b/python_anvil/api_resources/requests.py
@@ -68,8 +68,9 @@ def get(self, url, params=None, **kwargs):
 
     def post(self, url, data=None, **kwargs):
         retry = kwargs.pop("retry", True)
+        params = kwargs.pop("params", None)
         content, status_code, headers = self._request(
-            "POST", url, json=data, retry=retry
+            "POST", url, json=data, retry=retry, params=params
         )
         return self.process_response(content, status_code, headers, **kwargs)
 
diff --git a/python_anvil/tests/test_api.py b/python_anvil/tests/test_api.py
@@ -79,6 +79,36 @@ def test_with_kwargs(m_request_post, anvil):
                 include_headers=True,
             )
 
+        @mock.patch('python_anvil.api.RestRequest.post')
+        def test_with_version(m_request_post, anvil):
+            payload = {"data": {"one": "One string"}}
+            anvil.fill_pdf(
+                "some_template",
+                payload=payload,
+                include_headers=True,
+                version_number=Anvil.VERSION_LATEST,
+            )
+            m_request_post.assert_called_once_with(
+                "fill/some_template.pdf",
+                {"data": {"one": "One string"}},
+                include_headers=True,
+                params={"versionNumber": Anvil.VERSION_LATEST},
+            )
+
+        @mock.patch('python_anvil.api.RestRequest.post')
+        def test_with_params(m_request_post, anvil):
+            payload = {"data": {"one": "One string"}}
+            params = {"arbitrary": "Param"}
+            anvil.fill_pdf(
+                "some_template", payload=payload, include_headers=True, params=params
+            )
+            m_request_post.assert_called_once_with(
+                "fill/some_template.pdf",
+                {"data": {"one": "One string"}},
+                include_headers=True,
+                params=params,
+            )
+
     def describe_generate_pdf():
         @mock.patch('python_anvil.api.RestRequest.post')
         def test_dict_payload(m_request_post, anvil):

Original file line number	Diff line number	Diff line change
`@@ -68,8 +68,9 @@ def get(self, url, params=None, **kwargs):`
`68`	`68`
`69`	`69`	`def post(self, url, data=None, **kwargs):`
`70`	`70`	`retry = kwargs.pop("retry", True)`
	`71`	`+ params = kwargs.pop("params", None)`
`71`	`72`	`content, status_code, headers = self._request(`
`72`		`- "POST", url, json=data, retry=retry`
	`73`	`+ "POST", url, json=data, retry=retry, params=params`
`73`	`74`	`)`
`74`	`75`	`return self.process_response(content, status_code, headers, **kwargs)`
`75`	`76`