feat: allow DNS record(s) to be updated (#40)

Allow DNS record(s) to be updated:

- Allow a single DNS record to be updated. This will only allow the content of the DNS record to be updated when no other DNS records with the same name, expiry time and type exists.
- Allow all DNS records to be replaced at once.

Fixes #36

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

Author: roaldnefs

CHANGELOG.md

@@ -4,10 +4,12 @@ All notable changes in **python-transip** are documented below.
 ## [Unreleased]
 ### Added
 - This `CHANGELOG.md` file to be able to list all notable changes for each version of **python-transip**.
-- 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.
-- The `transip.v6.objects.ProductService` service to allow listing all products as a `transip.v6.objects.Product` object.
+- The `transip.TransIP.api_test` service to allow calling the test resource to make sure everything is working.
+- The option to list all invoices attached to your TransIP account from the `transip.TransIP.invoices` service.
+- The option to save an invoice as PDF file from `transip.v6.objects.Invoice` object.
+- The option to list all products available in TransIP from the `transip.TransIP.products` service.
+- The option to update a single SSH key from `transip.v6.objects.SshKey` object.
+- The option to update the content of a single DNS record from the `transip.v6.objects.Domain.dns` service, as well as from the `transip.v6.objects.DnsEntry` object.
+- The option to replace all existing DNS records of a single domain at once from the `transip.v6.objects.Domain.dns` service.
 
 [Unreleased]: https://github.com/roaldnefs/python-transip/compare/v0.3.0...HEAD

README.md

@@ -47,6 +47,8 @@
         - [The **DnsEntry** class](#the-dnsentry-class)
         - [List all DNS entries for a domain](#list-all-dns-entries-for-a-domain)
         - [Add a new single DNS entry to a domain](#add-a-new-single-dns-entry-to-a-domain)
+        - [Update single DNS entry](#update-single-dns-entry)
+        - [Update all DNS entries for a domain](#update-all-dns-entries-for-a-domain)
         - [Remove a DNS entry from a domain](#remove-a-dns-entry-from-a-domain)
 - [VPS](#vps)
 - [HA-IP](#ha-ip)
@@ -524,6 +526,7 @@ The **DnsEntry** class makes the following attributes available:
 The class has the following methods:
 
 - **delete()** will delete the DNS-record from the domain.
+- **update()** will send the updated attributes to the TransIP API. This can only be used when updating the **content** attribute of a DnsEntry and when there aren't any other DNS records with the same **name**, **expire** and **type** attributes.
 
 #### List all DNS entries for a domain
 Retrieve the DNS records of a single domain registered in your TransIP account by calling **dns.list()** on a **transip.v6.objects.Domain** object. This will return a list of **transip.v6.objects.DnsEntry** objects.
@@ -565,6 +568,55 @@ dns_entry_data = {
 domain.delete(dns_entry_data)
 ```
 
+#### Update single DNS entry
+Update a single DNS record of a domain by calling **dns.update(_data_)** on a **transip.v6.objects.Domain** object. The **data** keyword argument a dictionary containing the **name**, **expire**, **type** and **content** attributes.
+
+This can only be used when updating the **content** attribute of a DNS entry and when there aren't any other DNS records with the same **name**, **expire** and **type** attributes.
+
+For example:
+```python
+import transip
+# Initialize a client using the TransIP demo token.
+client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)
+
+# Retrieve a domain by its name.
+domain = client.domains.get('transipdemonstratie.nl')
+# Dictionary containing the information for a single updated DNS record.
+dns_entry_data = {
+    "name": "www",
+    "expire": 86400,
+    "type": "A",
+    "content": "127.0.0.2"  # The update content.
+}
+# Update the content of a single DNS record.
+domain.update(dns_entry_data)
+```
+
+#### Update all DNS entries for a domain
+Update all DNS records of a single domain registered in your TransIP account at once by calling **dns.replace()** on a **transip.v6.objects.Domain** object.
+
+**Note:** This will wipe all existing DNS records with the provided records.
+
+For example:
+```python
+import transip
+# Initialize a client using the TransIP demo token.
+client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)
+
+# Retrieve a domain by its name.
+domain = client.domains.get('transipdemonstratie.nl')
+# Retrieve the DNS records of a single domain.
+records = domain.dns.list()
+
+for record in records:
+    # Update the A-record for localhost
+    if record.name == 'localhost' and record.type == 'A':
+        record.content = '127.0.0.1'
+
+# Replace all the records with the updated ones
+domain.dns.replace(records)
+```
+
 #### Remove a DNS entry from a domain
 Delete an existing DNS record from a domain by calling **dns.delete(_data_)** on a **transip.v6.objects.Domain** object. The **data** keyword argument a dictionary containing the **name**, **expire**, **type** and **content** attributes.
 

tests/fixtures/domains.json

@@ -294,6 +294,36 @@
             }
         }
     },
+    {
+        "method": "PUT",
+        "url": "https://api.transip.nl/v6/domains/example.com/dns",
+        "status": 204,
+        "content_type": "application/json",
+        "match_json_params": {
+            "dnsEntries": [
+                {
+                    "name": "www",
+                    "expire": 86400,
+                    "type": "A",
+                    "content": "127.0.0.2"
+                }
+            ]
+        }
+    },
+    {
+        "method": "PATCH",
+        "url": "https://api.transip.nl/v6/domains/example.com/dns",
+        "status": 204,
+        "content_type": "application/json",
+        "match_json_params": {
+            "dnsEntry": {
+                  "name": "www",
+                  "expire": 86400,
+                  "type": "A",
+                  "content": "127.0.0.2"
+            }
+        }
+    },
     {
         "method": "GET",
         "url": "https://api.transip.nl/v6/domains/example.com/nameservers",

tests/services/test_domains.py

@@ -67,12 +67,37 @@ def test_nameservers_list(self) -> None:
 
     @responses.activate
     def test_dns_list(self) -> None:
+        """
+        Check if the DNS records for a single domain can be listed.
+        """
         domain: Domain = self.client.domains.get("example.com")  # type: ignore
         entries: List[DnsEntry] = domain.dns.list()  # type: ignore
+
+        self.assertEqual(len(entries), 1)
         entry: DnsEntry = entries[0]
+        self.assertEqual(entry.content, "127.0.0.1")  # type: ignore
+
+    @responses.activate
+    def test_dns_replace(self) -> None:
+        """
+        Check if the existing DNS records for a single domain can be replaced
+        at once.
+        """
+        domain: Domain = self.client.domains.get("example.com")  # type: ignore
+        records: List[DnsEntry] = domain.dns.list()  # type: ignore
+
+        # Ensure we have a single DNS record
+        self.assertEqual(len(records), 1)
+        # Update the content of the first DNS record in the list of existing
+        # records.
+        records[0].content = '127.0.0.2'
+
+        # Replace all existing records.
+        try:
+            domain.dns.replace(records)  # type: ignore
+        except Exception as exc:
+            assert False, f"'transip.v6.objects.Domain.dns.replace' raised an exception {exc}"
 
-        assert len(entries) == 1
-        assert entry.name == "www"  # type: ignore
 
     @responses.activate
     def test_dns_create(self) -> None:
@@ -87,6 +112,44 @@ def test_dns_create(self) -> None:
 
         assert len(responses.calls) == 2
 
+    @responses.activate
+    def test_dns_update(self) -> None:
+        """
+        Check if a single DNS entry can be updated.
+        """
+        dns_entry_data: Dict[str, Union[str, int]] = {
+            "name": "www",
+            "expire": 86400,
+            "type": "A",
+            "content": "127.0.0.2"  # original content is 127.0.0.1
+        }
+        domain: Domain = self.client.domains.get("example.com")  # type: ignore
+
+        try:
+            domain.dns.update(dns_entry_data)
+        except Exception as exc:
+            assert False, f"'transip.v6.objects.Domain.dns.update' raised an exception {exc}"
+
+    @responses.activate
+    def test_dns_update_object(self) -> None:
+        """
+        Check if a single DNS entry can be updated from the ApiObject itself.
+        """
+        domain: Domain = self.client.domains.get("example.com")  # type: ignore
+        entries: List[DnsEntry] = domain.dns.list()  # type: ignore
+
+        self.assertEqual(len(entries), 1)
+        entry: DnsEntry = entries[0]
+        self.assertEqual(entry.content, "127.0.0.1")  # type: ignore
+
+        entry.content = '127.0.0.2'
+        try:
+            entry.update()
+        except Exception as exc:
+            assert False, f"'transip.v6.objects.DnsEntry.update' raised an exception {exc}"
+
+        self.assertEqual(entry.content, "127.0.0.2")  # type: ignore
+
     @responses.activate
     def test_dns_delete(self) -> None:
         """Check if a single DNS entry can be deleted."""

transip/mixins.py

@@ -23,13 +23,12 @@
 from transip.base import ApiObject, ApiService
 
 
-# Typing alias for the _create_attrs attribute in the CreateMixin
-CreateAttrsTuple = Tuple[
+# Typing alias for the _create_attrs, _update_attrs and _delete_attrs
+# attributes in the CreateMixin, UpdateMixin and DeleteMixin
+AttrsTuple = Tuple[
     Union[Tuple[()], Tuple[str, ...]],
     Union[Tuple[()], Tuple[str, ...]]
 ]
-# Typing alias for the _update_attrs attribute in the UpdateMixin
-UpdateAttrsTuple = CreateAttrsTuple
 
 
 class GetMixin:
@@ -127,21 +126,22 @@ def list(self) -> List[Type[ApiObject]]:
 
 
 class UpdateMixin:
-    """Update an ApiObject.
+    """
+    Update an ApiObject.
     """
 
     client: TransIP
     path: str
 
     _req_update_attr: Optional[str] = None
-    _update_attrs: Optional[CreateAttrsTuple] = None
+    _update_attrs: Optional[AttrsTuple] = None
 
     def get_update_attrs(self) -> Tuple[
         Union[Tuple[()], Tuple[str, ...]],
         Union[Tuple[()], Tuple[str, ...]]
     ]:
         """
-        Return the required and optional attributes for updating a new object.
+        Return the required and optional attributes for updating an object.
 
         Returns:
             tuple: a tuple containing a tuple of required and optional
@@ -182,14 +182,76 @@ def update(
         self._check_update_attrs(data)
 
         # Some endpoints require the attributes to be packed in dictionary with
-        # a specific key while others endpoint do not
+        # a specific key while others endpoint may not
         if self._req_update_attr:
             data = {self._req_update_attr: data}
 
         if self.path:
             self.client.put(f"{self.path}/{id}", json=data)
 
 
+class ReplaceMixin:
+    """
+    Replace a list of ApiObject at once by wiping to old objects and replacing
+    them with the provided list of ApiObjects.
+    """
+
+    client: TransIP
+    path: str
+
+    _req_replace_attr: Optional[str] = None
+    _replace_attrs: Optional[AttrsTuple] = None
+
+    def get_replace_attrs(self) -> Tuple[
+        Union[Tuple[()], Tuple[str, ...]],
+        Union[Tuple[()], Tuple[str, ...]]
+    ]:
+        """
+        Return the required and optional attributes for replacing a object.
+
+        Returns:
+            tuple: a tuple containing a tuple of required and optional
+                attributes.
+        """
+        if not self._replace_attrs:
+            return (tuple(), tuple())
+        else:
+            return self._replace_attrs
+
+    def replace(self, objs: List[Type[ApiObject]]) -> None:
+        """
+        Replace all existing objects with the provided once.
+
+        Args:
+            objs: List of ApiObjects to replace the existing once with.
+        """
+        data = []
+
+        required, optional = self.get_replace_attrs()
+
+        for obj in objs:
+            obj_data = {}
+
+            # Ensure all required attributes are added
+            for attr in required:
+                obj_data[attr] = getattr(obj, attr)
+            # Ensure all optional attributes are added
+            for attr in optional:
+                obj_data[attr] = getattr(obj, attr)
+            # Overwrite the existing attributes with any updated attributes
+            obj_data.update(obj._updated_attrs)  # type: ignore
+
+            data.append(obj_data)
+
+        # Some endpoints require the attributes to be packed in dictionary with
+        # a specific key while others endpoint may not
+        if self._req_replace_attr:
+            data = {self._req_replace_attr: data}  # type: ignore
+
+        if self.path:
+            self.client.put(self.path, json=data)
+
+
 class CreateMixin:
     """
     Create a new ApiObject.
@@ -198,7 +260,7 @@ class CreateMixin:
     path: str
 
     _req_create_attr: Optional[str] = None
-    _create_attrs: Optional[CreateAttrsTuple] = None
+    _create_attrs: Optional[AttrsTuple] = None
 
     def _check_create_attrs(self, attrs) -> None:
         """