Metadata-Version: 2.1
Name: udm-rest-client
Version: 0.3.0
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
Description: ======================
        Python UDM REST Client
        ======================
        
        |python| |license| |code style| |codecov| |docspassing| |travisci|
        
        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.6, 3.7, 3.8
        
        
        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)
            ...
            >>> # Python 3.6:
            >>> loop = asyncio.get_event_loop()
            >>> obj = loop.run_until_complete(get_obj("users/user", "uid=foo,cn=users,BASE-DN"))
            >>>
            >>> # Python 3.7+:
            >>> 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
        
        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.
        
        **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.
        
        Tests
        -----
        
        There are some isolated unittests, but most tests run against a real UDM 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.
        
        Run tests with current Python interpreter::
        
            $ make test
        
        Using `tox`_ the tests can be executed with all supported Python versions::
        
            $ make test-all
        
        It is also possible to use an existing UCS server for the tests. Export ``UCS_HOST`` (the servers IP/FQDN), ``UCS_USERDN`` (the DN of an administrator account, usually ``uid=Administrator``) and ``UCS_PASSWORD`` (the accounts password), before starting the tests::
        
            $ export UCS_HOST="my.server.local"
            $ export UCS_USERDN="uid=Administrator,cn=users,dc=domain,dc=local"
            $ export UCS_PASSWORD="s3cr3t"
            $ make test
        
        Don't forget to update the OpenAPI client library before running the test against a new server::
        
            $ update_openapi_client --generator <docker|java> $UCS_HOST
        
        To get the IP address of the UCS Docker container run::
        
            $ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' udm_rest_only
        
        Logging
        -------
        
        Standard logging is used for tracking the libraries 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``.
        
        Repo permissions
        ----------------
        * Github: @dansan and @JuergenBS
        * Gitlab: @JuergenBS
        * PyPI: @dansan and @SamuelYaron
        * RTD: @dansan and @SamuelYaron
        
        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
        .. _`tox`: http://tox.readthedocs.org/
        .. _`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-2/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.6+-blue.svg
            :alt: Python 3.6+
            :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
        .. |travisci| image:: https://travis-ci.com/univention/python-udm-rest-api-client.svg?branch=master
            :target: https://travis-ci.com/univention/python-udm-rest-api-client
        
        
        =======
        History
        =======
        
        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.
        
Keywords: Univention UCS UDM REST
Platform: UNKNOWN
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.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Systems Administration :: Authentication/Directory :: LDAP
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
