feat: add colocation endpoints (#45)

Add the colocation endpoints to list all endpoints and retrieve a single
endpoint by name.

Fixes #24

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

Author: roaldnefs

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes in **python-transip** are documented below.
 ## [Unreleased]
 ### Added
 - The option to replace all existing nameservers of a single domain at once from the `transip.v6.objects.Domain.nameservers` service.
+- The option to list all colocations from the `transip.TransIP.colocations` service ([#24](https://github.com/roaldnefs/python-transip/issues/24)).
+- The option to retrieve a single colocation by name from the `transip.TransIP.colocations` service ([#24](https://github.com/roaldnefs/python-transip/issues/24)).
 
 ## [0.4.0] (2021-01-24)
 ### Added

README.md

@@ -57,6 +57,10 @@
 - [VPS](#vps)
 - [HA-IP](#ha-ip)
 - [Colocation](#colocation)
+    - [Colocations](#colocations)
+        - [The **Colocation** class](#the-colocation-class)
+        - [List all colocations](#list-all-colocations)
+        - [Get colocation](#get-colocation)
 
 ## Introduction
 Welcome to the Python TransIP documentation.
@@ -708,3 +712,49 @@ The documentation for managing **HA-IPs** and related resources has not yet been
 
 ## Colocation
 The documentation for managing **colocations** 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.
+
+### Colocations
+Manage colocations.
+
+#### The **Colocation** class
+When listing all colocations in your TransIP account, a list of **transip.v6.objects.Colocation** objects is returned.
+
+**_class_ Colocation**
+
+The **Colocation** class makes the following attributes available:
+
+- **name**: The colocation name.
+- **ipRanges**: The list of IP ranges.
+
+#### List all colocations
+Retrieve the colocations registered in your TransIP account by calling **transip.TransIP.colocations.list()**. This will return a list of **transip.v6.objects.Colocation** objects.
+
+For example:
+```python
+import transip
+# Initialize a client using the TransIP demo token.
+client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)
+
+# Retrieve the colocations registered in your TransIP account.
+colocations = client.colocations.list()
+# Show the colocations information on the screen.
+for colocation in colocations:
+    ip_ranges = ' '.join(colocation.ipRanges)
+    print(f"Colocation: {colocation.name} has IP ranges: {ip_ranges}")
+```
+
+#### Get colocation
+Retrieve a single colocation registered in your TransIP account by its ID by calling **transip.TransIP.colocations.get(_name_)**. This will return a **transip.v6.objects.Colocation** 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 colocation by its name.
+colocation = client.colocations.get('example2')
+# Show colocation information on the screen.
+ip_ranges = ' '.join(colocation.ipRanges)
+print(f"Colocation: {colocation.name} has IP ranges: {ip_ranges}")
+```

tests/services/test_colocations.py

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2021 Roald Nefs <info@roaldnefs.com>
+#
+# This file is part of python-transip.
+#
+# python-transip is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# python-transip is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# 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, Optional
+import responses  # type: ignore
+import unittest
+import tempfile
+import os
+
+from transip import TransIP
+from transip.v6.objects import Colocation
+from tests.utils import load_responses_fixtures
+
+
+class ColocationsTest(unittest.TestCase):
+    """Test the ColocationService."""
+
+    client: TransIP
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        """Set up a minimal TransIP client for using the colocation services."""
+        cls.client = TransIP(access_token='ACCESS_TOKEN')
+
+    def setUp(self) -> None:
+        """Setup mocked responses for the '/colocations' endpoint."""
+        load_responses_fixtures("colocations.json")
+
+    @responses.activate
+    def test_list(self) -> None:
+        colocations: List[Colocation] = self.client.colocations.list()  # type: ignore
+        self.assertEqual(len(colocations), 1)
+        self.assertEqual(colocations[0].get_id(), "example2")  # type: ignore
+
+    @responses.activate
+    def test_get(self) -> None:
+        colocation_name: str = "example2"
+        colocation: Colocation = self.client.colocations.get(colocation_name)  # type: ignore
+        self.assertEqual(colocation.get_id(), colocation_name)  # type: ignore

transip/__init__.py

@@ -108,6 +108,9 @@ def __init__(
         self.vpss: Type['ApiService'] = (
             objects.VpsService(self)  # type: ignore
         )
+        self.colocations: Type['ApiService'] = (
+            objects.ColocationService(self)  # type: ignore
+        )
 
     @property
     def url(self) -> str:

transip/v6/objects.py

@@ -460,3 +460,17 @@ class VpsService(GetMixin, DeleteMixin, ListMixin, ApiService):
 
     _resp_list_attr: str = "vpss"
     _resp_get_attr: str = "vps"
+
+
+class Colocation(ApiObject):
+
+    _id_attr: str = "name"
+
+
+class ColocationService(GetMixin, ListMixin, ApiService):
+
+    _path: str = "/colocations"
+    _obj_cls: Optional[Type[ApiObject]] = Colocation
+
+    _resp_list_attr: str = "colocations"
+    _resp_get_attr: str = "colocation"