Metadata-Version: 2.1
Name: udm-rest-client
Version: 1.3.1
Summary: Python library to interact with the Univention UDM REST API. Implements the simple Python UDM API.
Home-page: https://github.com/univention/python-udm-rest-api-client
Author: Daniel Troeder
Author-email: troeder@univention.de
License: GNU Affero General Public License v3
Keywords: Univention UCS UDM REST
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Systems Administration :: Authentication/Directory :: LDAP
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: aiohttp<4,>=3.8.1
Requires-Dist: async-property<0.3,>=0.2.1
Requires-Dist: click<9,>=7
Requires-Dist: docker<8,>=7.1
Requires-Dist: requests<3,>=2.26

######################
Python UDM REST Client
######################

|python| |license| |code style| |codecov| |docspassing|

Python library to interact with the Univention `UDM REST API`_,
implements the interface of the `Python UDM API`_.

* Free software: GNU Affero General Public License version 3
* Documentation: https://udm-rest-client.readthedocs.io


Features
========

* Asynchronous
* Automatic handling of HTTP(S) sessions
* Type annotations
* 100% test coverage (unittests + integration tests)
* Python 3.9, 3.10, 3.11


Usage
=====

The ``UDM`` context manager opens and closes a HTTP session::

    >>> import asyncio
    >>> from udm_rest_client.udm import UDM
    >>>
    >>> async def get_obj(mod_name, dn):
    ...     async with UDM(
    ...         "USERNAME",
    ...         "PASSWORD",
    ...         "https://FQDN.OF.UCS/univention/udm",
    ...         ssl_ca_cert="ucs-root-ca.crt"
    ...     ) as udm:
    ...         mod = udm.get(mod_name)
    ...         return await mod.get(dn)
    ...
    >>> obj = asyncio.run(get_obj("users/user", "uid=foo,cn=users,BASE-DN"))
    >>>
    >>> print(obj)
    UdmObject('users/user', 'uid=foo,cn=users,BASE-DN')
    >>> print(obj.props.username)
    foo

There are more examples in the `docs`_ *usage* section.

If the SSL CA certificate is not available ``verify_ssl=False`` can be used in place of ``ssl_ca_cert=...``. 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
============

1. Install *Python UDM REST Client* via pip from `PyPI`_::

    $ pip install udm-rest-client

   If you see a complaint about docker needing a higher version of urrlib3, upgrade::

    $ pip install --upgrade urllib3

2. Install the OpenAPI client library used by the udm-rest-client. It is created by software from the `OpenAPI Generator`_ project. You need to either have a local Java installation (Java 8+) or run the projects Docker container. The process is scripted::

    $ update_openapi_client --generator docker ucs.master.fqdn.or.ip  # use Docker
    $ update_openapi_client --generator java ucs.master.fqdn.or.ip  # use Java

Use ``--insecure`` to ignore SSL verification errors. See ``--help`` for more options.

Use ``--username`` and ``--password`` to provide credentials if access to your openapi.json is protected. This is the
default in newer versions of UCS and thus credentials are needed.

**Important**:
Whenever a new UDM module is installed in the domain, it is necessary to rerun ``update_openapi_client``.
The new UDM module will otherwise not be available in the *Python UDM REST Client*.
Very few apps (like UCS\@school and Open-Xchange) install new UDM modules.
New extended attributes do *not* require to rebuild the OpenAPI client library.

Logging
=======

Standard logging is used for tracking the library's activity.
To capture the log messages for this project, subscribe to a logger named ``udm_rest_client``.

The *UDM REST API* on the UCS server logs into the file ``/var/log/univention/directory-manager-rest.log``.

Credits
=======

This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
.. _`UDM REST API`: https://docs.software-univention.de/developer-reference-4.4.html#udm:rest_api
.. _`Python UDM API`: https://github.com/univention/univention-corporate-server/blob/4.4-8/management/univention-directory-manager-modules/modules/univention/udm/__init__.py
.. _`OpenAPI Generator`: https://github.com/OpenAPITools/openapi-generator
.. _`docs`: https://udm-rest-client.readthedocs.io
.. _`PyPI`: https://pypi.org/project/udm-rest-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.9+-blue.svg
    :alt: Python 3.9+
    :target: https://www.python.org/
.. |code style| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :alt: Code style: black
    :target: https://github.com/psf/black
.. |codecov| image:: https://codecov.io/gh/univention/python-udm-rest-api-client/branch/master/graph/badge.svg
    :alt: Code coverage
    :target: https://codecov.io/gh/univention/python-udm-rest-api-client
.. |docspassing| image:: https://readthedocs.org/projects/udm-rest-client/badge/?version=latest
    :alt: Documentation Status
    :target: https://udm-rest-client.readthedocs.io/en/latest/?badge=latest


=======
History
=======

1.3.1 (2025-02-18)
------------------

* Update docker dependency to v7.
* Drop support for python 3.6, python 3.7 and python 3.8.

1.2.3 (2024-01-16)
-------------------

* The client now handles HTTP status responses from the UDM REST API based on generic range (e.g. 2xx-3xx) instead of specific codes.

1.2.2 (2023-06-05)
-------------------

* Fix ``update_openapi_client`` crashing with newer versions of the Python Docker client and ``requests`` (Issue #10).
* Testing fixes (Issues #5 and #9)

1.2.1 (2023-02-15)
-------------------

* Update OpenAPI client library generator (openapitools/openapi-generator-cli) to version ``5.4.0`` to support Python 3.11..

1.1.1 (2023-01-16)
-------------------

* Move operations succeed, when a language header is set.

1.1.0 (2022-11-29)
-------------------

* Adjust objectType return value of ``users/self`` to latest UCS erratum.

1.0.13 (2022-11-09)
-------------------

* Fix error handling in base_http.py.

1.0.12 (2022-11-02)
-------------------

* Add the possibility to send an Accept-Language header with each request.

1.0.11 (2022-10-19)
-------------------

* Handle UDM REST API doing immediate moves (without redirects) for objects without subordinates.

1.0.10 (2022-10-13)
-------------------

* Pass trough UDM REST API error in ``CreateError`` and ``ModifyError`` exceptions.

1.0.9 (2022-09-15)
------------------

* Format the correlation ID as a hex value.

1.0.8 (2022-09-11)
------------------

* Send a correlation ID with each request.
* Raise version of generated client library ``openapi-client-udm`` to ``1.0.1``.

1.0.7 (2022-01-18)
------------------

* Lower required version of ``click`` library, for compatibility with ``typer<0.4.0``.

1.0.6 (2022-01-05)
------------------

* UCS 5.0 container for testing is now run using LXD.
* Fix deprecated use of ``ruamel.yaml`` in tests.

1.0.5 (2021-12-09)
------------------

* Add process wide cache for the LDAP base of each host.

1.0.4 (2021-11-15)
------------------

* Update `aiohttp <https://github.com/aio-libs/aiohttp>`_ to (at least) Version ``3.8.1``, which fixes `aiohttp not honoring "no_proxy" <https://github.com/aio-libs/aiohttp/issues/4431>`_.
* Update development and testing dependencies.

1.0.3 (2021-03-25)
------------------

* Fix handling of values that are lists of dicts (e.g. ``dnsEntryZoneAlias`` of computer objects).

1.0.2 (2021-03-25)
------------------

* Fix not sending policy modifications to server.

1.0.1 (2021-02-10)
------------------

* The script to create/update the OpenAPI client ``update_openapi_client`` has been updated to use the OpenAPI Generator version ``5.0.0``.
* The ``update_openapi_client`` script now verifies the checksum of the downloaded JAR file.

1.0.0 (2021-02-03)
------------------

* **Breaking API CHANGE**: The ``options`` attribute of UDM objects is now a dictionary. It mirrors the UDM REST APIs ``options`` attribute value. Before it was a list, which did not allow to disable default options (Bug #50974).

0.4.0 (2020-04-06)
------------------

* Add the possibility to provide credentials in the update_openapi_client script to download the schema file.

0.3.1 (2020-03-19)
------------------

* Update download URL of openapi-generator jar.

0.3.0 (2020-03-18)
------------------

* allow setting properties that only exist after enabling an option (`Bug #50972 <http://forge.univention.org/bugzilla/show_bug.cgi?id=50972>`_)

0.2.1 (2019-12-14)
------------------

* fix not detecting changes in mutable property values

0.2.0 (2019-12-10)
------------------

* ``Mapping`` and ``Iterable`` interfaces were added to the object properties class. Adds item access (``obj.props["key"]``), ``obj.props.get("key")``, ``len(obj.props)``, ``key in obj.props``, ``obj.props.keys()``, ``obj.props.values()``, ``obj.props.items()``
* documentation improvements
* HTTP basic passwords are no longer logged
* map ``options`` and ``policies`` back to original values (were being rewritten to pep8 conform keys by the OpenAPI client)

0.1.1 (2019-11-25)
------------------

* allow specifying existing JAR for open api client build
* various small fixes to handle RTD and Travis-CI

0.1.0 (2019-11-22)
------------------

* First release.
