Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/univention/kelvin-rest-api-client

Python library to interact with the UCS@school Kelvin REST API.
https://github.com/univention/kelvin-rest-api-client

api-client httpx python rest-client ucs univention univention-corporate-server

Last synced: 2 months ago
JSON representation

Python library to interact with the UCS@school Kelvin REST API.

Awesome Lists containing this project

README 

          
=========================================

Python UCS\@school Kelvin REST API Client

=========================================



|python| |license| |ruff| |docspassing|



Python library to interact with the `UCS\@school Kelvin REST API`_.



* Free software: GNU Affero General Public License version 3

* Documentation: https://kelvin-rest-api-client.readthedocs.io



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:



.. code-block:: python



    >>> 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`_:



.. code-block:: console



    $ pip install kelvin-rest-api-client



Tests

-----



Development internal tests

==========================



The `Kelvin-client-daily `_-job, an integration test for the Kelvin client, is run and daily with the newest UCS.

The job takes around 10 minutes to run and can be configured to run with a feature branch and a Kelvin Rest Api version of your choice.

This is the recommended way to run the full integration test suite.



Local Tests

===========



There are some isolated unittests, but most tests run against a real *UCS\@school Kelvin REST API*.

A UCS 4.4 Docker container has been prepared for this (additionally to the Kelvin API Docker container).

The ``Makefile`` automates downloading and starting the Docker containers (3.2 GB GB) and running the tests.

It is also possible to use an existing UCS DC Master with UCS\@school and the Kelvin API installed.



Install the dependencies for testing in your python virtual environment:



.. code-block:: console



    $ uv sync --extra test



The tests expect the existence of two schools (``OUs``) on the target system (the Kelvin API does not support creation of schools yet).

The schools are ``DEMOSCHOOL`` and ``DEMOSCHOOL2``.

The first one usually already exists, but trying to create it again is safe.

To create the schools run *on the UCS DC Master*:



.. code-block:: console



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

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



Furthermore an email domain must exist:



.. code-block:: console



    $ udm mail/domain create \

        --ignore_exists \

        --position "cn=domain,cn=mail,$(ucr get ldap/base)" \

        --set name="$(ucr get domainname)"



Since version ``1.5.0`` the Kelvin REST API supports UDM properties in all resources. A configuration is required for the tests for this feature:



.. code-block:: console



    $ cat > /etc/ucsschool/kelvin/mapped_udm_properties.json <<__EOF__

    {

        "user": ["title"],

        "school_class": ["mailAddress"],

        "school": ["description"]

    }

    __EOF__



To use an existing UCS server for the tests, copy the file ``tests/test_server_example.yaml`` to ``tests/test_server.yaml`` and adapt the settings before starting the tests:



.. code-block:: console



    $ 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



Run tests with current Python interpreter:



.. code-block:: console



    $ make test



Using `tox`_ the tests can be executed with all supported Python versions:



.. code-block:: console



    $ 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

-------



.. code-block:: markdown



        - [ ] 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

        - [ ] Run `make release` and verify the installation

        - [ ] 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

-------



.. _`UCS\@school Kelvin REST API`: https://docs.software-univention.de/ucsschool-kelvin-rest-api/

.. _`tox`: http://tox.readthedocs.org/

.. _`docs`: https://kelvin-rest-api-client.readthedocs.io

.. _`PyPI`: https://pypi.org/project/kelvin-rest-api-client/

.. |license| image:: https://img.shields.io/badge/License-AGPL%20v3-orange.svg

    :alt: GNU AGPL V3 license

    :target: https://www.gnu.org/licenses/agpl-3.0

.. |python| image:: https://img.shields.io/badge/python-3.7+-blue.svg

    :alt: Python 3.7+

    :target: https://www.python.org/

.. |docspassing| image:: https://readthedocs.org/projects/kelvin-rest-api-client/badge/?version=latest

    :alt: Documentation Status

    :target: https://kelvin-rest-api-client.readthedocs.io/en/latest/?badge=latest

.. |travisci| image:: https://travis-ci.com/univention/kelvin-rest-api-client.svg?branch=master

    :target: https://app.travis-ci.com/github/univention/kelvin-rest-api-client

.. |ruff| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v0.json

   :target: https://github.com/charliermarsh/ruff