From 344821eee83be5ecc29ace6246d704e776f9bb07 Mon Sep 17 00:00:00 2001
From: Dominik Rimpf <dominik.rimpf@kit.edu>
Date: Mon, 18 Mar 2024 17:45:18 +0000
Subject: [PATCH] update readme
---
README.md | 37 ++++++++++++++++++++-----------------
1 file changed, 20 insertions(+), 17 deletions(-)
diff --git a/README.md b/README.md
index 24d525a..b3f235b 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,29 @@
-# 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', ...}, ...]]
```
--
GitLab