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.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

add_contacts ¶

add_contacts(
    host: int | str | Host, contacts: list[str]
) -> HostContactModification

Add contacts to a host (atomic; POST to /hosts/{name}/contacts/).

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required
`contacts`	`list[str]`	Email addresses to add as contacts.	required

all_ips_on_same_vlan ¶

all_ips_on_same_vlan(host: int | str | Host) -> bool

Return True if all host IPs share a single VLAN (or there are no IPs).

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required

assert_absent ¶

assert_absent(ident: str | int) -> None

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

Remove all contacts from a host (atomic; DELETE /hosts/{name}/contacts/).

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required

count ¶

count(*, strict: bool = False) -> int

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 = "",
    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 "".	`''`
`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 ¶

delete(obj: int | str | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`int \| str \| T`	The resource, ID, or name to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_id ¶

get_by_id(
    host_id: int, *, required: Literal[False]
) -> Host | None

get_by_id(
    host_id: int, *, required: Literal[True] = ...
) -> Host

get_by_id(
    host_id: int, *, required: bool = True
) -> Host | None

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 `required` is True and the host is not found.

get_by_ip ¶

get_by_ip(
    ip: str | IP_AddressT,
    *,
    required: Literal[False],
    ptr_fallback: bool = ...,
) -> Host | None

get_by_ip(
    ip: str | IP_AddressT,
    *,
    required: Literal[True] = ...,
    ptr_fallback: bool = ...,
) -> Host

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
`MultipleEntitiesFound`	If more than one host matches the IP address.
`EntityNotFound`	If `required` is True and no host is found.

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
`EntityNotFound`	If `required` is True and no host is found.

get_by_name ¶

get_by_name(
    name: str, *, required: Literal[False]
) -> T | None

get_by_name(
    name: str, *, required: Literal[True] = ...
) -> T

get_by_name(
    name: str, *, required: bool = True
) -> T | None

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 `required` is True and the resource is not found.

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 `HistoryItem` objects.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_ip ¶

list_by_ip(ip: str | IP_AddressT) -> list[Host]

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

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

list_by_name_regex ¶

list_by_name_regex(name: str) -> list[T]

Get multiple resources by a name regex.

Parameters:

Name	Type	Description	Default
`name`	`str`	The regex pattern for names to search for.	required

Returns:

Type	Description
`list[T]`	A list of resource objects.

networks ¶

networks(
    host: int | str | Host,
) -> dict[Network, list[IPAddress]]

Return a dict mapping each network to the host's IP addresses on that network.

Networks not registered in MREG produce a placeholder via :meth:~mreg_api.models.Network.dummy_network_from_ip.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required

refresh ¶

refresh(obj: T) -> T

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 ¶

remove_contacts(
    host: int | str | Host, contacts: list[str]
) -> HostContactModification

Remove specific contacts from a host (atomic; DELETE /hosts/{name}/contacts/).

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required
`contacts`	`list[str]`	Email addresses to remove from contacts.	required

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(
    host: 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
`host`	`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 ¶

vlans(host: int | str | Host) -> dict[int, list[IPAddress]]

Return a dict mapping VLAN ID to host IPs on that VLAN. IPs with no VLAN map to 0.

Performs API lookups to fetch all networks the host is associated with.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required

HostGroupManager ¶

Bases: NamedResourceManager[HostGroup], HistoryManager[HostGroup]

Operations on HostGroup resources.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

add_group ¶

add_group(
    hostgroup: int | str | HostGroup,
    subgroup: str | HostGroup,
) -> None

Add a group to a host group.

Parameters:

Name	Type	Description	Default
`hostgroup`	`int \| str \| HostGroup`	The parent HostGroup instance, name string, or numeric ID.	required
`subgroup`	`str \| HostGroup`	HostGroup instance or name string to add as a subgroup.	required

add_host ¶

add_host(
    hostgroup: int | str | HostGroup, host: str | Host
) -> None

Add a host to a host group.

Parameters:

Name	Type	Description	Default
`hostgroup`	`int \| str \| HostGroup`	HostGroup instance, name string, or numeric ID.	required
`host`	`str \| Host`	Host reference (name string or Host instance).	required

add_owner ¶

add_owner(
    hostgroup: int | str | HostGroup, name: str
) -> None

Add an owner to a host group.

Parameters:

Name	Type	Description	Default
`hostgroup`	`int \| str \| HostGroup`	HostGroup instance, name string, or numeric ID.	required
`name`	`str`	Name of the owner to add.	required

assert_absent ¶

assert_absent(ident: str | int) -> None

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 ¶

count(*, strict: bool = False) -> int

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 | UNSET = UNSET
) -> HostGroup

Create a host group.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the host group.	required
`description`	`str \| UNSET`	Description of the group. Omit to leave unset.	`UNSET`

Returns:

Name	Type	Description
`HostGroup`	`HostGroup`	The created host group.

delete ¶

delete(obj: int | str | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`int \| str \| T`	The resource, ID, or name to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_name ¶

get_by_name(
    name: str, *, required: Literal[False]
) -> T | None

get_by_name(
    name: str, *, required: Literal[True] = ...
) -> T

get_by_name(
    name: str, *, required: bool = True
) -> T | None

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 `required` is True and the resource is not found.

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 `HistoryItem` objects.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_host ¶

list_by_host(
    host: int | str | Host, *, traverse: bool = False
) -> list[HostGroup]

List all hostgroups that include the given host.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance, numeric ID, or name string.	required
`traverse`	`bool`	If True, recursively include parent groups of the direct groups.	`False`

list_by_name_regex ¶

list_by_name_regex(name: str) -> list[T]

Get multiple resources by a name regex.

Parameters:

Name	Type	Description	Default
`name`	`str`	The regex pattern for names to search for.	required

Returns:

Type	Description
`list[T]`	A list of resource objects.

list_parents ¶

list_parents(
    hostgroup: int | str | HostGroup,
) -> list[HostGroup]

Get all parent groups of a host group.

Renamed from get_all_parents to list_parents

Parameters:

Name	Type	Description	Default
`hostgroup`	`int \| str \| HostGroup`	HostGroup instance, name string, or numeric ID.	required

refresh ¶

refresh(obj: T) -> T

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_group(
    hostgroup: int | str | HostGroup,
    subgroup: str | HostGroup,
) -> None

Remove a group from a host group.

Parameters:

Name	Type	Description	Default
`hostgroup`	`int \| str \| HostGroup`	The parent HostGroup instance, name string, or numeric ID.	required
`subgroup`	`str \| HostGroup`	HostGroup instance or name string to remove.	required

remove_host ¶

remove_host(
    hostgroup: int | str | HostGroup, host: str | Host
) -> None

Remove a host from a host group.

Parameters:

Name	Type	Description	Default
`hostgroup`	`int \| str \| HostGroup`	HostGroup instance, name string, or numeric ID.	required
`host`	`str \| Host`	Host reference (name string or Host instance).	required

remove_owner ¶

remove_owner(
    hostgroup: int | str | HostGroup, name: str
) -> None

Remove an owner from a host group.

Parameters:

Name	Type	Description	Default
`hostgroup`	`int \| str \| HostGroup`	HostGroup instance, name string, or numeric ID.	required
`name`	`str`	Name of the owner to remove.	required

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(
    hostgroup: int | str | HostGroup, description: str
) -> None

Set the description for the host group.

Parameters:

Name	Type	Description	Default
`hostgroup`	`int \| str \| HostGroup`	HostGroup instance, name string, or numeric ID.	required
`description`	`str`	New description to set.	required

update ¶

update(
    hostgroup: int | str | HostGroup,
    *,
    description: str | UNSET = UNSET,
) -> None

Update a host group's mutable fields.

Parameters:

Name	Type	Description	Default
`hostgroup`	`int \| str \| HostGroup`	HostGroup instance, name string, or numeric ID.	required
`description`	`str \| UNSET`	New description. Omit to leave unchanged.	`UNSET`

IP addresses¶

IPAddressManager ¶

Bases: WriteResourceManager[IPAddress]

Operations on IPAddress resources.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

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
`EntityAlreadyExists`	If the IP already has a MAC and `force` is False.

count ¶

count(*, strict: bool = False) -> int

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(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

disassociate_mac ¶

disassociate_mac(
    ip: int | str | IP_AddressT | IPAddress,
) -> None

Remove the MAC address from an IP address.

Parameters:

Name	Type	Description	Default
`ip`	`int \| str \| IP_AddressT \| IPAddress`	IPAddress instance, numeric ID, or IP address string.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_host ¶

list_by_host(host: int | str | Host) -> list[IPAddress]

List all IP address records for a host.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required

list_by_ip ¶

list_by_ip(
    ip: int | str | IP_AddressT | IPAddress,
) -> list[IPAddress]

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

refresh ¶

refresh(obj: T) -> T

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(
    ip: 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
`ip`	`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.

community `cached` `property` ¶

community: CommunityManager

Manager for network community.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

policy `cached` `property` ¶

policy: NetworkPolicyManager

Manager for network policies.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

add_excluded_range ¶

add_excluded_range(
    network: str | int | Network, start: str, end: str
) -> None

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

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_ip ¶

get_by_ip(
    ip: str | IP_AddressT, *, required: Literal[False]
) -> Network | None

get_by_ip(
    ip: str | IP_AddressT, *, required: Literal[True] = ...
) -> Network

get_by_ip(
    ip: str | IP_AddressT, *, required: bool = True
) -> Network | None

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
`EntityNotFound`	If `required` is True and no network is found.

get_first_available_ip ¶

get_first_available_ip(
    network: str | int | Network,
) -> IP_AddressT

Return the first available IP address in the network.

Parameters:

Name	Type	Description	Default
`network`	`str \| int \| Network`	Network reference (address, numeric ID, or Network instance).	required

get_ptr_overrides ¶

get_ptr_overrides(
    network: str | int | Network,
) -> list[IP_AddressT]

Return IP addresses that have PTR overrides in the network.

Parameters:

Name	Type	Description	Default
`network`	`str \| int \| Network`	Network reference (address, numeric ID, or Network instance).	required

get_ptroverride_host_list ¶

get_ptroverride_host_list(
    network: str | int | Network,
) -> dict[str, str]

Return a dict of PTR override IPs to their associated hostnames.

Parameters:

Name	Type	Description	Default
`network`	`str \| int \| Network`	Network reference (address, numeric ID, or Network instance).	required

get_random_available_ip ¶

get_random_available_ip(
    network: str | int | Network,
) -> IP_AddressT

Return a random available IP address in the network.

Parameters:

Name	Type	Description	Default
`network`	`str \| int \| Network`	Network reference (address, numeric ID, or Network instance).	required

get_reserved_ips ¶

get_reserved_ips(
    network: str | int | Network,
) -> list[IP_AddressT]

Return the reserved IP addresses of the network.

Parameters:

Name	Type	Description	Default
`network`	`str \| int \| Network`	Network reference (address, numeric ID, or Network instance).	required

get_unused_count ¶

get_unused_count(network: str | int | Network) -> int

Return the number of unused IP addresses in the network.

Parameters:

Name	Type	Description	Default
`network`	`str \| int \| Network`	Network reference (address, numeric ID, or Network instance).	required

get_unused_list ¶

get_unused_list(
    network: str | int | Network,
) -> list[IP_AddressT]

Return the unused IP addresses in the network.

Parameters:

Name	Type	Description	Default
`network`	`str \| int \| Network`	Network reference (address, numeric ID, or Network instance).	required

get_used_count ¶

get_used_count(network: str | int | Network) -> int

Return the number of used IP addresses in the network.

Parameters:

Name	Type	Description	Default
`network`	`str \| int \| Network`	Network reference (address, numeric ID, or Network instance).	required

get_used_host_list ¶

get_used_host_list(
    network: str | int | Network,
) -> dict[str, list[str]]

Return a dict of used IP addresses to their associated hostnames.

Parameters:

Name	Type	Description	Default
`network`	`str \| int \| Network`	Network reference (address, numeric ID, or Network instance).	required

get_used_list ¶

get_used_list(
    network: str | int | Network,
) -> list[IP_AddressT]

Return the used IP addresses in the network.

Parameters:

Name	Type	Description	Default
`network`	`str \| int \| Network`	Network reference (address, numeric ID, or Network instance).	required

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

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 ¶

refresh(obj: T) -> T

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_excluded_range(
    network: str | int | Network, start: str, end: str
) -> None

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(
    network: str | int | Network,
    *,
    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
`network`	`str \| int \| Network`	Network reference (address, numeric ID, or Network instance).	required
`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.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

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_absent(ident: str | int) -> None

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 ¶

count(*, strict: bool = False) -> int

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 ¶

delete(obj: int | str | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`int \| str \| T`	The resource, ID, or name to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_name ¶

get_by_name(
    name: str, *, required: Literal[False]
) -> T | None

get_by_name(
    name: str, *, required: Literal[True] = ...
) -> T

get_by_name(
    name: str, *, required: bool = True
) -> T | None

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 `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	T \| None: The resource object if found, else None.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_name_regex ¶

list_by_name_regex(name: str) -> list[T]

Get multiple resources by a name regex.

Parameters:

Name	Type	Description	Default
`name`	`str`	The regex pattern for names to search for.	required

Returns:

Type	Description
`list[T]`	A list of resource objects.

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 ¶

refresh(obj: T) -> T

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
`EntityNotFound`	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(
    policy: 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
`policy`	`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.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 ¶

count(*, strict: bool = False) -> int

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 ¶

delete(obj: int | str | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`int \| str \| T`	The resource, ID, or name to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_name ¶

get_by_name(
    name: str, *, required: Literal[False]
) -> T | None

get_by_name(
    name: str, *, required: Literal[True] = ...
) -> T

get_by_name(
    name: str, *, required: bool = True
) -> T | None

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 `required` is True and the resource is not found.

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(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_name_regex ¶

list_by_name_regex(name: str) -> list[T]

Get multiple resources by a name regex.

Parameters:

Name	Type	Description	Default
`name`	`str`	The regex pattern for names to search for.	required

Returns:

Type	Description
`list[T]`	A list of resource objects.

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 ¶

refresh(obj: T) -> T

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(
    attr: int | str | NetworkPolicyAttribute,
    *,
    description: str | UNSET = UNSET,
) -> None

Update a network policy attribute's mutable fields.

Parameters:

Name	Type	Description	Default
`attr`	`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.

Communities are always scoped to a network — every method takes a network reference (address string or Network instance).

model_name `property` ¶

model_name: str

The name of the manager's model type.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client.

add_host ¶

add_host(
    community: int | str | Community,
    network: str | int | Network,
    host: int | str | Host,
    *,
    ipaddress: IP_AddressT | str | None = None,
) -> bool

Add a host to a community.

Parameters:

Name	Type	Description	Default
`community`	`int \| str \| Community`	Community ID, name or object. Using a name performs an extra lookup to resolve the ID.	required
`network`	`str \| int \| Network`	Network reference (address, ID, or Network instance).	required
`host`	`int \| str \| Host`	Host reference (ID 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(
    network: str | int | Network,
    *,
    name: str,
    description: str,
) -> Community

Create a community in a network.

Parameters:

Name	Type	Description	Default
`network`	`str \| int \| Network`	Network reference (address, ID, or Network instance).	required
`name`	`str`	Name of the community.	required
`description`	`str`	Description of the community.	required

Returns:

Name	Type	Description
`Community`	`Community`	The created community.

delete ¶

delete(
    community: int | str | Community,
    network: str | int | Network,
) -> None

Delete a community from a network.

Parameters:

Name	Type	Description	Default
`community`	`int \| str \| Community`	Community ID, name or object. Using a name performs an extra lookup to resolve the ID.	required
`network`	`str \| int \| Network`	Network reference (address, ID, or Network instance).	required

get ¶

get(
    community: int | str,
    network: str | int | Network,
    *,
    required: Literal[False],
) -> Community | None

get(
    community: int | str,
    network: str | int | Network,
    *,
    required: Literal[True] = ...,
) -> Community

get(
    community: int | str,
    network: str | int | Network,
    *,
    required: bool = True,
) -> Community | None

Get a community by ID or name within a network.

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 `required` is True and the community is not found.

get_by_id ¶

get_by_id(
    community_id: int,
    network: str | int | Network,
    *,
    required: Literal[False],
) -> Community | None

get_by_id(
    community_id: int,
    network: str | int | Network,
    *,
    required: Literal[True] = ...,
) -> Community

get_by_id(
    community_id: int,
    network: str | int | Network,
    *,
    required: bool = True,
) -> Community | None

Get a community by ID within a network.

Parameters:

Name	Type	Description	Default
`community_id`	`int`	The community ID to look up.	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 `required` is True and the community is not found.

get_by_name ¶

get_by_name(
    name: str,
    network: str | int | Network,
    *,
    required: Literal[False],
) -> Community | None

get_by_name(
    name: str,
    network: str | int | Network,
    *,
    required: Literal[True] = ...,
) -> Community

get_by_name(
    name: str,
    network: str | int | Network,
    *,
    required: bool = True,
) -> Community | None

Get a community by name within a network.

Parameters:

Name	Type	Description	Default
`name`	`str`	The community name to look up.	required
`network`	`str \| int \| Network`	Network reference (address, ID, or Network instance). Attempts to perform a direct lookup if a string is provided.	required
`required`	`bool`	When True (default), raise EntityNotFound if not found.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the community is not found.

get_hosts ¶

get_hosts(
    community: int | str | Community,
    network: str | int | Network,
) -> list[Host]

List all hosts in a community.

Parameters:

Name	Type	Description	Default
`community`	`int \| str \| Community`	Community ID, name or object. Using a name performs an extra lookup to resolve the ID.	required
`network`	`str \| int \| Network`	Network reference (address, ID, or Network instance).	required

list ¶

list(network: str | int | Network) -> list[Community]

List all communities for a network.

Parameters:

Name	Type	Description	Default
`network`	`str \| int \| Network`	Network reference (address, ID, or Network instance).	required

remove_host ¶

remove_host(
    community: int | str | Community,
    network: str | int | Network,
    host: int | str | Host,
    *,
    ipaddress: IP_AddressT | str | None = None,
) -> None

Remove a host from a community.

Parameters:

Name	Type	Description	Default
`community`	`int \| str \| Community`	Community ID, name or object. Using a name performs an extra lookup to resolve the ID.	required
`network`	`str \| int \| Network`	Network reference (address, ID, or Network instance).	required
`host`	`int \| str \| Host`	Host reference (ID 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`

update ¶

update(
    community: int | str | Community,
    network: str | int | Network,
    *,
    name: str | UNSET = UNSET,
    description: str | UNSET = UNSET,
) -> Community

Update a community's mutable fields.

Parameters:

Name	Type	Description	Default
`community`	`int \| str \| Community`	Community ID, name or object. Using a name performs an extra lookup to resolve the ID.	required
`network`	`str \| int \| Network`	Network reference (address, ID, or Network instance).	required
`name`	`str \| UNSET`	New name. Omit to leave unchanged.	`UNSET`
`description`	`str \| UNSET`	New description. Omit to leave unchanged.	`UNSET`

DNS records¶

CNAMEManager ¶

Bases: NamedResourceManager[CNAME]

Operations on CNAME resources.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 ¶

count(*, strict: bool = False) -> int

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 | HostName
) -> CNAME

Create a CNAME record.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required
`name`	`str \| HostName`	The alias name for the CNAME.	required

Returns:

Name	Type	Description
`CNAME`	`CNAME`	The created CNAME record.

delete ¶

delete(obj: int | str | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`int \| str \| T`	The resource, ID, or name to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

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 `required` is True and the CNAME is not found.

get_by_name ¶

get_by_name(
    name: str, *, required: Literal[False]
) -> CNAME | None

get_by_name(
    name: str, *, required: Literal[True] = ...
) -> CNAME

get_by_name(
    name: str, *, required: bool = True
) -> CNAME | None

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 `required` is True and the CNAME is not found.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_host ¶

list_by_host(host: int | str | Host) -> list[CNAME]

List all CNAME records for a host.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required

list_by_name_regex ¶

list_by_name_regex(name: str) -> list[T]

Get multiple resources by a name regex.

Parameters:

Name	Type	Description	Default
`name`	`str`	The regex pattern for names to search for.	required

Returns:

Type	Description
`list[T]`	A list of resource objects.

refresh ¶

refresh(obj: T) -> T

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(
    cname: 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
`cname`	`int \| CNAME`	CNAME instance or numeric ID.	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.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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, mx: str, priority: int
) -> MX

Create an MX record.

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

Returns:

Name	Type	Description
`MX`	`MX`	The created MX record.

delete ¶

delete(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_all ¶

get_by_all(
    host: int | str | Host, mx: str, priority: int
) -> MX

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: Literal[False],
) -> MX | None

get_unique(
    host: int | str | Host,
    mx: str,
    priority: int,
    *,
    required: Literal[True] = ...,
) -> MX

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 `required` is True.

Returns:

Type	Description
`MX \| None`	MX \| None: The matching MX record, or None if not found and `required` is False.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_host ¶

list_by_host(host: int | str | Host) -> list[MX]

List all MX records for a host.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required

refresh ¶

refresh(obj: T) -> T

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 | MX,
    *,
    mx: str | UNSET = UNSET,
    priority: int | UNSET = UNSET,
) -> None

Update an MX record's mutable fields.

Parameters:

Name	Type	Description	Default
`ref`	`int \| MX`	MX instance or numeric ID.	required
`mx`	`str \| UNSET`	New mail exchange hostname. Omit to leave unchanged.	`UNSET`
`priority`	`int \| UNSET`	New priority value. Omit to leave unchanged.	`UNSET`

TXTManager ¶

Bases: WriteResourceManager[TXT]

Operations on TXT resources.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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, txt: str) -> TXT

Create a TXT record.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required
`txt`	`str`	The TXT record value.	required

Returns:

Name	Type	Description
`TXT`	`TXT`	The created TXT record.

delete ¶

delete(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_host ¶

list_by_host(host: int | str | Host) -> list[TXT]

List all TXT records for a host.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required

refresh ¶

refresh(obj: T) -> T

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 | TXT, *, txt: str | UNSET = UNSET) -> None

Update a TXT record's mutable fields.

Parameters:

Name	Type	Description	Default
`ref`	`int \| TXT`	TXT instance or numeric ID.	required
`txt`	`str \| UNSET`	New TXT record value. Omit to leave unchanged.	`UNSET`

NAPTRManager ¶

Bases: WriteResourceManager[NAPTR]

Operations on NAPTR resources.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_unique ¶

get_unique(
    host: int | str | Host,
    preference: int,
    order: int,
    flag: str = ...,
    service: str = ...,
    regex: str = ...,
    replacement: str = ...,
    *,
    required: Literal[False],
) -> NAPTR | None

get_unique(
    host: int | str | Host,
    preference: int,
    order: int,
    flag: str = ...,
    service: str = ...,
    regex: str = ...,
    replacement: str = ...,
    *,
    required: Literal[True] = ...,
) -> NAPTR

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 `required` is True.

Returns:

Type	Description
`NAPTR \| None`	NAPTR \| None: The matching NAPTR record, or None if not found and `required` is False.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_host ¶

list_by_host(host: int | str | Host) -> list[NAPTR]

List all NAPTR records for a host.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required

refresh ¶

refresh(obj: T) -> T

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(
    naptr: 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
`naptr`	`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.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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. Pass None to use default, omit to leave unchanged.	`UNSET`

Returns:

Name	Type	Description
`Srv`	`Srv`	The created SRV record.

delete ¶

delete(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_unique ¶

get_unique(
    *,
    name: str,
    priority: int,
    weight: int,
    port: int,
    host: int | str | Host,
    required: Literal[False],
) -> Srv | None

get_unique(
    *,
    name: str,
    priority: int,
    weight: int,
    port: int,
    host: int | str | Host,
    required: Literal[True] = ...,
) -> Srv

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(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_host ¶

list_by_host(host: int | str | Host) -> list[Srv]

List all SRV records for a host.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required

refresh ¶

refresh(obj: T) -> T

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(
    srv: 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
`srv`	`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.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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. Pass None to use default, omit to leave unchanged.	`UNSET`

Returns:

Name	Type	Description
`SSHFP`	`SSHFP`	The created SSHFP record.

delete ¶

delete(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_host ¶

list_by_host(host: int | str | Host) -> list[SSHFP]

List all SSHFP records for a host.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required

refresh ¶

refresh(obj: T) -> T

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(
    sshfp: 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
`sshfp`	`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.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_host ¶

list_by_host(host: int | str | Host) -> list[PTR_override]

List all PTR override records for a host.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required

refresh ¶

refresh(obj: T) -> T

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(
    ptr: 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
`ptr`	`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).

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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, cpu: str, os: str
) -> HInfo

Create an HInfo record.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host ID, name or instance.	required
`cpu`	`str`	CPU hardware type string.	required
`os`	`str`	Operating system string.	required

Returns:

Name	Type	Description
`HInfo`	`HInfo`	The created HInfo record.

delete ¶

delete(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_host ¶

get_by_host(
    host: int | str | Host, *, required: bool = True
) -> HInfo | None

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 `required` is True and no HInfo record is found.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

refresh ¶

refresh(obj: T) -> T

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(
    hinfo: int | HInfo,
    *,
    cpu: str | UNSET = UNSET,
    os: str | UNSET = UNSET,
) -> None

Update an HInfo record's mutable fields.

Parameters:

Name	Type	Description	Default
`hinfo`	`int \| HInfo`	HInfo instance or numeric ID.	required
`cpu`	`str \| UNSET`	New CPU hardware type string. Omit to leave unchanged.	`UNSET`
`os`	`str \| UNSET`	New operating system string. Omit to leave unchanged.	`UNSET`

LocationManager ¶

Bases: WriteResourceManager[Location]

Operations on Location resources.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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, loc: str) -> Location

Create a LOC record.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance or numeric ID.	required
`loc`	`str`	The LOC record value.	required

Returns:

Name	Type	Description
`Location`	`Location`	The created LOC record.

delete ¶

delete(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_host ¶

get_by_host(
    host: int | str | Host, *, required: bool = True
) -> Location | None

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 `required` is True and no LOC record is found.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

refresh ¶

refresh(obj: T) -> T

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(
    location: int | Location, *, loc: str | UNSET = UNSET
) -> None

Update a LOC record's mutable fields.

Parameters:

Name	Type	Description	Default
`location`	`int \| Location`	Location instance or numeric ID.	required
`loc`	`str \| UNSET`	New LOC record value. Omit to leave unchanged.	`UNSET`

BacnetIDManager ¶

Bases: WriteResourceManager[BacnetID]

Operations on BacnetID resources.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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: str | HostName | Host, id: int) -> BacnetID

Create a BacnetID record.

Parameters:

Name	Type	Description	Default
`host`	`str \| HostName \| Host`	The host to create a BacnetID for.	required
`id`	`int`	The BACnet id.	required

Returns:

Name	Type	Description
`BacnetID`	`BacnetID`	The created BacnetID record.

delete ¶

delete(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_host ¶

get_by_host(
    host: str | HostName | Host, *, required: bool = True
) -> BacnetID | None

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 `required` is True and no BacnetID record is found.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_in_range ¶

list_in_range(start: int, end: int) -> list[BacnetID]

List BacnetID records within a numeric id range (inclusive).

Parameters:

Name	Type	Description	Default
`start`	`int`	The start of the BACnet ID range (inclusive).	required
`end`	`int`	The end of the BACnet ID range (inclusive).	required

refresh ¶

refresh(obj: T) -> T

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.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

add_atom ¶

add_atom(
    role: int | str | Role, atom: int | str | Atom
) -> bool

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_host(role: int | Role, host: str | Host) -> bool

Add a host to 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 added. DEPRECATED: Maintains parity with older library versions. Will never return False on failure; an exception is raised instead.

add_label ¶

add_label(
    role: int | str | Role, label: int | str | Label
) -> None

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_absent(ident: str | int) -> None

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 ¶

count(*, strict: bool = False) -> int

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 = '') -> Role

Create a role.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the role.	required
`description`	`str`	Description of the role. Defaults to "".	`''`

Returns:

Name	Type	Description
`Role`	`Role`	The created role.

delete ¶

delete(
    obj: int | str | Role, *, force: bool = False
) -> None

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
`DeleteError`	If the role is still in use on any hosts.

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_name ¶

get_by_name(
    name: str, *, required: Literal[False]
) -> T | None

get_by_name(
    name: str, *, required: Literal[True] = ...
) -> T

get_by_name(
    name: str, *, required: bool = True
) -> T | None

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 `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	T \| None: The resource object if found, else None.

get_labels ¶

get_labels(role: int | str | Role) -> list[Label]

List the labels associated with the role.

Parameters:

Name	Type	Description	Default
`role`	`int \| str \| Role`	Role instance, numeric ID, or name string.	required

Returns:

Type	Description
`list[Label]`	list[Label]: List of labels associated with the role.

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 `HistoryItem` objects.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_host ¶

list_by_host(host: int | str | Host) -> list[Role]

List all roles that include the given host.

Parameters:

Name	Type	Description	Default
`host`	`int \| str \| Host`	Host instance, name string, or numeric ID.	required

list_by_name_regex ¶

list_by_name_regex(name: str) -> list[T]

Get multiple resources by a name regex.

Parameters:

Name	Type	Description	Default
`name`	`str`	The regex pattern for names to search for.	required

Returns:

Type	Description
`list[T]`	A list of resource objects.

list_labels ¶

list_labels(role: int | str | Role) -> list[Label]

List the labels associated with the role.

Parameters:

Name	Type	Description	Default
`role`	`int \| str \| Role`	Role instance, numeric ID, or name string.	required

Returns:

Type	Description
`list[Label]`	list[Label]: List of labels associated with the role.

list_with_atom ¶

list_with_atom(atom: int | str | Atom) -> list[Role]

List all roles that contain a given atom.

Renamed from Role.get_roles_with_atom.

Parameters:

Name	Type	Description	Default
`atom`	`int \| str \| Atom`	Atom instance, numeric ID, or name string.	required

refresh ¶

refresh(obj: T) -> T

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_atom(
    role: int | str | Role, atom: int | str | Atom
) -> bool

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
`EntityOwnershipMismatch`	If the atom is not a member of the role.

remove_host ¶

remove_host(role: int | Role, host: str | Host) -> bool

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_label(
    role: int | str | Role, label: int | str | Label
) -> None

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.
`EntityOwnershipMismatch`	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 ¶

set_description(
    role: int | str | Role, description: str
) -> None

Set the description for the role.

Parameters:

Name	Type	Description	Default
`role`	`int \| str \| Role`	Role instance, numeric ID, or name string.	required
`description`	`str`	New description to set.	required

update ¶

update(
    role: int | str | Role,
    *,
    description: str | UNSET = UNSET,
) -> None

Update a role's mutable fields.

Parameters:

Name	Type	Description	Default
`role`	`int \| str \| Role`	Role instance, numeric ID, or name string.	required
`description`	`str \| UNSET`	New description. Omit to leave unchanged.	`UNSET`

AtomManager ¶

Bases: NamedResourceManager[Atom], HistoryManager[Atom]

Operations on Atom resources.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 ¶

count(*, strict: bool = False) -> int

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 = '') -> Atom

Create an atom.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the atom.	required
`description`	`str`	Description of the atom. Defaults to "".	`''`

Returns:

Name	Type	Description
`Atom`	`Atom`	The created atom.

delete ¶

delete(
    obj: int | str | Atom, *, force: bool = False
) -> None

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
`DeleteError`	If the atom is still used in any roles.

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_name ¶

get_by_name(
    name: str, *, required: Literal[False]
) -> T | None

get_by_name(
    name: str, *, required: Literal[True] = ...
) -> T

get_by_name(
    name: str, *, required: bool = True
) -> T | None

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 `required` is True and the resource is not found.

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 `HistoryItem` objects.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_name_regex ¶

list_by_name_regex(name: str) -> list[T]

Get multiple resources by a name regex.

Parameters:

Name	Type	Description	Default
`name`	`str`	The regex pattern for names to search for.	required

Returns:

Type	Description
`list[T]`	A list of resource objects.

refresh ¶

refresh(obj: T) -> T

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(
    atom: int | str | Atom, description: str
) -> None

Set the description for the atom.

Parameters:

Name	Type	Description	Default
`atom`	`int \| str \| Atom`	Atom instance, name string, or numeric ID.	required
`description`	`str`	New description to set.	required

update ¶

update(
    atom: int | str | Atom,
    *,
    description: str | UNSET = UNSET,
) -> None

Update an atom's mutable fields.

Parameters:

Name	Type	Description	Default
`atom`	`int \| str \| Atom`	Atom instance, name string, or numeric ID.	required
`description`	`str \| UNSET`	New description. Omit to leave unchanged.	`UNSET`

LabelManager ¶

Bases: NamedResourceManager[Label]

Operations on Label resources.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 ¶

count(*, strict: bool = False) -> int

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) -> Label

Create a label.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the label.	required
`description`	`str`	Description of the label.	required

Returns:

Name	Type	Description
`Label`	`Label`	The created label.

delete ¶

delete(obj: int | str | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`int \| str \| T`	The resource, ID, or name to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_name ¶

get_by_name(
    name: str, *, required: Literal[False]
) -> T | None

get_by_name(
    name: str, *, required: Literal[True] = ...
) -> T

get_by_name(
    name: str, *, required: bool = True
) -> T | None

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 `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	T \| None: The resource object if found, else None.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_name_regex ¶

list_by_name_regex(name: str) -> list[T]

Get multiple resources by a name regex.

Parameters:

Name	Type	Description	Default
`name`	`str`	The regex pattern for names to search for.	required

Returns:

Type	Description
`list[T]`	A list of resource objects.

refresh ¶

refresh(obj: T) -> T

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(
    label: int | str | Label, description: str
) -> None

Set the description for the label.

Parameters:

Name	Type	Description	Default
`label`	`int \| str \| Label`	Label instance, numeric ID, or name string.	required
`description`	`str`	New description to set.	required

update ¶

update(
    label: int | str | Label,
    *,
    description: str | UNSET = UNSET,
) -> None

Update a label's mutable fields.

Parameters:

Name	Type	Description	Default
`label`	`int \| str \| Label`	Label instance, numeric ID, or name string.	required
`description`	`str \| UNSET`	New description. Omit to leave unchanged.	`UNSET`

Zones¶

ZoneManager ¶

Public facade over the forward/reverse zone managers.

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.

init ¶

__init__(client: MregClient) -> None

Bind the facade and its private sub-managers to the client.

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(
    *,
    name: str,
    email: str,
    primary_ns: list[str],
    force: bool = False,
) -> Zone

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.

delete ¶

delete(zone: str | Zone, *, force: bool = False) -> None

Delete the zone, guarding against non-empty zones unless force.

Parameters:

Name	Type	Description	Default
`zone`	`str \| Zone`	Zone reference (name string or instance).	required
`force`	`bool`	When True, skip safety checks and delete even non-empty zones.	`False`

get ¶

get(name: str, *, required: Literal[False]) -> Zone | None

get(name: str, *, required: Literal[True] = ...) -> Zone

get(name: str, *, required: bool = True) -> Zone | None

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 `required` is True and the zone is not found.

get_by_name ¶

get_by_name(
    name: str, *, required: Literal[False]
) -> Zone | None

get_by_name(
    name: str, *, required: Literal[True] = ...
) -> Zone

get_by_name(
    name: str, *, required: bool = True
) -> Zone | None

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 `required` is True and the zone is not found.

get_from_host ¶

get_from_host(
    host: str | HostName | Host,
) -> ForwardZoneDelegation | ForwardZone | None

Get the forward zone (or delegation) responsible for a host or hostname.

Parameters:

Name	Type	Description	Default
`host`	`str \| HostName \| Host`	Host reference (name string or Host instance).	required

list_forward ¶

list_forward() -> list[ForwardZone]

List forward zones.

list_reverse ¶

list_reverse() -> list[ReverseZone]

List reverse zones.

list_subzones ¶

list_subzones(zone: ZoneT) -> Sequence[ZoneT]

list_subzones(zone: str | Zone) -> Sequence[Zone]

list_subzones(
    zone: str | Zone | ZoneT,
) -> Sequence[ZoneT] | Sequence[Zone]

List subzones of the zone (excluding the zone itself).

Parameters:

Name	Type	Description	Default
`zone`	`str \| Zone`	Zone reference (name string or instance).	required

refresh ¶

refresh(obj: ZoneT) -> ZoneT

Refresh a zone instance from the server.

Parameters:

Name	Type	Description	Default
`obj`	`ZoneT`	The zone to refresh.	required

set_default_ttl ¶

set_default_ttl(zone: str | Zone, ttl: int) -> None

Set the zone's default TTL.

Parameters:

Name	Type	Description	Default
`zone`	`str \| Zone`	Zone reference (name string or instance).	required
`ttl`	`int`	The new default TTL value (300-68400).	required

set_nameservers ¶

set_nameservers(
    zone: str | Zone,
    nameservers: list[str],
    *,
    force: bool = False,
) -> None

Replace the zone's nameservers.

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`

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,
) -> None

Update the zone's SOA fields.

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`

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`

zone_file ¶

zone_file(
    zone_name: str, *, exclude_private: bool = False
) -> str | None

Return the zone file content for the named zone, or None if not found.

Parameters:

Name	Type	Description	Default
`zone_name`	`str`	The name of the zone to fetch the file for.	required
`exclude_private`	`bool`	When True, exclude private records from the zone file.	`False`

DelegationManager ¶

Operations on zone delegations.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client.

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 ¶

delete(zone: str | Zone, name: str) -> None

Delete a delegation from zone.

Parameters:

Name	Type	Description	Default
`zone`	`str \| Zone`	The parent zone to delete the delegation from.	required
`name`	`str`	The delegation name to delete.	required

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 `required` is True and the delegation is not found.

list_by_zone ¶

list_by_zone(
    zone: str | Zone,
) -> list[ForwardZoneDelegation | ReverseZoneDelegation]

List all delegations for a zone.

Parameters:

Name	Type	Description	Default
`zone`	`str \| Zone`	The parent zone to list delegations for.	required

set_comment ¶

set_comment(
    zone: str | Zone, name: str, comment: str
) -> ForwardZoneDelegation | ReverseZoneDelegation

Set (or clear, with "") the comment for a delegation.

Parameters:

Name	Type	Description	Default
`zone`	`str \| Zone`	The parent zone containing the delegation.	required
`name`	`str`	The delegation name.	required
`comment`	`str`	The new comment. Pass "" to clear.	required

NameServerManager ¶

Bases: NamedResourceManager[NameServer]

Access to :class:~mreg_api.models.NameServer resources.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 ¶

count(*, strict: bool = False) -> int

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 ¶

delete(obj: int | str | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`int \| str \| T`	The resource, ID, or name to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

get_by_name ¶

get_by_name(
    name: str, *, required: Literal[False]
) -> T | None

get_by_name(
    name: str, *, required: Literal[True] = ...
) -> T

get_by_name(
    name: str, *, required: bool = True
) -> T | None

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 `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	T \| None: The resource object if found, else None.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_name_regex ¶

list_by_name_regex(name: str) -> list[T]

Get multiple resources by a name regex.

Parameters:

Name	Type	Description	Default
`name`	`str`	The regex pattern for names to search for.	required

Returns:

Type	Description
`list[T]`	A list of resource objects.

refresh ¶

refresh(obj: T) -> T

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

DHCP¶

DhcpHostIPv4Manager ¶

Bases: DhcpHostManager[DhcpHostIPv4]

Read-only manager for IPv4 DHCP host records.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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 ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_range ¶

list_by_range(
    ip: str | IP_AddressT, range: str
) -> list[T]

List DHCP hosts within the given IP range.

Parameters:

Name	Type	Description	Default
`ip`	`str \| IP_AddressT`	The start IP address of the range.	required
`range`	`str`	The range specifier.	required

refresh ¶

refresh(obj: T) -> T

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.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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 ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_range ¶

list_by_range(
    ip: str | IP_AddressT, range: str
) -> list[T]

List DHCP hosts within the given IP range.

Parameters:

Name	Type	Description	Default
`ip`	`str \| IP_AddressT`	The start IP address of the range.	required
`range`	`str`	The range specifier.	required

refresh ¶

refresh(obj: T) -> T

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.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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 ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

list_by_range ¶

list_by_range(
    ip: str | IP_AddressT, range: str
) -> list[T]

List DHCP hosts within the given IP range.

Parameters:

Name	Type	Description	Default
`ip`	`str \| IP_AddressT`	The start IP address of the range.	required
`range`	`str`	The range specifier.	required

refresh ¶

refresh(obj: T) -> T

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.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

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_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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(
    *,
    group: str,
    range: str,
    regex: str,
    labels: list[int] | None = None,
) -> Permission

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(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

first ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

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 `required` is True and no match is found.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

refresh ¶

refresh(obj: T) -> T

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 or the permission lacks it.

update ¶

update(
    permission: 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
`permission`	`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.

init ¶

__init__(client: MregClient) -> None

Initialize the namespace with a client instance.

ServerVersionManager ¶

Bases: GetManager[ServerVersion]

Access to server version metadata.

init ¶

__init__(client: MregClient) -> None

Initialize the manager with a client instance.

get ¶

get(*, required: bool = False) -> ServerVersion

Fetch the server version from the meta endpoint.

Parameters:

Name	Type	Description	Default
`required`	`bool`	When `True`, raise on error. When `False`, return `ServerVersion(version="Unknown")` on failure.	`False`

validate_response ¶

validate_response(response: Response) -> T

Validate a JSON response and construct the manager's type.

ServerLibrariesManager ¶

Access to server library metadata.

init ¶

__init__(client: MregClient) -> None

Initialize the manager with a client instance.

get ¶

get(*, required: bool = False) -> ServerLibraries

Fetch the server library list from the meta endpoint.

Parameters:

Name	Type	Description	Default
`required`	`bool`	When `True`, raise on error. When `False`, return `ServerLibraries(libraries=[])` on failure.	`False`

UserInfoManager ¶

Bases: GetManager[UserInfo]

Access to user information.

init ¶

__init__(client: MregClient) -> None

Initialize the manager with a client instance.

get ¶

get(
    *, required: bool = False, user: str | None = None
) -> UserInfo

Fetch user information from the meta endpoint.

Parameters:

Name	Type	Description	Default
`required`	`bool`	When `True`, raise on error. When `False`, return a zeroed-out `UserInfo` on failure.	`False`
`user`	`str \| None`	The username to fetch. If `None`, fetches the current user.	`None`

validate_response ¶

validate_response(response: Response) -> T

Validate a JSON response and construct the manager's type.

LDAPHealthManager ¶

Bases: GetManager[LDAPHealth]

Access to LDAP health status.

init ¶

__init__(client: MregClient) -> None

Initialize the manager with a client instance.

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 `True`, raise on non-503 errors.	`False`

validate_response ¶

validate_response(response: Response) -> T

Validate a JSON response and construct the manager's type.

HeartbeatHealthManager ¶

Bases: GetManager[HeartbeatHealth]

Access to heartbeat health status.

init ¶

__init__(client: MregClient) -> None

Initialize the manager with a client instance.

get ¶

get(*, required: bool = False) -> HeartbeatHealth

Fetch heartbeat health from the health endpoint.

Parameters:

Name	Type	Description	Default
`required`	`bool`	When `True`, raise on error. When `False`, return `HeartbeatHealth(uptime=-1, start_time=0)` on failure.	`False`

validate_response ¶

validate_response(response: Response) -> T

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 `True`, raises on any failure instead of returning a default object.	`False`

validate_response ¶

validate_response(response: Response) -> T

Validate a JSON response and construct the manager's type.

Base Manager Classes¶

ResourceManager ¶

Bases: Generic[T], ABC

Basic manager for performing read operations on an API resource type.

endpoint `abstractmethod` `property` ¶

endpoint: Endpoint

Return the API endpoint for this manager's resource type.

model `abstractmethod` `property` ¶

model: type[T]

The model type this manager operates on.

model_name `property` ¶

model_name: str

The canonical name of the manager's model.

init ¶

__init__(client: MregClient) -> None

Bind the manager to the client that owns it.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 `ident` exists.

count ¶

count(*, strict: bool = False) -> int

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 ¶

first(
    *,
    required: Literal[False],
    **query: str | int | float | bool | None,
) -> T | None

first(
    *,
    required: Literal[True] = ...,
    **query: str | int | float | bool | None,
) -> T

first(
    *,
    required: bool = True,
    **query: str | int | float | bool | None,
) -> T | None

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` (default), raise `EntityNotFound` if no resource exists. Pass `False` to return `None` instead.	`True`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and no resource is found.

Returns:

Type	Description
`T \| None`	The first resource found, or `None` when `required` is False.

get ¶

get(
    ident: str | int | T, *, required: Literal[False]
) -> T | None

get(
    ident: str | int | T, *, required: Literal[True] = ...
) -> T

get(
    ident: str | int | T, *, required: bool = True
) -> T | None

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` (default), raise `EntityNotFound` if missing. Pass `False` to return `T \| None` instead.	`True`

Raises:

Type	Description
`EntityNotFound`	If `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	The resource, or `None` when `required` is False.

list ¶

list(
    *,
    limit: int | None = None,
    **query: str | int | float | bool | None,
) -> list[T]

List resources, optionally filtered by query parameters.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of results to return, None means no limit. Defaults to None.	`None`
`**query`	`str \| int \| float \| bool \| None`	Optional filter parameters forwarded to the list endpoint.	`{}`

refresh ¶

refresh(obj: T) -> T

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.

delete ¶

delete(obj: int | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`T`	The ID or object reference of resource to delete.	required

NamedResourceManager ¶

Bases: WriteResourceManager[T], ABC

Extended WriteResourceManager for resources that support name-based lookups.

assert_absent ¶

assert_absent(ident: str | int) -> None

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 ¶

delete(obj: int | str | T) -> None

Delete a resource.

Parameters:

Name	Type	Description	Default
`obj`	`int \| str \| T`	The resource, ID, or name to delete.	required

get_by_name ¶

get_by_name(
    name: str, *, required: Literal[False]
) -> T | None

get_by_name(
    name: str, *, required: Literal[True] = ...
) -> T

get_by_name(
    name: str, *, required: bool = True
) -> T | None

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 `required` is True and the resource is not found.

Returns:

Type	Description
`T \| None`	T \| None: The resource object if found, else None.

list_by_name_regex ¶

list_by_name_regex(name: str) -> list[T]

Get multiple resources by a name regex.

Parameters:

Name	Type	Description	Default
`name`	`str`	The regex pattern for names to search for.	required

Returns:

Type	Description
`list[T]`	A list of resource objects.

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

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 `HistoryItem` objects.

GetManager ¶

Bases: Generic[T], ABC

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.

model `abstractmethod` `property` ¶

model: type[T]

The model type this manager operates on.

init ¶

__init__(client: MregClient) -> None

Initialize the manager with a client instance.

get `abstractmethod` ¶

get(*, required: bool = False) -> T

Get the resource from the endpoint.

validate_response ¶

validate_response(response: Response) -> T

Validate a JSON response and construct the manager's type.

Managers¶

Hosts¶

HostManager ¶

model_name property ¶

__init__ ¶

add_contacts ¶

all_ips_on_same_vlan ¶

assert_absent ¶

clear_contacts ¶

count ¶

create ¶

delete ¶

first ¶

get ¶

get_by_id ¶

get_by_ip ¶

get_by_mac ¶

get_by_name ¶

history ¶

list ¶

list_by_ip ¶

list_by_mac ¶

list_by_name_regex ¶

networks ¶

refresh ¶

remove_contacts ¶

rename ¶

update ¶

vlans ¶

HostGroupManager ¶

model_name property ¶

__init__ ¶

add_group ¶

add_host ¶

add_owner ¶

assert_absent ¶

count ¶

create ¶

delete ¶

first ¶

get ¶

get_by_name ¶

history ¶

list ¶

list_by_host ¶

list_by_name_regex ¶

list_parents ¶

refresh ¶

remove_group ¶

remove_host ¶

remove_owner ¶

rename ¶

set_description ¶

update ¶

IP addresses¶

IPAddressManager ¶

model_name property ¶

__init__ ¶

assert_absent ¶

associate_mac ¶

count ¶

create ¶

delete ¶

disassociate_mac ¶

first ¶

get ¶

list ¶

list_by_host ¶

list_by_ip ¶

list_by_mac ¶

refresh ¶

update ¶

Networks¶

NetworkManager ¶

community cached property ¶

model_name property ¶

policy cached property ¶

__init__ ¶

add_excluded_range ¶

assert_absent ¶

model_name `property` ¶

init ¶

model_name `property` ¶

init ¶

model_name `property` ¶

init ¶

community `cached` `property` ¶

model_name `property` ¶

policy `cached` `property` ¶

init ¶

attribute `cached` `property` ¶

model_name `property` ¶

init ¶

model_name `property` ¶

init ¶

model_name `property` ¶

init ¶