Metadata-Version: 2.4
Name: pyTooling.GitHub
Version: 0.1.0rc1
Summary: Working with GitHub pipelines - workflow files, action files, convert pipeline runs to (OTLP) traces.
Home-page: https://GitHub.com/pyTooling/pyTooling.GitHub
Author: Patrick Lehmann
Author-email: Paebbels@gmail.com
License: Apache-2.0
Project-URL: Documentation, https://pyTooling.GitHub.io/pyTooling.GitHub
Project-URL: Source Code, https://GitHub.com/pyTooling/pyTooling.GitHub
Project-URL: Issue Tracker, https://GitHub.com/pyTooling/pyTooling.GitHub/issues
Keywords: GitHub,GitHub Actions,Workflow,Pipeline,CI,Trace,OpenTelemetry,OTLP,Sphinx
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 :: 3 - Alpha
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: pyTooling[terminal]<11.0,>=10.0.0rc3
Requires-Dist: ruamel.yaml~=0.19.1
Provides-Extra: doc
Requires-Dist: pyTooling[terminal]<11.0,>=10.0.0rc3; extra == "doc"
Requires-Dist: sphinx_rtd_theme~=3.1; extra == "doc"
Requires-Dist: sphinxcontrib-mermaid~=2.1; extra == "doc"
Requires-Dist: pyTooling.Sphinx[reports]~=0.1.0rc2; extra == "doc"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "doc"
Requires-Dist: sphinx_design~=0.7.0; extra == "doc"
Requires-Dist: sphinx_autodoc_typehints~=3.13; extra == "doc"
Requires-Dist: ruamel.yaml~=0.19.1; extra == "doc"
Requires-Dist: autoapi>=2.0.1; extra == "doc"
Requires-Dist: docutils_stubs~=0.0.22; extra == "doc"
Requires-Dist: sphinx~=9.1; extra == "doc"
Provides-Extra: test
Requires-Dist: pyTooling[terminal]<11.0,>=10.0.0rc3; extra == "test"
Requires-Dist: mypy[reports]~=2.3; extra == "test"
Requires-Dist: pyTooling.Sphinx~=0.1.0rc2; python_version >= "3.12" and 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: colorama~=0.4.6; extra == "test"
Requires-Dist: ruamel.yaml~=0.19.1; extra == "test"
Requires-Dist: pytest-cov~=7.1; extra == "test"
Requires-Dist: pytest~=9.1; extra == "test"
Requires-Dist: pytest-xdist~=3.8; extra == "test"
Requires-Dist: Coverage~=7.15; extra == "test"
Requires-Dist: typing_extensions~=4.16; extra == "test"
Requires-Dist: matplotlib>=3.10; extra == "test"
Provides-Extra: diagram
Requires-Dist: matplotlib>=3.10; extra == "diagram"
Provides-Extra: sphinx
Requires-Dist: pyTooling.Sphinx~=0.1.0rc2; extra == "sphinx"
Provides-Extra: all
Requires-Dist: mypy[reports]~=2.3; extra == "all"
Requires-Dist: matplotlib>=3.10; extra == "all"
Requires-Dist: pyTooling[terminal]<11.0,>=10.0.0rc3; extra == "all"
Requires-Dist: pyTooling.Sphinx~=0.1.0rc2; python_version >= "3.12" and extra == "all"
Requires-Dist: pyTooling.Sphinx[reports]~=0.1.0rc2; extra == "all"
Requires-Dist: colorama~=0.4.6; extra == "all"
Requires-Dist: sphinx_autodoc_typehints~=3.13; extra == "all"
Requires-Dist: autoapi>=2.0.1; extra == "all"
Requires-Dist: docutils_stubs~=0.0.22; extra == "all"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "all"
Requires-Dist: sphinx_design~=0.7.0; extra == "all"
Requires-Dist: ruamel.yaml~=0.19.1; extra == "all"
Requires-Dist: pytest-cov~=7.1; extra == "all"
Requires-Dist: pytest~=9.1; extra == "all"
Requires-Dist: typing_extensions~=4.16; extra == "all"
Requires-Dist: pytest-xdist~=3.8; extra == "all"
Requires-Dist: sphinx~=9.1; extra == "all"
Requires-Dist: pyTooling.Sphinx~=0.1.0rc2; extra == "all"
Requires-Dist: sphinxcontrib-mermaid~=2.1; extra == "all"
Requires-Dist: sphinx_rtd_theme~=3.1; 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: Coverage~=7.15; 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-GitHub-63bf7f?longCache=true&style=flat-square&longCache=true&logo=GitHub)](https://GitHub.com/pyTooling/pyTooling.GitHub)
[![Sourcecode License](https://img.shields.io/pypi/l/pyTooling.GitHub?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.GitHub&logo=GitHub&logoColor=fff&up_color=blueviolet&up_message=Read%20now%20%E2%9E%9A&url=https%3A%2F%2FpyTooling.github.io%2FpyTooling.GitHub%2Findex.html)](https://pyTooling.github.io/pyTooling.GitHub/)
[![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.GitHub?longCache=true&style=flat-square&logo=PyPI&logoColor=FBE072)](https://pypi.org/project/pyTooling.GitHub/)
![PyPI - Status](https://img.shields.io/pypi/status/pyTooling.GitHub?longCache=true&style=flat-square&logo=PyPI&logoColor=FBE072)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyTooling.GitHub?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.GitHub/Pipeline.yml?branch=main&longCache=true&style=flat-square&label=build%20and%20test&logo=GitHub%20Actions&logoColor=FFFFFF)](https://GitHub.com/pyTooling/pyTooling.GitHub/actions/workflows/Pipeline.yml)
[![Libraries.io status for latest release](https://img.shields.io/librariesio/release/pypi/pyTooling.GitHub?longCache=true&style=flat-square&logo=Libraries.io&logoColor=fff)](https://libraries.io/github/pyTooling/pyTooling.GitHub)
[![Codacy - Quality](https://img.shields.io/codacy/grade/e56604e36cf04f6090e0b171e948c1fa?longCache=true&style=flat-square&logo=Codacy)](https://app.codacy.com/gh/pyTooling/pyTooling.GitHub/dashboard)
[![Codacy - Coverage](https://img.shields.io/codacy/coverage/e56604e36cf04f6090e0b171e948c1fa?longCache=true&style=flat-square&logo=Codacy)](https://app.codacy.com/gh/pyTooling/pyTooling.GitHub/dashboard)
[![Codecov - Branch Coverage](https://img.shields.io/codecov/c/github/pyTooling/pyTooling.GitHub?longCache=true&style=flat-square&logo=Codecov)](https://codecov.io/gh/pyTooling/pyTooling.GitHub)

# pyTooling.GitHub

**pyTooling.GitHub** works with GitHub Actions pipelines: it reads workflow and action files into a data model,
reads the runs of a pipeline from GitHub's REST API, and converts them into traces - e.g. OpenTelemetry's OTLP/JSON
or a Gantt chart of the jobs and steps. A Sphinx domain `ghactions` documents workflows and their inputs, outputs and
secrets taken straight from the workflow files.

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.


> [!IMPORTANT]
> The Sphinx domain `ghactions` in `pyTooling.GitHub.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.GitHub
```


## Features

### Data models

* [Pipeline runs][PipelineRun] - A GitHub Actions workflow run - pipeline, workflows, matrices, jobs and steps with
  their times and outcomes - read from the GitHub REST API's payloads.
* [Workflow files][WorkflowFile] - A workflow file: triggers, inputs, outputs, secrets, permissions and jobs with their
  dependencies, read with line numbers, and converted into a pipeline graph.
* [Action files][ActionFile] - An action's file: how it runs, and the steps of a composite action with the actions
  they run in turn.

### Sphinx domain `ghactions`

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

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

It is enabled in `conf.py`, and sets up pyTooling.Sphinx itself:

```python
# doc/conf.py
extensions = [
  ...,
  "pyTooling.GitHub.Sphinx",
]
```

* [Workflows and their parameters][GHAWorkflows] - `ghactions:workflow`, `ghactions:input`, `ghactions:output`,
  `ghactions:secret` and `ghactions:autoinputs`, taken straight from the workflow file; roles to reference them.
* [Summaries][GHASummaries] - `ghactions:parameter-table`, `ghactions:interface`, `ghactions:dependencies` and
  `ghactions:yaml`.

### Visualization

* [Pipeline graph][PipelineGraph] - `ghactions:pipeline-graph` draws the jobs of a workflow and their `needs` as a
  Graphviz graph, with the reusable workflows it calls expanded.
* [Pipeline trace diagram][PipelineTrace] - Reads a workflow run through the GitHub 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.GitHub[diagram]
```

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

[PipelineRun]: https://pyTooling.github.io/pyTooling.GitHub/Data/PipelineRun.html
[WorkflowFile]: https://pyTooling.github.io/pyTooling.GitHub/Data/WorkflowFile.html
[ActionFile]: https://pyTooling.github.io/pyTooling.GitHub/Data/ActionFile.html
[GHAWorkflows]: https://pyTooling.github.io/pyTooling.GitHub/GHA/Workflows.html
[GHASummaries]: https://pyTooling.github.io/pyTooling.GitHub/GHA/Summaries.html
[PipelineGraph]: https://pyTooling.github.io/pyTooling.GitHub/Visualization/PipelineGraph.html
[PipelineTrace]: https://pyTooling.github.io/pyTooling.GitHub/Visualization/PipelineTrace.html
[CLI]: https://pyTooling.github.io/pyTooling.GitHub/CLI.html
[pyTooling.Sphinx]: https://pyTooling.github.io/pyTooling.Sphinx/


## Consumers

This layer is used by:

* 🚧 [pyTooling/Actions](https://GitHub.com/pyTooling/Actions) - its documentation of the job templates will use the
  `ghactions` domain.


## Contributors

* [Patrick Lehmann](https://GitHub.com/Paebbels) (Maintainer)
* [and more...](https://GitHub.com/pyTooling/pyTooling.GitHub/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).


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

SPDX-License-Identifier: Apache-2.0
