Metadata-Version: 2.2
Name: zabel-elements
Version: 1.39.2
Summary: The Zabel default clients and images
Home-page: https://github.com/engie-group/zabel
Author: Martin Lafaix
Author-email: martin.lafaix@external.engie.com
License: Eclipse Public License 2.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Eclipse Public License 2.0 (EPL-2.0)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >= 3.12.0
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: zabel-commons>=1.8
Provides-Extra: gitlab
Requires-Dist: python-gitlab>=6.1; extra == "gitlab"
Provides-Extra: jira
Requires-Dist: Jira>=3.0; extra == "jira"
Provides-Extra: kubernetes
Requires-Dist: kubernetes>=33.1.0; extra == "kubernetes"
Provides-Extra: okta
Requires-Dist: okta<=2.9.10,>=2.9; extra == "okta"
Provides-Extra: pynacl
Requires-Dist: pynacl>=1.5.0; extra == "pynacl"
Provides-Extra: all
Requires-Dist: Jira>=3.0; extra == "all"
Requires-Dist: kubernetes>=33.1.0; extra == "all"
Requires-Dist: okta<=2.9.10,>=2.9; extra == "all"
Requires-Dist: pynacl>=1.5.0; extra == "all"
Requires-Dist: python-gitlab>=6.1; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# zabel-elements

## Overview

This is part of the Zabel platform.  The **zabel-elements** package contains
the standard _elements_ library for Zabel.

An element is an external service such as _Artifactory_ or _Jenkins_ or an
LDAP server that can be managed or used by Zabel.

This package provides the necessary wrappers for some elements commonly found
in many workplaces, namely:

<div class="grid cards" markdown>

- Artifactory
- Atlassian
- CloudBeesJenkins
- Confluence
- ConfluenceCloud
- GitHub
- GitHubCloud
- GitLab
- Jira
- JiraCloud
- Kubernetes (in alpha)
- Okta
- SonarQube
- SonatypeNexus
- SquashTM

</div>

Elements are of two kinds: _Managed services_, which represent services that
are managed by Zabel, and _Utilities_, which represent services that are used
by Zabel.

Managed services host project resources.  They typically are the tools that
project members interact with directly.

Utilities may also host project resources, but they typically are not used
directly by project members.  They are either references or infrastructure
services necessary for the managed services to function, but otherwise not
seen by project members.  An LDAP server would probably be a utility, used
both as a reference and as an access control tool.

In the above list, Atlassian, Kubernetes and Okta are utilities.  The other
elements are managed services.

You can use this library independently of the Zabel platform, as it has no
specific dependencies on it.  In particular, the **zabel.elements.clients**
module may be of interest if you want to perform some configuration tasks
from your own Python code.

Contributions of new wrappers or extensions of existing wrappers are welcomed.
But elements can be provided in their own packages too.

## Architecture

It contains two parts:

- The **zabel.elements.clients** module
- The **zabel.elements.images** base classes module

There is one _image_ per client (hence one image per element).  Images are classes
with a standardized constructor taking no parameters and a `run()` method and are
how code is packaged so that it can be deployed on the Zabel platform.

## zabel.elements.clients

The **zabel.elements.clients** module provides a wrapper class per tool.

It relies on the **zabel-commons** library, using its
_zabel.commons.exceptions_ module for the _ApiError_ exception class,
its _zabel.commons.sessions_ module for HTTPS session handling,
and its _zabel.commons.utils_ module that contains useful functions.

### Conventions for Clients

If an existing library already provides all the needed functionality, there is
no need to add it to this library.

If an existing library already provides some of the needed functionality, a
wrapper class can be written that will use this existing library as a client.
Do not inherit from it.

Wrapper classes have two parts: a _base_ part that implements single API
calls (and possibly pagination), and a _regular_ part that inherits from the
base part and possibly extends it.

The base part may not exist if an already existing library provides wrappers
for the needed low-level calls.  In such a case, the regular class may simply
use the existing library as a client and inherit from `object`.

Similarly, the regular part may be empty, in that it may simply inherit from
the base class and contain no additional code.

At import time, wrapper classes should not import libraries not part of the
Python standard library or **requests** or modules part of the
**zabel-commons** library.  That way, projects not needing some tool do not
have to install their required dependencies.  Wrapper classes may import
libraries in their `__init__()` methods, though.

If an API call is successful, it will return a value (possibly None).  If not,
it will raise an _ApiError_ exception.

If a wrapper class method is called with an obviously invalid parameter
(wrong type, not a permitted value, ...), a _ValueError_ exception will be
raised.

<h4>Note</h4>

Base classes do not try to provide features not offered by the tool API.

Their methods closely match the underlying API.

They offer a uniform (or, at least, harmonized) naming convention, and may
simplify technical details (pagination is automatically performed if
needed).

## zabel.elements.images

The **zabel.elements.images** module provides image wrappers for the
built-in clients' classes (those defined in the **zabel.elements.clients**
module).

Those abstract image wrappers implement an `__init__()` constructor with no
parameter and a default `run()` method that can be overridden.

Managed services also implement at least the `list_members()` method of
the _ManagedServiceApp_ interface.  They may provide `get_member()` if a fast
implementation is available.

Concrete classes deriving those abstract managed services wrappers should
provide a `get_canonical_member_id()` method that takes a parameter, a user
from the wrapped API point of view, and returns the canonical user ID, as
well as a `get_internal_member_id()` method that takes a canonical user ID
and returns the internal key for that user.

They should also provide concrete implementations for the remaining methods
provided by the _ManagedServiceApp_ interface.

### Conventions for Images

Utilities images must implement the _UtilityApp_ interface and managed services
images must implement the _ManagedServiceApp_ interface.

## License

```text
Copyright (c) 2019 Martin Lafaix (martin.lafaix@external.engie.com) and others

This program and the accompanying materials are made
available under the terms of the Eclipse Public License 2.0
which is available at https://www.eclipse.org/legal/epl-2.0/

SPDX-License-Identifier: EPL-2.0
```
