Resources¶

Every MREG resource type is an attribute on the client, and they all expose more or less the same interface. Learn it once and it applies everywhere:

client = MregClient(..., domain="example.com")

client.host      # manage hosts
client.network   # manage networks
client.cname     # manage CNAME records


host = client.host.get("myhost")
network = client.network.get("10.0.0.0/24")

networks = client.network.list()

cname = client.cname.create(host="myhost.example.com", name="alias.example.com")

# Identifier or model object can be used for updates
client.host.update(host, description="New description")
client.network.update("10.0.0.0/24", description="New description")

# Identifier or model object can be used for deletion
client.host.delete("myhost")
client.network.delete(network)

Methods¶

Not every resource supports every method — read-only resources have no create/update/ delete, and only some support get_by_name or history. The per-resource Managers reference shows exactly what each manager provides.

Fetching¶

get interprets the argument type: a string (name), an int (ID), or an existing model object (to refresh it). If a domain is set on the client, bare names are expanded to FQDNs automatically.

host = client.host.get("myhost.example.com")
host = client.host.get("myhost")  # domain appended automatically if set
host = client.host.get(123)       # by ID
host = client.host.get(host)      # refresh a model object

By default a missing resource (404) raises a GetError. Pass required=False to return None on 404 instead:

host = client.host.get("myhost", required=False)
if host is not None:
    ...

Listing and filtering¶

list returns resources of that type. Keyword arguments map to model fields for filtering and are forwarded to the API. list returns up to limit results (default no limit). Fetching all hosts is very slow, and should be avoided at all costs.

all_hosts = client.host.list()
hosts = client.host.list(name__startswith="test-", limit=500)
first = client.host.first(name__startswith="test-")
n = client.host.count(name__startswith="test-")

Creating¶

create takes keyword arguments matching the model's fields. Every create method returns the created object on success. A PostError is raised if the creation fails.

host = client.host.create(
    name="newhost.example.com",
    comment="Created via the API",
    fetch_after_create=True,
)

Updating¶

update accepts a model object or an identifier (name, ID), plus the fields to change. The available fields vary depending on the resource. A PatchError is raised if the update fails.

client.host.update(
    host, # or name or ID
    comment="Updated comment",
    ttl=3600,
)

Refreshing after update¶

Updating a resource does not modify the client-side copy of the object. You can call refresh() to fetch the updated state of the object:

client.host.update(host, comment="Updated comment")
refreshed = client.host.refresh(host)

Deleting¶

delete accepts a model object or an identifier. A DeleteError is raised if the deletion fails.

client.host.delete(host)               # by object
client.host.delete("newhost.example.com")  # by name
client.host.delete(123)                    # by ID

All managers¶

Every attribute below is a manager on the client. Follow the link for its full method reference.

Nested sub-managers¶

A few managers are also composed logically on top of each other, so as to categorize related operations.

• client.network ⇾ client.network.policy, client.network.community
• client.network.policy ⇾ client.network.policy.attribute
• client.meta ⇾ client.meta.version, client.meta.libraries, client.meta.userinfo, client.meta.ldap, client.meta.heartbeat, client.meta.health
• client.policy ⇾ client.policy.role, client.policy.atom, client.policy.label