Metadata-Version: 2.4
Name: cikit
Version: 0.0.3
Summary: CI helper toolkit
Author-email: Sven Schlender <svesch@gmx.de>
License-Expression: GPL-3.0-or-later
Project-URL: Documentation, https://cikit-a4de14.gitlab.io
Project-URL: Repository, https://gitlab.com/svesch/cikit
Keywords: ci,gitlab,pipeline,artifacts,sphinx
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.34
Requires-Dist: anybadge>=1.16
Requires-Dist: pygal>=3.1.0
Dynamic: license-file


# cikit

**cikit** is a lightweight Python toolkit for building reproducible CI/CD pipelines.

It provides reusable building blocks for:

* CI environment handling
* provider abstraction (GitLab and local execution)
* command execution
* test execution and coverage reporting
* lint integration (Ruff, Pylint)
* Sphinx documentation generation
* artifact management
* badge generation
* project metadata handling
* build and pipeline reporting

The package is designed for projects that want to keep CI logic in Python instead of large shell scripts or complex YAML definitions.

## Features

### Environment Management

Resolve CI variables from multiple sources:

* operating system environment
* CI provider
* project defaults
* template expansion using `${VAR}` syntax

```python
from cikit.env import CiEnvironment

env = CiEnvironment()
print(env["PROJECT_ROOT"])
print(env["PIPELINE_ID"])
```

### Command Execution

Run external tools with:

* live output streaming
* timeout handling
* structured result objects
* graceful process termination

```python
from cikit.command import run_command

result = run_command(["pytest"])
result.check_returncode()
```

### Lint Integration

Generate machine-readable and human-readable reports from:

* Ruff
* Pylint

Reports can be converted into reStructuredText and published as documentation artifacts.

### Testing and Coverage

Built-in helpers for:

* pytest execution
* JUnit XML generation
* coverage collection
* Cobertura reports
* CI summaries

### Documentation Generation

Integrates with Sphinx and automatically publishes:

* generated RST files
* badges
* coverage reports
* build artifacts

Generated content can be included directly in project documentation.

### Project Metadata

Read project information from:

* `pyproject.toml`
* `cikit.toml`

Generate version files and metadata artifacts from a unified project model.

### Job Data and Metrics

Optional integration with the JobData backend allows pipelines to store:

* build results
* quality metrics
* coverage values
* historical trends

This data can be used to generate badges and timeline charts across multiple pipeline runs.

## Installation

```bash
pip install cikit
```

or with uv:

```bash
uv add cikit
```

## Quick Example

```python
from cikit.env import CiEnvironment
from cikit.logging_utils import setup_logging
from cikit.command import run_command

setup_logging()

env = CiEnvironment()

result = run_command(
    ["pytest"],
    cwd=env["PROJECT_ROOT"],
)

result.check_returncode()
```

## Typical Project Structure

```text
project/
├── docs/
├── src/
├── tests/
├── pyproject.toml
└── public/
    ├── artifacts/
    ├── badges/
    └── rst/
```

## Design Goals

* Pure Python implementation
* CI-provider abstraction
* Reproducible builds
* Local execution without CI infrastructure
* Testability
* Minimal external dependencies
* Sphinx-friendly reporting
* GitLab-oriented, but not GitLab-exclusive

## Documentation

The full documentation contains:

* CI environment reference
* command execution API
* lint reporting
* testing helpers
* Sphinx integration
* JobData integration
* artifact management
* examples and recipes

## License

GPL-3.0-or-later
