Skip to content
Snippets Groups Projects
Commit 344821ee authored by Dominik Rimpf's avatar Dominik Rimpf :chipmunk:
Browse files

update readme

parent 30a1eb35
No related branches found
No related tags found
No related merge requests found
Pipeline #275794 passed
# NETDB API 3.x Client Library for Python3
# NETDB API Client Library for Python
## Install
The current version of the library is 3.2 which features support for NETDB API versions 3.2 (release), 3.1 (oldrelease) and 3.0 (deprecated). If not explicitly specified the most recent supported version will be used. Examples for using an older API version are listed in section "Usage".
### 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-3.2-py3-none-any.whl?job=build`
The library can be installed from our python-registry:
```
pip install netdb-client --index-url https://gitlab.kit.edu/api/v4/groups/198806/-/packages/pypi/simple
```
The library supports the last 3 NETDB-API releases (release, oldrelease, deprecated). The version of the library is defined by the newest supported API version.
### Self-Built
`pip install git+https://git.scc.kit.edu/scc-net/netvs/netdb-client-lib.git@master`
If not explicitly specified the most recent supported version will be used. Examples for using an older API version are listed in section "Usage".
There are also development build against the NETDB-Devel-API (api.netdb-devel.scc.kit.edu).
## Usage
### Init
Initialisation works as followed, for configuration an `APIEndpoint`-Instance has to be passed to the `API-Session` call.
```python
>>> import netdb_client.api32
>>> import netdb_client.api40
>>> endpoint = netdb_client.APIEndpoint(
base_url='www-net-devel.scc.kit.edu',
token='<token>'
)
>>> api = netdb_client.api32.APISession(endpoint)
>>> api = netdb_client.api40.APISession(endpoint)
```
`util` provides an `ArgumentParser`-Class which can be used for configuration and config loading. This class has been
......@@ -36,7 +39,7 @@ Variable precendence is as followed (from greatest to least, means the first sou
>>> parser = netdb_client.util.ArgumentParser(description='Beispielbeschreibung für Skript.')
>>> args = parser.parse_args()
>>> endpoint = netdb_client.APIEndpoint(**vars(args))
>>> api = netdb_client.api32.APISession(endpoint)
>>> api = netdb_client.api40.APISession(endpoint)
```
Example help (`h` / `--help`) output:
```
......@@ -72,33 +75,33 @@ Variable precendence is as followed (from greatest to least,means the first list
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](https://git.scc.kit.edu/scc-net/netvs/netdb-client-lib/-/wikis/API-3.0---3.1-Migration-Guide).
### API 3.2 -> API 4.0
See the [API 4.0 Release Notes](https://doku.netdb.scc.kit.edu/webapi/4.0/relnotes/).
## Examples
More examples can be found in our repository [net-api-python-scripts](https://git.scc.kit.edu/scc-net/net-api-python-scripts) where we store some handy scripts for our daily work and some time-consuming tasks.
### Basic queries
List all BCDs:
```python
>>> import netdb_client.api32.nd
>>> netdb_client.api32.nd.Bcd.list(api_session=api)
>>> import netdb_client.api40.nd
>>> netdb_client.api40.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:
```python
>>> import netdb_client.api32.dns
>>> netdb_client.api32.dns.Record.list(api_session=api, type_old="CNAME", bcd_list_old=["scc-net-web-1"])
>>> import netdb_client.api40.dns
>>> netdb_client.api40.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:
```python
>>> import netdb_client.api32.nd
>>> import netdb_client.api40.nd
>>> api.execute_ta([
netdb_client.nd.api32.Bcd.list_ta(), # == {"name": "nd.bcd.list"}
{"name": "nd.ip_subnet.list", "join": {0: "default"}},
{"name": "nd.ip_subnet.list", "inner_join_ref": {0: "default"}},
])
[[{'name': 'scc-net-web-1', ...}], [{'bcd': 'scc-net-web-1', ...}, ...]]
```
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment