gitlab-cicd-python-wrapper 0.1.0__py3-none-any.whl

gitlab_cicd_python_wrapper-0.1.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: gitlab-cicd-python-wrapper
+Version: 0.1.0
+Summary: Pydantic models wrapping GitLab CI/CD YAML with 1:1 mapping
+License: MIT
+Author: Szymon Richert
+Author-email: szymon.rychu@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: aiofiles (>=24.0,<25.0)
+Requires-Dist: pydantic (>=2.0,<3.0)
+Requires-Dist: ruamel.yaml (>=0.18,<0.19)
+Description-Content-Type: text/markdown
+
+# Gitlab CICD Python Wrapper
+
+Pydantic models wrapping every GitLab CI/CD YAML keyword with 1:1 mapping to
+[GitLab CI/CD YAML reference](https://docs.gitlab.com/ci/yaml/).
+
+## Features
+
+- Programmatic pipeline generation using Python-native objects
+- Validation framework for existing pipelines
+- Comment-preserving round-trip serialization (load -> validate -> write = identical YAML)
+- GitLab CI/CD Component parsing with input validation
+- Both sync and async APIs
+- CLI validator and pre-commit hook
+
+## Installation
+
+```bash
+pip install gitlab-cicd-python-wrapper
+```
+
+Or with Poetry:
+
+```bash
+poetry add gitlab-cicd-python-wrapper
+```
+
+## Compatibility Matrix
+
+| GitLab Version | Pipeline Coverage | Component Coverage | Notes |
+|----------------|-------------------|-------------------|-------|
+| 17.x           | Full              | Full              | All keywords as of 17.9 |
+| 16.x           | Full              | Partial           | Components GA in 17.0 |
+| 15.x           | Partial           | N/A               | Deprecated keywords still accepted |
+
+## Quick Start
+
+### Generate a Pipeline
+
+```python
+from gitlab_cicd_python_wrapper import Pipeline, Job, Image, Artifacts
+
+pipeline = Pipeline(
+    stages=["build", "test", "deploy"],
+    jobs={
+        "build": Job(
+            stage="build",
+            image=Image(name="python:3.11"),
+            script=["pip install -r requirements.txt", "python setup.py build"],
+            artifacts=Artifacts(paths=["dist/"]),
+        ),
+        "test": Job(
+            stage="test",
+            script=["pytest"],
+            needs=["build"],
+        ),
+    },
+)
+
+print(pipeline.to_yaml())
+```
+
+### Validate an Existing Pipeline
+
+```python
+from gitlab_cicd_python_wrapper import Pipeline
+
+# Load and validate
+pipeline = Pipeline.from_yaml(".gitlab-ci.yml")
+print(f"Stages: {pipeline.stages}")
+print(f"Jobs: {list(pipeline.jobs.keys())}")
+
+# Validate without loading
+errors = Pipeline.validate_file(".gitlab-ci.yml")
+if errors:
+    for err in errors:
+        print(f"Error: {err}")
+```
+
+### Round-Trip Editing (Comments Preserved)
+
+```python
+from gitlab_cicd_python_wrapper import Pipeline
+
+# Load -> modify -> save preserves comments and formatting
+pipeline = Pipeline.from_yaml(".gitlab-ci.yml")
+pipeline.to_yaml("validated-output.yml")
+# Output is byte-identical to input for unmodified pipelines
+```
+
+## CLI Validator
+
+```bash
+# Validate pipeline files
+gitlab-cicd-validate .gitlab-ci.yml
+
+# Validate multiple files
+gitlab-cicd-validate .gitlab-ci.yml .gitlab/ci/*.yml
+
+# Validate component templates
+gitlab-cicd-validate --component templates/build.yml
+
+# JSON output
+gitlab-cicd-validate --format json .gitlab-ci.yml
+
+# Strict mode (fail on warnings)
+gitlab-cicd-validate --strict .gitlab-ci.yml
+```
+
+## Pre-commit Hook
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/szymonrychu/gitlab-cicd-python-wrapper
+    rev: v0.1.0
+    hooks:
+      - id: gitlab-cicd-validate
+        args: ['--strict']
+      - id: gitlab-cicd-validate-components
+```
+
+This validates `.gitlab-ci.yml` and any YAML files under `.gitlab/ci/` automatically,
+plus component templates under `templates/`.
+
+## Component Parsing
+
+Parse and validate GitLab CI/CD components with input validation:
+
+```python
+from gitlab_cicd_python_wrapper import Component
+
+# Load a component template
+component = Component.from_yaml("templates/deploy.yml")
+
+# Inspect the spec
+for name, input_def in component.spec.inputs.items():
+    print(f"{name}: type={input_def.type}, default={input_def.default}")
+
+# Validate inputs (raises ValueError on failure)
+resolved = component.validate_inputs({
+    "stage": "deploy",
+    "environment": "production",
+    "timeout": 3600,
+})
+
+# Render with inputs interpolated (returns a Pipeline)
+pipeline = component.render({
+    "stage": "deploy",
+    "environment": "production",
+    "timeout": 3600,
+})
+print(pipeline.to_yaml())
+```
+
+## Dynamic Child Pipelines
+
+Generate pipelines dynamically for use with `trigger:include`:
+
+```python
+from gitlab_cicd_python_wrapper import Pipeline, Job
+
+services = ["api", "web", "worker"]
+
+jobs = {}
+for svc in services:
+    jobs[f"build-{svc}"] = Job(
+        stage="build",
+        image="docker:latest",
+        script=[f"docker build -t {svc} services/{svc}/"],
+        tags=["docker"],
+    )
+
+child = Pipeline(stages=["build"], jobs=jobs)
+child.to_yaml("generated-pipeline.yml")
+
+# Parent pipeline triggers it:
+# trigger:
+#   include:
+#     - artifact: generated-pipeline.yml
+#       job: generate-pipeline
+```
+
+## Async API
+
+```python
+import asyncio
+from gitlab_cicd_python_wrapper import AsyncPipeline, AsyncComponent
+
+async def main():
+    # Pipeline
+    pipeline = await AsyncPipeline.from_yaml(".gitlab-ci.yml")
+    print(f"Stages: {pipeline.stages}")
+    print(f"Jobs: {list(pipeline.jobs.keys())}")
+    await AsyncPipeline.to_yaml(pipeline, "validated-output.yml")
+
+    # Component
+    component = await AsyncComponent.from_yaml("templates/build.yml")
+    resolved = component.validate_inputs({"image": "python:3.12"})
+
+asyncio.run(main())
+```
+
+## Docker
+
+Run the validator as a container:
+
+```bash
+docker run --rm -v $(pwd):/data szymonrychu/gitlab-cicd-python-wrapper /data/.gitlab-ci.yml
+```
+
+## PyPI Configuration
+
+To publish this library to PyPI using GitHub Actions trusted publishing:
+
+1. Create an account at [pypi.org](https://pypi.org)
+2. Go to "Your projects" -> "Publishing" -> "Add a new pending publisher"
+3. Set: GitHub owner=`szymonrychu`, repo=`gitlab-cicd-python-wrapper`,
+   workflow=`pypi.yaml`, environment=`pypi`
+4. Create a GitHub environment named `pypi` in your repo settings
+5. Push a semantic version tag (e.g., `v0.1.0`) to trigger the publish workflow
+
+## Development
+
+```bash
+# Install dependencies
+mise install
+poetry install
+
+# Run tests
+poetry run pytest
+
+# Run linters
+pre-commit run --all-files
+
+# Run CLI
+poetry run gitlab-cicd-validate .gitlab-ci.yml
+```
+
+## License
+
+MIT
+

gitlab_cicd_python_wrapper-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+gitlab_cicd_python_wrapper/__init__.py,sha256=izJGQLQYfNwlhT4CfQj2PkyaMyxPer_qJxGWsAqov4o,2729
+gitlab_cicd_python_wrapper/_async.py,sha256=4utMoYEjSw0hY0VLXggM-w8M_A2ZM7NylUDkFzNSj1Q,1640
+gitlab_cicd_python_wrapper/artifacts.py,sha256=9iHV_3x-auI5JOyBP1rxi829xxOIVJfL0CefpeqIrCs,1413
+gitlab_cicd_python_wrapper/cache.py,sha256=hh176DIj5_Ybt1wZyQvLWKxaDpo3we39FxpclOjgpbo,708
+gitlab_cicd_python_wrapper/cli.py,sha256=vLppAfcDCp2MscCgkgG89A-ZDAEnBJ0GqTkiqRFY_uM,2283
+gitlab_cicd_python_wrapper/common.py,sha256=sS2MWShEiFj0_HOKCEOy4jOY1-nedmfo74U61CcGyx4,1964
+gitlab_cicd_python_wrapper/component.py,sha256=6QGTFpndL-cZ3I-Zkmly6mKzG-UUI5u0UqgcIQ8Rukc,5518
+gitlab_cicd_python_wrapper/environment.py,sha256=OJlIJizqFFZCTcidGvkadxQeQd2RbWxoKjUAowDeig8,630
+gitlab_cicd_python_wrapper/globals.py,sha256=9TSMuwNCZEH49DAYsfcP289FjyHMsql86iQCE9iipyI,1452
+gitlab_cicd_python_wrapper/image.py,sha256=ZRN5-x59O3vdq8gjra24ySAZBqazRhZqEQnrHtuM0t4,579
+gitlab_cicd_python_wrapper/include.py,sha256=yw9Z5elalYbDR0i6-rSvseSh4mbglssJ_h19tLoK4aA,1910
+gitlab_cicd_python_wrapper/job.py,sha256=u7M6tZYr7NwjSA3jqyPbHn7zzbuk_-bkaKZigaCWAbE,3257
+gitlab_cicd_python_wrapper/needs.py,sha256=srle4kFGF2qKLLWJ3yxZpwIrjk4_9tq0d2RTL5Kv-wQ,423
+gitlab_cicd_python_wrapper/pages.py,sha256=bTnMPDhmxEgpiVP4Ugq7Y5xwWYaX8pdkkV5jMUbzp-k,239
+gitlab_cicd_python_wrapper/pipeline.py,sha256=UN5mByMH27gxmFt1pCXgFUFfVD_OgdopuWy46Hx8RdY,3146
+gitlab_cicd_python_wrapper/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gitlab_cicd_python_wrapper/release.py,sha256=T62NekMPNtBq83_-HQF46xj23Zv9YWHG6qgGqco5b-0,346
+gitlab_cicd_python_wrapper/retry.py,sha256=9a8C7KcBdXDmhE6_to3cVCiS64dgS71h_gjD4VLd6pI,312
+gitlab_cicd_python_wrapper/rules.py,sha256=Oeb38l_V13UCsodGqjIfou1kyQJ26bV46ilL9BQ0lDs,853
+gitlab_cicd_python_wrapper/secrets.py,sha256=XQfloQmdkIsJfMRjG7Ebayy4z0rWiOT1ILc0gQQqAR8,484
+gitlab_cicd_python_wrapper/serialization.py,sha256=uarKZy2CTYpiM9zsZjw87mxvRd-9dpn1wzQ3BlECrL4,1610
+gitlab_cicd_python_wrapper/spec.py,sha256=QFtpzSpulzHs8OD3mDcaGGXd2WBT-DinPV3Tbf9Hf_w,1960
+gitlab_cicd_python_wrapper/trigger.py,sha256=6_aFJ-dJJxT3of8GskHkfdzRc4xbCiFxDQe7cpDBqOg,612
+gitlab_cicd_python_wrapper/variables.py,sha256=3gGqgeNpEJXVIC_LqJe0JBYdj2lQzhTNdOF1n3G3uHY,296
+gitlab_cicd_python_wrapper-0.1.0.dist-info/METADATA,sha256=_ui1FIF7UqQu-yEgG2_B0elFCPeElDUrJpCOEJNsCnQ,6653
+gitlab_cicd_python_wrapper-0.1.0.dist-info/WHEEL,sha256=Vz2fHgx6HFtSwhs8KvkHLqH5Ea4w1_rner5uNVGCeIE,88
+gitlab_cicd_python_wrapper-0.1.0.dist-info/entry_points.txt,sha256=7NbmwUr5FV_UzfkTARFO7g9BaOBbUu9_wM7InnynvM8,76
+gitlab_cicd_python_wrapper-0.1.0.dist-info/RECORD,,

gitlab_cicd_python_wrapper-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.2
+Root-Is-Purelib: true
+Tag: py3-none-any

gitlab_cicd_python_wrapper-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+gitlab-cicd-validate=gitlab_cicd_python_wrapper.cli:main
+