zabel-elements 1.30.2

The Zabel default clients and images

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:

• Artifactory
• CloudBeesJenkins
• Confluence
• GitHub
• Jira
• Kubernetes (in alpha)
• Okta
• SonarQube
• SquashTM

Elements are of two kinds: ManagedServices, 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, 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 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.

Note

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 ManagedService 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 ManagedService interface.

Conventions for Images

Utilities must implement the Utility interface and managed services must implement the ManagedService interface.

License

Copyright (c) 2019-2023 Martin Lafaix ([e-mail]) 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