Package: zabel-elements
zabel-elementsOverviewThis is part of the Zabel platform.  Thezabel-elementspackage
contains the standardelementslibrary for Zabel.An element is an external service such asArtifactoryorJenkinsor 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:ArtifactoryCloudBeesJenkinsConfluenceGitHubJiraKubernetes (in alpha)OktaSonarQubeSquashTMElements are of two kinds:ManagedServices, which represent services that are
managed by Zabel, andUtilities, 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 is a utility.  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, thezabel.elements.clientsmodule 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.ArchitectureIt contains two parts:Thezabel.elements.clientsmoduleThezabel.elements.imagesbase classes moduleThere is oneimageper client (hence one image per element).  Images are
classes with a standardized constructor and arun()method and are how
code is packaged so that it can be deployed on the Zabel platform.zabel.elements.clientsThezabel.elements.clientsmodule provides a wrapper class per
tool.It relies on thezabel-commonslibrary, using itszabel.commons.exceptionsmodule for theApiErrorexception class,
itszabel.commons.sessionsmodule for HTTPS session handling,
and itszabel.commons.utilsmodule that contains useful functions.Conventions for ClientsIf 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: abasepart that implements single
API calls (and possibly pagination), and aregularpart 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 fromobject.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 orrequestsor modules part of thezabel-commonslibrary.  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 anApiErrorexception.If a wrapper class method is called with an obviously invalid parameter
(wrong type, not a permitted value, ...), aValueErrorexception will
be raised.NoteBase 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.imagesThezabel.elements.imagesmodule provides image wrappers for the
built-in clients' classes (those defined in thezabel.elements.clientsmodule).Those abstract image wrappers implement an__init__()constructor with
no parameter and a defaultrun()method that can be overridden.Managed services also implement at least thelist_members()method of
theManagedServiceinterface.  They may provideget_member()if a
fast implementation is available.Concrete classes deriving those abstract managed services wrappers
should provide aget_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 aget_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 theManagedServiceinterface.Conventions for ImagesUtilities must implement theUtilityinterface and managed services
must implement theManagedServiceinterface.LicenseCopyright (c) 2019-2023 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