mtn-cloud 0.3.3__tar.gz → 0.4.0__tar.gz

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mtn-cloud
-Version: 0.3.3
+Version: 0.4.0
 Summary: Community Python SDK for MTN Cloud - Deploy and manage cloud resources with ease
 Project-URL: Homepage, https://github.com/mahveotm/mtn-cloud-python
 Project-URL: Documentation, https://github.com/mahveotm/mtn-cloud-python#readme
@@ -230,6 +230,12 @@ subnets = cloud.networks.list_subnets(new_network.id)
 print(f"Subnets: {len(subnets)}")
 ```
 
+Create routers with existing public networks and internal subnets using
+`cloud.routers.create(...)`, then confirm provisioning with
+`cloud.routers.wait_until_ready(router.id)`. See the
+[Networking guide](docs/networking.md#create-an-mtn-router) and
+[router example](examples/create_router.py) for resource discovery and cleanup.
+
 ### 5. Manage Security Groups
 
 ```python
@@ -359,7 +365,6 @@ Storage vs archive model:
 - `cloud.archive_buckets`: logical file container attached to a provider
 - file operations happen through archive APIs
 
-
 ## Error Handling
 
 ```python
@@ -462,6 +467,7 @@ MIT License. See [LICENSE](LICENSE) for details.
 
 - [MTN Cloud Console](https://console.cloud.mtn.ng)
 - [MTN Cloud Guide](https://cloud.mtn.ng/documentation)
+- [MTN Cloud Pricing](https://cloud.mtn.ng/pricing/pricing-calculator)
 - [Morpheus API Documentation (supplementary)](https://apidocs.morpheusdata.com/)
 - [GitHub Repository](https://github.com/mahveotm/mtn-cloud-python)
 - [PyPI Package](https://pypi.org/project/mtn-cloud/)

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/README.md

@@ -188,6 +188,12 @@ subnets = cloud.networks.list_subnets(new_network.id)
 print(f"Subnets: {len(subnets)}")
 ```
 
+Create routers with existing public networks and internal subnets using
+`cloud.routers.create(...)`, then confirm provisioning with
+`cloud.routers.wait_until_ready(router.id)`. See the
+[Networking guide](docs/networking.md#create-an-mtn-router) and
+[router example](examples/create_router.py) for resource discovery and cleanup.
+
 ### 5. Manage Security Groups
 
 ```python
@@ -317,7 +323,6 @@ Storage vs archive model:
 - `cloud.archive_buckets`: logical file container attached to a provider
 - file operations happen through archive APIs
 
-
 ## Error Handling
 
 ```python
@@ -420,6 +425,7 @@ MIT License. See [LICENSE](LICENSE) for details.
 
 - [MTN Cloud Console](https://console.cloud.mtn.ng)
 - [MTN Cloud Guide](https://cloud.mtn.ng/documentation)
+- [MTN Cloud Pricing](https://cloud.mtn.ng/pricing/pricing-calculator)
 - [Morpheus API Documentation (supplementary)](https://apidocs.morpheusdata.com/)
 - [GitHub Repository](https://github.com/mahveotm/mtn-cloud-python)
 - [PyPI Package](https://pypi.org/project/mtn-cloud/)

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/docs/api-overview.md

@@ -14,6 +14,7 @@ from mtn_cloud import MTNCloud
 - `instances`
 - `instance_types`
 - `networks`
+- `routers`
 - `clouds`
 - `groups`
 - `plans`

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/docs/api-reference/client.md

@@ -22,6 +22,9 @@ Tokens and passwords are stored as masked secret values. Use
 integration needs the underlying value; normal SDK usage never needs to reveal
 them.
 
+`cloud.routers` exposes router discovery, MTN router creation/deletion, and explicit
+readiness/deletion waits. See the [Routers API](./routers.md).
+
 The transport:
 
 - preserves the `mtn-cloud-python/<version>` user-agent identity required by the

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/docs/api-reference/index.md

@@ -8,6 +8,7 @@ This section documents the public SDK surface in endpoint-first format.
 - [Instances (`cloud.instances`)](./instances.md)
 - [Instance Types (`cloud.instance_types`)](./instance-types.md)
 - [Networks (`cloud.networks`)](./networks.md)
+- [Routers (`cloud.routers`)](./routers.md)
 - [Clouds (`cloud.clouds`)](./clouds.md)
 - [Groups (`cloud.groups`)](./groups.md)
 - [Plans (`cloud.plans`)](./plans.md)

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/docs/api-reference/networks.md

@@ -19,12 +19,13 @@
 ### `get_by_name(name: str, cloud_id: int | None = None) -> Network`
 
 - Endpoint sequence:
-    - `GET /api/networks?name=<name>&max=1`
+    - `GET /api/networks?name=<name>&max=100`, paging to check for duplicate exact names
     - Adds `zoneId=<cloud_id>` when provided
 - Returns: `Network`
 - Raises:
     - common API exceptions
-    - `NotFoundError` when no match
+    - `NotFoundError` when no exact match
+    - `ValueError` when multiple exact names match in the selected cloud; use a unique name or `get(id)`
 
 ### `list_by_cloud(cloud_id: int) -> list[Network]`
 
@@ -118,5 +119,5 @@
 - Returns: `list[NetworkPoolIp]`
 - Raises: common API exceptions
 
-> **Note:** Standalone floating-IP endpoints (`/api/networks/floating-ips`) are restricted (HTTP 403) on MTN Cloud tenant accounts and are not exposed by the SDK. Assign external/public connectivity at provisioning time via the instance's `os_external_network_id` instead.
+> **Note:** Standalone floating-IP endpoints (`/api/networks/floating-ips`) are restricted (HTTP 403) on MTN Cloud tenant accounts and are not exposed by the SDK. Use an [MTN router](./routers.md) for a network gateway, or the instance's `os_external_network_id` for public connectivity during provisioning.
 

mtn_cloud-0.4.0/docs/api-reference/routers.md

@@ -0,0 +1,65 @@
+# Routers: `cloud.routers`
+
+Access via `cloud.routers`. List and get inspect router records. Creation and
+deletion support only MTN's `neutronRouter` type; the type is resolved automatically.
+
+### `list(max_results=None, offset=0, sort=None, direction=None, phrase=None, **filters) -> list[Router]`
+
+- Endpoint: `GET /api/networks/routers`
+- Parameters: shared list query arguments; see [API conventions](./index.md).
+- Returns: router records visible to the account, including their type and status.
+- Raises: common API exceptions.
+
+### `get(resource_id: int) -> Router`
+
+- Endpoint: `GET /api/networks/routers/{id}`
+- Parameters: numeric Morpheus router ID.
+- Returns: `Router`, including `status`, `type`, `site`, `zone`, `interfaces`,
+  `external_network`, `external_ip`, and `external_id` when available.
+- Raises: `NotFoundError` when absent; common API exceptions.
+
+### `create(name: str, *, group_id: int, cloud_id: int, resource_pool_id: int, internal_subnet_ids: list[int], external_network_id: int | None = None, enabled: bool = True) -> Router`
+
+- Endpoint: `POST /api/networks/routers`, followed by a router read.
+- Parameters:
+    - `name`: nonempty router name.
+    - `group_id`, `cloud_id`: group and its selected cloud.
+    - `resource_pool_id`: numeric project ID from `instances.get_resource_pool(...).id`.
+    - `internal_subnet_ids`: nonempty list of positive Morpheus subnet IDs from
+      `networks.list_subnets(...)`. Subnets must belong to the selected project.
+    - `external_network_id`: optional public network ID from `networks.get_by_name(...).id`.
+    - `enabled`: whether the router is enabled; defaults to `True`.
+- Returns: initial `Router` record. Provisioning may still be in progress.
+- Raises: Pydantic `ValidationError` for invalid inputs; `ValueError` when the MTN
+  router type is unavailable; common API exceptions. A failed read after successful
+  submission raises `MTNCloudError` with `response["router_id"]` for cleanup.
+
+Call `wait_until_ready(router.id)` to confirm backend readiness.
+
+### `delete(router_id: int) -> bool`
+
+- Endpoints: reads the router to check its type, then `DELETE /api/networks/routers/{id}`.
+- Returns: `True` when deletion is submitted or the router is already absent.
+- Raises: `ValueError` for a non-MTN router; common API exceptions.
+
+Call `wait_until_deleted(router_id)` to confirm removal. Existing networks and
+resource pools are not deleted.
+
+### `wait_until_ready(router_id: int, timeout: float = 300, poll_interval: float = 5) -> Router`
+
+- Endpoint: polls `GET /api/networks/routers/{id}`.
+- Parameters: router ID and positive timeout/poll interval in seconds.
+- Returns: router with status `ok`, `available`, or `active`.
+- Raises: `MTNCloudError` for `failed`/`error` status, SDK `TimeoutError` on timeout,
+  `ValueError` for invalid timing or a non-MTN router, and common API exceptions.
+  Provisioning failure and polling timeout errors include `response["router_id"]`.
+
+### `wait_until_deleted(router_id: int, timeout: float = 300, poll_interval: float = 5) -> bool`
+
+- Endpoint: polls `GET /api/networks/routers/{id}` until it returns 404.
+- Returns: `True` after removal.
+- Raises: SDK `TimeoutError` with `response["router_id"]`, `ValueError` for invalid
+  timing, and common API exceptions. Authorization and server errors are not
+  treated as successful deletion.
+
+See the [Networking guide](../networking.md#create-an-mtn-router) for a complete example.

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/docs/networking.md

@@ -5,7 +5,7 @@ Use this guide for creating and managing MTN Cloud networks via the SDK.
 ## Before You Start
 
 - You need an existing Resource Pool (Project). Create one from **Provisioning → Catalog → Create Project** if you haven't already.
-- MTN Cloud networking runs on OpenStack Neutron. Networks you create are private by default — VMs get private IPs automatically. Public internet access is configured at provisioning time via the instance's external network (`os_external_network_id`), not through a standalone floating-IP API.
+- MTN Cloud networking runs on OpenStack Neutron. Networks you create are private by default — VMs get private IPs automatically. Public connectivity can be configured through an MTN router with a public network gateway, or through the instance's external network (`os_external_network_id`) at provisioning time. Router gateways and instance public IP assignment are separate operations.
 - Use `list_types(openstack_only=True)` to discover the valid network type IDs for your account.
 
 ## Typical Networking Flow
@@ -76,6 +76,65 @@ print(f"Subnets: {len(subnets)}")
 cloud.networks.delete(new_network.id)
 ```
 
+## Create an MTN Router
+
+Use an existing resource pool, a public network, and an internal network in that
+pool. Discover their IDs instead of copying them from the console. Resource pools
+(projects) are distinct from the network IP pools described below.
+
+```python
+from mtn_cloud import MTNCloud
+
+with MTNCloud() as cloud:  # Reads MTN_CLOUD_TOKEN
+    group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
+    if len(group.cloud_ids) != 1:
+        raise ValueError("Select a cloud explicitly for this group.")
+    cloud_id = group.cloud_ids[0]
+
+    pool = cloud.instances.get_resource_pool(
+        "my-project", group_id=group.id, cloud_id=cloud_id
+    )
+    public = cloud.networks.get_by_name("public-network-01", cloud_id=cloud_id)
+    internal = cloud.networks.get_by_name("app-net", cloud_id=cloud_id)
+    internal = cloud.networks.get(internal.id)
+    if internal.zone_pool is None or internal.zone_pool.id != pool.id:
+        raise ValueError("The internal network must belong to the selected resource pool.")
+    subnets = cloud.networks.list_subnets(internal.id)
+
+    router = cloud.routers.create(
+        name="app-router",
+        group_id=group.id,
+        cloud_id=cloud_id,
+        resource_pool_id=pool.id,
+        external_network_id=public.id,
+        internal_subnet_ids=[subnet.id for subnet in subnets],
+    )
+    print("Submitted router:", router.id)
+    router = cloud.routers.wait_until_ready(router.id)
+    print(router.id, router.status, router.external_ip)
+
+    # When no longer needed:
+    # cloud.routers.delete(router.id)
+    # cloud.routers.wait_until_deleted(router.id)
+```
+
+This attaches all subnets returned for the internal network. To attach only one,
+select it explicitly by name or CIDR. The IDs must be Morpheus subnet IDs, not
+network IDs or OpenStack UUIDs. At least one subnet is required.
+
+Only MTN's `neutronRouter` type is supported for creation and deletion. The SDK
+selects the type automatically. `create()` submits provisioning and reads the
+initial router record; use `wait_until_ready()` to confirm that it succeeded.
+Both wait methods default to a five-minute timeout and five-second polling.
+
+A provisioning failure raises `MTNCloudError`; waiting too long raises the SDK's
+`TimeoutError`. These errors include the router ID in `error.response["router_id"]`.
+A failed initial read after creation also preserves the ID there. Inspect or delete
+that router explicitly; the SDK does not automatically remove failed routers.
+Deleting a router leaves its existing networks and resource pool intact.
+
+See the [Routers API reference](./api-reference/routers.md) for method details.
+
 ## Network Pools
 
 Network pools are managed ranges of IP addresses used for static assignment. Inspect them and the individual addresses they track:

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/src/mtn_cloud/_version.py

@@ -1,3 +1,3 @@
 """Package version metadata."""
 
-__version__ = "0.3.3"
+__version__ = "0.4.0"

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/src/mtn_cloud/client.py

@@ -13,6 +13,7 @@ from mtn_cloud.resources.instance_types import InstanceTypesResource
 from mtn_cloud.resources.instances import InstancesResource
 from mtn_cloud.resources.networks import NetworksResource
 from mtn_cloud.resources.plans import PlansResource
+from mtn_cloud.resources.routers import RoutersResource
 from mtn_cloud.resources.security_groups import SecurityGroupsResource
 from mtn_cloud.resources.storage_buckets import StorageBucketsResource
 from mtn_cloud.resources.virtual_images import VirtualImagesResource
@@ -60,6 +61,7 @@ class MTNCloud:
         instances: Manage compute instances
         instance_types: Discover available instance types
         networks: Manage networks
+        routers: Manage MTN routers
         clouds: Manage clouds/zones
         groups: Manage groups (sites)
         plans: Manage service plans
@@ -123,6 +125,7 @@ class MTNCloud:
         self._instances: InstancesResource | None = None
         self._instance_types: InstanceTypesResource | None = None
         self._networks: NetworksResource | None = None
+        self._routers: RoutersResource | None = None
         self._clouds: CloudsResource | None = None
         self._groups: GroupsResource | None = None
         self._plans: PlansResource | None = None
@@ -190,6 +193,13 @@ class MTNCloud:
             self._networks = NetworksResource(self._http)
         return self._networks
 
+    @property
+    def routers(self) -> RoutersResource:
+        """Access MTN router discovery, creation, deletion, and readiness checks."""
+        if self._routers is None:
+            self._routers = RoutersResource(self._http)
+        return self._routers
+
     @property
     def groups(self) -> GroupsResource:
         """

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/src/mtn_cloud/config.py

@@ -1,4 +1,4 @@
-"""Configuration models and defaults for the MTN Cloud SDK."""
+"""Configuration models and defaults for MTN Cloud SDK."""
 
 from pydantic import Field, SecretStr, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/src/mtn_cloud/http.py

@@ -62,9 +62,11 @@ def _redact_sensitive(value: Any, *, known_secrets: Sequence[str] = ()) -> Any:
         return REDACTED
     if isinstance(value, Mapping):
         return {
-            key: REDACTED
-            if _is_sensitive_key(key)
-            else _redact_sensitive(item, known_secrets=known_secrets)
+            key: (
+                REDACTED
+                if _is_sensitive_key(key)
+                else _redact_sensitive(item, known_secrets=known_secrets)
+            )
             for key, item in value.items()
         }
     if isinstance(value, list | tuple | set | frozenset):

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/src/mtn_cloud/models/__init__.py

@@ -40,6 +40,7 @@ from mtn_cloud.models.network import (
 )
 from mtn_cloud.models.plan import ServicePlan
 from mtn_cloud.models.resource_pool import ResourcePool
+from mtn_cloud.models.router import Router, RouterCreate, RouterInterface
 from mtn_cloud.models.security_group import (
     SecurityGroup,
     SecurityGroupCreate,
@@ -74,6 +75,10 @@ __all__ = [
     # Instance Type
     "InstanceType",
     "InstanceTypeLayout",
+    # Router
+    "Router",
+    "RouterCreate",
+    "RouterInterface",
     # Network
     "Network",
     "NetworkType",

mtn_cloud-0.4.0/src/mtn_cloud/models/router.py

@@ -0,0 +1,63 @@
+"""Models for MTN Cloud routers."""
+
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from mtn_cloud.models.base import BaseModel, Resource
+from mtn_cloud.models.network import ResourceReference
+
+PositiveID = Annotated[int, Field(gt=0, strict=True)]
+
+
+class RouterInterface(BaseModel):
+    """An internal network attached to a router."""
+
+    cidr: str | None = None
+    network: ResourceReference | None = None
+
+
+class Router(Resource):
+    """A router returned by MTN Cloud."""
+
+    status: str | None = None
+    enabled: bool = True
+    type: ResourceReference | None = None
+    site: ResourceReference | None = None
+    zone: ResourceReference | None = None
+    external_network: ResourceReference | None = Field(default=None, alias="externalNetwork")
+    external_ip: str | None = Field(default=None, alias="externalIp")
+    external_id: str | None = Field(default=None, alias="externalId")
+    interfaces: list[RouterInterface] = Field(default_factory=list)
+
+
+class RouterCreate(BaseModel):
+    """Typed inputs for creating an MTN neutronRouter."""
+
+    name: str = Field(min_length=1)
+    group_id: PositiveID
+    cloud_id: PositiveID
+    resource_pool_id: PositiveID
+    internal_subnet_ids: list[PositiveID] = Field(min_length=1)
+    external_network_id: PositiveID | None = None
+    enabled: bool = True
+
+    def to_api_payload(self, type_id: int) -> dict[str, Any]:
+        """Build the MTN REST request using the resolved neutronRouter type ID."""
+        pool_code = f"pool-{self.resource_pool_id}"
+        router: dict[str, Any] = {
+            "name": self.name,
+            "site": {"id": self.group_id},
+            "zone": {"id": self.cloud_id},
+            "type": {"id": type_id},
+            "poolId": pool_code,
+            "config": {"poolId": pool_code},
+            "enabled": self.enabled,
+            "interfaces": [
+                {"networkSubnet": {"id": subnet_id}}
+                for subnet_id in dict.fromkeys(self.internal_subnet_ids)
+            ],
+        }
+        if self.external_network_id is not None:
+            router["externalNetwork"] = {"id": self.external_network_id}
+        return {"networkRouter": router}

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/src/mtn_cloud/resources/__init__.py

@@ -9,6 +9,7 @@ from mtn_cloud.resources.instance_types import InstanceTypesResource
 from mtn_cloud.resources.instances import InstancesResource
 from mtn_cloud.resources.networks import NetworksResource
 from mtn_cloud.resources.plans import PlansResource
+from mtn_cloud.resources.routers import RoutersResource
 from mtn_cloud.resources.security_groups import SecurityGroupsResource
 from mtn_cloud.resources.storage_buckets import StorageBucketsResource
 from mtn_cloud.resources.virtual_images import VirtualImagesResource
@@ -18,6 +19,7 @@ __all__ = [
     "InstancesResource",
     "InstanceTypesResource",
     "NetworksResource",
+    "RoutersResource",
     "GroupsResource",
     "CloudsResource",
     "PlansResource",

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/src/mtn_cloud/resources/networks.py

@@ -107,8 +107,16 @@ class NetworksResource(BaseResource[Network]):
 
         Raises:
             NotFoundError: If network not found
+            ValueError: If multiple networks have the exact name in the selected cloud
         """
-        networks = self.list(name=name, cloud_id=cloud_id, max_results=1)
+        networks = []
+        for network in self.iter_all(name=name, cloud_id=cloud_id):
+            if network.name == name:
+                networks.append(network)
+                if len(networks) > 1:
+                    raise ValueError(
+                        f"Network name '{name}' is ambiguous; use a unique name or get(id)."
+                    )
         if not networks:
             raise NotFoundError(
                 resource_type="Network",

mtn_cloud-0.4.0/src/mtn_cloud/resources/routers.py

@@ -0,0 +1,157 @@
+"""Resource manager for MTN Cloud routers."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from mtn_cloud.exceptions import MTNCloudError, NotFoundError, TimeoutError
+from mtn_cloud.models.router import Router, RouterCreate
+from mtn_cloud.resources.base import BaseResource
+
+
+class RoutersResource(BaseResource[Router]):
+    """Inspect routers and create/delete MTN neutronRouter resources."""
+
+    _path = "/networks/routers"
+    _model = Router
+    _name = "router"
+    _list_key = "networkRouters"
+    _item_key = "networkRouter"
+
+    def _type_id(self) -> int:
+        matches: list[dict[str, Any]] = []
+        offset = 0
+        while True:
+            response = self._http.get(
+                "/network-router-types", params={"max": 100, "offset": offset}
+            )
+            page = response.get("networkRouterTypes", [])
+            matches.extend(item for item in page if item.get("code") == "neutronRouter")
+            if len(page) < 100:
+                break
+            offset += len(page)
+        if len(matches) != 1:
+            raise ValueError("Expected exactly one available MTN neutronRouter type.")
+        type_id = int(matches[0]["id"])
+        detail = self._http.get(f"/network-router-types/{type_id}")["networkRouterType"]
+        if (
+            detail.get("code") != "neutronRouter"
+            or not detail.get("creatable")
+            or detail.get("hasNetworkServer")
+        ):
+            raise ValueError("The MTN neutronRouter type is not available for creation.")
+        return type_id
+
+    def create(
+        self,
+        name: str,
+        *,
+        group_id: int,
+        cloud_id: int,
+        resource_pool_id: int,
+        internal_subnet_ids: list[int],
+        external_network_id: int | None = None,
+        enabled: bool = True,
+    ) -> Router:
+        """Submit an MTN router and fetch its initial state.
+
+        Use numeric Morpheus IDs, including the resource pool's numeric ID.
+        Internal subnets must belong to that pool. Call wait_until_ready() to
+        confirm provisioning; successful submission alone does not mean ready.
+        Errors after creation include the router ID in response["router_id"].
+        """
+        request = RouterCreate(
+            name=name,
+            group_id=group_id,
+            cloud_id=cloud_id,
+            resource_pool_id=resource_pool_id,
+            internal_subnet_ids=internal_subnet_ids,
+            external_network_id=external_network_id,
+            enabled=enabled,
+        )
+        response = self._http.post(self._path, json=request.to_api_payload(self._type_id()))
+        router_id = response.get("id")
+        if response.get("success") is not True or type(router_id) is not int or router_id <= 0:
+            raise MTNCloudError(
+                "Router creation did not return success and a valid ID.",
+                response=response,
+            )
+        try:
+            return self.get(router_id)
+        except Exception as exc:
+            raise MTNCloudError(
+                f"Router {router_id} was submitted but could not be read; inspect or delete it by ID.",
+                response={"router_id": router_id},
+            ) from exc
+
+    def delete(self, router_id: int) -> bool:
+        """Submit deletion of an MTN router; an already absent router is success.
+
+        Call wait_until_deleted() to confirm removal. Other router types cannot
+        be deleted through this manager.
+        """
+        try:
+            router = self.get(router_id)
+        except NotFoundError:
+            return True
+        self._require_mtn(router)
+        try:
+            return self._delete(router_id)
+        except NotFoundError:
+            return True
+
+    @staticmethod
+    def _require_mtn(router: Router) -> None:
+        if router.type is None or router.type.code != "neutronRouter":
+            raise ValueError(f"Router {router.id} is not an MTN neutronRouter.")
+
+    @staticmethod
+    def _deadline(timeout: float, poll_interval: float) -> float:
+        if timeout <= 0 or poll_interval <= 0:
+            raise ValueError("timeout and poll_interval must be positive.")
+        return time.monotonic() + timeout
+
+    def wait_until_ready(
+        self, router_id: int, timeout: float = 300, poll_interval: float = 5
+    ) -> Router:
+        """Wait for ok/available/active; raise on provisioning failure or timeout."""
+        deadline = self._deadline(timeout, poll_interval)
+        while True:
+            router = self.get(router_id)
+            self._require_mtn(router)
+            status = (router.status or "").lower()
+            if status in {"ok", "available", "active"}:
+                return router
+            if status in {"failed", "error"}:
+                raise MTNCloudError(
+                    f"Router {router_id} provisioning failed: {status}.",
+                    response={"router_id": router_id, "status": status},
+                )
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(
+                    f"Router {router_id} did not become ready (status: {status}).",
+                    timeout=timeout,
+                    response={"router_id": router_id, "status": status},
+                )
+            time.sleep(min(poll_interval, remaining))
+
+    def wait_until_deleted(
+        self, router_id: int, timeout: float = 300, poll_interval: float = 5
+    ) -> bool:
+        """Wait until the router endpoint returns 404; other API errors propagate."""
+        deadline = self._deadline(timeout, poll_interval)
+        while True:
+            try:
+                self.get(router_id)
+            except NotFoundError:
+                return True
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(
+                    f"Router {router_id} was not deleted.",
+                    timeout=timeout,
+                    response={"router_id": router_id},
+                )
+            time.sleep(min(poll_interval, remaining))

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/tests/test_client.py

@@ -15,6 +15,7 @@ from mtn_cloud.resources.instance_types import InstanceTypesResource
 from mtn_cloud.resources.instances import InstancesResource
 from mtn_cloud.resources.networks import NetworksResource
 from mtn_cloud.resources.plans import PlansResource
+from mtn_cloud.resources.routers import RoutersResource
 from mtn_cloud.resources.security_groups import SecurityGroupsResource
 from mtn_cloud.resources.storage_buckets import StorageBucketsResource
 from mtn_cloud.resources.virtual_images import VirtualImagesResource
@@ -124,6 +125,7 @@ class TestMTNCloudResources:
             ("instances", InstancesResource),
             ("instance_types", InstanceTypesResource),
             ("networks", NetworksResource),
+            ("routers", RoutersResource),
             ("groups", GroupsResource),
             ("clouds", CloudsResource),
             ("plans", PlansResource),
@@ -151,6 +153,7 @@ class TestMTNCloudResources:
             "instances",
             "instance_types",
             "networks",
+            "routers",
             "groups",
             "clouds",
             "plans",

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/tests/test_http.py

@@ -261,7 +261,12 @@ class TestResponseHandling:
         client, _ = client_with_response(
             response(
                 402,
-                {"message": "quota exceeded", "quotaType": "instances", "current": 5, "limit": 5},
+                {
+                    "message": "quota exceeded",
+                    "quotaType": "instances",
+                    "current": 5,
+                    "limit": 5,
+                },
             )
         )
 

{mtn_cloud-0.3.3 → mtn_cloud-0.4.0}/tests/test_networks.py

@@ -451,3 +451,50 @@ class TestNetworksResource:
 
 def _call_data(call_args: Any) -> dict[str, Any]:
     return {"args": list(call_args.args), "kwargs": call_args.kwargs}
+
+
+def test_get_by_name_rejects_ambiguous_networks(mock_http: MagicMock) -> None:
+    mock_http.get.return_value = {
+        "networks": [
+            {"id": 1, "name": "app"},
+            {"id": 2, "name": "app"},
+        ]
+    }
+    with pytest.raises(ValueError, match="ambiguous"):
+        NetworksResource(mock_http).get_by_name("app", cloud_id=4)
+
+
+def test_get_by_name_uses_exact_match(mock_http: MagicMock) -> None:
+    mock_http.get.return_value = {
+        "networks": [
+            {"id": 1, "name": "app-other"},
+            {"id": 2, "name": "app"},
+        ]
+    }
+    assert NetworksResource(mock_http).get_by_name("app", cloud_id=4).id == 2
+    assert mock_http.get.call_args.kwargs["params"]["zoneId"] == 4
+
+
+def test_get_by_name_rejects_ambiguity_across_pages(mock_http: MagicMock) -> None:
+    first_page = [{"id": 1, "name": "app"}] + [
+        {"id": network_id, "name": f"app-{network_id}"} for network_id in range(2, 101)
+    ]
+    mock_http.get.side_effect = [
+        {"networks": first_page},
+        {"networks": [{"id": 101, "name": "app"}]},
+    ]
+
+    with pytest.raises(ValueError, match="ambiguous"):
+        NetworksResource(mock_http).get_by_name("app", cloud_id=4)
+
+    assert mock_http.get.call_count == 2
+    first_request, second_request = mock_http.get.call_args_list
+    assert first_request.args == ("/networks",)
+    assert first_request.kwargs["params"] == {"max": 100, "name": "app", "zoneId": 4}
+    assert second_request.args == ("/networks",)
+    assert second_request.kwargs["params"] == {
+        "max": 100,
+        "offset": 100,
+        "name": "app",
+        "zoneId": 4,
+    }

mtn_cloud-0.4.0/tests/test_routers.py

@@ -0,0 +1,139 @@
+"""Focused router lifecycle tests using the shared mocked HTTP client."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from mtn_cloud.exceptions import MTNCloudError, NotFoundError, TimeoutError
+from mtn_cloud.resources.routers import RoutersResource
+
+ROUTER = {
+    "id": 42,
+    "name": "app",
+    "status": "ok",
+    "type": {"id": 1, "code": "neutronRouter"},
+}
+CREATE = {
+    "name": "app",
+    "group_id": 621,
+    "cloud_id": 4,
+    "resource_pool_id": 213,
+    "internal_subnet_ids": [4112],
+    "external_network_id": 34,
+}
+
+
+def prepare_create(http: MagicMock) -> RoutersResource:
+    http.get.side_effect = [
+        {
+            "networkRouterTypes": [
+                {"id": 9, "code": "other"},
+                {"id": 1, "code": "neutronRouter"},
+            ]
+        },
+        {
+            "networkRouterType": {
+                "id": 1,
+                "code": "neutronRouter",
+                "creatable": True,
+                "hasNetworkServer": False,
+            }
+        },
+        {"networkRouter": ROUTER},
+    ]
+    http.post.return_value = {"success": True, "id": 42}
+    return RoutersResource(http)
+
+
+def test_create_resolves_mtn_type_and_reads_id_only_response(
+    mock_http: MagicMock,
+) -> None:
+    routers = prepare_create(mock_http)
+    assert routers.create(**CREATE).id == 42
+    mock_http.post.assert_called_once_with(
+        "/networks/routers",
+        json={
+            "networkRouter": {
+                "name": "app",
+                "site": {"id": 621},
+                "zone": {"id": 4},
+                "type": {"id": 1},
+                "poolId": "pool-213",
+                "config": {"poolId": "pool-213"},
+                "enabled": True,
+                "externalNetwork": {"id": 34},
+                "interfaces": [{"networkSubnet": {"id": 4112}}],
+            }
+        },
+    )
+    mock_http.get.assert_called_with("/networks/routers/42")
+
+
+def test_post_create_read_error_preserves_cleanup_id(mock_http: MagicMock) -> None:
+    routers = prepare_create(mock_http)
+    responses = list(mock_http.get.side_effect)
+    responses[-1] = NotFoundError(resource_type="Router", resource_id=42)
+    mock_http.get.side_effect = responses
+    with pytest.raises(MTNCloudError) as exc:
+        routers.create(**CREATE)
+    assert exc.value.response == {"router_id": 42}
+
+
+def test_rejects_invalid_subnets_before_requests(mock_http: MagicMock) -> None:
+    with pytest.raises(ValueError):
+        RoutersResource(mock_http).create(**{**CREATE, "internal_subnet_ids": []})
+    mock_http.get.assert_not_called()
+    mock_http.post.assert_not_called()
+
+
+def test_list_and_delete_lifecycle(mock_http: MagicMock) -> None:
+    routers = RoutersResource(mock_http)
+    mock_http.get.return_value = {"networkRouters": [ROUTER]}
+    assert routers.list()[0].id == 42
+    mock_http.get.return_value = {"networkRouter": ROUTER}
+    assert routers.delete(42)
+    mock_http.delete.assert_called_once_with("/networks/routers/42", params=None)
+    mock_http.get.side_effect = [{"networkRouter": ROUTER}, NotFoundError()]
+    with patch("mtn_cloud.resources.routers.time.sleep"):
+        assert routers.wait_until_deleted(42)
+    mock_http.get.side_effect = NotFoundError()
+    assert routers.delete(42)
+
+
+def test_delete_rejects_other_router_types(mock_http: MagicMock) -> None:
+    mock_http.get.return_value = {"networkRouter": {**ROUTER, "type": {"id": 9, "code": "other"}}}
+    with pytest.raises(ValueError, match="not an MTN"):
+        RoutersResource(mock_http).delete(42)
+    mock_http.delete.assert_not_called()
+
+
+def test_wait_until_ready(mock_http: MagicMock) -> None:
+    mock_http.get.side_effect = [
+        {"networkRouter": {**ROUTER, "status": "provisioning"}},
+        {"networkRouter": ROUTER},
+    ]
+    with patch("mtn_cloud.resources.routers.time.sleep"):
+        assert RoutersResource(mock_http).wait_until_ready(42).status == "ok"
+
+
+def test_failed_provisioning_keeps_router_id(mock_http: MagicMock) -> None:
+    mock_http.get.return_value = {"networkRouter": {**ROUTER, "status": "failed"}}
+    with pytest.raises(MTNCloudError, match="provisioning failed") as exc:
+        RoutersResource(mock_http).wait_until_ready(42)
+    assert exc.value.response["router_id"] == 42
+
+
+@pytest.mark.parametrize("method", ["wait_until_ready", "wait_until_deleted"])
+def test_wait_timeout(mock_http: MagicMock, method: str) -> None:
+    mock_http.get.return_value = {"networkRouter": {**ROUTER, "status": "provisioning"}}
+    with patch("mtn_cloud.resources.routers.time.monotonic", side_effect=[0, 301]):
+        with pytest.raises(TimeoutError) as exc:
+            getattr(RoutersResource(mock_http), method)(42)
+    assert exc.value.response["router_id"] == 42
+
+
+def test_create_requires_mtn_type(mock_http: MagicMock) -> None:
+    mock_http.get.return_value = {"networkRouterTypes": [{"id": 9, "code": "other"}]}
+    with pytest.raises(ValueError, match="neutronRouter"):
+        RoutersResource(mock_http).create(**CREATE)
+    mock_http.post.assert_not_called()