udm-rest-client 1.4.0

Python library to interact with the Univention UDM REST API. Implements the simple Python UDM API.

Python library to interact with the Univention UDM REST API, implements the interface of the Python UDM API.

• Free software: GNU Affero General Public License version 3

• Documentation: https://udm-rest-client.readthedocs.io

Features

• Asynchronous

• Automatic handling of HTTP(S) sessions

• Type annotations

• 100% test coverage (unittests + integration tests)

• Python 3.9, 3.10, 3.11

Usage

The UDM context 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)
...
>>> 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)
foo

There are more examples in the docs usage section.

If the SSL CA certificate is not available verify_ssl=False can be used in place of ssl_ca_cert=.... Obviously that is not safe! The CA of any UCS server can always be downloaded from http://FQDN.OF.UCS/ucs-root-ca.crt.

Installation

1. Install Python UDM REST Client via pip from PyPI:

   $ pip install udm-rest-client

   If you see a complaint about docker needing a higher version of urrlib3, upgrade:

   $ pip install --upgrade urllib3

2. Install the OpenAPI client library used by the udm-rest-client. It is created by software from the OpenAPI Generator project. 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 Java

Use --insecure to ignore SSL verification errors. See --help for more options.

Use --username and --password to 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 rerun update_openapi_client. The new UDM module will otherwise not be available in the Python UDM REST Client. Very few apps (like UCS@school and Open-Xchange) install new UDM modules. New extended attributes do not require to rebuild the OpenAPI client library.

Logging

Standard logging is used for tracking the library’s activity. To capture the log messages for this project, subscribe to a logger named udm_rest_client.

The UDM REST API on the UCS server logs into the file /var/log/univention/directory-manager-rest.log.

Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

History

1.4.0 (2026-07-08)

• Add support for specifying the OpenAPI schema via –file instead of downloading it on the fly.

1.3.2 (2026-04-07)

• Add support for aiohttp >= 3.13.4

1.3.1 (2025-02-18)

• Update docker dependency to v7.

• Drop support for python 3.6, python 3.7 and python 3.8.

1.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)

• Fix update_openapi_client crashing with newer versions of the Python Docker client and requests (Issue #10).

• Testing fixes (Issues #5 and #9)

1.2.1 (2023-02-15)

• Update OpenAPI client library generator (openapitools/openapi-generator-cli) to version 5.4.0 to 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 of users/self to 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 in CreateError and ModifyError exceptions.

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 library openapi-client-udm to 1.0.1.

1.0.7 (2022-01-18)

• Lower required version of click library, for compatibility with typer<0.4.0.

1.0.6 (2022-01-05)

• UCS 5.0 container for testing is now run using LXD.

• Fix deprecated use of ruamel.yaml in tests.

1.0.5 (2021-12-09)

• Add process wide cache for the LDAP base of each host.

1.0.4 (2021-11-15)

• Update aiohttp to (at least) Version 3.8.1, which fixes aiohttp 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. dnsEntryZoneAlias of 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 client update_openapi_client has been updated to use the OpenAPI Generator version 5.0.0.

• The update_openapi_client script now verifies the checksum of the downloaded JAR file.

1.0.0 (2021-02-03)

• Breaking API CHANGE: The options attribute of UDM objects is now a dictionary. It mirrors the UDM REST APIs options attribute 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 values

0.2.0 (2019-12-10)

• Mapping and Iterable interfaces 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 improvements

• HTTP basic passwords are no longer logged

• map options and policies back 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 build

• various small fixes to handle RTD and Travis-CI

0.1.0 (2019-11-22)

• First release.