Features

• Asynchronous

• Automatic handling of HTTP(S) sessions

• Type annotations

• ~95% test coverage (unittests + integration tests)

• Python 3.7, 3.8, 3.9, 3.10

Compatibility

A list of UCS@school Kelvin REST API server versions which introduce breaking changes can be found in the UCS@school Kelvin REST API Documentation.

Usage

The Session context manager opens and closes a HTTP session:

>>> import asyncio
>>> from ucsschool.kelvin.client import Session, User, UserResource
>>>
>>> async def get_user(username: str) -> User:
...     async with Session(
...         "USERNAME",
...         "PASSWORD",
...         "master.ucs.local",
...         verify="ucs-root-ca.crt"
...     ) as session:
...         return await UserResource(session=session).get(name=username)
...
>>> obj = asyncio.run(get_user("demo_student"))
>>>
>>> print(obj)
User('name'='test_user', dn='uid=test_user,cn=schueler,cn=users,ou=DEMOSCHOOL,dc=example,dc=com')
>>> print(obj.firstname, obj.lastname)
Test User

There are more examples in the docs usage section.

For HTTPS to work, the SSL CA of the target system (UCS Master) must either be publicly signed, installed on the client system or available as file (as in the example above). If the SSL CA certificate is not available verify=False. 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

Install UCS@school Kelvin REST API Client via pip from PyPI:

$ pip install kelvin-rest-api-client

Tests

$ uv sync --extra test

$ /usr/share/ucs-school-import/scripts/create_ou DEMOSCHOOL
$ /usr/share/ucs-school-import/scripts/create_ou DEMOSCHOOL2

$ udm mail/domain create \
    --ignore_exists \
    --position "cn=domain,cn=mail,$(ucr get ldap/base)" \
    --set name="$(ucr get domainname)"

$ cat > /etc/ucsschool/kelvin/mapped_udm_properties.json <<__EOF__
{
    "user": ["title"],
    "school_class": ["mailAddress"],
    "school": ["description"]
}
__EOF__

$ cp tests/test_server_example.yaml tests/test_server.yaml
$ $EDITOR tests/test_server.yaml
# check settings with a single test:
$ uv run python -m pytest tests/test_user.py::test_get

$ make test

$ make test-all

Logging

Standard logging is used for tracking the libraries activity. To capture the log messages for this project, subscribe to a logger named ucsschool.kelvin.client. Attention: Passwords and session tokens will be logged at log level DEBUG!

The UCS@school Kelvin REST API on the UCS server logs into the file /var/log/univention/ucsschool-kelvin-rest-api/http.log. The UDM REST API on the UCS server logs into the file /var/log/univention/directory-manager-rest.log.

Release

- [ ] Check and update contents of [HISTORY.rst](./HISTORY.rst>)
- [ ] Check and update contents of [VERSION.txt](./VERSION.txt>)
- [ ] Kelvin client [Jenkins test](https://univention-dist-jenkins.k8s.knut.univention.de/job/UCSschool-5.0/view/Daily%20Tests/job/Kelvin-client-daily>) OK
- [ ] Tag commit in gitlab
- [ ] Run `make dist`
- [ ] Run `make docs`
- [ ] Run `make release-test` and verify the installation # uv auth login test.pypi.org/legacy
- [ ] Run `make release` and verify the installation # uv auth login upload.pypi.org
- [ ] Verify packages on https://pypi.org/
- [ ] Release mail & chat announcement

Repo permissions

• Github: @dansan and @JuergenBS

• Gitlab: @JuergenBS

• PyPI: @dansan and @SamuelYaron

• RTD: @dansan and @SamuelYaron

Credits