Skip to content

PYPI_README.rst

Latest commit

 

History

History
115 lines (86 loc) · 4.56 KB

PYPI_README.rst

File metadata and controls

115 lines (86 loc) · 4.56 KB

Python UDM REST Client

Python 3.9+ GNU AGPL V3 license Code style: black Code coverage Documentation Status

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

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.