diff --git a/README.md b/README.md index 24d525af877d8692ad16c57f479e777b2bf0f103..b3f235b9776f382a647590314202ee8ae4ca6dbe 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', ...}, ...]] ```