Package: kelvin-rest-api-client
Python UCS@school Kelvin REST API ClientPython library to interact with theUCS@school Kelvin REST API.Free software: GNU Affero General Public License version 3Documentation:https://kelvin-rest-api-client.readthedocs.ioFeaturesAsynchronousAutomatic handling of HTTP(S) sessionsType annotations~95% test coverage (unittests + integration tests)Python 3.7, 3.8, 3.9, 3.10CompatibilityA list of UCS@school Kelvin REST API server versions which introduce breaking changes can be found in the [UCS@school Kelvin REST API Documentation](https://docs.software-univention.de/ucsschool-kelvin-rest-api/kelvin-client-compatibility.html).UsageTheSessioncontext manager opens and closes a HTTP session:>>>importasyncio>>>fromucsschool.kelvin.clientimportSession,User,UserResource>>>>>>asyncdefget_user(username:str)->User:...asyncwithSession(..."USERNAME",..."PASSWORD",..."master.ucs.local",...verify="ucs-root-ca.crt"...)assession:...returnawaitUserResource(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)TestUserThere are more examples in thedocsusagesection.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 availableverify=False.
Obviously that isnot safe! The CA of any UCS server can always be downloaded fromhttp://FQDN.OF.UCS/ucs-root-ca.crt.InstallationInstallUCS@school Kelvin REST API Clientvia pip fromPyPI:$pipinstallkelvin-rest-api-clientTestsThere are some isolated unittests, but most tests run against a realUCS@school Kelvin REST API.
A UCS Docker container has been prepared for this (additionally to the Kelvin API Docker container).
TheMakefileautomates 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.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 areDEMOSCHOOLandDEMOSCHOOL2.
The first one usually already exists, but trying to create it again is safe.
To create the schools runon the UCS DC Master:$/usr/share/ucs-school-import/scripts/create_ouDEMOSCHOOL$/usr/share/ucs-school-import/scripts/create_ouDEMOSCHOOL2Furthermore an email domain must exist:$udmmail/domaincreate\--ignore_exists\--position"cn=domain,cn=mail,$(ucrgetldap/base)"\--setname="$(ucrgetdomainname)"Since version1.5.0the Kelvin REST API supports UDM properties in all resources. A configuration is required for the tests for this feature:$cat>/etc/ucsschool/kelvin/mapped_udm_properties.json<<__EOF__{
    "user": ["title"],
    "school_class": ["mailAddress"],
    "school": ["description"]
}
__EOF__The provided UCS Docker containers already contain both OUs.
They can be started using the Makefile:$makestart-docker-containersDownloading Docker image '..-ucsschool-udm-rest-api-only:stable-4.4-8'...
Downloading Docker image '../ucsschool-kelvin-rest-api:1.5.5'...
Starting UCS docker container...
Waiting for UCS docker container to start...
Waiting for IP address of UCS container...
Waiting for UDM REST API...........
Creating Kelvin REST API container...
Configuring Kelvin REST API container...
Rebuilding the OpenAPI client library in the Kelvin API Container...
Starting Kelvin REST API server...
Waiting for Kelvin docker container to start...
Waiting for IP address of Kelvin container...
Waiting for Kelvin API...
Fixing log file permissions...
Setting up reverse proxy...
==> UDM REST API log file: /tmp/udm-rest-api-log/directory-manager-rest.log
==> UDM REST API: http://172.17.0.2/univention/udm/
==> Kelvin API configs: /tmp/kelvin-api/configs/
==> Kelvin API hooks: /tmp/kelvin-api/kelvin-hooks/
==> Kelvin API log file: /tmp/kelvin-api/log/http.log
==> Kelvin API: http://172.17.0.3:8911/ucsschool/kelvin/v1/docs
==> Kelvin API: https://172.17.0.2/ucsschool/kelvin/v1/docsThe Docker containers can be stopped and removed by running:$makestop-and-remove-docker-containersThe Docker images will not be removed, only the running containers.Run tests with current Python interpreter:$maketestUsingtoxthe tests can be executed with all supported Python versions:$maketest-allTo use an existing UCS server for the tests, copy the filetests/test_server_example.yamltotests/test_server.yamland adapt the settings before starting the tests:$cptests/test_server_example.yamltests/test_server.yaml$$EDITORtests/test_server.yaml#checksettingswithasingletest:$python-mpytesttests/test_user.py::test_get#ifOK,runalltests:$maketestLoggingStandard logging is used for tracking the libraries activity.
To capture the log messages for this project, subscribe to a logger nameducsschool.kelvin.client.Attention:Passwords and session tokens will be logged at log levelDEBUG!TheUCS@school Kelvin REST APIon the UCS server logs into the file/var/log/univention/ucsschool-kelvin-rest-api/http.log.
TheUDM REST APIon the UCS server logs into the file/var/log/univention/directory-manager-rest.log.Repo permissionsGithub: @dansan and @JuergenBSGitlab: @JuergenBSPyPI: @dansan and @SamuelYaronRTD: @dansan and @SamuelYaronCreditsHistory2.2.3 (2023-06-22)%xxescaped names of school classes, users and workgroups are now unescaped.2.2.2 (2023-04-14)Support HEAD forSchoolClass,User,WorkGroup, andRole.2.2.1 (2022-12-15)Use deepcopy into_dictmethod to prevent values ofudm_propertiesfrom being updated in objects which are copied.2.2.0 (2022-10-13)Support HttpAccept-LanguageHeader.2.1.0 (2022-10-07)Support HEAD forSchool.2.0.1 (2022-10-05)Use detailed upstream error message inInvalidRequestexception messages.2.0.0 (2022-09-10)API Change: The required argumentschoolin theUserconstructor has now the default argumentNone. The argumentnameis not required anymore. Optional values, which are set toNone, are not passed to the Kelvin server anymore. This enables automatic value generation on the Kelvin REST API server. To make use of this, the attributes can be either set toNone, the empty string""or left out completely. Additionally, you have to create a schema for the corresponding attribute on the Kelvin REST API server.Send a correlation ID with each request.1.7.1 (2022-08-30)Loosen dependency constraints.1.7.0 (2022-07-07)Support userworkgroupsattribute.1.6.1 (2022-06-30)Ignore unknown attributes in KelvinObject child classes.1.6.0 (2022-06-27)Add support for workgroup resource.1.5.2.1 (2022-04-05)Fixed: Logger does replace values of credentials with placeholders.1.5.2 (2022-02-22)Automatic tests now run with Python 3.7 - 3.10.Fixed: The timeout attribute from a session instance is now used for requests.1.5.1 (2021-11-30)Add attributeexpiration_dateto theUserclass. The attribute was added to the Kelvin REST API app in version1.5.1.1.5.0 (2021-09-21)Add attributeudm_propertiesto classesSchoolandSchoolClass.  The attributes were added to the Kelvin REST API app in version1.5.0.0.3.0 (2021-05-04)Add support for the creation of school (OU) objects.0.2.2 (2020-11-09)Add support for thekelvin_password_hashesattribute of theUserclass.0.2.1 (2020-08-07)fix JWT token validity calculation: timestamp uses UTCdocumentation fixesdependency updatestests also run on Python 3.9-dev0.2.0 (2020-04-17)move tox to test requirementsfix user object creation with default parameterschangeas_dictto be a method instead of a propertyfix flaky testsimprove test coveragepass more env args to toxfix AttributeError with repr(role)add complete usage documentation0.1.0 (2020-04-16)First release.