NETDB API 3.x Client Library for Python3
Changes in netdb_client 2.x
From version 2.0 onwards the config option version has been dropped. This is because the API Library is built against a specific WebAPI Version and is not cross-compatible with different WebAPI versions.
The existing config files can still be used, but the config option will be ignored.
Install
Pre-Built (updated every night)
pip install https://git.scc.kit.edu/scc-net/netvs/netdb-client-lib/-/jobs/artifacts/master/raw/dist/netdb_client-2.0-py3-none-any.whl?job=build
Self-Built
pip install git+https://git.scc.kit.edu/scc-net/netvs/netdb-client-lib.git@master
Usage
Init
Initialisation works as followed, for configuration an APIEndpoint-Instance has to be passed to the API-Session call.
>>> import netdb_client
>>> import netdb_client.util
>>> endpoint = netdb_client.APIEndpoint(
base_url='www-net-devel.scc.kit.edu',
version='3.0',
token='<token>'
)
>>> api = netdb_client.APISession(endpoint)util provides an ArgumentParser-Class which can be used for configuration and config loading. This class has been
implemented transparent, so you can extend the arguments or functionality as needed by your application or script.
The functionality has been extended, so the parse_args() method checks for environment variables and an config file in "ini"-format.
Variable precendence is as followed (from greatest to least, means the first source overwrites all other):
- cli-arguments
- environment variables
- config-file (default path:
~/.config/netdb_client.ini)
>>> import netdb_client.util
>>> parser = netdb_client.util.ArgumentParser(description='Beispielbeschreibung für Skript.')
>>> args = parser.parse_args()
>>> endpoint = netdb_client.APIEndpoint(**vars(args))
>>> api = netdb_client.APISession(endpoint)Example help (h / --help) output:
usage: test.py [-h] [--auth-config AUTH_CONFIG] [--endpoint ENDPOINT] [--base-url BASE_URL] [--version VERSION] [--token TOKEN]
Argument Parser for netdb_client
optional arguments:
-h, --help show this help message and exit
--auth-config AUTH_CONFIG
config file path (default: /Users/dominik/.config/netdb_client.ini)
--endpoint ENDPOINT, -e ENDPOINT
endpoint to use.
Environment: "NETDB_ENDPOINT"
Config: [DEFAULT]: endpoint
--base-url BASE_URL, -b BASE_URL
webapi server.
Environment: "NETDB_BASE_URL"
Config: [$endpoint]: base_url
--version VERSION webapi version.
Environment: "NETDB_VERSION"
Config: [$endpoint]: version
--token TOKEN, -t TOKEN
user API token.
Environment: "NETDB_TOKEN"
Config: [$endpoint]: token
The Variables BASE_URL, VERSION and TOKEN can be loaded from config file,environment or from command line arguments.
Variable precendence is as followed (from greatest to least,means the first listed variable overwrites all other variables):
1. cli-arguments
2. environment variables
3. config-fileConfig file
An example config can be found in this repo (example_config.ini). Be aware to set the file mode of the config at least to 0600 but never other-readable.
Migration
API 3.0 -> API 3.1
See the API 3.0 -> API 3.1 wiki article.
Examples
More examples can be found in the wiki article
Basic queries
List all BCDs:
>>> import netdb_client.nd
>>> netdb_client.nd.Bcd.list(api_session=api)
[Bcd(name='scc-net-web-1', categ='USER', is_own=True, log_pk=13270200, seclvl=0, vlan_count=1, description='[scc-net-web/1]: Webserver von SCC-NET / [ipv6-scc-net-web/1]: Webserver von SCC-NET *** ehemalige Bereichsinfo ***: [scc-net-web/1]: Webserver von SCC-NET / [ipv6-scc-net-web/1]: Webserver von SCC-NET', dhcp_enabled=False, subnet_count=2, ou_short_name='SCC-NET', dhcp_ttl_value=600, admin_description=None, dhcp_accept_new_leases=False, dhcp_leasetime_dyn_days=0, dhcp_leasetime_dyn_hours=2, dhcp_leasetime_dyn_minutes=0, dhcp_leasetime_static_days=0, dhcp_leasetime_static_hours=6, dhcp_offer_rsv_time_minutes=0, dhcp_offer_rsv_time_seconds=30, dhcp_leasetime_static_minutes=0, dhcp_accept_requested_hostname=True)]List all CNAME-Records for given BCD:
>>> import netdb_client.dns
>>> netdb_client.dns.Record.list(api_session=api, type_old="CNAME", bcd_list_old=["scc-net-web-1"])
[..., Record(ttl=None, data='net-web09.scc.kit.edu.', fqdn='netvs-devel.scc.kit.edu.', type='CNAME', zone='kit.edu.', is_own=True, fqdn_type='alias', host_is_nws=False, target_fqdn='net-web09.scc.kit.edu.', target_ipaddr=None, ttl_reset_date=None, fqdn_description=None, target_fqdn_type='host', ttl_zone_default=3600, target_data_unref=None, target_is_singleton=True, target_is_reverse_unique=False), ...]Advanced queries
List BCDs with their Subnets:
>>> netdb_client.nd
>>> api.execute_ta([
netdb_client.nd.Bcd.list_ta(), # == {"name": "nd.bcd.list"}
{"name": "nd.ip_subnet.list", "join": {0: "api_fkey_nd_ip_subnet_bcd"}},
])
[[{'name': 'scc-net-web-1', ...}], [{'bcd': 'scc-net-web-1', ...}, ...]]