Package: udm-rest-client
Python UDM REST ClientPython library to interact with the UniventionUDM REST API, implements the interface of thePython UDM API.Free software: GNU Affero General Public License version 3Documentation:https://udm-rest-client.readthedocs.ioFeaturesAsynchronousAutomatic handling of HTTP(S) sessionsType annotations100% test coverage (unittests + integration tests)Python 3.6, 3.7, 3.8, 3.9, 3.10, 3.11UsageTheUDMcontext manager opens and closes a HTTP session:>>> import asyncio
>>> from udm_rest_client.udm import UDM
>>>
>>> async def get_obj(mod_name, dn):
...     async with UDM(
...         "USERNAME",
...         "PASSWORD",
...         "https://FQDN.OF.UCS/univention/udm",
...         ssl_ca_cert="ucs-root-ca.crt"
...     ) as udm:
...         mod = udm.get(mod_name)
...         return await mod.get(dn)
...
>>> # Python 3.6:
>>> loop = asyncio.get_event_loop()
>>> obj = loop.run_until_complete(get_obj("users/user", "uid=foo,cn=users,BASE-DN"))
>>>
>>> # Python 3.7+:
>>> obj = asyncio.run(get_obj("users/user", "uid=foo,cn=users,BASE-DN"))
>>>
>>> print(obj)
UdmObject('users/user', 'uid=foo,cn=users,BASE-DN')
>>> print(obj.props.username)
fooThere are more examples in thedocsusagesection.If the SSL CA certificate is not availableverify_ssl=Falsecan be used in place ofssl_ca_cert=.... Obviously that is not safe! The CA of any UCS server can always be downloaded fromhttp://FQDN.OF.UCS/ucs-root-ca.crt.InstallationInstallPython UDM REST Clientvia pip fromPyPI:$ pip install udm-rest-clientInstall the OpenAPI client library used by the udm-rest-client. It is created by software from theOpenAPI Generatorproject. You need to either have a local Java installation (Java 8+) or run the projects Docker container. The process is scripted:$ update_openapi_client --generator docker ucs.master.fqdn.or.ip  # use Docker
$ update_openapi_client --generator java ucs.master.fqdn.or.ip  # use JavaUse--insecureto ignore SSL verification errors. See--helpfor more options.Use--usernameand--passwordto provide credentials if access to your openapi.json is protected. This is the
default in newer versions of UCS and thus credentials are needed.Important:
Whenever a new UDM module is installed in the domain, it is necessary to rerunupdate_openapi_client.
The new UDM module will otherwise not be available in thePython UDM REST Client.
Very few apps (like UCS@school and Open-Xchange) install new UDM modules.
New extended attributes donotrequire to rebuild the OpenAPI client library.TestsThere are some isolated unittests, but most tests run against a real UDM REST API. Either an existing UCS installation can be used, or a LXD container started.Run tests with the current Python interpreter:$ make testUsingtoxthe tests can be executed with all supported Python versions:$ make test-allUsing the UCS LXD container is automated in theMakefile. It has commands to download and start the LXD image (1 GB) and running the tests:$ make create-lxd-test-server-config
$ make testInitializing LXD is however left up to the developer (seehttps://linuxcontainers.org/lxd/). Using storage backendlvm,btrfsorzfsis recommended for repeated use. To run the tests only once, the storage backenddiris the easiest to use. It is very slow though, as it requires unpacking the image every time the container is started.TheMakefilealso needsyqto be installed:https://github.com/mikefarah/yqIt is also possible to use an existing UCS server for the tests. ExportUCS_HOST(the servers IP/FQDN),UCS_USERDN(the DN of an administrator account, usuallyuid=Administrator,cn=users,dc=...) andUCS_PASSWORD(the accounts password), before starting the tests:$ export UCS_HOST="my.server.local"
$ export UCS_USERDN="uid=Administrator,cn=users,dc=domain,dc=local"
$ export UCS_PASSWORD="s3cr3t"
$ make testMuch more comfortable (especially for repeated use) is creating a filetest_server.yamlin thetestsdirectory, which will automatically be used by the tests:$ cp test_server_example.yaml test/test_server.yaml
$ $EDITOR test_server.yamlDon’t forget to update the OpenAPI client library before running the test against a new server:$ update_openapi_client --generator <docker|java> --username Administrator --password s3cr3t $UCS_HOSTRunupdate_openapi_client--helpto see further options.To get the IP address of the running UCS LXD container execute:$ . lxd.sh ; lxd_container_ipLoggingStandard logging is used for tracking the libraries activity.
To capture the log messages for this project, subscribe to a logger namedudm_rest_client.TheUDM REST APIon the UCS server logs into the file/var/log/univention/directory-manager-rest.log.Repo permissionsGitHub: @dansan, @SamuelYaron, @brodersen4univention, @twenzel, @botnerGitLab: UCS developersPyPI: @dansan, @SamuelYaron, @brodersen4univention, @twenzel, @botnerPyPI: @dansan, @SamuelYaron, @brodersen4univention, @twenzel, @botnerReleasesNoteThese instructions require aPyPIaccount with permissions for theudm-rest-clientpackage.Verify thedaily tests.Increment the version:
*udm_rest_client/__init__.py*setup.pyUpdateHISTORY.rstwith changelog notes.Push the package to test PyPi:makerelease-testVerify that the test version works before continuing with the next step.Push the package to production PyPi:makereleaseCreditsThis package was created withCookiecutterand theaudreyr/cookiecutter-pypackageproject template.History1.2.3 (2024-01-16)The client now handles HTTP status responses from the UDM REST API based on generic range (e.g. 2xx-3xx) instead of specific codes.1.2.2 (2023-06-05)Fixupdate_openapi_clientcrashing with newer versions of the Python Docker client andrequests(Issue #10).Testing fixes (Issues #5 and #9)1.2.1 (2023-02-15)Update OpenAPI client library generator (openapitools/openapi-generator-cli) to version5.4.0to support Python 3.11..1.1.1 (2023-01-16)Move operations succeed, when a language header is set.1.1.0 (2022-11-29)Adjust objectType return value ofusers/selfto latest UCS erratum.1.0.13 (2022-11-09)Fix error handling in base_http.py.1.0.12 (2022-11-02)Add the possibility to send an Accept-Language header with each request.1.0.11 (2022-10-19)Handle UDM REST API doing immediate moves (without redirects) for objects without subordinates.1.0.10 (2022-10-13)Pass trough UDM REST API error inCreateErrorandModifyErrorexceptions.1.0.9 (2022-09-15)Format the correlation ID as a hex value.1.0.8 (2022-09-11)Send a correlation ID with each request.Raise version of generated client libraryopenapi-client-udmto1.0.1.1.0.7 (2022-01-18)Lower required version ofclicklibrary, for compatibility withtyper<0.4.0.1.0.6 (2022-01-05)UCS 5.0 container for testing is now run using LXD.Fix deprecated use ofruamel.yamlin tests.1.0.5 (2021-12-09)Add process wide cache for the LDAP base of each host.1.0.4 (2021-11-15)Updateaiohttpto (at least) Version3.8.1, which fixesaiohttp not honoring “no_proxy”.Update development and testing dependencies.1.0.3 (2021-03-25)Fix handling of values that are lists of dicts (e.g.dnsEntryZoneAliasof computer objects).1.0.2 (2021-03-25)Fix not sending policy modifications to server.1.0.1 (2021-02-10)The script to create/update the OpenAPI clientupdate_openapi_clienthas been updated to use the OpenAPI Generator version5.0.0.Theupdate_openapi_clientscript now verifies the checksum of the downloaded JAR file.1.0.0 (2021-02-03)Breaking API CHANGE: Theoptionsattribute of UDM objects is now a dictionary. It mirrors the UDM REST APIsoptionsattribute value. Before it was a list, which did not allow to disable default options (Bug #50974).0.4.0 (2020-04-06)Add the possibility to provide credentials in the update_openapi_client script to download the schema file.0.3.1 (2020-03-19)Update download URL of openapi-generator jar.0.3.0 (2020-03-18)allow setting properties that only exist after enabling an option (Bug #50972)0.2.1 (2019-12-14)fix not detecting changes in mutable property values0.2.0 (2019-12-10)MappingandIterableinterfaces were added to the object properties class. Adds item access (obj.props["key"]),obj.props.get("key"),len(obj.props),key in obj.props,obj.props.keys(),obj.props.values(),obj.props.items()documentation improvementsHTTP basic passwords are no longer loggedmapoptionsandpoliciesback to original values (were being rewritten to pep8 conform keys by the OpenAPI client)0.1.1 (2019-11-25)allow specifying existing JAR for open api client buildvarious small fixes to handle RTD and Travis-CI0.1.0 (2019-11-22)First release.