udm-rest-api-client 0.0.2

Description:

udmrestapiclient 0.0.2

UDM REST API Client





Client library and CLI to interact with the Univention Directory Manager (UDM) REST API.
Features

Asynchronous and synchronous Python functions
Command line interface
Automatic handling of HTTP(S) sessions
Type annotations
Python 3.7+

Usage
Synchronous Python code
from univention.admin.rest.client import UDM

udm = UDM.http("https://10.20.30.40/univention/udm/", "Administrator", "s3cr3t")
module = udm.get("users/user")

# 1. create a user
obj = module.new()
obj.properties["username"] = "foo"
obj.properties["password"] = "univention"
obj.properties["lastname"] = "foo"
obj.save()

# 2. search for users
for result in module.search("uid=*"):
obj = result.open()
print(obj)
print(obj.properties)
print(obj.objects.groups)

# 3. get by dn
ldap_base = udm.get_ldap_base()
obj = module.get(f"uid=foo,cn=users,{ldap_base}")

# 4. get referenced objects e.g. groups
pg = obj.objects["primaryGroup"].open()
print(pg.dn, pg.properties)
print(obj.objects["groups"])

# 5. modify
obj.properties["description"] = "foo"
obj.save()

# 6. move to the ldap base
obj.move(ldap_base)

# 7. remove
obj.delete()

Asynchronous Python code
import asyncio
from univention.admin.rest.async_client import UDM

async def main():
async with UDM.http("http://10.20.30.40./univention/udm/", "Administrator", "s3cr3t") as udm:
module = await udm.get("users/user")

# 1. create a user
obj = await module.new()
obj.properties["username"] = "foo"
obj.properties["password"] = "univention"
obj.properties["lastname"] = "foo"
await obj.save()

# 2. search for users
async for result in module.search("uid=*"):
obj = await result.open()
print(obj)
print(obj.properties)
print(obj.objects.groups)

# 3. get by dn
ldap_base = await udm.get_ldap_base()
obj = await module.get(f"uid=foo,cn=users,{ldap_base}")

# 4. get referenced objects e.g. groups
pg = await obj.objects["primaryGroup"].open()
print(pg.dn, pg.properties)
print(obj.objects["groups"])

# 5. modify
obj.properties["description"] = "foo"
await obj.save()

# 6. move to the ldap base
await obj.move(ldap_base)

# 7. remove
await obj.delete()

asyncio.run(main())

Command line interface
PASS_FILE="$HOME/pw-$(date +%Y%m%d%H%M%S)"
echo "s3cr3t" > "$PASS_FILE"

udm \
--username Administrator \
--bindpwdfile "$PASS_FILE" \
--uri http://10.20.30.40/univention/udm/ \
users/user list \
--filter uid=Administrator

rm -f "$PASS_FILE"

Instead of using udm, the CLI can also be called using python3 -m univention.admin.rest.client.
Error codes
Error codes and other details of the UDM REST API can be found in its documentation.
Installation
The dependencies for the CLI, synchronous and asynchronous clients differ.
They are available separately as "extra" dependencies, to reduce your projects total dependencies.
Without installing the "extra" requirements, only the common dependencies of the three interfaces will be installed, and none will be usable.

async: installs aiohttp
sync: installs requests
cli: installs python-ldap and requests

To install the library including the dependencies for the synchronous client via pip from PyPI run:
pip install udm-rest-api-client[sync]

To install the library including the dependencies for the asynchronous client via pip from PyPI run:
pip install udm-rest-api-client[async]

To install the CLI (incl. the required library and its dependencies):
pip install udm-rest-api-client[cli]

Multiple extras can be specified at the same time:
pip install udm-rest-api-client[async,cli,dev,sync]

CLI and pipx
If you wish to use the udm command line interface from anywhere in your system,
without having to manually handle virtual environments,
install it using pipx:
pipx install udm-rest-api-client[cli]

which udm
$HOME/.local/bin/udm

Building and publishing
There is a Makefile that offers all required commands.
A help text is available, when started without arguments:
$ make

clean remove all build and Python artifacts
clean-build remove build artifacts
clean-pyc remove Python file artifacts
build builds source and wheel package
publish package and upload a release to pypi
publish-test package and upload a release to the pypi test site
install-hatch install 'hatch' using 'pipx'

The build system uses hatch.
To install it, run make install-hatch.
Then execute make publish-test to build and publish the client to https://test.pypi.org/project/udm-rest-api-client/ or make publish to publish to https://pypi.org/project/udm-rest-api-client/ .
License
The UDM REST API Client is distributed under the terms of the GNU Affero General Public License v3.0 only (AGPLv3) license.
Changelog
udm-rest-api-client (0.0.2) unstable; urgency=medium

Initial release. (Bug #57204)
Split from univention-directory-manager-rest (10.0.8-5 / 12.0.7)

... see here for earlier changes.