feat: allow DNS entry to be deleted (#37)

Fixes #34

Author: roaldnefs

README.md

@@ -38,7 +38,16 @@
         - [Add a new SSH key](#add-a-new-ssh-key)
         - [Update an SSH key](#update-an-ssh-key)
         - [Delete an SSH key](#delete-an-ssh-key)
-- [Domains](#domains)
+- [Domain](#domain)
+    - [Domains](#domains)
+        - [The **Domain** class](#the-domain-class)
+        - [List all domains](#list-all-domains)
+        - [Retrieve an existing domain](#retrieve-an-existing-domain)
+    - [DNS](#dns)
+        - [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)
+        - [Remove a DNS entry from a domain](#remove-a-dns-entry-from-a-domain)
 - [VPS](#vps)
 - [HA-IP](#ha-ip)
 - [Colocation](#colocation)
@@ -102,7 +111,7 @@ The [general TransIP API](https://api.transip.nl/rest/docs.html#general) resourc
 ### Products
 Manage available TransIP products and product specifications.
 
-### The **Product** class
+#### The **Product** class
 When listing all products available on TransIP, a list of **transip.v6.objects.Product** objects is returned.
 
 **_class_ Product**
@@ -115,7 +124,7 @@ The **Product** class makes the following attributes available:
 - **recurringPrice**: The recurring price for the product in cents.
 - **elements**: The service to list detailed information on the product elements.
 
-### The **ProductElement** class
+#### The **ProductElement** class
 When listing all product elements of a **transip.v6.objects.Product** object, a list of **transip.v6.objects.ProductElement** objects is returned.
 
 **_class_ ProductElement**
@@ -165,7 +174,7 @@ for product in client.products.list():
 ### Availability Zones
 Manage TransIP availability zones.
 
-### The **AvailabilityZone** class
+#### The **AvailabilityZone** class
 When listing all the available availability zones on TransIP, a list of **transip.v6.objects.AvailabilityZone** objects is returned.
 
 **_class_ AvailabilityZone**
@@ -212,7 +221,7 @@ The [account TransIP API](https://api.transip.nl/rest/docs.html#account) resourc
 ### Invoices
 Manage invoices attached to your TransIP account.
 
-### The **Invoice** class
+#### The **Invoice** class
 When listing all invoices attached to your TransIP account, a list of **transip.v6.objects.Invoice** objects is returned.
 
 **_class_ Invoice**
@@ -230,7 +239,7 @@ The **Invoice** class makes the following attributes available:
 - **items**: The service to list detailed information on the individual invoice items.
 
 
-### The **InvoiceItem** class
+#### The **InvoiceItem** class
 When listing all invoices items attached to a **transip.v6.objects.Invoice** object, a list of **transip.v6.objects.InvoiceItem** objects is returned.
 
 **_class_ InvoiceItem**
@@ -437,8 +446,148 @@ The **transip.v6.objects.SshKey** class also provides a **delete()** method to d
 
 **Note:** when using the demo access token, the API currently doesn't list any SSH keys.
 
-## Domains
-The documentation for managing **domains** and related resources has not yet been documented. Feel free to file an [issue](https://github.com/roaldnefs/python-transip/issues/new/choose) for adding the missing section(s) in the documentation.
+## Domain
+The [domains TransIP API](https://api.transip.nl/rest/docs.html#general) resources allow you to manage domains, branding, contacts, DNS, DNSSEC, nameservers, actions, SSL, WHOIS, availability  and call the tlds resource.
+
+The documentation for managing **domains** and related resources has not yet completely been documented. Feel free to file an [issue](https://github.com/roaldnefs/python-transip/issues/new/choose) for adding the missing section(s) in the documentation.
+
+### Domains
+Manage domains.
+
+#### The **Domain** class
+When listing all domains in your TransIP account, a list of **transip.v6.objects.Domain** objects is returned.
+
+**_class_ Domain**
+
+The **Domain** class makes the following attributes available:
+
+- **name**: The name, including the tld of this domain.
+- **authCode**: The authcode for this domain as generated by the registry.
+- **isTransferLocked**: If this domain supports transfer locking, this flag is True when the domains ability to transfer is locked at the registry.
+- **registrationDate**: The registration date of the domain, in YYYY-mm-dd format.
+- **renewalDate**: The next renewal date of the domain, in YYYY-mm-dd format.
+- **isWhitelabel**: If this domain is added to your whitelabel.
+- **cancellationDate**: Cancellation data, in YYYY-mm-dd h:i:s format, None if the domain is active.
+- **cancellationStatus**: Cancellation status, None if the domain is active, ‘cancelled’ when the domain is cancelled.
+- **isDnsOnly**: Whether this domain is DNS only.
+- **tags**: The custom tags added to this domain.
+- **contacts**: The service to manage the domain contacts.
+- **dns**: The service to manage the DNS-records of the domain.
+- **nameservers**: The service to manage the nameservers of the domain.
+
+#### List all domains
+Retrieve all domains registered in your TransIP account by calling **transip.TransIP.domains.list()**. This will return a list of **transip.v6.objects.Domain** objects.
+
+For example:
+```python
+import transip
+# Initialize a client using the TransIP demo token.
+client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)
+
+# List all domains.
+domains = client.domains.list()
+# Show domain information on the screen.
+for domain in domains:
+    print(f"Domain {domain.name} was registered at {domain.registrationDate}")
+```
+
+#### Retrieve an existing domain
+Retrieve a single domain registered ion your TransIP account by its ID by calling **transip.TransIP.domains.get(_name_)**. This will return a **transip.v6.objects.Domain** object.
+
+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')
+# Show domain information on the screen.
+print(f"Domain {domain.name} was registered at {domain.registrationDate}")
+```
+
+### DNS
+Manage DNS records of a domain. Any changes made here will be pushed to the TransIP nameservers.
+#### The **DnsEntry** class
+
+When listing all DNS-records of a **transip.v6.objects.Domain** object, a list of **transip.v6.objects.DnsEntry** objects is returned.
+
+**_class_ DnsEntry**
+
+The **DnsEntry** class makes the following attributes available:
+
+- **name**: The name of the dns entry, for example ‘@’ or ‘www’
+- **expire**: The expiration period of the dns entry, in seconds. For example 86400 for a day of expiration.
+- **type**: The type of dns entry. Possbible types are ‘A’, ‘AAAA’, ‘CNAME’, ‘MX’, ‘NS’, ‘TXT’, ‘SRV’, ‘SSHFP’ and ‘TLSA’.
+- **content**: The content of of the dns entry, for example ‘10 mail’, ‘127.0.0.1’ or ‘www’.
+
+The class has the following methods:
+
+- **delete()** will delete the DNS-record from the domain.
+
+#### 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.
+
+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()
+# Show the DNS record information on the screen.
+for record in records:
+    print(f"DNS: {record.name} {record.expire} {record.type} {record.content}")
+```
+
+#### Add a new single DNS entry to a domain
+Add an new DNS record to a domain by calling **dns.create(_data_)** on a **transip.v6.objects.Domain** object. The **data** keyword argument a dictionary containing the **name**, **expire**, **type** and **content** 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 DNS record.
+dns_entry_data = {
+    "name": "www",
+    "expire": 86400,
+    "type": "A",
+    "content": "127.0.0.1"
+}
+# Add the DNS record to the domain.
+domain.delete(dns_entry_data)
+```
+
+#### 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.
+
+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 DNS record.
+dns_entry_data = {
+    "name": "www",
+    "expire": 86400,
+    "type": "A",
+    "content": "127.0.0.1"
+}
+# Delete the DNS record from the domain.
+domain.delete(dns_entry_data)
+```
+
+The **transip.v6.objects.DnsEntry** class also provides a **delete()** method to delete a **DnsEntry** object from an instance.
 
 ## VPS
 The documentation for managing **VPSs** and related resources has not yet been documented. Feel free to file an [issue](https://github.com/roaldnefs/python-transip/issues/new/choose) for adding the missing section(s) in the documentation.

tests/fixtures/domains.json

@@ -266,6 +266,20 @@
         "status": 200,
         "content_type": "application/json"
     },
+    {
+        "method": "DELETE",
+        "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.1"
+            }
+        }
+    },
     {
         "method": "POST",
         "url": "https://api.transip.nl/v6/domains/example.com/dns",

tests/services/test_domains.py

@@ -86,3 +86,47 @@ def test_dns_create(self) -> None:
         domain.dns.create(dns_entry_data)  # type: ignore
 
         assert len(responses.calls) == 2
+
+    @responses.activate
+    def test_dns_delete(self) -> None:
+        """Check if a single DNS entry can be deleted."""
+        dns_entry_data: Dict[str, Union[str, int]] = {
+            "name": "www",
+            "expire": 86400,
+            "type": "A",
+            "content": "127.0.0.1"
+        }
+        domain: Domain = self.client.domains.get("example.com")  # type: ignore
+
+        try:
+            domain.dns.delete(dns_entry_data)  # type: ignore
+        except Exception as exc:
+            assert False, (
+                "'transip.v6.objects.Domain.dns.delete' raised an exception "
+                f"{exc}"
+            )
+        # Ensure only two calls are being made: the retrieval of the domain and
+        # the deletion of the DNS entry
+        self.assertEqual(len(responses.calls), 2)
+
+    @responses.activate
+    def test_dns_delete_object(self) -> None:
+        """Check if a DNS entry can be deleted from the object itself."""
+        domain: Domain = self.client.domains.get("example.com")  # type: ignore
+        entries = domain.dns.list()
+
+        self.assertEqual(len(entries), 1)
+
+        entry: DnsEntry = entries[0]  # type: ignore
+        try:
+            # Delete the first DNS entry
+            entry.delete()
+        except Exception as exc:
+            assert False, (
+                "'transip.v6.objects.DnsEntry.delete' raised an exception "
+                f"{exc}"
+            )
+        # Ensure only three calls are being made; the retrieval of the domain,
+        # the listing of the DNS entries and the deletion of a single DNS
+        # entry.
+        self.assertEqual(len(responses.calls), 3)

transip/__init__.py

@@ -426,12 +426,16 @@ def patch(
     def delete(
         self,
         path: str,
+        data: Optional[Any] = None,
+        json: Optional[Any] = None,
         params: Optional[Dict[str, Any]] = None
     ) -> Any:
         """Make a GET request to the TransIP API.
 
         Args:
             path (str): The path to append to the API URL
+            data (dict): The body to attach to the request
+            json (dict): The json body to attach to the request
             params (dict): URL parameters to append to the URL
 
         Returns:
@@ -441,5 +445,5 @@ def delete(
             TransIPHTTPError: When the return code of the request is not 2xx
         """
         return self.request(
-            "DELETE", path, params=params
+            "DELETE", path, data=data, json=json, params=params
         )