Managers¶
This page describes the per-resource managers exposed on MregClient instances.
A manager is a class that encapsulates the logic for interacting with a specific MREG resource type.
Depending on the resource, a manager may implement all CRUD operations (create, read, update, delete)
or just a subset, in addition to other methods for more granular resource-specific operations.
The CRUD interface is documented in Resources.This page is the per-manager API reference.
Some managers have additional methods, such as HostManager.get_by_ip or PermissionManager.get_by_triplet.
Other managers, such as the read-only meta-endpoint managers exposed via MregClient.meta, have a more limited interface, exposing only a get method.
Hosts¶
HostManager
¶
Bases: NamedResourceManager[Host], HistoryManager[Host]
Operations on Host resources.
add_contacts
¶
all_ips_on_same_vlan
¶
assert_absent
¶
Assert that a given resource does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter or name to check. |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with the given identifier exists. |
clear_contacts
¶
clear_contacts(
host: int | str | Host,
) -> HostContactModification
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
create(
name: str | HostName,
*,
comment: str | None = None,
contacts: list[str] | None = None,
ipaddress: IP_AddressT | str | None = None,
network: IP_NetworkT | str | None = None,
) -> Host
Create a host.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str | HostName
|
Name of the host to create. |
required |
comment
|
str
|
Comment for the host. Defaults to "". |
None
|
contacts
|
list[str] | None
|
List of contacts for the host. |
None
|
ipaddress
|
IP_AddressT | str | None
|
IP address of the host. |
None
|
network
|
IP_NetworkT | str | None
|
Network of the host. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Host |
Host
|
The created host. |
delete
¶
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_id
¶
Get a host by its numeric id.
Distinct from :meth:get: the Host endpoint id-field is the hostname, so
:meth:get resolves by name while this resolves by the numeric id.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host_id
|
int
|
The numeric id of the host. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
get_by_ip
¶
get_by_ip(
ip: str | IP_AddressT,
*,
required: bool = True,
ptr_fallback: bool = True,
) -> Host | None
Get a host by IP address (A/AAAA, optionally falling back to PTR override).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ip
|
str | IP_AddressT
|
The IP address to look up. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
ptr_fallback
|
bool
|
When True (default), fall back to PTR override if no host is found. |
True
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the provided IP address is not valid. |
MultipleEntitiesFound
|
If more than one host matches the IP address. |
EntityNotFound
|
If |
get_by_mac
¶
get_by_mac(
mac: str | MacAddress, *, required: Literal[False]
) -> Host | None
get_by_mac(
mac: str | MacAddress, *, required: Literal[True] = ...
) -> Host
get_by_mac(
mac: str | MacAddress, *, required: bool = True
) -> Host | None
Get a host by MAC address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mac
|
str | MacAddress
|
The MAC address to look up. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the provided MAC address is not valid. |
EntityNotFound
|
If |
get_by_name
¶
Get a resource by its name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name field for the resource to look up. |
required |
required
|
bool
|
Raise if not found. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
T | None: The resource object if found, else None. |
history
¶
history(name: str) -> list[HistoryItem]
Get the audit history for a named resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The name of the resource to fetch history for. |
required |
Returns:
| Type | Description |
|---|---|
list[HistoryItem]
|
A list of |
list
¶
list_by_ip
¶
List hosts by IP address (A/AAAA, falling back to PTR override).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ip
|
str | IP_AddressT
|
IP address to filter by. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the provided IP address is not valid. |
Returns:
| Type | Description |
|---|---|
list[Host]
|
list[Host]: List of hosts matching the IP address. |
list_by_mac
¶
list_by_mac(mac: str | MacAddress) -> list[Host]
List hosts by MAC address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mac
|
str | MacAddress
|
The MAC address to filter by. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the provided MAC address is not valid. |
Returns:
| Type | Description |
|---|---|
list[Host]
|
list[Host]: List of hosts matching the MAC address. |
list_by_name_regex
¶
networks
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
remove_contacts
¶
rename
¶
rename(obj: T, new_name: str) -> None
Rename the resource.
Does not refresh the object locally.
Call refresh() with the object to fetch the updated resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource to rename. |
required |
new_name
|
str
|
The new name to set. |
required |
update
¶
update(
ref: int | str | Host,
*,
name: str | HostName | UNSET = UNSET,
comment: str | None | UNSET = UNSET,
contacts: list[str] | UNSET = UNSET,
ttl: int | None | UNSET = UNSET,
) -> None
Update a host's mutable fields.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
int | str | Host
|
Host instance or numeric ID. |
required |
name
|
str | HostName | UNSET
|
New name for the host. Omit to leave unchanged. |
UNSET
|
comment
|
str | None | UNSET
|
New comment. Pass None to unset, omit to leave unchanged. |
UNSET
|
contacts
|
list[str] | UNSET
|
New contacts list. Omit to leave unchanged. |
UNSET
|
ttl
|
int | None | UNSET
|
New TTL. Pass None to reset to default, omit to leave unchanged. |
UNSET
|
vlans
¶
HostGroupManager
¶
Bases: NamedResourceManager[HostGroup], HistoryManager[HostGroup]
Operations on HostGroup resources.
add_group
¶
add_host
¶
add_owner
¶
assert_absent
¶
Assert that a given resource does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter or name to check. |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with the given identifier exists. |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
delete
¶
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_name
¶
Get a resource by its name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name field for the resource to look up. |
required |
required
|
bool
|
Raise if not found. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
T | None: The resource object if found, else None. |
history
¶
history(name: str) -> list[HistoryItem]
Get the audit history for a named resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The name of the resource to fetch history for. |
required |
Returns:
| Type | Description |
|---|---|
list[HistoryItem]
|
A list of |
list
¶
list_by_host
¶
list_by_name_regex
¶
list_parents
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
remove_group
¶
remove_host
¶
remove_owner
¶
rename
¶
rename(obj: T, new_name: str) -> None
Rename the resource.
Does not refresh the object locally.
Call refresh() with the object to fetch the updated resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource to rename. |
required |
new_name
|
str
|
The new name to set. |
required |
set_description
¶
update
¶
IP addresses¶
IPAddressManager
¶
Bases: WriteResourceManager[IPAddress]
Operations on IPAddress resources.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
associate_mac
¶
associate_mac(
ip: int | str | IP_AddressT | IPAddress,
mac: str | MacAddress,
*,
force: bool = False,
) -> None
Associate a MAC address with an IP address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ip
|
int | str | IP_AddressT | IPAddress
|
IPAddress instance, numeric ID, or IP address string. |
required |
mac
|
str | MacAddress
|
The MAC address to associate. |
required |
force
|
bool
|
When True, skip safety checks and overwrite an existing MAC. |
False
|
Raises:
| Type | Description |
|---|---|
ForceMissing
|
If the IP already has a MAC and |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
create(
ipaddress: str | IP_AddressT,
*,
host: int | str | Host | None = None,
macaddress: str | MacAddress | None = None,
) -> IPAddress
Create an IP address record.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ipaddress
|
str | IP_AddressT
|
The IP address to assign. |
required |
host
|
int | str | Host
|
Host instance, name, or numeric ID. |
None
|
macaddress
|
str | MacAddress | None
|
Optional MAC address to associate. Pass None to omit. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
IPAddress |
IPAddress
|
The created IP address record. |
delete
¶
Delete a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The ID or object reference of resource to delete. |
required |
disassociate_mac
¶
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
list
¶
list_by_host
¶
list_by_ip
¶
List all IP address records with a given IP address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ip
|
IP_AddressT | str
|
The IP address to filter by. |
required |
list_by_mac
¶
list_by_mac(mac: str | MacAddress) -> list[IPAddress]
List all IP address records with a given MAC address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mac
|
str | MacAddress
|
The MAC address to filter by. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the provided MAC address is not valid. |
Returns:
| Type | Description |
|---|---|
list[IPAddress]
|
list[IPAddress]: List of IP addresses with the given MAC address. |
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
update
¶
update(
ref: int | str | IP_AddressT | IPAddress,
*,
ipaddress: IP_AddressT | str | UNSET = UNSET,
macaddress: str | MacAddress | None | UNSET = UNSET,
host: int | str | Host | UNSET | None = UNSET,
) -> None
Update an IP address record's mutable fields.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
int | str | IP_AddressT | IPAddress
|
IPAddress instance, numeric ID, or IP address string. |
required |
ipaddress
|
IP_AddressT | str | UNSET
|
New IP address. Omit to leave unchanged. |
UNSET
|
macaddress
|
str | MacAddress | None | UNSET
|
New MAC address. Pass None to unset, omit to leave unchanged. |
UNSET
|
host
|
int | str | Host | UNSET
|
Host to (dis)associate with IP. Omit to leave unchanged. |
UNSET
|
Networks¶
NetworkManager
¶
Bases: WriteResourceManager[Network]
Operations on Network resources.
add_excluded_range
¶
Add an excluded IP range to the network.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
str | int | Network
|
Network reference (address, numeric ID, or Network instance). |
required |
start
|
str
|
The start IP address of the excluded range. |
required |
end
|
str
|
The end IP address of the excluded range. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the start or end IPs are not valid IP addresses. |
InputFailure
|
If the start and end IP addresses are not of the same version. |
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
create(
network: str,
*,
description: str = "",
vlan: int | None | UNSET = UNSET,
dns_delegated: bool | UNSET = UNSET,
category: str | UNSET = UNSET,
location: str | UNSET = UNSET,
frozen: bool | UNSET = UNSET,
reserved: int | UNSET = UNSET,
) -> Network
Create a network.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
str
|
The network address in CIDR notation. |
required |
description
|
str
|
Description of the network. Defaults to "". |
''
|
vlan
|
int | None | UNSET
|
VLAN ID. Pass None to unset, omit to leave unchanged. |
UNSET
|
dns_delegated
|
bool | UNSET
|
Whether DNS is delegated. Omit to leave unchanged. |
UNSET
|
category
|
str | UNSET
|
Network category. Omit to leave unchanged. |
UNSET
|
location
|
str | UNSET
|
Network location. Omit to leave unchanged. |
UNSET
|
frozen
|
bool | UNSET
|
Whether the network is frozen. Omit to leave unchanged. |
UNSET
|
reserved
|
int | UNSET
|
Number of reserved addresses. Omit to leave unchanged. |
UNSET
|
Returns:
| Name | Type | Description |
|---|---|---|
Network |
Network
|
The created network. |
delete
¶
Delete a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The ID or object reference of resource to delete. |
required |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_ip
¶
Get the network containing an IP address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ip
|
str | IP_AddressT
|
The IP address to look up. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the provided IP address is not valid. |
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
Network | None
|
Network | None: The network containing the IP address, or None if not found and |
get_first_available_ip
¶
get_ptr_overrides
¶
get_ptroverride_host_list
¶
get_random_available_ip
¶
get_reserved_ips
¶
get_unused_count
¶
get_unused_list
¶
get_used_count
¶
get_used_host_list
¶
get_used_list
¶
list
¶
list_by_policy
¶
list_by_policy(
policy: int | NetworkPolicy,
) -> list[Network]
List networks that share the same policy as the given network.
Alias for policy.networks()
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
policy
|
int | NetworkPolicy
|
NetworkPolicy instance or numeric ID. |
required |
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
remove_excluded_range
¶
Remove an excluded IP range from the network.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
str | int | Network
|
Network reference (address, numeric ID, or Network instance). |
required |
start
|
str
|
The start IP address of the excluded range. |
required |
end
|
str
|
The end IP address of the excluded range. |
required |
update
¶
update(
ref: str | int | Network,
*,
network: str | UNSET = UNSET,
description: str | UNSET = UNSET,
vlan: int | None | UNSET = UNSET,
dns_delegated: bool | UNSET = UNSET,
category: str | UNSET = UNSET,
location: str | UNSET = UNSET,
frozen: bool | UNSET = UNSET,
reserved: int | UNSET = UNSET,
policy: int | None | UNSET = UNSET,
max_communities: int | None | UNSET = UNSET,
) -> None
Update a network's mutable fields.
Pass policy=None or max_communities=None to unset; omit to leave unchanged.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
str | int | Network
|
Network reference (address, numeric ID, or Network instance). |
required |
network
|
str | UNSET
|
New network address in CIDR notation. Omit to leave unchanged. |
UNSET
|
description
|
str | UNSET
|
New description. Omit to leave unchanged. |
UNSET
|
vlan
|
int | None | UNSET
|
New VLAN ID. Pass None to unset, omit to leave unchanged. |
UNSET
|
dns_delegated
|
bool | UNSET
|
Whether DNS is delegated. Omit to leave unchanged. |
UNSET
|
category
|
str | UNSET
|
New category. Omit to leave unchanged. |
UNSET
|
location
|
str | UNSET
|
New location. Omit to leave unchanged. |
UNSET
|
frozen
|
bool | UNSET
|
Whether the network is frozen. Omit to leave unchanged. |
UNSET
|
reserved
|
int | UNSET
|
Number of reserved addresses. Omit to leave unchanged. |
UNSET
|
policy
|
int | None | UNSET
|
Network policy ID. Pass None to unset, omit to leave unchanged. |
UNSET
|
max_communities
|
int | None | UNSET
|
Max communities. Pass None to unset, omit to leave unchanged. |
UNSET
|
NetworkPolicyManager
¶
Bases: NamedResourceManager[NetworkPolicy]
Operations on NetworkPolicy resources.
attribute
cached
property
¶
attribute: NetworkPolicyAttributeManager
Manager for network policy attributes.
add_attribute
¶
add_attribute(
policy: int | str | NetworkPolicy,
attr: str | NetworkPolicyAttribute,
value: bool = True,
) -> None
Add an attribute to a policy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
policy
|
int | str | NetworkPolicy
|
NetworkPolicy instance, numeric ID, or name string. |
required |
attr
|
str | NetworkPolicyAttribute
|
The attribute to add. |
required |
value
|
bool
|
The boolean value to set for the attribute. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If the policy already has this attribute. |
assert_absent
¶
Assert that a given resource does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter or name to check. |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with the given identifier exists. |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
create(
name: str,
*,
description: str = "",
attributes: list[NetworkPolicyAttributeValue]
| None = None,
community_template_pattern: str | None | UNSET = UNSET,
) -> NetworkPolicy
Create a network policy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The policy name (lowercased). |
required |
description
|
str
|
Optional description. |
''
|
attributes
|
list[NetworkPolicyAttributeValue] | None
|
Optional list of attribute name/value pairs to attach at creation. |
None
|
community_template_pattern
|
str | None | UNSET
|
Optional community name template pattern. |
UNSET
|
Returns:
| Name | Type | Description |
|---|---|---|
NetworkPolicy |
NetworkPolicy
|
The created network policy. |
delete
¶
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_name
¶
Get a resource by its name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name field for the resource to look up. |
required |
required
|
bool
|
Raise if not found. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
T | None: The resource object if found, else None. |
list
¶
list_by_name_regex
¶
networks
¶
networks(
policy: int | str | NetworkPolicy,
) -> list[Network]
Get all networks that use this policy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
policy
|
int | str | NetworkPolicy
|
NetworkPolicy instance, numeric ID, or name string. |
required |
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
remove_attribute
¶
remove_attribute(
policy: int | str | NetworkPolicy,
attribute: str | NetworkPolicyAttribute,
) -> None
Remove an attribute from a policy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
policy
|
int | str | NetworkPolicy
|
NetworkPolicy instance, numeric ID, or name string. |
required |
attribute
|
str | NetworkPolicyAttribute
|
NetworkPolicyAttribute instance or name string. |
required |
Raises:
| Type | Description |
|---|---|
EntityRelationMissing
|
If the policy does not have this attribute. |
rename
¶
rename(obj: T, new_name: str) -> None
Rename the resource.
Does not refresh the object locally.
Call refresh() with the object to fetch the updated resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource to rename. |
required |
new_name
|
str
|
The new name to set. |
required |
set_description
¶
set_description(
policy: int | str | NetworkPolicy, description: str
) -> None
Set the description for the policy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
policy
|
int | str | NetworkPolicy
|
NetworkPolicy instance, numeric ID, or name string. |
required |
description
|
str
|
New description to set. |
required |
update
¶
update(
ref: int | str | NetworkPolicy,
*,
description: str | UNSET = UNSET,
community_template_pattern: str | None | UNSET = UNSET,
) -> None
Update a network policy's mutable fields.
Pass community_template_pattern=None to unset it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
int | str | NetworkPolicy
|
NetworkPolicy instance, numeric ID, or name string. |
required |
description
|
str | UNSET
|
New description. Omit to leave unchanged. |
UNSET
|
community_template_pattern
|
str | None | UNSET
|
New community name template pattern. Pass None to unset, omit to leave unchanged. |
UNSET
|
NetworkPolicyAttributeManager
¶
Bases: NamedResourceManager[NetworkPolicyAttribute]
Operations on NetworkPolicyAttribute resources.
assert_absent
¶
Assert that a given resource does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter or name to check. |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with the given identifier exists. |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
create(
name: str, description: str
) -> NetworkPolicyAttribute
Create a network policy attribute.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name of the attribute (lowercased). |
required |
description
|
str
|
Description of the attribute. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
NetworkPolicyAttribute |
NetworkPolicyAttribute
|
The created network policy attribute. |
delete
¶
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_name
¶
Get a resource by its name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name field for the resource to look up. |
required |
required
|
bool
|
Raise if not found. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
T | None: The resource object if found, else None. |
get_policies
¶
get_policies(
attr: int | str | NetworkPolicyAttribute,
) -> list[NetworkPolicy]
List all network policies that use this attribute.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attr
|
int | str | NetworkPolicyAttribute
|
NetworkPolicyAttribute instance, numeric ID, or name. |
required |
Returns:
| Type | Description |
|---|---|
list[NetworkPolicy]
|
list[NetworkPolicy]: List of network policies that use this attribute. |
list
¶
list_by_name_regex
¶
list_policies
¶
list_policies(
attr: int | str | NetworkPolicyAttribute,
) -> list[NetworkPolicy]
List all network policies that use this attribute.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attr
|
int | str | NetworkPolicyAttribute
|
NetworkPolicyAttribute instance, numeric ID, or name. |
required |
Returns:
| Type | Description |
|---|---|
list[NetworkPolicy]
|
list[NetworkPolicy]: List of network policies that use this attribute. |
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
rename
¶
rename(obj: T, new_name: str) -> None
Rename the resource.
Does not refresh the object locally.
Call refresh() with the object to fetch the updated resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource to rename. |
required |
new_name
|
str
|
The new name to set. |
required |
set_description
¶
set_description(
attr: int | str | NetworkPolicyAttribute,
description: str,
) -> None
Set the description for the attribute.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attr
|
int | str | NetworkPolicyAttribute
|
NetworkPolicyAttribute instance, numeric ID, or name. |
required |
description
|
str
|
New description to set. |
required |
update
¶
update(
ref: int | str | NetworkPolicyAttribute,
*,
description: str | UNSET = UNSET,
) -> None
Update a network policy attribute's mutable fields.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
int | str | NetworkPolicyAttribute
|
NetworkPolicyAttribute instance, numeric ID, or name. |
required |
description
|
str | UNSET
|
New description. Omit to leave unchanged. |
UNSET
|
CommunityManager
¶
Operations on network communities.
add_host
¶
add_host(
community: Community,
host: int | str | Host,
*,
ipaddress: IP_AddressT | str | None = None,
) -> bool
Add a host to a community.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
community
|
Community
|
The community to add the host to. |
required |
host
|
int | str | Host
|
Host reference (ID, name or Host instance). |
required |
ipaddress
|
IP_AddressT | str | None
|
Optional IP address to associate with the host in this community. Required if host has multiple IP addresses in the network. |
None
|
create
¶
Create a community in a network.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name of the community. |
required |
description
|
str
|
Description of the community. |
required |
network
|
str | int | Network
|
Network reference (address, ID, or Network instance). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Community |
Community
|
The created community. |
delete
¶
delete(community: Community) -> None
Delete a community.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
community
|
Community
|
The community to delete. |
required |
first
¶
first(
network: str | int | Network,
*,
required: bool = True,
**query: str | int | float | bool | None,
) -> Community | None
Return the first community in a network matching the query.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
str | int | Network
|
Network reference (address, ID, or Network instance). |
required |
required
|
bool
|
When True (default), raise EntityNotFound if none is found. |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
get
¶
get(
community: int | str,
network: str | int | Network,
*,
required: bool = True,
) -> Community | None
Get a community by ID or name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
community
|
int | str
|
Community ID or name. |
required |
network
|
str | int | Network
|
Network reference (address, ID, or Network instance). |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
get_hosts
¶
List all hosts in a community.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
community
|
Community
|
The community to list hosts for. |
required |
list
¶
list(
network: str | int | Network,
*,
limit: int | None = None,
**query: str | int | float | bool | None,
) -> list[Community]
List communities in a network, optionally filtered by query parameters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
str | int | Network
|
Network reference (address, ID, or Network instance). |
required |
limit
|
int | None
|
Maximum number of results to return, None means no limit. |
None
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
refresh
¶
Fetch a fresh copy of a community from the server.
remove_host
¶
remove_host(
community: Community,
host: int | str | Host,
*,
ipaddress: IP_AddressT | str | None = None,
) -> None
Remove a host from a community.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
community
|
Community
|
The community to remove the host from. |
required |
host
|
int | str | Host
|
Host reference (ID, name or Host instance). |
required |
ipaddress
|
IP_AddressT | str | None
|
Optional IP address to disassociate from the host in this community. Required if the host has multiple IP addresses in the community. |
None
|
DNS records¶
CNAMEManager
¶
Bases: NamedResourceManager[CNAME]
Operations on CNAME resources.
assert_absent
¶
Assert that a given resource does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter or name to check. |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with the given identifier exists. |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
delete
¶
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_host_and_name
¶
get_by_host_and_name(
host: int | str | Host,
name: str | HostName,
*,
required: bool = True,
) -> CNAME | None
Get a CNAME record matching both the host and alias name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
int | str | Host
|
Host instance or numeric ID. |
required |
name
|
str | HostName
|
The alias name to look up. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
get_by_name
¶
Get a CNAME record by alias name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The alias name to look up. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
list
¶
list_by_host
¶
list_by_name_regex
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
rename
¶
rename(obj: T, new_name: str) -> None
Rename the resource.
Does not refresh the object locally.
Call refresh() with the object to fetch the updated resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource to rename. |
required |
new_name
|
str
|
The new name to set. |
required |
update
¶
update(
ref: int | str | CNAME,
*,
host: int | str | Host | UNSET = UNSET,
name: str | HostName | UNSET = UNSET,
ttl: int | None | UNSET = UNSET,
) -> None
Update a CNAME record's mutable fields. Pass ttl=None to reset to default.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
int | str | CNAME
|
CNAME instance, numeric ID, or string identifier. |
required |
host
|
int | str | Host | UNSET
|
New host reference. Omit to leave unchanged. |
UNSET
|
name
|
str | HostName | UNSET
|
New alias name. Omit to leave unchanged. |
UNSET
|
ttl
|
int | None | UNSET
|
New TTL. Pass None to reset to default, omit to leave unchanged. |
UNSET
|
MXManager
¶
Bases: WriteResourceManager[MX]
Operations on MX resources.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
delete
¶
Delete a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The ID or object reference of resource to delete. |
required |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_all
¶
Get an MX record matching host, mx value, and priority.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
int | str | Host
|
Host instance or numeric ID. |
required |
mx
|
str
|
The mail exchange hostname. |
required |
priority
|
int
|
The MX priority value. |
required |
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If no matching MX record exists. |
get_unique
¶
get_unique(
host: int | str | Host,
mx: str,
priority: int,
*,
required: bool = True,
) -> MX | None
Get an MX record matching host, mx value, and priority.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
int | str | Host
|
Host instance or numeric ID. |
required |
mx
|
str
|
The mail exchange hostname. |
required |
priority
|
int
|
The MX priority value. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If no matching MX record exists and |
Returns:
| Type | Description |
|---|---|
MX | None
|
MX | None: The matching MX record, or None if not found and |
list
¶
list_by_host
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
update
¶
TXTManager
¶
Bases: WriteResourceManager[TXT]
Operations on TXT resources.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
delete
¶
Delete a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The ID or object reference of resource to delete. |
required |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
list
¶
list_by_host
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
NAPTRManager
¶
Bases: WriteResourceManager[NAPTR]
Operations on NAPTR resources.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
create(
host: int | str | Host,
preference: int,
order: int,
*,
flag: str = "",
service: str = "",
regex: str = "",
replacement: str,
) -> NAPTR
Create a NAPTR record.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
int | str | Host
|
Host instance or numeric ID. |
required |
preference
|
int
|
The NAPTR preference value. |
required |
order
|
int
|
The NAPTR order value. |
required |
flag
|
str
|
The NAPTR flag. Defaults to "". |
''
|
service
|
str
|
The NAPTR service. Defaults to "". |
''
|
regex
|
str
|
The NAPTR regular expression. Defaults to "". |
''
|
replacement
|
str
|
The NAPTR replacement string. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
NAPTR |
NAPTR
|
The created NAPTR record. |
delete
¶
Delete a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The ID or object reference of resource to delete. |
required |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_unique
¶
get_unique(
host: int | str | Host,
preference: int,
order: int,
flag: str = "",
service: str = "",
regex: str = "",
replacement: str = "",
*,
required: bool = True,
) -> NAPTR | None
Get a NAPTR record matching host, preference, order, flag, service, regex, and replacement.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
int | str | Host
|
Host instance or numeric ID. |
required |
preference
|
int
|
The NAPTR preference value. |
required |
order
|
int
|
The NAPTR order value. |
required |
flag
|
str
|
The NAPTR flag. Defaults to "". |
''
|
service
|
str
|
The NAPTR service. Defaults to "". |
''
|
regex
|
str
|
The NAPTR regular expression. Defaults to "". |
''
|
replacement
|
str
|
The NAPTR replacement string. |
''
|
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If no matching NAPTR record exists and |
Returns:
| Type | Description |
|---|---|
NAPTR | None
|
NAPTR | None: The matching NAPTR record, or None if not found and |
list
¶
list_by_host
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
update
¶
update(
ref: int | NAPTR,
*,
preference: int | UNSET = UNSET,
order: int | UNSET = UNSET,
flag: str | UNSET = UNSET,
service: str | UNSET = UNSET,
regex: str | UNSET = UNSET,
replacement: str | UNSET = UNSET,
) -> None
Update a NAPTR record's mutable fields.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
int | NAPTR
|
NAPTR instance or numeric ID. |
required |
preference
|
int | UNSET
|
New preference value. Omit to leave unchanged. |
UNSET
|
order
|
int | UNSET
|
New order value. Omit to leave unchanged. |
UNSET
|
flag
|
str | UNSET
|
New flag. Omit to leave unchanged. |
UNSET
|
service
|
str | UNSET
|
New service. Omit to leave unchanged. |
UNSET
|
regex
|
str | UNSET
|
New regular expression. Omit to leave unchanged. |
UNSET
|
replacement
|
str | UNSET
|
New replacement string. Omit to leave unchanged. |
UNSET
|
SrvManager
¶
Bases: WriteResourceManager[Srv]
Operations on Srv resources.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
create(
host: int | str | Host,
name: str,
priority: int,
weight: int,
port: int,
*,
ttl: int | None | UNSET = UNSET,
) -> Srv
Create a SRV record.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
int | str | Host
|
Host instance or numeric ID. |
required |
name
|
str
|
The SRV service name. |
required |
priority
|
int
|
The SRV priority value. |
required |
weight
|
int
|
The SRV weight value. |
required |
port
|
int
|
The SRV port number. |
required |
ttl
|
int | None | UNSET
|
TTL. Uses default TTL if not specified. |
UNSET
|
Returns:
| Name | Type | Description |
|---|---|---|
Srv |
Srv
|
The created SRV record. |
delete
¶
Delete a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The ID or object reference of resource to delete. |
required |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_unique
¶
get_unique(
*,
name: str,
priority: int,
weight: int,
port: int,
host: int | str | Host,
required: bool = True,
) -> Srv | None
Get a SRV record matching name, priority, weight, port, and host.
list
¶
list_by_host
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
update
¶
update(
ref: int | Srv,
*,
name: str | UNSET = UNSET,
priority: int | UNSET = UNSET,
weight: int | UNSET = UNSET,
port: int | UNSET = UNSET,
ttl: int | None | UNSET = UNSET,
) -> None
Update a SRV record's mutable fields. Pass ttl=None to reset to default.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
int | Srv
|
Srv instance or numeric ID. |
required |
name
|
str | UNSET
|
New service name. Omit to leave unchanged. |
UNSET
|
priority
|
int | UNSET
|
New priority value. Omit to leave unchanged. |
UNSET
|
weight
|
int | UNSET
|
New weight value. Omit to leave unchanged. |
UNSET
|
port
|
int | UNSET
|
New port number. Omit to leave unchanged. |
UNSET
|
ttl
|
int | None | UNSET
|
New TTL. Pass None to reset to default, omit to leave unchanged. |
UNSET
|
SSHFPManager
¶
Bases: WriteResourceManager[SSHFP]
Operations on SSHFP resources.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
create(
host: int | str | Host,
algorithm: int,
hash_type: int,
fingerprint: str,
*,
ttl: int | None | UNSET = UNSET,
) -> SSHFP
Create an SSHFP record.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
int | str | Host
|
Host instance or numeric ID. |
required |
algorithm
|
int
|
The SSHFP algorithm number. |
required |
hash_type
|
int
|
The SSHFP hash type number. |
required |
fingerprint
|
str
|
The SSH key fingerprint. |
required |
ttl
|
int | None | UNSET
|
TTL. Uses default TTL if not specified. |
UNSET
|
Returns:
| Name | Type | Description |
|---|---|---|
SSHFP |
SSHFP
|
The created SSHFP record. |
delete
¶
Delete a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The ID or object reference of resource to delete. |
required |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
list
¶
list_by_host
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
update
¶
update(
ref: int | SSHFP,
*,
algorithm: int | UNSET = UNSET,
hash_type: int | UNSET = UNSET,
fingerprint: str | UNSET = UNSET,
ttl: int | None | UNSET = UNSET,
) -> None
Update an SSHFP record's mutable fields. Pass ttl=None to reset to default.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
int | SSHFP
|
SSHFP instance or numeric ID. |
required |
algorithm
|
int | UNSET
|
New algorithm number. Omit to leave unchanged. |
UNSET
|
hash_type
|
int | UNSET
|
New hash type number. Omit to leave unchanged. |
UNSET
|
fingerprint
|
str | UNSET
|
New fingerprint. Omit to leave unchanged. |
UNSET
|
ttl
|
int | None | UNSET
|
New TTL. Pass None to reset to default, omit to leave unchanged. |
UNSET
|
PTROverrideManager
¶
Bases: WriteResourceManager[PTR_override]
Operations on PTR_override resources.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
create(
host: int | str | Host, ipaddress: IP_AddressT | str
) -> PTR_override
Create a PTR override record.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
int | str | Host
|
Host instance or numeric ID. |
required |
ipaddress
|
IP_AddressT | str
|
The IP address for the PTR override. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
PTR_override |
PTR_override
|
The created PTR override record. |
delete
¶
Delete a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The ID or object reference of resource to delete. |
required |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
list
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
update
¶
update(
ref: int | PTR_override,
*,
host: int | str | Host | UNSET = UNSET,
ipaddress: IP_AddressT | str | UNSET = UNSET,
) -> None
Update a PTR override record's mutable fields.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
int | PTR_override
|
PTR_override instance or numeric ID. |
required |
host
|
int | str | Host | UNSET
|
New host reference. Omit to leave unchanged. |
UNSET
|
ipaddress
|
IP_AddressT | str | UNSET
|
New IP address. Omit to leave unchanged. |
UNSET
|
HInfoManager
¶
Bases: WriteResourceManager[HInfo]
Operations on HInfo resources.
HInfo is a 1-per-host record; the path parameter is the host ID (not a numeric row id).
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
delete
¶
Delete a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The ID or object reference of resource to delete. |
required |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_host
¶
Get the HInfo record for a host.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
int | str | Host
|
Host instance or numeric ID. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
list
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
update
¶
LocationManager
¶
Bases: WriteResourceManager[Location]
Operations on Location resources.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
delete
¶
Delete a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The ID or object reference of resource to delete. |
required |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_host
¶
Get the LOC record for a host.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
int | str | Host
|
Host instance or numeric ID. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
list
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
BacnetIDManager
¶
Bases: WriteResourceManager[BacnetID]
Operations on BacnetID resources.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
delete
¶
Delete a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The ID or object reference of resource to delete. |
required |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_host
¶
Get the BacnetID record for a host by its FQDN.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
str | HostName | Host
|
Host reference (name string or Host instance). |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
list
¶
list_in_range
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
Host policy¶
RoleManager
¶
Bases: NamedResourceManager[Role], HistoryManager[Role]
Operations on Role resources.
add_atom
¶
Add an atom to the role.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
role
|
int | str | Role
|
Role instance, numeric ID, or name string. |
required |
atom
|
int | str | Atom
|
Atom instance, numeric ID, or name string. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the atom was successfully added. DEPRECATED: Maintains parity with older library versions. Will never return False on failure; an exception is raised instead. |
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If the atom does not exist. |
EntityAlreadyExists
|
If the atom is already a member of the role. |
add_host
¶
Add a host to the role by name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
role
|
int | str | Role
|
Role id, name or instance. |
required |
host
|
str | Host
|
Host reference (name string or Host instance). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the host was successfully added. DEPRECATED: Maintains parity with older library versions. Will never return False on failure; an exception is raised instead. |
add_label
¶
Add a label to the role.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
role
|
int | str | Role
|
Role instance, numeric ID, or name string. |
required |
label
|
int | str | Label
|
Label instance, name, or numeric ID. |
required |
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If the label does not exist. |
EntityAlreadyExists
|
If the role already has the label. |
assert_absent
¶
Assert that a given resource does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter or name to check. |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with the given identifier exists. |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
delete
¶
Delete a role.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
int | str | Role
|
Role instance, numeric ID, or name string. |
required |
force
|
bool
|
Force deletion even if the role is in use. Defaults to False. |
False
|
Raises:
| Type | Description |
|---|---|
ForceMissing
|
If the role is still in use on any hosts and |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_name
¶
Get a resource by its name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name field for the resource to look up. |
required |
required
|
bool
|
Raise if not found. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
T | None: The resource object if found, else None. |
get_labels
¶
history
¶
history(name: str) -> list[HistoryItem]
Get the audit history for a named resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The name of the resource to fetch history for. |
required |
Returns:
| Type | Description |
|---|---|
list[HistoryItem]
|
A list of |
list
¶
list_by_host
¶
list_by_name_regex
¶
list_labels
¶
list_with_atom
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
remove_atom
¶
Remove an atom from the role.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
role
|
int | str | Role
|
Role instance, numeric ID, or name string. |
required |
atom
|
int | str | Atom
|
Atom instance, numeric ID, or name string. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the atom was successfully removed. DEPRECATED: Maintains parity with older library versions. Will never return False on failure; an exception is raised instead. |
Raises:
| Type | Description |
|---|---|
EntityRelationMissing
|
If the atom is not a member of the role. |
remove_host
¶
Remove a host from the role by name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
role
|
int | Role
|
Role instance or numeric ID. |
required |
host
|
str | Host
|
Host reference (name string or Host instance). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the host was successfully removed. DEPRECATED: Maintains parity with older library versions. Will never return False on failure; an exception is raised instead. |
remove_label
¶
Remove a label from the role.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
role
|
int | str | Role
|
Role instance, numeric ID, or name string. |
required |
label
|
int | str | Label
|
Label instance, name, or numeric ID. |
required |
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If the label does not exist. |
EntityRelationMissing
|
If the role does not have the label. |
rename
¶
rename(obj: T, new_name: str) -> None
Rename the resource.
Does not refresh the object locally.
Call refresh() with the object to fetch the updated resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource to rename. |
required |
new_name
|
str
|
The new name to set. |
required |
set_description
¶
update
¶
AtomManager
¶
Bases: NamedResourceManager[Atom], HistoryManager[Atom]
Operations on Atom resources.
assert_absent
¶
Assert that a given resource does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter or name to check. |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with the given identifier exists. |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
delete
¶
Delete an atom.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
int | str | Atom
|
Atom instance, name string, or numeric ID. |
required |
force
|
bool
|
Force deletion even if the atom is used in roles. Defaults to False. |
False
|
Raises:
| Type | Description |
|---|---|
ForceMissing
|
If the atom is still used in any roles and |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_name
¶
Get a resource by its name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name field for the resource to look up. |
required |
required
|
bool
|
Raise if not found. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
T | None: The resource object if found, else None. |
history
¶
history(name: str) -> list[HistoryItem]
Get the audit history for a named resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The name of the resource to fetch history for. |
required |
Returns:
| Type | Description |
|---|---|
list[HistoryItem]
|
A list of |
list
¶
list_by_name_regex
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
rename
¶
rename(obj: T, new_name: str) -> None
Rename the resource.
Does not refresh the object locally.
Call refresh() with the object to fetch the updated resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource to rename. |
required |
new_name
|
str
|
The new name to set. |
required |
set_description
¶
update
¶
LabelManager
¶
Bases: NamedResourceManager[Label]
Operations on Label resources.
assert_absent
¶
Assert that a given resource does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter or name to check. |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with the given identifier exists. |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
delete
¶
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_name
¶
Get a resource by its name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name field for the resource to look up. |
required |
required
|
bool
|
Raise if not found. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
T | None: The resource object if found, else None. |
list
¶
list_by_name_regex
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
rename
¶
rename(obj: T, new_name: str) -> None
Rename the resource.
Does not refresh the object locally.
Call refresh() with the object to fetch the updated resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource to rename. |
required |
new_name
|
str
|
The new name to set. |
required |
set_description
¶
update
¶
Zones¶
ZoneManager
¶
Zone management for forward and reverse zones.
Zones split into forward/reverse, but are otherwise very similar in their APIs. This manager delegates to the correct forward/reverse manager based on the name or object types passed in to methods.
Similar to other managers, methods take names or instances, but crucially NOT IDs,
since we cannot distinguish between forward/reverse zones by ID alone. Use the
public forward / reverse sub-managers for ID-based lookups and standalone use.
assert_absent
¶
assert_absent(name: str) -> None
Raise EntityAlreadyExists if a zone with name exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The zone name to check. |
required |
create
¶
Create a forward or reverse zone (type chosen by name shape).
Verifies the nameservers and that no zone with this name exists first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The zone name (determines forward vs. reverse by shape). |
required |
email
|
str
|
The zone admin email address. |
required |
primary_ns
|
list[str]
|
List of primary nameserver names. |
required |
force
|
bool
|
When True, skip safety checks on nameservers. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
Zone |
Zone
|
The created zone. |
Raises:
| Type | Description |
|---|---|
InputFailure
|
If no nameservers are given. |
ForceMissing
|
If a nameserver is missing (or lacks glue) and |
EntityAlreadyExists
|
If a zone with this name already exists. |
delete
¶
get
¶
Get a zone by name; forward/reverse chosen by name shape.
Alias for get_by_name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The zone name to look up. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
get_by_name
¶
Get a zone by name; forward/reverse chosen by name shape.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The zone name to look up. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
get_from_host
¶
get_from_host(
host: str | HostName | Host,
) -> ForwardZoneDelegation | ForwardZone | None
list_subzones
¶
refresh
¶
Refresh a zone instance from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
ZoneT
|
The zone to refresh. |
required |
set_default_ttl
¶
set_nameservers
¶
Replace the zone's nameservers.
Verifies the nameservers first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zone
|
str | Zone
|
Zone reference (name string or instance). |
required |
nameservers
|
list[str]
|
The new list of nameserver names. |
required |
force
|
bool
|
When True, skip safety checks on nameserver existence. |
False
|
Raises:
| Type | Description |
|---|---|
InputFailure
|
If no nameservers are given. |
ForceMissing
|
If a nameserver is missing (or lacks glue) and |
update_soa
¶
update_soa(
zone: str | Zone,
*,
primary_ns: str | UNSET = UNSET,
email: str | UNSET = UNSET,
serialno: int | UNSET = UNSET,
refresh: int | UNSET = UNSET,
retry: int | UNSET = UNSET,
expire: int | UNSET = UNSET,
soa_ttl: int | UNSET = UNSET,
force: bool = False,
) -> None
Update the zone's SOA fields.
The primary nameserver, when provided, is verified first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zone
|
str | Zone
|
Zone reference (name string or instance). |
required |
primary_ns
|
str | UNSET
|
New primary nameserver. Omit to leave unchanged. |
UNSET
|
email
|
str | UNSET
|
New zone admin email. Omit to leave unchanged. |
UNSET
|
serialno
|
int | UNSET
|
New serial number. Omit to leave unchanged. |
UNSET
|
refresh
|
int | UNSET
|
New refresh interval. Omit to leave unchanged. |
UNSET
|
retry
|
int | UNSET
|
New retry interval. Omit to leave unchanged. |
UNSET
|
expire
|
int | UNSET
|
New expire interval. Omit to leave unchanged. |
UNSET
|
soa_ttl
|
int | UNSET
|
New SOA TTL. Omit to leave unchanged. |
UNSET
|
force
|
bool
|
When True, skip safety checks on the primary nameserver. |
False
|
Raises:
| Type | Description |
|---|---|
InputFailure
|
If no fields are provided. |
ForceMissing
|
If the primary nameserver is missing (or lacks glue)
and |
verify_nameservers
¶
verify_nameservers(
nameservers: list[str], force: bool = False
) -> list[VerifiedNS]
zone_file
¶
ForwardZoneManager
¶
Bases: ZoneSubManager[ForwardZone]
Manager for forward zones.
assert_absent
¶
Assert that a given resource does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter or name to check. |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with the given identifier exists. |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
Create a new zone.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The zone name. |
required |
email
|
str
|
The zone admin email address. |
required |
primary_ns
|
list[str]
|
List of primary nameserver names. |
required |
force
|
bool
|
When True, skip safety checks on nameservers. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
ZoneT |
ZoneT
|
The created zone. |
Raises:
| Type | Description |
|---|---|
InputFailure
|
If no nameservers are given. |
ForceMissing
|
If a nameserver is missing (or lacks glue) and |
EntityAlreadyExists
|
If a zone with this name already exists. |
delete
¶
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_name
¶
Get a resource by its name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name field for the resource to look up. |
required |
required
|
bool
|
Raise if not found. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
T | None: The resource object if found, else None. |
get_from_host
¶
get_from_host(
host: str | HostName | Host,
) -> ForwardZoneDelegation | ForwardZone | None
list
¶
list_by_name_regex
¶
list_subzones
¶
list_subzones(zone: ZoneT) -> list[ZoneT]
List subzones of the zone (excluding the zone itself).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zone
|
ZoneT
|
The parent zone to list subzones for. |
required |
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
rename
¶
rename(obj: T, new_name: str) -> None
Rename the resource.
Does not refresh the object locally.
Call refresh() with the object to fetch the updated resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource to rename. |
required |
new_name
|
str
|
The new name to set. |
required |
set_default_ttl
¶
set_default_ttl(zone: ZoneT, ttl: int) -> None
Set the zone's default TTL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zone
|
ZoneT
|
The zone to update. |
required |
ttl
|
int
|
The new default TTL value (300–68400). |
required |
set_nameservers
¶
Replace the zone's nameservers (hits the per-type nameservers endpoint).
Verifies the nameservers first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zone
|
ZoneT
|
The zone to update. |
required |
nameservers
|
list[str]
|
The new list of nameserver names. |
required |
force
|
bool
|
When True, skip safety checks on nameserver existence. |
False
|
Raises:
| Type | Description |
|---|---|
InputFailure
|
If no nameservers are given. |
ForceMissing
|
If a nameserver is missing (or lacks glue) and |
update_soa
¶
update_soa(
zone: ZoneT,
*,
primary_ns: str | UNSET = UNSET,
email: str | UNSET = UNSET,
serialno: int | UNSET = UNSET,
refresh: int | UNSET = UNSET,
retry: int | UNSET = UNSET,
expire: int | UNSET = UNSET,
soa_ttl: int | UNSET = UNSET,
force: bool = False,
) -> None
Update the zone's SOA fields. At least one field must be provided.
The primary nameserver, when provided, is verified first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zone
|
ZoneT
|
The zone to update. |
required |
primary_ns
|
str | UNSET
|
New primary nameserver. Omit to leave unchanged. |
UNSET
|
email
|
str | UNSET
|
New zone admin email. Omit to leave unchanged. |
UNSET
|
serialno
|
int | UNSET
|
New serial number. Omit to leave unchanged. |
UNSET
|
refresh
|
int | UNSET
|
New refresh interval. Omit to leave unchanged. |
UNSET
|
retry
|
int | UNSET
|
New retry interval. Omit to leave unchanged. |
UNSET
|
expire
|
int | UNSET
|
New expire interval. Omit to leave unchanged. |
UNSET
|
soa_ttl
|
int | UNSET
|
New SOA TTL. Omit to leave unchanged. |
UNSET
|
force
|
bool
|
When True, skip safety checks on the primary nameserver. |
False
|
Raises:
| Type | Description |
|---|---|
InputFailure
|
If no fields are provided. |
ForceMissing
|
If the primary nameserver is missing (or lacks glue)
and |
verify_nameservers
¶
verify_nameservers(
nameservers: list[str], *, force: bool = False
) -> list[VerifiedNS]
Verify nameservers exist in mreg and have glue (raises otherwise).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nameservers
|
list[str]
|
List of nameserver names to verify. |
required |
force
|
bool
|
When True, skip safety checks on nameserver existence. |
False
|
Returns:
| Type | Description |
|---|---|
list[VerifiedNS]
|
list[VerifiedNS]: The verified nameserver names. |
Raises:
| Type | Description |
|---|---|
InputFailure
|
If no nameservers are given. |
ForceMissing
|
If a nameserver is missing (or lacks glue) and |
ReverseZoneManager
¶
Bases: ZoneSubManager[ReverseZone]
Manager for reverse zones.
assert_absent
¶
Assert that a given resource does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter or name to check. |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with the given identifier exists. |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
Create a new zone.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The zone name. |
required |
email
|
str
|
The zone admin email address. |
required |
primary_ns
|
list[str]
|
List of primary nameserver names. |
required |
force
|
bool
|
When True, skip safety checks on nameservers. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
ZoneT |
ZoneT
|
The created zone. |
Raises:
| Type | Description |
|---|---|
InputFailure
|
If no nameservers are given. |
ForceMissing
|
If a nameserver is missing (or lacks glue) and |
EntityAlreadyExists
|
If a zone with this name already exists. |
delete
¶
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_name
¶
Get a resource by its name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name field for the resource to look up. |
required |
required
|
bool
|
Raise if not found. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
T | None: The resource object if found, else None. |
list
¶
list_by_name_regex
¶
list_subzones
¶
list_subzones(zone: ZoneT) -> list[ZoneT]
List subzones of the zone (excluding the zone itself).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zone
|
ZoneT
|
The parent zone to list subzones for. |
required |
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
rename
¶
rename(obj: T, new_name: str) -> None
Rename the resource.
Does not refresh the object locally.
Call refresh() with the object to fetch the updated resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource to rename. |
required |
new_name
|
str
|
The new name to set. |
required |
set_default_ttl
¶
set_default_ttl(zone: ZoneT, ttl: int) -> None
Set the zone's default TTL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zone
|
ZoneT
|
The zone to update. |
required |
ttl
|
int
|
The new default TTL value (300–68400). |
required |
set_nameservers
¶
Replace the zone's nameservers (hits the per-type nameservers endpoint).
Verifies the nameservers first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zone
|
ZoneT
|
The zone to update. |
required |
nameservers
|
list[str]
|
The new list of nameserver names. |
required |
force
|
bool
|
When True, skip safety checks on nameserver existence. |
False
|
Raises:
| Type | Description |
|---|---|
InputFailure
|
If no nameservers are given. |
ForceMissing
|
If a nameserver is missing (or lacks glue) and |
update_soa
¶
update_soa(
zone: ZoneT,
*,
primary_ns: str | UNSET = UNSET,
email: str | UNSET = UNSET,
serialno: int | UNSET = UNSET,
refresh: int | UNSET = UNSET,
retry: int | UNSET = UNSET,
expire: int | UNSET = UNSET,
soa_ttl: int | UNSET = UNSET,
force: bool = False,
) -> None
Update the zone's SOA fields. At least one field must be provided.
The primary nameserver, when provided, is verified first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zone
|
ZoneT
|
The zone to update. |
required |
primary_ns
|
str | UNSET
|
New primary nameserver. Omit to leave unchanged. |
UNSET
|
email
|
str | UNSET
|
New zone admin email. Omit to leave unchanged. |
UNSET
|
serialno
|
int | UNSET
|
New serial number. Omit to leave unchanged. |
UNSET
|
refresh
|
int | UNSET
|
New refresh interval. Omit to leave unchanged. |
UNSET
|
retry
|
int | UNSET
|
New retry interval. Omit to leave unchanged. |
UNSET
|
expire
|
int | UNSET
|
New expire interval. Omit to leave unchanged. |
UNSET
|
soa_ttl
|
int | UNSET
|
New SOA TTL. Omit to leave unchanged. |
UNSET
|
force
|
bool
|
When True, skip safety checks on the primary nameserver. |
False
|
Raises:
| Type | Description |
|---|---|
InputFailure
|
If no fields are provided. |
ForceMissing
|
If the primary nameserver is missing (or lacks glue)
and |
verify_nameservers
¶
verify_nameservers(
nameservers: list[str], *, force: bool = False
) -> list[VerifiedNS]
Verify nameservers exist in mreg and have glue (raises otherwise).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nameservers
|
list[str]
|
List of nameserver names to verify. |
required |
force
|
bool
|
When True, skip safety checks on nameserver existence. |
False
|
Returns:
| Type | Description |
|---|---|
list[VerifiedNS]
|
list[VerifiedNS]: The verified nameserver names. |
Raises:
| Type | Description |
|---|---|
InputFailure
|
If no nameservers are given. |
ForceMissing
|
If a nameserver is missing (or lacks glue) and |
DelegationManager
¶
Operations on zone delegations.
create
¶
create(
zone: ForwardZone,
name: str,
nameservers: list[str],
*,
comment: str = ...,
force: bool = ...,
) -> ForwardZoneDelegation
create(
zone: ReverseZone,
name: str,
nameservers: list[str],
*,
comment: str = ...,
force: bool = ...,
) -> ReverseZoneDelegation
create(
zone: str | Zone,
name: str,
nameservers: list[str],
*,
comment: str = ...,
force: bool = ...,
) -> ForwardZoneDelegation | ReverseZoneDelegation
create(
zone: str | Zone,
name: str,
nameservers: list[str],
*,
comment: str = "",
force: bool = False,
) -> ForwardZoneDelegation | ReverseZoneDelegation
Create a delegation in zone.
Verifies the delegation name is within the zone and the nameservers exist, and that the delegation does not already exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zone
|
str | Zone
|
The parent zone to create the delegation in. |
required |
name
|
str
|
The delegation name (must be within the parent zone). |
required |
nameservers
|
list[str]
|
List of nameserver names for the delegation. |
required |
comment
|
str
|
Optional comment for the delegation. Defaults to "". |
''
|
force
|
bool
|
When True, skip nameserver safety checks. |
False
|
Returns:
| Type | Description |
|---|---|
ForwardZoneDelegation | ReverseZoneDelegation
|
ForwardZoneDelegation | ReverseZoneDelegation: The created zone delegation. |
delete
¶
get
¶
get(
zone: Zone, name: str, *, required: Literal[False]
) -> ForwardZoneDelegation | ReverseZoneDelegation | None
get(
zone: Zone, name: str, *, required: Literal[True] = ...
) -> ForwardZoneDelegation | ReverseZoneDelegation
get(
zone: Zone, name: str, *, required: bool = True
) -> ForwardZoneDelegation | ReverseZoneDelegation | None
Get a delegation in zone by name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zone
|
Zone
|
The parent zone to search in. |
required |
name
|
str
|
The delegation name to look up. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
list_by_zone
¶
list_by_zone(
zone: str | Zone,
) -> list[ForwardZoneDelegation | ReverseZoneDelegation]
set_comment
¶
set_comment(
zone: str | Zone, name: str, comment: str
) -> ForwardZoneDelegation | ReverseZoneDelegation
NameServerManager
¶
Bases: NamedResourceManager[NameServer]
Access to :class:~mreg_api.models.NameServer resources.
assert_absent
¶
Assert that a given resource does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter or name to check. |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with the given identifier exists. |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
create(
name: str, *, ttl: int | None | UNSET = UNSET
) -> NameServer
Create a nameserver.
NOTE: this endpoint does not return the resource after creation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The nameserver name to create. |
required |
ttl
|
int | None | UNSET
|
Optional TTL for the nameserver. If None, uses default TTL. |
UNSET
|
Returns:
| Name | Type | Description |
|---|---|---|
NameServer |
NameServer
|
The created nameserver. |
delete
¶
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_name
¶
Get a resource by its name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name field for the resource to look up. |
required |
required
|
bool
|
Raise if not found. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
T | None: The resource object if found, else None. |
list
¶
list_by_name_regex
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
DHCP¶
DhcpHostIPv4Manager
¶
Bases: DhcpHostManager[DhcpHostIPv4]
Read-only manager for IPv4 DHCP host records.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
list
¶
list_by_range
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
DhcpHostIPv6Manager
¶
Bases: DhcpHostManager[DhcpHostIPv6]
Read-only manager for IPv6 DHCP host records.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
list
¶
list_by_range
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
DhcpHostIPv6ByIPv4Manager
¶
Bases: DhcpHostManager[DhcpHostIPv6ByIPv4]
Read-only manager for IPv6-via-IPv4 DHCP host records.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
list
¶
list_by_range
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
Access control¶
PermissionManager
¶
Bases: WriteResourceManager[Permission]
Operations on Permission resources.
add_label
¶
add_label(
permission: int | Permission, label: int | str | Label
) -> None
Add a label to the permission.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
permission
|
int | Permission
|
The permission (instance or numeric id). |
required |
label
|
int | str | Label
|
The label to add (instance, name, or numeric id). |
required |
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If the label does not exist. |
EntityAlreadyExists
|
If the permission already has this label. |
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
create
¶
Create a permission.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
group
|
str
|
The netgroup the permission applies to. |
required |
range
|
str
|
The network range (CIDR) the permission covers. |
required |
regex
|
str
|
The host regex pattern for the permission. |
required |
labels
|
list[int] | None
|
Optional list of label IDs to attach. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Permission |
Permission
|
The created permission. |
delete
¶
Delete a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The ID or object reference of resource to delete. |
required |
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
get_by_triplet
¶
get_by_triplet(
group: str,
range: str,
regex: str,
*,
required: Literal[False],
) -> Permission | None
get_by_triplet(
group: str,
range: str,
regex: str,
*,
required: Literal[True] = ...,
) -> Permission
get_by_triplet(
group: str,
range: str,
regex: str,
*,
required: bool = True,
) -> Permission | None
Get a permission by the (group, range, regex) triplet.
Replaces Permission.get_by_query_unique_or_raise from the old model API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
group
|
str
|
The netgroup name. |
required |
range
|
str
|
The network range (CIDR). |
required |
regex
|
str
|
The host regex pattern. |
required |
required
|
bool
|
When True (default), raise EntityNotFound if not found. |
True
|
Raises:
| Type | Description |
|---|---|
MultipleEntitiesFound
|
If more than one permission matches the triplet. |
EntityNotFound
|
If |
list
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
remove_label
¶
remove_label(
permission: int | Permission, label: int | str | Label
) -> None
Remove a label from the permission.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
permission
|
int | Permission
|
The permission (instance or numeric id). |
required |
label
|
int | str | Label
|
The label to remove (instance, name, or numeric id). |
required |
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If the label does not exist. |
EntityRelationMissing
|
If the permission does not have the label. |
update
¶
update(
ref: int | Permission,
*,
group: str | UNSET = UNSET,
range: str | UNSET = UNSET,
regex: str | UNSET = UNSET,
labels: list[int] | UNSET = UNSET,
) -> None
Update a permission's mutable fields.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref
|
int | Permission
|
Permission instance or numeric ID. |
required |
group
|
str | UNSET
|
New netgroup name. Omit to leave unchanged. |
UNSET
|
range
|
str | UNSET
|
New network range (CIDR). Omit to leave unchanged. |
UNSET
|
regex
|
str | UNSET
|
New host regex pattern. Omit to leave unchanged. |
UNSET
|
labels
|
list[int] | UNSET
|
New list of label IDs. Omit to leave unchanged. |
UNSET
|
Server metadata and health¶
Reached through client.meta (e.g. client.meta.version, client.meta.health).
MetaManagerNamespace
¶
Class that composes managers for the various /api/meta endpoints.
ServerVersionManager
¶
Bases: GetManager[ServerVersion]
Access to server version metadata.
get
¶
get(*, required: bool = False) -> ServerVersion
Fetch the server version from the meta endpoint.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
False
|
validate_response
¶
Validate a JSON response and construct the manager's type.
ServerLibrariesManager
¶
Access to server library metadata.
get
¶
get(*, required: bool = False) -> ServerLibraries
Fetch the server library list from the meta endpoint.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
False
|
UserInfoManager
¶
Bases: GetManager[UserInfo]
Access to user information.
LDAPHealthManager
¶
Bases: GetManager[LDAPHealth]
Access to LDAP health status.
get
¶
get(*, required: bool = False) -> LDAPHealth
Fetch LDAP health from the health endpoint.
A 503 response means LDAP is down and is not treated as a hard error.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
False
|
validate_response
¶
Validate a JSON response and construct the manager's type.
HeartbeatHealthManager
¶
Bases: GetManager[HeartbeatHealth]
Access to heartbeat health status.
get
¶
get(*, required: bool = False) -> HeartbeatHealth
Fetch heartbeat health from the health endpoint.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
False
|
validate_response
¶
Validate a JSON response and construct the manager's type.
HealthManager
¶
Bases: GetManager[HealthInfo]
Access to combined health information.
__init__
¶
__init__(
client: MregClient,
heartbeat_manager: HeartbeatHealthManager | None = None,
ldap_manager: LDAPHealthManager | None = None,
) -> None
Initialize the manager with a client instance.
Optionally takes in existing heartbeat and LDAP managers to avoid creating new ones.
get
¶
get(*, required: bool = False) -> HealthInfo
Fetch combined health from all health endpoints.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
Forwarded to both sub-managers. When |
False
|
validate_response
¶
Validate a JSON response and construct the manager's type.
Base Manager Classes¶
ResourceManager
¶
Basic manager for performing read operations on an API resource type.
endpoint
abstractmethod
property
¶
endpoint: str
Return the API endpoint for this manager's resource type.
Usually an Endpoint member, but managers bound to a parent resource
(e.g. NetworkCommunityManager) return a formatted endpoint string.
assert_absent
¶
Assert that no resource with ident exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter to check (id / name / network, per resource). |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with |
count
¶
Return the server-reported total count of resources at this endpoint.
Falls back on fetching all results and counting them client-side
if endpoint does not support counting via pagination and strict is False.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
strict
|
bool
|
Raise exception instead of falling back on counting client-side. |
False
|
first
¶
Return the first resource, raising if not found by default.
Passes page_size=1 to avoid over-fetching.
Over-fetches on certain non-standard endpoints that do not implement pagination
such as networks/{network}/unused_list, /dhcphosts, and others.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
required
|
bool
|
When |
True
|
**query
|
str | int | float | bool | None
|
Optional filter parameters forwarded to the list endpoint. |
{}
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The first resource found, or |
get
¶
Get a resource by its endpoint identifier (str) or its ID (int).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int | T
|
The path parameter (id / name / network, per resource). String arguments are only supported for resources that are addressed by a non-numeric path parameter (e.g. name, network, hostname). |
required |
required
|
bool
|
When |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
The resource, or |
list
¶
refresh
¶
Fetch a fresh copy of the resource from the server.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
T
|
The resource object to refresh. |
required |
Returns:
| Type | Description |
|---|---|
T
|
A fresh copy of the resource object. |
Prefers the immutable id when the model has one, so refreshing a renamed
resource does not break the lookup. Models without an id field
(HInfo, Location — keyed by host) fall back to the path parameter.
WriteResourceManager
¶
Bases: ResourceManager[T], ABC
Manager for performing CRUD operations on an API resource type.
NamedResourceManager
¶
Bases: WriteResourceManager[T], ABC
Extended WriteResourceManager for resources that support name-based lookups.
assert_absent
¶
Assert that a given resource does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ident
|
str | int
|
The path parameter or name to check. |
required |
Raises:
| Type | Description |
|---|---|
EntityAlreadyExists
|
If a resource with the given identifier exists. |
delete
¶
get_by_name
¶
Get a resource by its name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name field for the resource to look up. |
required |
required
|
bool
|
Raise if not found. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
EntityNotFound
|
If |
Returns:
| Type | Description |
|---|---|
T | None
|
T | None: The resource object if found, else None. |
list_by_name_regex
¶
HistoryManager
¶
Bases: ResourceManager[T], ABC
Manager capable of fetching history for a resource.
history_resource
abstractmethod
property
¶
history_resource: HistoryResource
The history resource corresponding to this manager's resource.
Used to construct the query for fetching history items.
history
¶
history(name: str) -> list[HistoryItem]
Get the audit history for a named resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The name of the resource to fetch history for. |
required |
Returns:
| Type | Description |
|---|---|
list[HistoryItem]
|
A list of |
GetManager
¶
A manager implementing only a get() method that fetches a meta-endpoint resource.
Each of these manager's get method contains some idiosyncratic logic for fetching and validating the resource, and has some built-in error handling for when the resource is not available.
validate_response
¶
Validate a JSON response and construct the manager's type.