Metadata-Version: 2.4
Name: pyTooling.GitLab
Version: 0.1.0rc1
Summary: Working with GitLab pipelines - pipeline configuration files, convert pipeline runs to (OTLP) traces.
Home-page: https://GitHub.com/pyTooling/pyTooling.GitLab
Author: Patrick Lehmann
Author-email: Paebbels@gmail.com
License: Apache-2.0
Project-URL: Documentation, https://pyTooling.GitHub.io/pyTooling.GitLab
Project-URL: Source Code, https://GitHub.com/pyTooling/pyTooling.GitLab
Project-URL: Issue Tracker, https://GitHub.com/pyTooling/pyTooling.GitLab/issues
Keywords: GitLab,GitLab CI/CD,Pipeline,CI,Trace,OpenTelemetry,OTLP
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Development Status :: 2 - Pre-Alpha
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
License-File: NOTICE.md
Requires-Dist: pyTooling[terminal]<11.0,>=10.0.0rc3
Requires-Dist: ruamel.yaml~=0.19.1
Provides-Extra: doc
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "doc"
Requires-Dist: autoapi>=2.0.1; extra == "doc"
Requires-Dist: sphinx~=9.1; extra == "doc"
Requires-Dist: sphinx_design~=0.7.0; extra == "doc"
Requires-Dist: ruamel.yaml~=0.19.1; extra == "doc"
Requires-Dist: pyTooling[terminal]<11.0,>=10.0.0rc3; extra == "doc"
Requires-Dist: sphinxcontrib-mermaid~=2.1; extra == "doc"
Requires-Dist: sphinx_rtd_theme~=3.1; extra == "doc"
Requires-Dist: docutils_stubs~=0.0.22; extra == "doc"
Requires-Dist: pyTooling.Sphinx[reports]~=0.1.0rc3; extra == "doc"
Requires-Dist: sphinx_autodoc_typehints~=3.13; extra == "doc"
Provides-Extra: test
Requires-Dist: pytest~=9.1; extra == "test"
Requires-Dist: matplotlib>=3.10; (implementation_name != "pypy" or sys_platform == "darwin" or (sys_platform == "linux" and implementation_version < "8")) and extra == "test"
Requires-Dist: pytest-xdist~=3.8; extra == "test"
Requires-Dist: Coverage~=7.15; extra == "test"
Requires-Dist: pyTooling.Sphinx~=0.1.0rc3; python_version >= "3.12" and extra == "test"
Requires-Dist: mypy[reports]~=2.3; extra == "test"
Requires-Dist: pytest-cov~=7.1; extra == "test"
Requires-Dist: typing_extensions~=4.16; extra == "test"
Requires-Dist: ruamel.yaml~=0.19.1; extra == "test"
Requires-Dist: pyTooling[terminal]<11.0,>=10.0.0rc3; extra == "test"
Requires-Dist: matplotlib>=3.10; extra == "test"
Requires-Dist: colorama~=0.4.6; extra == "test"
Provides-Extra: diagram
Requires-Dist: matplotlib>=3.10; extra == "diagram"
Provides-Extra: sphinx
Requires-Dist: pyTooling.Sphinx~=0.1.0rc3; extra == "sphinx"
Provides-Extra: all
Requires-Dist: pytest~=9.1; extra == "all"
Requires-Dist: pyTooling.Sphinx~=0.1.0rc3; extra == "all"
Requires-Dist: pyTooling.Sphinx~=0.1.0rc3; python_version >= "3.12" and extra == "all"
Requires-Dist: typing_extensions~=4.16; extra == "all"
Requires-Dist: ruamel.yaml~=0.19.1; extra == "all"
Requires-Dist: pyTooling[terminal]<11.0,>=10.0.0rc3; extra == "all"
Requires-Dist: matplotlib>=3.10; extra == "all"
Requires-Dist: colorama~=0.4.6; extra == "all"
Requires-Dist: sphinx_autodoc_typehints~=3.13; extra == "all"
Requires-Dist: matplotlib>=3.10; (implementation_name != "pypy" or sys_platform == "darwin" or (sys_platform == "linux" and implementation_version < "8")) and extra == "all"
Requires-Dist: pytest-cov~=7.1; extra == "all"
Requires-Dist: autoapi>=2.0.1; extra == "all"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "all"
Requires-Dist: docutils_stubs~=0.0.22; extra == "all"
Requires-Dist: sphinx~=9.1; extra == "all"
Requires-Dist: sphinx_design~=0.7.0; extra == "all"
Requires-Dist: sphinxcontrib-mermaid~=2.1; extra == "all"
Requires-Dist: pytest-xdist~=3.8; extra == "all"
Requires-Dist: Coverage~=7.15; extra == "all"
Requires-Dist: mypy[reports]~=2.3; extra == "all"
Requires-Dist: sphinx_rtd_theme~=3.1; extra == "all"
Requires-Dist: pyTooling.Sphinx[reports]~=0.1.0rc3; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

[![Sourcecode on GitHub](https://img.shields.io/badge/pyTooling-GitLab-63bf7f?longCache=true&style=flat-square&longCache=true&logo=GitHub)](https://GitHub.com/pyTooling/pyTooling.GitLab)
[![Sourcecode License](https://img.shields.io/pypi/l/pyTooling.GitLab?longCache=true&style=flat-square&logo=Apache&label=code)](LICENSE.md)
[![Documentation](https://img.shields.io/website?longCache=true&style=flat-square&label=pyTooling.github.io%2FpyTooling.GitLab&logo=GitHub&logoColor=fff&up_color=blueviolet&up_message=Read%20now%20%E2%9E%9A&url=https%3A%2F%2FpyTooling.github.io%2FpyTooling.GitLab%2Findex.html)](https://pyTooling.github.io/pyTooling.GitLab/)
[![Documentation License](https://img.shields.io/badge/doc-CC--BY%204.0-green?longCache=true&style=flat-square&logo=CreativeCommons&logoColor=fff)](doc/Doc-License.rst)  
[![PyPI](https://img.shields.io/pypi/v/pyTooling.GitLab?longCache=true&style=flat-square&logo=PyPI&logoColor=FBE072)](https://pypi.org/project/pyTooling.GitLab/)
![PyPI - Status](https://img.shields.io/pypi/status/pyTooling.GitLab?longCache=true&style=flat-square&logo=PyPI&logoColor=FBE072)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyTooling.GitLab?longCache=true&style=flat-square&logo=PyPI&logoColor=FBE072)  
[![GitHub Workflow - Build and Test Status](https://img.shields.io/github/actions/workflow/status/pyTooling/pyTooling.GitLab/Pipeline.yml?branch=main&longCache=true&style=flat-square&label=build%20and%20test&logo=GitHub%20Actions&logoColor=FFFFFF)](https://GitHub.com/pyTooling/pyTooling.GitLab/actions/workflows/Pipeline.yml)
[![Libraries.io status for latest release](https://img.shields.io/librariesio/release/pypi/pyTooling.GitLab?longCache=true&style=flat-square&logo=Libraries.io&logoColor=fff)](https://libraries.io/github/pyTooling/pyTooling.GitLab)
[![Codacy - Quality](https://img.shields.io/codacy/grade/dae89de7264d479daf8d6197c8ed2186?longCache=true&style=flat-square&logo=Codacy)](https://app.codacy.com/gh/pyTooling/pyTooling.GitLab/dashboard)
[![Codacy - Coverage](https://img.shields.io/codacy/coverage/dae89de7264d479daf8d6197c8ed2186?longCache=true&style=flat-square&logo=Codacy)](https://app.codacy.com/gh/pyTooling/pyTooling.GitLab/dashboard)
[![Codecov - Branch Coverage](https://img.shields.io/codecov/c/github/pyTooling/pyTooling.GitLab?longCache=true&style=flat-square&logo=Codecov)](https://codecov.io/gh/pyTooling/pyTooling.GitLab)

# pyTooling.GitLab

**pyTooling.GitLab** works with GitLab CI/CD pipelines: it reads pipeline files (`.gitlab-ci.yml`) into a data model,
reads the runs of a pipeline from GitLab's REST API, and converts them into traces - e.g. OpenTelemetry's OTLP/JSON or
a Gantt chart of the jobs. A Sphinx domain `glci` documents a pipeline file's inputs and variables taken straight from
the file.

It builds on [pyTooling](https://GitHub.com/pyTooling/pyTooling)'s generic CI pipeline model and tracing, and on
[pyTooling.Sphinx](https://GitHub.com/pyTooling/pyTooling.Sphinx) for its documentation extensions. Its sibling
[pyTooling.GitHub](https://GitHub.com/pyTooling/pyTooling.GitHub) does the same for GitHub Actions.


> [!IMPORTANT]
> The Sphinx domain `glci` in `pyTooling.GitLab.Sphinx` requires [pyTooling.Sphinx][pyTooling.Sphinx], and thus
> **Python 3.12 or newer**, because Sphinx 9.1 requires Python 3.12.

The package is installed from PyPI:

```bash
pip install pyTooling.GitLab
```


## Features

### Data models

* [Pipeline runs][PipelineRun] - A GitLab pipeline - its jobs, matrices and child pipelines with their times and
  outcomes - read from the GitLab REST API's payloads.
* [Pipeline files][PipelineFile] - A `.gitlab-ci.yml` and the files it includes: stages, jobs with their needs and
  rules, variables and inputs, read with line numbers, and converted into a pipeline graph.

### Sphinx domain `glci`

The domain needs the extra `sphinx`, which installs pyTooling.Sphinx:

```bash
pip install pyTooling.GitLab[sphinx]
```

* [Pipelines and their parameters][GLCIPipelines] - A pipeline file's `spec:inputs` and its described variables,
  taken straight from the file; roles to reference them.
* [Summaries][GLCISummaries] - Parameter tables, the interface, the dependencies and YAML excerpts of a pipeline
  file.

### Visualization

* [Pipeline graph][PipelineGraph] - The jobs of a pipeline file, their stages and `needs` as a Graphviz graph.
* [Pipeline trace diagram][PipelineTrace] - Reads a pipeline through the GitLab REST API into a trace, written as
  OpenTelemetry's OTLP/JSON or drawn as a Gantt chart.

### Program

Gantt charts need the extra `diagram`, which installs matplotlib:

```bash
pip install pyTooling.GitLab[diagram]
```

* [pytooling-gitlab][CLI] - The command `pipeline` reads a pipeline into a trace, writes it, and draws it as a
  Gantt chart.

[PipelineRun]: https://pyTooling.github.io/pyTooling.GitLab/Data/PipelineRun.html
[PipelineFile]: https://pyTooling.github.io/pyTooling.GitLab/Data/PipelineFile.html
[GLCIPipelines]: https://pyTooling.github.io/pyTooling.GitLab/GLCI/Pipelines.html
[GLCISummaries]: https://pyTooling.github.io/pyTooling.GitLab/GLCI/Summaries.html
[PipelineGraph]: https://pyTooling.github.io/pyTooling.GitLab/Visualization/PipelineGraph.html
[PipelineTrace]: https://pyTooling.github.io/pyTooling.GitLab/Visualization/PipelineTrace.html
[CLI]: https://pyTooling.github.io/pyTooling.GitLab/CLI.html
[pyTooling.Sphinx]: https://pyTooling.github.io/pyTooling.Sphinx/


## Contributors

* [Patrick Lehmann](https://GitHub.com/Paebbels) (Maintainer)
* [and more...](https://GitHub.com/pyTooling/pyTooling.GitLab/graphs/contributors)


## License

This Python package (source code) is licensed under [Apache License 2.0](LICENSE.md).  
The accompanying documentation is licensed under [Creative Commons - Attribution 4.0 (CC-BY 4.0)](doc/Doc-License.rst).  
Content of other projects - e.g. recorded pipelines of public gitlab.com projects as test data - is listed with its
license in [NOTICE.md](NOTICE.md).


-------------------------

SPDX-License-Identifier: Apache-2.0
