Metadata-Version: 2.4
Name: cikit
Version: 0.0.5
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,devops,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 for GitLab and local execution
* command execution
* test execution and coverage reporting
* lint integration with Ruff and Pylint
* Sphinx documentation generation
* artifact management
* badge generation
* project metadata handling
* cikit data 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, get_env_vars

env = CiEnvironment(get_env_vars())

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
* CTest 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.

### Cikit Data and Metrics

Optional integration with the cikit data backend allows pipelines to store:

* build results
* quality metrics
* coverage values
* historical trends
* local artifact metadata

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.command import run_command
from cikit.env import CiEnvironment, get_env_vars
from cikit.logging_utils import setup_logging

setup_logging()

env = CiEnvironment(get_env_vars())

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

result.check_returncode()
```

## Typical Project Structure

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

## CI Command Framework

Projects can define Python-based CI commands in a root-level `ci_commands` package.
The `cikit` console command discovers these commands automatically and provides
shared logging, status handling, environment initialization and error handling.

A minimal command module typically looks like this:

```python
import argparse

from cikit import CiSection
from cikit.ci import run_ci_script


def run(env, status, args: argparse.Namespace):
    """Run command logic."""
    with CiSection("Run custom step", status=status):
        ...


def command(args: argparse.Namespace) -> int:
    """Run command."""
    return run_ci_script("custom", lambda env, status: run(env, status, args), args=args)


def register(subparsers: argparse._SubParsersAction):
    """Register command."""
    parser = subparsers.add_parser("custom", help="Run custom CI step.")
    parser.set_defaults(func=command)
```

The default logical run name can be overridden globally:

```bash
cikit --name custom-run custom
```

## 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
* CI command framework
* lint reporting
* testing helpers
* coverage reporting
* Sphinx integration
* cikit data integration
* artifact management
* examples and recipes

## License

GPL-3.0-or-later
