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

gitlab_cicd_python_wrapper/__init__.py

@@ -0,0 +1,99 @@
+"""Gitlab CICD Python Wrapper - Pydantic models for GitLab CI/CD YAML."""
+
+__version__ = "0.1.0"
+
+from gitlab_cicd_python_wrapper._async import AsyncComponent, AsyncPipeline
+from gitlab_cicd_python_wrapper.artifacts import ArtifactReports, Artifacts
+from gitlab_cicd_python_wrapper.cache import Cache, CacheKey
+from gitlab_cicd_python_wrapper.common import (
+    ArtifactAccess,
+    ArtifactWhen,
+    AutoCancelOnJobFailure,
+    AutoCancelOnNewCommit,
+    CachePolicy,
+    CacheWhen,
+    DeploymentTier,
+    EnvironmentAction,
+    InputType,
+    RetryWhen,
+    WhenCondition,
+)
+from gitlab_cicd_python_wrapper.component import Component
+from gitlab_cicd_python_wrapper.environment import Environment
+from gitlab_cicd_python_wrapper.globals import AutoCancel, Default, Workflow
+from gitlab_cicd_python_wrapper.image import Image, Service
+from gitlab_cicd_python_wrapper.include import (
+    ComponentReference,
+    IncludeComponent,
+    IncludeItem,
+    IncludeLocal,
+    IncludeProject,
+    IncludeRemote,
+    IncludeTemplate,
+)
+from gitlab_cicd_python_wrapper.job import AllowFailure, Inherit, Job, Parallel
+from gitlab_cicd_python_wrapper.needs import Need, NeedsPipeline
+from gitlab_cicd_python_wrapper.pages import Pages
+from gitlab_cicd_python_wrapper.pipeline import Pipeline
+from gitlab_cicd_python_wrapper.release import Release
+from gitlab_cicd_python_wrapper.retry import Retry
+from gitlab_cicd_python_wrapper.rules import Rule, WorkflowRule
+from gitlab_cicd_python_wrapper.secrets import Secret, VaultConfig, VaultEngine
+from gitlab_cicd_python_wrapper.spec import ComponentInput, ComponentSpec, InputRule
+from gitlab_cicd_python_wrapper.trigger import Trigger, TriggerForward
+from gitlab_cicd_python_wrapper.variables import Variable
+
+__all__ = [
+    "AllowFailure",
+    "ArtifactAccess",
+    "ArtifactReports",
+    "ArtifactWhen",
+    "Artifacts",
+    "AsyncComponent",
+    "AsyncPipeline",
+    "AutoCancel",
+    "AutoCancelOnJobFailure",
+    "AutoCancelOnNewCommit",
+    "Cache",
+    "CacheKey",
+    "CachePolicy",
+    "CacheWhen",
+    "Component",
+    "ComponentInput",
+    "ComponentReference",
+    "ComponentSpec",
+    "Default",
+    "DeploymentTier",
+    "Environment",
+    "EnvironmentAction",
+    "Image",
+    "IncludeComponent",
+    "IncludeItem",
+    "IncludeLocal",
+    "IncludeProject",
+    "IncludeRemote",
+    "IncludeTemplate",
+    "Inherit",
+    "InputRule",
+    "InputType",
+    "Job",
+    "Need",
+    "NeedsPipeline",
+    "Pages",
+    "Parallel",
+    "Pipeline",
+    "Release",
+    "Retry",
+    "RetryWhen",
+    "Rule",
+    "Secret",
+    "Service",
+    "Trigger",
+    "TriggerForward",
+    "Variable",
+    "VaultConfig",
+    "VaultEngine",
+    "WhenCondition",
+    "Workflow",
+    "WorkflowRule",
+]

gitlab_cicd_python_wrapper/_async.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import aiofiles
+
+from gitlab_cicd_python_wrapper.component import Component
+from gitlab_cicd_python_wrapper.pipeline import Pipeline
+
+
+class AsyncPipeline:
+    @classmethod
+    async def from_yaml(cls, source: str | Path) -> Pipeline:
+        if isinstance(source, Path):
+            async with aiofiles.open(source) as f:
+                content = await f.read()
+            return Pipeline.from_yaml(content)
+        return Pipeline.from_yaml(source)
+
+    @classmethod
+    async def to_yaml(cls, pipeline: Pipeline, target: str | Path | None = None) -> str:
+        result = pipeline.to_yaml()
+        if target is not None:
+            async with aiofiles.open(target, "w") as f:
+                await f.write(result)
+        return result
+
+    @classmethod
+    async def validate_file(cls, path: Path) -> list[str]:
+        async with aiofiles.open(path) as f:
+            content = await f.read()
+        return Pipeline.validate_file_from_string(content)
+
+
+class AsyncComponent:
+    @classmethod
+    async def from_yaml(cls, source: str | Path) -> Component:
+        if isinstance(source, Path):
+            async with aiofiles.open(source) as f:
+                content = await f.read()
+            return Component.from_yaml(content)
+        return Component.from_yaml(source)
+
+    @classmethod
+    async def to_yaml(cls, component: Component, target: str | Path | None = None) -> str:
+        result = component.to_yaml()
+        if target is not None:
+            async with aiofiles.open(target, "w") as f:
+                await f.write(result)
+        return result

gitlab_cicd_python_wrapper/artifacts.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from gitlab_cicd_python_wrapper.common import ArtifactAccess, ArtifactWhen
+
+
+class ArtifactReports(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    junit: list[str] | str | None = None
+    coverage_report: dict[str, str] | None = None
+    codequality: list[str] | str | None = None
+    sast: list[str] | str | None = None
+    dependency_scanning: list[str] | str | None = None
+    container_scanning: list[str] | str | None = None
+    dast: list[str] | str | None = None
+    license_scanning: list[str] | str | None = None
+    performance: list[str] | str | None = None
+    dotenv: list[str] | str | None = None
+    terraform: list[str] | str | None = None
+    metrics: list[str] | str | None = None
+    requirements: list[str] | str | None = None
+    secret_detection: list[str] | str | None = None
+    cyclonedx: list[str] | str | None = None
+
+
+class Artifacts(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    paths: list[str] | None = None
+    exclude: list[str] | None = None
+    expire_in: str | None = None
+    expose_as: str | None = None
+    name: str | None = None
+    public: bool | None = None
+    access: ArtifactAccess | None = None
+    reports: ArtifactReports | None = None
+    untracked: bool | None = None
+    when: ArtifactWhen | None = None

gitlab_cicd_python_wrapper/cache.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from gitlab_cicd_python_wrapper.common import CachePolicy, CacheWhen
+
+
+class CacheKey(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    files: list[str] | None = None
+    files_commits: list[str] | None = None
+    prefix: str | None = None
+
+
+class Cache(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    paths: list[str] | None = None
+    key: str | CacheKey | None = None
+    untracked: bool | None = None
+    unprotect: bool | None = None
+    when: CacheWhen | None = None
+    policy: CachePolicy | None = None
+    fallback_keys: list[str] | None = None

gitlab_cicd_python_wrapper/cli.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from gitlab_cicd_python_wrapper import __version__
+from gitlab_cicd_python_wrapper.component import Component
+from gitlab_cicd_python_wrapper.pipeline import Pipeline
+
+
+def _validate_pipeline(path: Path) -> list[str]:
+    return Pipeline.validate_file(path)
+
+
+def _validate_component(path: Path) -> list[str]:
+    return Component.validate_file(path)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="gitlab-cicd-validate",
+        description="Validate GitLab CI/CD YAML files",
+    )
+    parser.add_argument("files", nargs="+", type=Path, help="YAML files to validate")
+    parser.add_argument("--strict", action="store_true", help="Enable strict validation")
+    parser.add_argument("--component", action="store_true", help="Validate as component")
+    parser.add_argument(
+        "--format", choices=["text", "json"], default="text", dest="output_format", help="Output format"
+    )
+    parser.add_argument("--quiet", action="store_true", help="Suppress output on success")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    args = parser.parse_args()
+
+    all_valid = True
+    results: list[dict] = []
+
+    for file_path in args.files:
+        if args.component:
+            errors = _validate_component(file_path)
+        else:
+            errors = _validate_pipeline(file_path)
+
+        valid = len(errors) == 0
+        if not valid:
+            all_valid = False
+
+        result = {"file": str(file_path), "valid": valid, "errors": errors}
+        results.append(result)
+
+    if args.output_format == "json":
+        print(json.dumps(results, indent=2))
+    elif not args.quiet:
+        for result in results:
+            if result["valid"]:
+                print(f"{result['file']}: valid")
+            else:
+                print(f"{result['file']}: invalid")
+                for error in result["errors"]:
+                    print(f"  - {error}")
+    elif not all_valid:
+        for result in results:
+            if not result["valid"]:
+                print(f"{result['file']}: invalid")
+                for error in result["errors"]:
+                    print(f"  - {error}")
+
+    return 0 if all_valid else 1

gitlab_cicd_python_wrapper/common.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class WhenCondition(str, Enum):
+    on_success = "on_success"
+    on_failure = "on_failure"
+    always = "always"
+    never = "never"
+    manual = "manual"
+    delayed = "delayed"
+
+
+class CachePolicy(str, Enum):
+    pull = "pull"
+    push = "push"
+    pull_push = "pull-push"
+
+
+class CacheWhen(str, Enum):
+    on_success = "on_success"
+    on_failure = "on_failure"
+    always = "always"
+
+
+class ArtifactWhen(str, Enum):
+    on_success = "on_success"
+    on_failure = "on_failure"
+    always = "always"
+
+
+class ArtifactAccess(str, Enum):
+    all = "all"
+    developer = "developer"
+    maintainer = "maintainer"
+    none = "none"
+
+
+class RetryWhen(str, Enum):
+    always = "always"
+    unknown_failure = "unknown_failure"
+    script_failure = "script_failure"
+    api_failure = "api_failure"
+    stuck_or_timeout_failure = "stuck_or_timeout_failure"
+    runner_system_failure = "runner_system_failure"
+    missing_dependency_failure = "missing_dependency_failure"
+    runner_unsupported = "runner_unsupported"
+    stale_schedule = "stale_schedule"
+    job_execution_timeout = "job_execution_timeout"
+    archived_failure = "archived_failure"
+    unmet_prerequisites = "unmet_prerequisites"
+    scheduler_failure = "scheduler_failure"
+    data_integrity_failure = "data_integrity_failure"
+
+
+class DeploymentTier(str, Enum):
+    production = "production"
+    staging = "staging"
+    testing = "testing"
+    development = "development"
+    other = "other"
+
+
+class EnvironmentAction(str, Enum):
+    start = "start"
+    stop = "stop"
+    prepare = "prepare"
+    rollback = "rollback"
+
+
+class AutoCancelOnNewCommit(str, Enum):
+    conservative = "conservative"
+    interruptible = "interruptible"
+    none = "none"
+
+
+class AutoCancelOnJobFailure(str, Enum):
+    all = "all"
+    none = "none"
+
+
+class InputType(str, Enum):
+    string = "string"
+    number = "number"
+    boolean = "boolean"
+    array = "array"

gitlab_cicd_python_wrapper/component.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from gitlab_cicd_python_wrapper.pipeline import Pipeline
+
+from pydantic import BaseModel, ConfigDict
+
+from gitlab_cicd_python_wrapper.common import InputType
+from gitlab_cicd_python_wrapper.job import Job
+from gitlab_cicd_python_wrapper.serialization import dump_yaml_multi, load_yaml_multi
+from gitlab_cicd_python_wrapper.spec import ComponentSpec
+
+INPUT_INTERPOLATION_RE = re.compile(r"\$\[\[\s*inputs\.(\w+)\s*\]\]")
+COMPONENT_INTERPOLATION_RE = re.compile(r"\$\[\[\s*component\.(\w+)\s*\]\]")
+_INTERPOLATION_RE = re.compile(r"\$\[\[.+?\]\]")
+
+
+def _strip_interpolation_fields(raw_job: dict) -> dict:
+    stripped = {}
+    for k, v in raw_job.items():
+        if isinstance(v, str) and _INTERPOLATION_RE.fullmatch(v.strip()):
+            continue
+        stripped[k] = v
+    return stripped
+
+
+def _check_type(name: str, value: Any, expected: InputType) -> None:
+    type_map = {
+        InputType.string: str,
+        InputType.number: (int, float),
+        InputType.boolean: bool,
+        InputType.array: list,
+    }
+    expected_type = type_map[expected]
+    if not isinstance(value, expected_type):
+        raise ValueError(f"Input '{name}' must be of type {expected.value}, got {type(value).__name__}")
+
+
+class Component(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    spec: ComponentSpec
+    jobs: dict[str, Job]
+
+    _raws: list = []
+    _raw_jobs: dict[str, dict] = {}
+
+    @classmethod
+    def from_yaml(cls, source: str | Path) -> Component:
+        dicts, raws = load_yaml_multi(source)
+        if len(dicts) < 2:
+            raise ValueError("Component must have spec: section and job definitions separated by ---")
+        spec_data = dicts[0].get("spec", dicts[0])
+        spec = ComponentSpec.model_validate(spec_data)
+        job_data = dicts[1]
+        jobs = {}
+        raw_jobs = {}
+        for name, raw_job in job_data.items():
+            raw_jobs[name] = dict(raw_job) if hasattr(raw_job, "items") else raw_job
+            try:
+                jobs[name] = Job.model_validate(raw_job)
+            except Exception:
+                jobs[name] = Job.model_validate(_strip_interpolation_fields(raw_job))
+        component = cls(spec=spec, jobs=jobs)
+        component._raws = raws
+        component._raw_jobs = raw_jobs
+        return component
+
+    def validate_inputs(self, provided: dict[str, Any]) -> dict[str, Any]:
+        if self.spec.inputs is None:
+            if provided:
+                raise ValueError(f"Component accepts no inputs, but got: {list(provided.keys())}")
+            return {}
+        resolved = {}
+        for name, input_def in self.spec.inputs.items():
+            if name in provided:
+                value = provided[name]
+            elif input_def.default is not None:
+                value = input_def.default
+            else:
+                raise ValueError(f"Input '{name}' is required (no default provided)")
+            _check_type(name, value, input_def.type)
+            if input_def.options is not None and value not in input_def.options:
+                raise ValueError(f"Input '{name}' value '{value}' must be one of: {input_def.options}")
+            if input_def.regex is not None and isinstance(value, str):
+                if not re.match(input_def.regex, value):
+                    raise ValueError(f"Input '{name}' value '{value}' does not match regex: {input_def.regex}")
+            resolved[name] = value
+        extra = set(provided) - set(self.spec.inputs)
+        if extra:
+            raise ValueError(f"Unknown inputs: {extra}")
+        return resolved
+
+    def render(self, inputs: dict[str, Any]) -> "Pipeline":
+        from gitlab_cicd_python_wrapper.pipeline import Pipeline
+
+        resolved = self.validate_inputs(inputs)
+
+        def interpolate(value: Any) -> Any:
+            if isinstance(value, str):
+
+                def replace_input(m: re.Match) -> str:
+                    key = m.group(1)
+                    v = resolved.get(key, m.group(0))
+                    return str(v) if not isinstance(v, str) else v
+
+                return INPUT_INTERPOLATION_RE.sub(replace_input, value)
+            if isinstance(value, list):
+                return [interpolate(v) for v in value]
+            if isinstance(value, dict):
+                return {k: interpolate(v) for k, v in value.items()}
+            return value
+
+        raw_source = (
+            self._raw_jobs
+            if self._raw_jobs
+            else {n: j.model_dump(exclude_none=True, by_alias=True) for n, j in self.jobs.items()}
+        )
+        jobs = {}
+        for name, raw_job in raw_source.items():
+            job_data = interpolate(raw_job)
+            jobs[name] = Job.model_validate(job_data)
+        return Pipeline(jobs=jobs)
+
+    def to_yaml(self, target: str | Path | None = None) -> str:
+        if self._raws:
+            return dump_yaml_multi(self._raws, target)
+        raise NotImplementedError("to_yaml from constructed Component not yet supported")
+
+    @classmethod
+    def validate_file(cls, path: Path) -> list[str]:
+        try:
+            cls.from_yaml(path)
+            return []
+        except Exception as e:
+            return [str(e)]
+
+    @classmethod
+    def validate_file_from_string(cls, content: str) -> list[str]:
+        try:
+            cls.from_yaml(content)
+            return []
+        except Exception as e:
+            return [str(e)]

gitlab_cicd_python_wrapper/environment.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from gitlab_cicd_python_wrapper.common import DeploymentTier, EnvironmentAction
+
+
+class EnvironmentKubernetes(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    namespace: str | None = None
+
+
+class Environment(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    name: str
+    url: str | None = None
+    deployment_tier: DeploymentTier | None = None
+    auto_stop_in: str | None = None
+    action: EnvironmentAction | None = None
+    kubernetes: EnvironmentKubernetes | None = None

gitlab_cicd_python_wrapper/globals.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from gitlab_cicd_python_wrapper.artifacts import Artifacts
+from gitlab_cicd_python_wrapper.cache import Cache
+from gitlab_cicd_python_wrapper.common import (
+    AutoCancelOnJobFailure,
+    AutoCancelOnNewCommit,
+)
+from gitlab_cicd_python_wrapper.image import Image, Service
+from gitlab_cicd_python_wrapper.retry import Retry
+from gitlab_cicd_python_wrapper.rules import WorkflowRule
+
+
+class Default(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    after_script: list[str] | None = None
+    artifacts: Artifacts | None = None
+    before_script: list[str] | None = None
+    cache: Cache | list[Cache] | None = None
+    hooks: dict[str, list[str]] | None = None
+    id_tokens: dict[str, dict[str, str]] | None = None
+    image: str | Image | None = None
+    interruptible: bool | None = None
+    retry: int | Retry | None = None
+    services: list[str | Service] | None = None
+    tags: list[str] | None = None
+
+
+class AutoCancel(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    on_new_commit: AutoCancelOnNewCommit | None = None
+    on_job_failure: AutoCancelOnJobFailure | None = None
+
+
+class Workflow(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    name: str | None = None
+    rules: list[WorkflowRule] | None = None
+    auto_cancel: AutoCancel | None = None

gitlab_cicd_python_wrapper/image.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Image(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    name: str
+    entrypoint: list[str] | str | None = None
+    pull_policy: str | None = None
+
+
+class Service(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    name: str
+    alias: str | None = None
+    entrypoint: list[str] | str | None = None
+    command: list[str] | str | None = None
+    pull_policy: str | None = None
+    variables: dict[str, str] | None = None

gitlab_cicd_python_wrapper/include.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Any, Union
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ComponentReference(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    fqdn: str
+    project_path: str
+    component_name: str
+    version: str
+
+    @classmethod
+    def from_string(cls, ref: str) -> ComponentReference:
+        base, version = ref.split("@", 1)
+        parts = base.split("/")
+        return cls(
+            fqdn=parts[0],
+            component_name=parts[-1],
+            project_path="/".join(parts[1:-1]),
+            version=version,
+        )
+
+
+class IncludeLocal(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    local: str
+    inputs: dict[str, Any] | None = None
+    rules: list[dict[str, Any]] | None = None
+
+
+class IncludeRemote(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    remote: str
+    inputs: dict | None = None
+    rules: list[dict] | None = None
+    integrity: str | None = None
+    cache: bool | str | None = None
+
+
+class IncludeTemplate(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    template: str
+    inputs: dict | None = None
+
+
+class IncludeProject(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    project: str
+    file: str | list[str] | None = None
+    ref: str | None = None
+    inputs: dict | None = None
+    rules: list[dict] | None = None
+
+
+class IncludeComponent(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    component: str
+    inputs: dict | None = None
+    rules: list[dict] | None = None
+
+    @property
+    def parsed_ref(self) -> ComponentReference:
+        return ComponentReference.from_string(self.component)
+
+
+IncludeItem = Union[IncludeLocal, IncludeRemote, IncludeTemplate, IncludeProject, IncludeComponent]