# 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.
<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 _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
```text
Copyright (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
```
Raw data
{
"_id": null,
"home_page": "https://github.com/engie-group/zabel",
"name": "zabel-elements",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": null,
"keywords": null,
"author": "Martin Lafaix",
"author_email": "martin.lafaix@external.engie.com",
"download_url": null,
"platform": null,
"description": "# zabel-elements\n\n## Overview\n\nThis is part of the Zabel platform. The **zabel-elements** package\ncontains the standard _elements_ library for Zabel.\n\nAn element is an external service such as _Artifactory_ or _Jenkins_ or an\nLDAP server that can be managed or used by Zabel.\n\nThis package provides the necessary wrappers for some elements commonly\nfound in many workplaces, namely:\n\n- Artifactory\n- CloudBeesJenkins\n- Confluence\n- GitHub\n- Jira\n- Kubernetes (in alpha)\n- Okta\n- SonarQube\n- SquashTM\n\nElements are of two kinds: _ManagedServices_, which represent services that are\nmanaged by Zabel, and _Utilities_, which represent services that are used by Zabel.\n\nManaged services host project resources. They typically are the tools that project\nmembers interact with directly.\n\nUtilities may also host project resources, but they typically are not used directly\nby project members. They are either references or infrastructure services necessary\nfor the managed services to function, but otherwise not seen by project members.\nAn LDAP server would probably be a utility, used both as a reference and as an access\ncontrol tool.\n\nIn the above list, Kubernetes and Okta are utilities. The other elements are managed services.\n\nYou can use this library independently of the Zabel platform, as it has no\nspecific dependencies on it. In particular, the **zabel.elements.clients**\nmodule may be of interest if you want to perform some configuration tasks\nfrom your own Python code.\n\nContributions of new wrappers or extensions of existing wrappers are welcomed.\nBut elements can be provided in their own packages too.\n\n## Architecture\n\nIt contains two parts:\n\n- The **zabel.elements.clients** module\n- The **zabel.elements.images** base classes module\n\nThere is one _image_ per client (hence one image per element). Images are\nclasses with a standardized constructor and a `run()` method and are how\ncode is packaged so that it can be deployed on the Zabel platform.\n\n## zabel.elements.clients\n\nThe **zabel.elements.clients** module provides a wrapper class per\ntool.\n\nIt relies on the **zabel-commons** library, using its\n_zabel.commons.exceptions_ module for the _ApiError_ exception class,\nits _zabel.commons.sessions_ module for HTTPS session handling,\nand its _zabel.commons.utils_ module that contains useful functions.\n\n### Conventions for Clients\n\nIf an existing library already provides all the needed functionality,\nthere is no need to add it to this library.\n\nIf an existing library already provides some of the needed\nfunctionality, a wrapper class can be written that will use this\nexisting library as a client. Do not inherit from it.\n\nWrapper classes have two parts: a _base_ part that implements single\nAPI calls (and possibly pagination), and a _regular_ part that\ninherits from the base part and possibly extends it.\n\nThe base part may not exist if an already existing library\nprovides wrappers for the needed low-level calls. In such a\ncase, the regular class may simply use the existing library as\na client and inherit from `object`.\n\nSimilarly, the regular part may be empty, in that it may simply inherit\nfrom the base class and contain no additional code.\n\nAt import time, wrapper classes should not import libraries not part of\nthe Python standard library or **requests** or modules part of the\n**zabel-commons** library. That way, projects not needing some tool do\nnot have to install their required dependencies. Wrapper classes may\nimport libraries in their `__init__()` methods, though.\n\nIf an API call is successful, it will return a value (possibly None).\nIf not, it will raise an _ApiError_ exception.\n\nIf a wrapper class method is called with an obviously invalid parameter\n(wrong type, not a permitted value, ...), a _ValueError_ exception will\nbe raised.\n\n<h4>Note</h4>\n\nBase classes do not try to provide features not offered by the tool API.\n\nTheir methods closely match the underlying API.\n\nThey offer a uniform (or, at least, harmonized) naming convention,\nand may simplify technical details (pagination is automatically\nperformed if needed).\n\n## zabel.elements.images\n\nThe **zabel.elements.images** module provides image wrappers for the\nbuilt-in clients' classes (those defined in the **zabel.elements.clients**\nmodule).\n\nThose abstract image wrappers implement an `__init__()` constructor with\nno parameter and a default `run()` method that can be overridden.\n\nManaged services also implement at least the `list_members()` method of\nthe _ManagedService_ interface. They may provide `get_member()` if a\nfast implementation is available.\n\nConcrete classes deriving those abstract managed services wrappers\nshould provide a `get_canonical_member_id()` method that takes a\nparameter, a user from the wrapped API point of view, and returns the\ncanonical user ID, as well as a `get_internal_member_id()` method that\ntakes a canonical user ID and returns the internal key for that user.\n\nThey should also provide concrete implementations for the remaining\nmethods provided by the _ManagedService_ interface.\n\n### Conventions for Images\n\nUtilities must implement the _Utility_ interface and managed services\nmust implement the _ManagedService_ interface.\n\n## License\n\n```text\nCopyright (c) 2019-2023 Martin Lafaix (martin.lafaix@external.engie.com) and others\n\nThis program and the accompanying materials are made\navailable under the terms of the Eclipse Public License 2.0\nwhich is available at https://www.eclipse.org/legal/epl-2.0/\n\nSPDX-License-Identifier: EPL-2.0\n```\n",
"bugtrack_url": null,
"license": "Eclipse Public License 2.0",
"summary": "The Zabel default clients and images",
"version": "1.30.0",
"project_urls": {
"Homepage": "https://github.com/engie-group/zabel"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "066647e695dc433c9cae790e843a6f5404ff6ccf1e759645afd83e7b6589d272",
"md5": "e90ef0ed4e33e603f4d559a231d440b3",
"sha256": "0a778234d72b2e0d3c23f97f8114b55a12e59bd208cf151dd89fcb9c7db0bc49"
},
"downloads": -1,
"filename": "zabel_elements-1.30.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e90ef0ed4e33e603f4d559a231d440b3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 125821,
"upload_time": "2024-11-22T13:16:47",
"upload_time_iso_8601": "2024-11-22T13:16:47.358254Z",
"url": "https://files.pythonhosted.org/packages/06/66/47e695dc433c9cae790e843a6f5404ff6ccf1e759645afd83e7b6589d272/zabel_elements-1.30.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-22 13:16:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "engie-group",
"github_project": "zabel",
"github_not_found": true,
"lcname": "zabel-elements"
}
JSON
