pyixapi 0.2.8__tar.gz → 0.3.0__tar.gz

{pyixapi-0.2.8 → pyixapi-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyixapi
-Version: 0.2.8
+Version: 0.3.0
 Summary: Python API client library for IX-API
 Author: Guillaume Mazoyer
 Author-email: Guillaume Mazoyer <oss@mazoyer.eu>
@@ -12,7 +12,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: pyjwt>=2.4.0,<2.13
+Requires-Dist: pyjwt>=2.4.0,<2.14
 Requires-Dist: requests>=2.32.4,<3.0
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{pyixapi-0.2.8 → pyixapi-0.3.0}/pyixapi/core/api.py

@@ -12,6 +12,7 @@ from pyixapi.models import (
     IP,
     MAC,
     Account,
+    AvailabilityZone,
     Connection,
     Contact,
     Demarc,
@@ -30,9 +31,10 @@ from pyixapi.models import (
     ProductOffering,
     Role,
     RoleAssignment,
+    RoutingFunction,
 )
 
-__version__ = "0.2.8"
+__version__ = "0.3.0"
 
 
 class API(object):
@@ -61,11 +63,11 @@ class API(object):
         self.http_session = requests.Session()
         self.user_agent = user_agent
         self.proxies = proxies
+        self._version: int | None = None
 
         self.auth = Endpoint(self, "auth")
         self.connections = Endpoint(self, "connections", model=Connection)
         self.contacts = Endpoint(self, "contacts", model=Contact)
-        self.demarcs = Endpoint(self, "demarcs", model=Demarc)
         self.devices = Endpoint(self, "devices", model=Device)
         self.facilities = Endpoint(self, "facilities", model=Facility)
         self.ips = Endpoint(self, "ips", model=IP)
@@ -76,6 +78,7 @@ class API(object):
         self.network_services = Endpoint(self, "network-services", model=NetworkService)
         self.pops = Endpoint(self, "pops", model=PoP)
         # Version 2+
+        self.availability_zones = Endpoint(self, "availability-zones", model=AvailabilityZone)
         self.member_joining_rules = Endpoint(self, "member-joining-rules", model=MemberJoiningRule)
         self.metro_areas = Endpoint(self, "metro-areas", model=MetroArea)
         self.metro_area_networks = Endpoint(self, "metro-area-networks", model=MetroAreaNetwork)
@@ -83,12 +86,19 @@ class API(object):
         self.port_reservations = Endpoint(self, "port-reservations", model=PortReservation)
         self.roles = Endpoint(self, "roles", model=Role)
         self.role_assignments = Endpoint(self, "role-assignments", model=RoleAssignment)
+        self.routing_functions = Endpoint(self, "routing-functions", model=RoutingFunction)
 
     @property
     def version(self) -> int:
         """
         Get the API version of IX-API.
+
+        The version is resolved once on first access and cached for the lifetime
+        of the API instance, as it does not change between requests.
         """
+        if self._version is not None:
+            return self._version
+
         version = Request(
             base=self.url,
             token=self.access_token,
@@ -104,12 +114,19 @@ class API(object):
                 stacklevel=2,
             )
 
+        self._version = version
         return version
 
     @property
     def accounts(self) -> Endpoint:
         return Endpoint(self, "customers" if self.version == 1 else "accounts", model=Account)
 
+    @property
+    def demarcs(self) -> Endpoint:
+        if self.version != 1:
+            raise AttributeError("demarcs endpoint is only available in IX-API v1")
+        return Endpoint(self, "demarcs", model=Demarc)
+
     @property
     def product_offerings(self) -> Endpoint:
         return Endpoint(
@@ -118,6 +135,21 @@ class API(object):
             model=ProductOffering,
         )
 
+    def account(self) -> Account:
+        """
+        Get the authenticated user's own account.
+
+        Available in IX-API 2 or newer.
+        """
+        r = Request(
+            base=cat(self.url, "account"),
+            token=self.access_token,
+            http_session=self.http_session,
+            user_agent=self.user_agent,
+            proxies=self.proxies,
+        )
+        return Account(r._make_call(), self, self.accounts)
+
     def authenticate(self) -> Record | None:
         """
         Authenticate and generate a pair of tokens.
@@ -168,6 +200,20 @@ class API(object):
 
         return Record(r, self, self.auth)
 
+    def extensions(self) -> list[dict[str, Any]]:
+        """
+        Get the list of extensions supported by the IX-API implementation.
+
+        Available in IX-API 2 or newer.
+        """
+        return Request(
+            base=cat(self.url, "extensions"),
+            token=self.access_token,
+            http_session=self.http_session,
+            user_agent=self.user_agent,
+            proxies=self.proxies,
+        )._make_call()
+
     def health(self) -> dict[str, Any]:
         """
         Get the health information from IX-API.
@@ -184,3 +230,17 @@ class API(object):
             user_agent=self.user_agent,
             proxies=self.proxies,
         ).get_health()
+
+    def implementation(self) -> dict[str, Any]:
+        """
+        Get implementation details of the IX-API server.
+
+        Available in IX-API 2 or newer.
+        """
+        return Request(
+            base=cat(self.url, "implementation"),
+            token=self.access_token,
+            http_session=self.http_session,
+            user_agent=self.user_agent,
+            proxies=self.proxies,
+        )._make_call()

{pyixapi-0.2.8 → pyixapi-0.3.0}/pyixapi/core/query.py

@@ -59,10 +59,8 @@ class Request(object):
     Responsible for building the URL and making the HTTP(S) requests to the API.
 
     :param base: (str) Base URL passed in api() instantiation.
-    :param filters: (dict, optional) contains key/value pairs that correlate to the
-        filters a given endpoint accepts.
-        In (e.g. /api/v1/devices?name='test') 'name': 'test' would be in the filters
-        dict.
+    :param filters: (dict, optional) key/value pairs matching the filters an
+        endpoint accepts, e.g. {"name": "test"} for /devices?name=test.
     """
 
     def __init__(
@@ -84,17 +82,6 @@ class Request(object):
         self.user_agent = user_agent
         self.proxies = proxies
 
-    def get_openapi(self) -> dict[str, Any]:
-        """
-        Get the OpenAPI Spec.
-        """
-        headers = {"Content-Type": "application/json;"}
-        req = self.http_session.get(cat(self.base, "docs/?format=openapi"), headers=headers)
-        if req.ok:
-            return req.json()
-        else:
-            raise RequestError(req)
-
     def get_version(self) -> int:
         """
         Get the API version of IX-API.
@@ -129,7 +116,7 @@ class Request(object):
         add_params: dict[str, Any] | None = None,
         data: dict[str, Any] | None = None,
     ) -> Any:
-        if verb in ("post", "put") or verb == "delete" and data:
+        if verb in ("post", "put") or (verb == "delete" and data):
             headers: dict[str, str] = {"Content-Type": "application/json;"}
         else:
             headers = {"accept": "application/json;"}
@@ -184,7 +171,7 @@ class Request(object):
             for i in req:
                 yield i
         else:
-            self.count = len(req)
+            self.count = 1
             yield req
 
     def put(self, data: dict[str, Any]) -> dict[str, Any]:

{pyixapi-0.2.8 → pyixapi-0.3.0}/pyixapi/core/response.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, Iterator
 
 from pyixapi.core.query import Request
-from pyixapi.core.util import Hashabledict
+from pyixapi.core.util import Hashabledict, cat
 
 if TYPE_CHECKING:
     from pyixapi.core.api import API
@@ -90,11 +90,11 @@ class Record(object):
     Create Python objects from IX-API responses.
 
     Nested dicts that represent other endpoints are also turned into
-    :py:class:`.Record` objects. All fields are then assigned to the object's
-    attributes. If a missing attribute is requested (e.g. requesting a field that's
-    only present on a full response on a :py:class:`.Record` made from a nested
-    response) then pyixapi will make a request for the full object and return the
-    requested value.
+    :py:class:`.Record` objects (when the corresponding model declares them as a
+    class attribute). All fields are then assigned to the object's attributes.
+
+    Only the fields present in the response are set as attributes; accessing a
+    field that was not returned raises :py:exc:`AttributeError`.
 
     :examples:
     Default representation of the object is usually its ID and/or name:
@@ -149,7 +149,6 @@ class Record(object):
     url: str | None = None
 
     def __init__(self, values: dict[str, Any], api: API, endpoint: Endpoint) -> None:
-        self._full_cache: list[Any] = []
         self._init_cache: list[tuple[str, Any]] = []
         self.api = api
         self.default_ret: type[Record] = Record
@@ -179,12 +178,6 @@ class Record(object):
     def __repr__(self) -> str:
         return str(dict(self))
 
-    def __getstate__(self) -> dict[str, Any]:
-        return self.__dict__
-
-    def __setstate__(self, d: dict[str, Any]) -> None:
-        self.__dict__.update(d)
-
     def __key__(self) -> tuple[str, ...] | tuple[str]:
         if hasattr(self, "id"):
             return (self.endpoint.name, self.id)
@@ -212,8 +205,7 @@ class Record(object):
             if isinstance(list_item, dict):
                 lookup = getattr(self.__class__, key_name, None)
                 if not isinstance(lookup, list):
-                    # This is *list_parser*, so if the custom model field is not
-                    # a list (or is not defined), just return the default model
+                    # Field not declared as a list model: use the default Record.
                     return self.default_ret(list_item, self.api, self.endpoint)
                 else:
                     model = lookup[0]
@@ -259,16 +251,18 @@ class Record(object):
         return r
 
     def _diff(self) -> set[str]:
-        def fmt_dict(k: str, v: Any) -> tuple[str, Any]:
+        def make_hashable(v: Any) -> Any:
+            # Hashable, structure-preserving form for set comparison. Lists become
+            # tuples, not a joined string (which would collide).
             if isinstance(v, dict):
-                return k, Hashabledict(v)
+                return Hashabledict({k: make_hashable(val) for k, val in v.items()})
             if isinstance(v, list):
-                return k, ",".join(map(str, v))
-            return k, v
+                return tuple(make_hashable(i) for i in v)
+            return v
 
-        current = Hashabledict({fmt_dict(k, v) for k, v in self.serialize().items()})
-        init = Hashabledict({fmt_dict(k, v) for k, v in self.serialize(init=True).items()})
-        return set([i[0] for i in set(current.items()) ^ set(init.items())])
+        current = {k: make_hashable(v) for k, v in self.serialize().items()}
+        init = {k: make_hashable(v) for k, v in self.serialize(init=True).items()}
+        return {key for key, _ in set(current.items()) ^ set(init.items())}
 
     def updates(self) -> dict[str, Any]:
         """
@@ -284,6 +278,15 @@ class Record(object):
                 return {i: serialized[i] for i in diff}
         return {}
 
+    def _make_request(self, sub_path: str) -> Request:
+        return Request(
+            base=cat(self.endpoint.url, self.id, sub_path),
+            token=self.api.access_token,
+            http_session=self.api.http_session,
+            user_agent=self.api.user_agent,
+            proxies=self.api.proxies,
+        )
+
     def save(self) -> bool:
         """
         Save changes to an existing object.
@@ -298,10 +301,15 @@ class Record(object):
                 base=self.endpoint.url,
                 token=self.api.access_token,
                 http_session=self.api.http_session,
-                user_agent=self.user_agent,
+                user_agent=self.api.user_agent,
                 proxies=self.api.proxies,
             )
-            if r.patch(updates):
+            result = r.patch(updates)
+            if result:
+                # Refresh the record from the server response
+                if isinstance(result, dict):
+                    self._init_cache = []
+                    self._parse_values(result)
                 return True
         return False
 
@@ -326,7 +334,7 @@ class Record(object):
             base=self.endpoint.url,
             token=self.api.access_token,
             http_session=self.api.http_session,
-            user_agent=self.user_agent,
+            user_agent=self.api.user_agent,
             proxies=self.api.proxies,
         )
-        return True if r.delete() else False
+        return r.delete()

{pyixapi-0.2.8 → pyixapi-0.3.0}/pyixapi/core/token.py

@@ -29,9 +29,6 @@ class Token:
         self.encoded: str = token  # Cache signed token data
         self.expires_at: datetime = expires_at
 
-    def __str__(self) -> str:
-        return self.encoded
-
     def __repr__(self) -> str:
         return f"<Token ttl={self.ttl}s>"
 

{pyixapi-0.2.8 → pyixapi-0.3.0}/pyixapi/core/util.py

@@ -15,16 +15,16 @@ def cat(*args: Any, separator: str = "/", trailing: str = "") -> str:
 
     If an item cannot be parsed as a string, an AttributeError will be raised.
 
-    >>> concatenate("a", "b", "c")
-    'a/b/c/'
-    >>> concatenate("a", "b", "/c/", separator="")
+    >>> cat("a", "/b/", "c/")
     'a/b/c'
-    >>> concatenate("a", "/b/", 1)
-    'a/b/1/'
-    >>> concatenate("a", "b", "c", separator="_", trailing="_")
-    'a_b_c_'
+    >>> cat("a", 1, "b")
+    'a/1/b'
+    >>> cat("a", "b", "c", separator="_")
+    'a_b_c'
+    >>> cat("a", "b", "c", trailing="/")
+    'a/b/c/'
     """
-    s = separator.join([str(i).lstrip(separator).rstrip(separator) for i in args])
+    s = separator.join([str(i).strip(separator) for i in args if str(i)])
     if trailing:
         s += trailing
     return s

{pyixapi-0.2.8 → pyixapi-0.3.0}/pyixapi/models.py

@@ -1,4 +1,5 @@
 import ipaddress
+from typing import Any
 
 from pyixapi.core.response import Record
 
@@ -24,6 +25,21 @@ class Connection(Record):
     def __str__(self) -> str:
         return f"{self.id}: {self.name}"
 
+    def cancellation_policy(self) -> dict[str, Any]:
+        return self._make_request("cancellation-policy")._make_call()
+
+    def get_loa(self) -> dict[str, Any]:
+        return self._make_request("loa")._make_call()
+
+    def upload_loa(self, data: dict[str, Any]) -> dict[str, Any]:
+        return self._make_request("loa")._make_call(verb="post", data=data)
+
+    def statistics(self, **kwargs: Any) -> dict[str, Any]:
+        return self._make_request("statistics")._make_call(add_params=kwargs or None)
+
+    def statistics_timeseries(self, aggregate: str, **kwargs: Any) -> dict[str, Any]:
+        return self._make_request(f"statistics/{aggregate}/timeseries")._make_call(add_params=kwargs or None)
+
 
 class Contact(Record):
     """
@@ -133,6 +149,21 @@ class NetworkServiceConfig(Record):
     def __str__(self) -> str:
         return self.id
 
+    def cancellation_policy(self) -> dict[str, Any]:
+        return self._make_request("cancellation-policy")._make_call()
+
+    def peer_statistics(self, **kwargs: Any) -> dict[str, Any]:
+        return self._make_request("peer-statistics")._make_call(add_params=kwargs or None)
+
+    def peer_statistics_timeseries(self, aggregate: str, **kwargs: Any) -> dict[str, Any]:
+        return self._make_request(f"peer-statistics/{aggregate}/timeseries")._make_call(add_params=kwargs or None)
+
+    def statistics(self, **kwargs: Any) -> dict[str, Any]:
+        return self._make_request("statistics")._make_call(add_params=kwargs or None)
+
+    def statistics_timeseries(self, aggregate: str, **kwargs: Any) -> dict[str, Any]:
+        return self._make_request(f"statistics/{aggregate}/timeseries")._make_call(add_params=kwargs or None)
+
 
 class NetworkService(Record):
     """
@@ -143,6 +174,27 @@ class NetworkService(Record):
     def __str__(self) -> str:
         return self.id
 
+    def cancellation_policy(self) -> dict[str, Any]:
+        return self._make_request("cancellation-policy")._make_call()
+
+    def change_request(self) -> dict[str, Any]:
+        return self._make_request("change-request")._make_call()
+
+    def create_change_request(self, data: dict[str, Any]) -> dict[str, Any]:
+        return self._make_request("change-request")._make_call(verb="post", data=data)
+
+    def delete_change_request(self) -> bool:
+        return self._make_request("change-request")._make_call(verb="delete")
+
+    def rtt_statistics(self, **kwargs: Any) -> dict[str, Any]:
+        return self._make_request("rtt-statistics")._make_call(add_params=kwargs or None)
+
+    def statistics(self, **kwargs: Any) -> dict[str, Any]:
+        return self._make_request("statistics")._make_call(add_params=kwargs or None)
+
+    def statistics_timeseries(self, aggregate: str, **kwargs: Any) -> dict[str, Any]:
+        return self._make_request(f"statistics/{aggregate}/timeseries")._make_call(add_params=kwargs or None)
+
 
 class PoP(Record):
     """
@@ -168,6 +220,15 @@ class ProductOffering(Record):
 # Version 2 and up
 
 
+class AvailabilityZone(Record):
+    """
+    An AvailabilityZone describes the physical location or zone of a resource.
+    """
+
+    def __str__(self) -> str:
+        return self.name
+
+
 class MemberJoiningRule(Record):
     """
     A MemberJoiningRule defines a rule to allow or deny access for an Account to a
@@ -212,6 +273,12 @@ class Port(Record):
     def __str__(self) -> str:
         return self.name
 
+    def statistics(self, **kwargs: Any) -> dict[str, Any]:
+        return self._make_request("statistics")._make_call(add_params=kwargs or None)
+
+    def statistics_timeseries(self, aggregate: str, **kwargs: Any) -> dict[str, Any]:
+        return self._make_request(f"statistics/{aggregate}/timeseries")._make_call(add_params=kwargs or None)
+
 
 class PortReservation(Record):
     """
@@ -226,6 +293,28 @@ class PortReservation(Record):
     def __str__(self) -> str:
         return self.id
 
+    def cancellation_policy(self) -> dict[str, Any]:
+        return self._make_request("cancellation-policy")._make_call()
+
+    def get_loa(self) -> dict[str, Any]:
+        return self._make_request("loa")._make_call()
+
+    def upload_loa(self, data: dict[str, Any]) -> dict[str, Any]:
+        return self._make_request("loa")._make_call(verb="post", data=data)
+
+
+class RoutingFunction(Record):
+    """
+    A RoutingFunction is a function that provides routing capabilities within a
+    network service.
+    """
+
+    def __str__(self) -> str:
+        return self.id
+
+    def cancellation_policy(self) -> dict[str, Any]:
+        return self._make_request("cancellation-policy")._make_call()
+
 
 class Role(Record):
     """

{pyixapi-0.2.8 → pyixapi-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyixapi"
-version = "0.2.8"
+version = "0.3.0"
 description = "Python API client library for IX-API"
 authors = [{ name = "Guillaume Mazoyer", email = "oss@mazoyer.eu" }]
 readme = "README.md"
@@ -15,15 +15,11 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
 ]
-dependencies = ["PyJWT>=2.4.0,<2.13", "requests>=2.32.4,<3.0"]
+dependencies = ["PyJWT>=2.4.0,<2.14", "requests>=2.32.4,<3.0"]
 
 [dependency-groups]
 dev = ["pytest", "pytest-cov", "ruff", "ty"]
 
-[tool.poetry]
-requires-poetry = ">=2.0"
-packages = [{ include = "pyixapi" }]
-
 [tool.ruff]
 line-length = 120
 exclude = [".git", ".tox", ".venv", "env", "_build", "build", "dist", "examples", "__main__.py"]
@@ -63,7 +59,7 @@ invalid-return-type = "ignore"
 unresolved-import = "ignore"
 
 [tool.pytest.ini_options]
-addopts = "--cov=pyixapi --cov-report=term-missing --cov-report=xml"
+addopts = "--cov=pyixapi --cov-branch --cov-report=term-missing --cov-report=xml"
 
 [tool.coverage.run]
 source = ["pyixapi"]