mtn-cloud 0.2.19__tar.gz → 0.3.1__tar.gz

{mtn_cloud-0.2.19 → mtn_cloud-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtn-cloud
-Version: 0.2.19
+Version: 0.3.1
 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
@@ -84,7 +84,6 @@ pip install mtn-cloud
 - [Advanced Cookbook](https://mahveotm.github.io/mtn-cloud-python/advanced-cookbook/)
 - [API Overview](https://mahveotm.github.io/mtn-cloud-python/api-overview/)
 - [API Reference](https://mahveotm.github.io/mtn-cloud-python/api-reference/)
-- [Docstring Style Standard](https://mahveotm.github.io/mtn-cloud-python/docstring-style/)
 
 ## Quick Start
 
@@ -200,27 +199,32 @@ cloud.instances.delete(123, force=True, preserve_volumes=True)
 ### 4. Work with Networks
 
 ```python
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
+
 # List networks
-networks = cloud.networks.list(cloud_id=1)
+networks = cloud.networks.list(cloud_id=group.cloud_ids[0])
 for n in networks[:5]:
     print(n.id, n.name, n.cidr)
 
-# Create an OpenStack-focused network
-network_types = cloud.networks.list_types(openstack_only=True)
+# Create an OpenStack network (needs an OpenStack type + a resource pool)
+net_type = next(
+    t for t in cloud.networks.list_types(openstack_only=True)
+    if t.code == "openstackPrivate"
+)
+pool = cloud.instances.get_resource_pool("my-project", group=group.name)
+
 new_network = cloud.networks.create(
     name="mtn-prod-net",
-    cloud_id=1,
-    group_id=621,
-    type_id=network_types[0].id,
+    cloud_id=group.cloud_ids[0],
+    group_id=group.id,
+    type_id=net_type.id,
+    resource_pool_id=pool.id,
     cidr="10.42.10.0/24",
     gateway="10.42.10.1",
     dns_primary="8.8.8.8",
-    visibility="private",
-    dhcp_server=True,
 )
 
-# Update and list subnets
-cloud.networks.update(new_network.id, description="Production network")
+# Inspect subnets
 subnets = cloud.networks.list_subnets(new_network.id)
 print(f"Subnets: {len(subnets)}")
 ```

{mtn_cloud-0.2.19 → mtn_cloud-0.3.1}/README.md

@@ -40,7 +40,6 @@ pip install mtn-cloud
 - [Advanced Cookbook](https://mahveotm.github.io/mtn-cloud-python/advanced-cookbook/)
 - [API Overview](https://mahveotm.github.io/mtn-cloud-python/api-overview/)
 - [API Reference](https://mahveotm.github.io/mtn-cloud-python/api-reference/)
-- [Docstring Style Standard](https://mahveotm.github.io/mtn-cloud-python/docstring-style/)
 
 ## Quick Start
 
@@ -156,27 +155,32 @@ cloud.instances.delete(123, force=True, preserve_volumes=True)
 ### 4. Work with Networks
 
 ```python
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
+
 # List networks
-networks = cloud.networks.list(cloud_id=1)
+networks = cloud.networks.list(cloud_id=group.cloud_ids[0])
 for n in networks[:5]:
     print(n.id, n.name, n.cidr)
 
-# Create an OpenStack-focused network
-network_types = cloud.networks.list_types(openstack_only=True)
+# Create an OpenStack network (needs an OpenStack type + a resource pool)
+net_type = next(
+    t for t in cloud.networks.list_types(openstack_only=True)
+    if t.code == "openstackPrivate"
+)
+pool = cloud.instances.get_resource_pool("my-project", group=group.name)
+
 new_network = cloud.networks.create(
     name="mtn-prod-net",
-    cloud_id=1,
-    group_id=621,
-    type_id=network_types[0].id,
+    cloud_id=group.cloud_ids[0],
+    group_id=group.id,
+    type_id=net_type.id,
+    resource_pool_id=pool.id,
     cidr="10.42.10.0/24",
     gateway="10.42.10.1",
     dns_primary="8.8.8.8",
-    visibility="private",
-    dhcp_server=True,
 )
 
-# Update and list subnets
-cloud.networks.update(new_network.id, description="Production network")
+# Inspect subnets
 subnets = cloud.networks.list_subnets(new_network.id)
 print(f"Subnets: {len(subnets)}")
 ```

{mtn_cloud-0.2.19 → mtn_cloud-0.3.1}/docs/advanced-cookbook.md

@@ -103,9 +103,10 @@ from mtn_cloud import (
 try:
     cloud.networks.create(
         name="prod-net",
-        cloud_id=1,
+        cloud_id=4,
         group_id=621,
-        type_id=8,
+        type_id=12,             # an OpenStack type from list_types(openstack_only=True)
+        resource_pool_id=230,   # numeric pool ID from get_resource_pool(...).id
         cidr="10.42.10.0/24",
     )
 except AuthenticationError:
@@ -149,8 +150,17 @@ with MTNCloud(token="your-api-token") as cloud:
 Pick explicit templates and plans instead of "first result" in production.
 
 ```python
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
 target_type = cloud.instance_types.get_by_code("MTN-U24.04LTS")
-target_plan = cloud.plans.get_by_name("G2S4")
+
+plans = cloud.instances.list_service_plans(
+    zone_id=group.cloud_ids[0],
+    layout_id=target_type.default_layout_id,
+    group_id=group.id,
+)
+target_plan = next(p for p in plans if p["name"] == "G2S4")
+
+pool = cloud.instances.get_resource_pool("my-project", group=group.name)
 
 instance = cloud.instances.create(
     name="api-worker-01",
@@ -158,8 +168,8 @@ instance = cloud.instances.create(
     type=target_type.code,
     group="MTNNG_CLOUD_AZ_1",
     layout=target_type.default_layout_id,
-    plan=target_plan.id,
-    resource_pool_id="pool-214",
+    plan=target_plan["id"],
+    resource_pool_id=pool.code,
 )
 ```
 

{mtn_cloud-0.2.19 → mtn_cloud-0.3.1}/docs/api-reference/networks.md

@@ -32,7 +32,7 @@
 - Returns: `list[Network]`
 - Raises: common API exceptions
 
-### `create(name: str, *, cloud_id: int, group_id: int, type_id=None, display_name=None, labels=None, description=None, cidr=None, gateway=None, dns_primary=None, dns_secondary=None, vlan_id=None, switch_id=None, pool_id=None, allow_static_override=None, assign_public_ip=None, active=None, dhcp_server=None, network_domain_id=None, search_domains=None, network_proxy_id=None, appliance_url_proxy_bypass=None, no_proxy=None, visibility=None, tenant_ids=None, resource_permission_all=None, resource_permission_site_ids=None) -> Network`
+### `create(name: str, *, cloud_id: int, group_id: int, type_id=None, resource_pool_id=None, display_name=None, labels=None, description=None, cidr=None, gateway=None, dns_primary=None, dns_secondary=None, vlan_id=None, switch_id=None, pool_id=None, allow_static_override=None, assign_public_ip=None, active=None, dhcp_server=None, network_domain_id=None, search_domains=None, network_proxy_id=None, appliance_url_proxy_bypass=None, no_proxy=None, visibility=None, tenant_ids=None, resource_permission_all=None, resource_permission_site_ids=None) -> Network`
 
 - Endpoint: `POST /api/networks`
 - Parameters:
@@ -40,8 +40,11 @@
         - `name`: network name
         - `cloud_id`: cloud/zone ID
         - `group_id`: group/site ID
+    - Required for OpenStack networks (e.g. `openstackPrivate`):
+        - `type_id`: an OpenStack network type ID from `list_types(openstack_only=True)`
+        - `resource_pool_id`: numeric resource pool ID (sent as `zonePool`); get it from `instances.get_resource_pool(...).id`
     - Common optional network config:
-        - `type_id`, `display_name`, `labels`, `description`, `cidr`, `gateway`
+        - `display_name`, `labels`, `description`, `cidr`, `gateway`
         - `dns_primary`, `dns_secondary`, `vlan_id`, `switch_id`, `pool_id`
         - `allow_static_override`, `assign_public_ip`, `active`, `dhcp_server`
         - `network_domain_id`, `search_domains`, `network_proxy_id`

{mtn_cloud-0.2.19 → mtn_cloud-0.3.1}/docs/index.md

@@ -18,7 +18,6 @@ Use this guide in two ways:
 8. [Advanced Cookbook](./advanced-cookbook.md)
 9. [API Overview](./api-overview.md)
 10. [API Reference](./api-reference/index.md)
-11. [Docstring Style Standard](./docstring-style.md)
 
 ## Who This Is For
 

{mtn_cloud-0.2.19 → mtn_cloud-0.3.1}/docs/networking.md

@@ -33,21 +33,25 @@ print([(t.id, t.name) for t in network_types[:5]])
 
 ## Create a Network
 
+An OpenStack network requires an OpenStack `type_id` and a `resource_pool_id` (the numeric pool ID — the network is created inside that resource pool). Pick a private network type and a pool:
+
 ```python
 networks = cloud.networks.list(cloud_id=cloud_id)
 for network in networks[:5]:
     print(network.id, network.name, network.cidr)
 
+net_type = next(t for t in network_types if t.code == "openstackPrivate")
+pool = cloud.instances.get_resource_pool("my-project", group=group.name)
+
 new_network = cloud.networks.create(
     name="mtn-prod-net",
     cloud_id=cloud_id,                  # from group.cloud_ids[0]
     group_id=group.id,                  # from groups.get_by_name(...)
-    type_id=network_types[0].id,        # from list_types(openstack_only=True)
+    type_id=net_type.id,                # an OpenStack type from list_types(openstack_only=True)
+    resource_pool_id=pool.id,           # numeric pool ID from get_resource_pool(...)
     cidr="10.42.10.0/24",
     gateway="10.42.10.1",
     dns_primary="8.8.8.8",
-    visibility="private",
-    dhcp_server=True,                   # enables automatic IP assignment
 )
 
 print(new_network.id, new_network.name)

{mtn_cloud-0.2.19 → mtn_cloud-0.3.1}/docs/quickstart.md

@@ -57,11 +57,28 @@ One tenancy can have multiple resource pools — useful for separating dev, stag
 
 Security groups are the firewall layer for your VMs. Without one, you will not be able to SSH or RDP in after provisioning.
 
-1. Go to **Infrastructure → Network → Security Groups** and create a group.
-2. Add an inbound rule: SSH port 22 (TCP) for Linux VMs, or RDP port 3389 (TCP) for Windows VMs.
-3. Restrict the source to your IP range, e.g., `200.200.113.15/32` for a single machine.
+You can create one either in the console (**Infrastructure → Network → Security Groups**) or directly with the SDK:
 
-The group name (e.g., `"default"`) is passed as the `security_group` parameter when creating an instance.
+```python
+# Create the group
+sg = cloud.security_groups.create(
+    name="web-servers",
+    description="SSH + HTTPS access",
+)
+
+# Allow SSH from a single machine (use 3389/tcp instead for Windows RDP)
+cloud.security_groups.create_rule(
+    sg.id,
+    name="allow-ssh",
+    direction="ingress",
+    protocol="tcp",
+    port_range="22",
+    source_type="cidr",
+    source="200.200.113.15/32",   # restrict to your IP range
+)
+```
+
+The group name (e.g., `"web-servers"` or `"default"`) is passed as the `security_group` parameter when creating an instance. See the [Security Groups guide](./security-groups.md) for the full workflow.
 
 Optionally, add an SSH key pair under **User Settings → SSH Keys** for key-based access.
 
@@ -77,18 +94,30 @@ Keep the credentials from that email — you will pass them directly into the SD
 
 ## 5. Discover Core Reference Data
 
-Before creating resources, look up the valid IDs and codes for your account. These are tenant-specific and cannot be copied from documentation or other accounts.
+Before creating resources, look up the valid IDs and codes for your account. These are tenant-specific and cannot be copied from documentation or other accounts. Everything below uses permission-safe endpoints — the admin-level `clouds.list()` and `plans.list()` are restricted on most tenant accounts and aren't needed.
 
 ```python
-groups = cloud.groups.list()
-clouds = cloud.clouds.list_openstack()
-instance_types = cloud.instance_types.list_os()
-plans = cloud.plans.list()
-
-print("Groups:", [(g.id, g.name) for g in groups[:5]])
-print("Clouds:", [(c.id, c.name) for c in clouds[:5]])
-print("Instance types:", [(t.code, t.default_layout_id) for t in instance_types[:5]])
-print("Plans:", [(p.id, p.name, p.cores, p.memory_gb) for p in plans[:5]])
+# Group — also carries the cloud/zone IDs you need
+group = cloud.groups.get_by_name("MTNNG_CLOUD_AZ_1")
+cloud_id = group.cloud_ids[0]
+
+# Instance type — carries its own default_layout_id
+itype = cloud.instance_types.get_by_code("MTN-CS10")
+
+# Resource pool — the resource_pool_id, where the instance is hosted
+pools = cloud.instances.list_resource_pools(group=group.name)
+
+# Service plans — CPU/memory/storage tiers for this zone + layout
+plans = cloud.instances.list_service_plans(
+    zone_id=cloud_id,
+    layout_id=itype.default_layout_id,
+    group_id=group.id,
+)
+
+print("group:", group.id, "cloud_id:", cloud_id)
+print("layout:", itype.default_layout_id)
+print("pools:", [(p.code, p.name) for p in pools[:5]])
+print("plans:", [(pl["id"], pl["name"]) for pl in plans[:5]])
 ```
 
 MTN Cloud currently has two live zones: **Lagos AZ1** (`MTNNG_CLOUD_AZ_1`) and **Lagos AZ2** (`MTNNG_CLOUD_AZ_2`).
@@ -105,9 +134,9 @@ instance = cloud.instances.create(
     group="MTNNG_CLOUD_AZ_1",
     layout=327,
     plan=6923,
-    resource_pool_id="pool-214",        # from your project order
+    resource_pool_id=pools[0].code,     # from list_resource_pools() above
     availability_zone="Lagos-AZ-1-fd1",
-    security_group="default",           # security group name from the console
+    security_group="web-servers",       # the security group you created above
 )
 
 print(instance.id, instance.name, instance.status, instance.primary_ip)

{mtn_cloud-0.2.19 → mtn_cloud-0.3.1}/src/mtn_cloud/_version.py

@@ -1,3 +1,3 @@
 """Package version metadata."""
 
-__version__ = "0.2.19"
+__version__ = "0.3.1"

{mtn_cloud-0.2.19 → mtn_cloud-0.3.1}/src/mtn_cloud/models/base.py

@@ -7,7 +7,7 @@ from datetime import datetime
 from typing import Any, Generic, TypeVar
 
 from pydantic import BaseModel as PydanticBaseModel
-from pydantic import ConfigDict, Field
+from pydantic import ConfigDict, Field, field_validator
 
 
 class BaseModel(PydanticBaseModel):
@@ -28,6 +28,12 @@ class BaseModel(PydanticBaseModel):
         from_attributes=True,
     )
 
+    @field_validator("labels", mode="before", check_fields=False)
+    @classmethod
+    def _coerce_null_labels(cls, value: Any) -> Any:
+        """Treat a null ``labels`` field from the API as an empty list."""
+        return [] if value is None else value
+
 
 class Resource(BaseModel):
     """

{mtn_cloud-0.2.19 → mtn_cloud-0.3.1}/src/mtn_cloud/models/network.py

@@ -238,6 +238,7 @@ class NetworkCreate(BaseModel):
     cloud_id: int
     group_id: int
     type_id: int | None = None
+    resource_pool_id: int | None = None
     display_name: str | None = Field(default=None, alias="displayName")
     labels: list[str] | None = None
     description: str | None = None
@@ -272,6 +273,8 @@ class NetworkCreate(BaseModel):
 
         if self.type_id is not None:
             network["type"] = {"id": self.type_id}
+        if self.resource_pool_id is not None:
+            network["zonePool"] = {"id": self.resource_pool_id}
         if self.display_name is not None:
             network["displayName"] = self.display_name
         if self.labels is not None:

{mtn_cloud-0.2.19 → mtn_cloud-0.3.1}/src/mtn_cloud/resources/networks.py

@@ -135,6 +135,7 @@ class NetworksResource(BaseResource[Network]):
         cloud_id: int,
         group_id: int,
         type_id: int | None = None,
+        resource_pool_id: int | None = None,
         display_name: str | None = None,
         labels: List[str] | None = None,
         description: str | None = None,
@@ -162,6 +163,10 @@ class NetworksResource(BaseResource[Network]):
         """
         Create a network using MTN OpenStack-compatible fields.
 
+        OpenStack network types (e.g. ``openstackPrivate``) require both an
+        OpenStack ``type_id`` from ``list_types(openstack_only=True)`` and a
+        ``resource_pool_id`` (the numeric pool ID from ``get_resource_pool``).
+
         Notes:
             - Non-OpenStack provider-specific `config` variants are intentionally excluded.
             - Use integer IDs for cloud/group/type to keep payload typing uniform.
@@ -171,6 +176,7 @@ class NetworksResource(BaseResource[Network]):
             cloud_id=cloud_id,
             group_id=group_id,
             type_id=type_id,
+            resource_pool_id=resource_pool_id,
             display_name=display_name,
             labels=labels,
             description=description,
@@ -295,7 +301,7 @@ class NetworksResource(BaseResource[Network]):
             phrase: Optional phrase filter
             openstack_only: Return only network types tagged for OpenStack
         """
-        params: dict[str, Any] = {}
+        params: dict[str, Any] = {"max": 500}
         if name:
             params["name"] = name
         if code:

{mtn_cloud-0.2.19 → mtn_cloud-0.3.1}/tests/test_networks.py

@@ -115,6 +115,7 @@ class TestNetworkPayloadModels:
             ("network.cidr", "192.168.10.0/24"),
             ("network.dnsPrimary", "8.8.8.8"),
             ("network.visibility", "private"),
+            ("network.zonePool.id", 230),
             ("network.tenants", [{"id": 1}, {"id": 2}]),
             ("network.resourcePermission.all", True),
         ],
@@ -126,6 +127,7 @@ class TestNetworkPayloadModels:
             cloud_id=1,
             group_id=10,
             type_id=7,
+            resource_pool_id=230,
             cidr="192.168.10.0/24",
             gateway="192.168.10.1",
             dns_primary="8.8.8.8",
@@ -136,6 +138,12 @@ class TestNetworkPayloadModels:
 
         assert nested_value(payload, path) == expected
 
+    def test_network_accepts_null_labels(self) -> None:
+        """Coerce a null labels field from the API into an empty list."""
+        network = Network.model_validate({"id": 1, "name": "n", "labels": None})
+
+        assert network.labels == []
+
     @pytest.mark.parametrize(
         ("path", "expected"),
         [

mtn_cloud-0.2.19/docs/docstring-style.md

@@ -1,50 +0,0 @@
-# Docstring Style Standard
-
-This SDK uses a uniform docstring style for public classes and methods.
-
-## Goals
-
-- Fast scanning for beginners.
-- Predictable structure for advanced users.
-- Consistent IDE help and generated documentation output.
-
-## Method Template
-
-```python
-def example(arg1: str, arg2: int | None = None) -> bool:
-    """One-line summary.
-
-    Optional short context paragraph.
-
-    Args:
-        arg1: Required value description.
-        arg2: Optional value description.
-
-    Returns:
-        Description of return value.
-
-    Raises:
-        ValueError: If input validation fails.
-        MTNCloudError: If the API request fails.
-    """
-```
-
-## Class Template
-
-```python
-class Example:
-    """One-line summary.
-
-    Explain what the class represents and when it should be used.
-    """
-```
-
-## Rules
-
-1. Start with an imperative one-line summary.
-2. Use `Args`, `Returns`, and `Raises` on public methods.
-3. Include examples only when they add clarity.
-4. Avoid Markdown code fences inside docstrings; prefer plain text blocks.
-5. Keep docstrings accurate to the current method signature.
-6. Prefer exact resource names used by the SDK (`group`, `cloud`, `archive bucket`).
-