Python library to interact with the UCS@school Kelvin REST API.
Project description
Python UCS@school Kelvin REST API Client
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
90% test coverage (unittests + integration tests)
Python 3.7, 3.8, 3.9
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
There are some isolated unittests, but most tests run against a real UCS@school Kelvin REST API. .. A UCS Docker container is used for this. The Makefile automates downloading and starting the Docker container (1 GB) and running the tests.
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 will is safe. To create the schools run on the system with the Kelvin API:
$ /usr/share/ucs-school-import/scripts/create_ou DEMOSCHOOL $ /usr/share/ucs-school-import/scripts/create_ou DEMOSCHOOL2
Run tests with current Python interpreter:
$ make test
Using tox the tests can be executed with all supported Python versions:
$ make test-all
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:
$ cp tests/test_server_example.yaml tests/test_server.yaml $ $EDITOR tests/test_server.yaml # check settings with a single test: $ python -m pytest tests/test_user.py::test_get # if OK, run all tests: $ make test
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.
Repo permissions
Github: @dansan and @JuergenBS
Gitlab: @JuergenBS
PyPI: @dansan and @SamuelYaron
RTD: @dansan and @SamuelYaron
Credits
History
0.2.0 (2020-04-17)
move tox to test requirements
fix user object creation with default parameters
change ‘as_dict’ to be a method instead of a property
fix flaky tests
improve test coverage
pass more env args to tox
fix AttributeError with repr(role)
add complete usage documentation
0.1.0 (2020-04-16)
First release.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for kelvin-rest-api-client-0.2.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | bdb7742cd277bc743e084f427cc39703f0299b6c7fc0a8cedd8352d5f17d9a09 |
|
MD5 | f8544805a70fe48cb06ffa9f75e6ccba |
|
BLAKE2b-256 | c460cbdd564051bb4c2bb140d4743e628830218d3ba4b7dca58cdf5d01cf6599 |
Hashes for kelvin_rest_api_client-0.2.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2966c04b1e9e0c15410e62949d3f0764a64740334a7e6996be547c41955012a2 |
|
MD5 | d7b52783a8a735d96d555447d0854751 |
|
BLAKE2b-256 | edef1dc47bdbfb1f7cc800f147ea7ebc299637e5509fffd15d7a808e9d8b3770 |