NbForager

class nbforager.NbForager(host: str, token: str = '', scheme: str = 'https', port: int = 0, verify: bool = True, limit: int = 1000, url_length: int = 2047, threads: int = 1, interval: float = 0.0, timeout: int = 60, max_retries: int = 0, sleep: int = 10, strict: bool = False, extended_get: bool = True, loners: Dict[str, List[str]] | None = None, cache: str = '', **kwargs)

Forages data from Netbox for further processing.

  • Request data from Netbox (using NbApi) and save it in the NbForager.root object,

  • Assemble objects within itself as a multidimensional dictionary in NbForager.tree object,

  • Read/write objects from/to the cache pickle file,

Initialize NbForager.

Parameters:

cache – Path to cache. If the value ends with .pickle, it is the path to a file; otherwise, it is the path to a directory. The default value is NbCache.{host}.pickle.

NbApi parameters:

Parameters:

  • host (str) – Netbox host name.

  • token (str) – Netbox token.

  • scheme (str) – Access method: https or http. Default is https.

  • port (int) – TCP port. Default is 443 for scheme=`https`, 80 for scheme=`http`.

  • verify (bool) – Transport Layer Security. True - A TLS certificate is required, False - Requests will accept any TLS certificate. Default is True.

  • limit (int) – Split the query to multiple requests if the count of objects exceeds this value. Default is 1000.

  • url_length (int) – Split the query to multiple requests if the URL length exceeds maximum length due to a long list of GET parameters. Default is 2047.

  • threads (int) – Threads count. <=1 is loop mode, >=2 is threading mode. Default is 1.

  • interval (float) – Wait this time between the threading requests (seconds). Default is 0. Useful to optimize session spikes and achieve script stability in Docker with limited resources.

  • timeout (int) – Session timeout (seconds). Default is 60.

  • max_retries (int) – Retries the request multiple times if the Netbox API does not respond or responds with a timeout. Default is 0. This is useful for scheduled scripts in cron jobs, when the connection to Netbox server is not stable.

  • sleep (int) – Interval (seconds) before the next retry after session timeout reached. Default is 10.

  • strict (bool) – When querying objects by tag, if there are no tags present, the Netbox API response returns a status_code=400. True - HTTPError is raised when status_code=400. False - WARNING message is logged and an empty list is returned with status_code=200. Default is False.

  • extended_get (bool) – True - Extend filtering parameters in GET request, {parameter} can be used instead of {parameter}_id. Default is True.

  • loners (dict) – Set Filtering parameters in an OR manner.

Data attributes:

Variables:

  • root (obj) – NbTree object that holds raw Netbox objects. It is data source for the tree.

  • tree (obj) – NbTree object that holds joined Netbox objects.

  • status (dict) – Result from Netbox status endpoint. Netbox version.

Application/model foragers:

Variables:
clear(root: bool = True, tree: bool = True) → None

Clear objects by resetting the NbForager.root and NbForager.tree.

Parameters:

  • root – If True, clear data in NbForager.root.

  • tree – If True, reset NbForager.tree.

Returns:

None. Update self object.

copy() → NbForager

Copy data in the NbForager.root and NbForager.tree.

Returns:

Copy of NbForager object.

Return type:

NbForager

count() → int

Count of the Netbox objects in the NbForager.root object.

Returns:

Count of the Netbox objects.

Return type:

int

get_status() → None

Retrieve status from the Netbox, save data to the NbForager.status.

Returns:

None. Update self object.

join_tree(dcim: bool = False, ipam: bool = False, ipam_prefixes: bool = False) → None

Assemble Netbox objects in NbForager.tree within itself.

The Netbox objects are represented as a multidimensional dictionary. Join objects that are present in the API response.

Parameters:

  • dcim –

    True - Create additional keys to represent Netbox dcim objects.

    In dcim.devices, virtualization.virtual_machines:

    • _console_ports

    • _console_server_ports

    • _device_bays

    • _front_ports

    • _interfaces

    • _inventory_items

    • _module_bays

    • _power_outlets

    • _power_ports

    • _rear_ports

    • _vc_members

    In dcim.interfaces, virtualization.interfaces:

    • _ip_addresses

  • ipam –

    True - Create additional keys to represent Netbox ipam objects.

    In ipam.aggregate, ipam.prefixes, ipam.ip_addresses:

    • _ipv4 IPv4 object

    • _aggregate Aggregate data for ipam.prefixes and ipam.ip_addresses

    • _super_prefix Related parent prefix data for ipam.prefixes and ipam.ip_addresses

    • _sub_prefixes Related child prefixes data for ipam.prefixes and ipam.ip_addresses

    • _ip_addresses Related IP addresses data for ipam.aggregates and ipam.prefixes

  • ipam_prefixes – True - Join only ipam/prefixes, skip ipam/ip-addresses.

Returns:

None. Update NbForager.tree with the joined Netbox objects.

read_cache() → None

Read cached data from a pickle file.

Save data to the NbForager.root and NbForager.status.

Returns:

None. Update self object.

version() → str

Get Netbox version from the NbForager.status.

Before getting the version, you need to update the NbForager.status by using the get_status() or read_cache() method.

Returns:

Netbox version if version >= 3, otherwise an empty string.

write_cache() → None

Write NbForager.root and NbForager.status to a pickle file.

Returns:

None. Update a pickle file.

Forager methods

class nbforager.foragers.forager.Forager(forager_a)

Base for Foragers.

count() → int

Count Netbox objects in NbForager.root.{model}.

Returns:

Count of the Netbox objects.

Return type:

int

find_root(**kwargs) → List[Dict[str, Any]]

Find Netbox objects in NbForager.root by extended finding parameters.

Parameters:

kwargs – Extended filtering parameters. Different parameters work like an AND operator. Different values of the same parameter work like an OR operator. Parameters with double underscores __ will be split into a list of keys.

Returns:

Filtered Netbox objects.

find_rse(role: str = '', site: str = '', env: str = '', **kwargs) → List[Dict[str, Any]]

Find Netbox objects in NbForager.tree by Role-Site-Env finding parameters.

This method used in a specific project to simplify prefixes search.

Parameters:

  • role – ipam/role/slug value.

  • site – ipam/site/slug value.

  • env – custom_fields/env value.

  • kwargs – Role-Site-Env filtering parameters.

Returns:

Filtered Netbox objects.

find_tree(**kwargs) → List[Dict[str, Any]]

Find Netbox objects in NbForager.tree by extended finding parameters.

Parameters:

kwargs – Extended filtering parameters. Different parameters work like an AND operator. Different values of the same parameter work like an OR operator. Parameters with double underscores __ will be split into a list of keys.

Returns:

Filtered Netbox objects.

get(nested: bool = False, **kwargs) → None

Retrieve data from Netbox API.

Request data based on the filter parameters (kwargs described in the NbApi connector) and save to the NbForager.root.

Parameters:

  • nested (bool) – True - Request base and nested objects, False - Request only base objects. Default is False

  • kwargs – Filtering parameters.

Returns:

None. Update self root data in related app/model.

graphql(fields: str, filters: str = '') → None

Request data from Netbox GraphQL API.

Parameters:

  • fields – Fields to include in the query, e.g. id name tenant { id name }.

  • filters – Parameters to filter Netbox objects, e.g. { status: STATUS_ACTIVE, name: {exact: "SITE1"}}.

Returns:

None. Update self root data in related app/model.