# Pydantic GitLab
[](https://badge.fury.io/py/pydantic-gitlab)
[](https://pypi.org/project/pydantic-gitlab/)
[](https://github.com/johnlepikhin/pydantic-gitlab/actions)
[](https://opensource.org/licenses/MIT)
A modern Python library for parsing and validating GitLab CI YAML files using Pydantic dataclasses.
## Features
- ✅ Full support for GitLab CI YAML syntax
- 🔍 Comprehensive validation with helpful error messages
- 📦 Type-safe dataclasses for all GitLab CI structures
- 🐍 Python 3.9+ support
- 📝 Excellent IDE support with autocompletion
## Installation
```bash
pip install pydantic-gitlab
```
## Quick Start
```python
import yaml
from pydantic_gitlab import GitLabCI
# Load your .gitlab-ci.yml file
with open(".gitlab-ci.yml", "r") as f:
yaml_content = yaml.safe_load(f)
# Parse and validate
try:
ci_config = GitLabCI(**yaml_content)
print("✅ Valid GitLab CI configuration!")
# Access configuration
for job_name, job in ci_config.jobs.items():
print(f"Job: {job_name}")
print(f" Stage: {job.stage}")
print(f" Script: {job.script}")
except Exception as e:
print(f"❌ Invalid configuration: {e}")
```
## Supported GitLab CI Features
- ✅ Jobs with all keywords (script, image, services, artifacts, etc.)
- ✅ Stages and dependencies
- ✅ Rules and conditions
- ✅ Variables (global and job-level)
- ✅ Include configurations
- ✅ Workflow rules
- ✅ Caching
- ✅ Artifacts and reports
- ✅ Environments and deployments
- ✅ Parallel jobs and matrix builds
- ✅ Trigger jobs
- ✅ Pages job
## Example
```python
from pydantic_gitlab import GitLabCI, GitLabCIJob, WhenType
# Create a job programmatically
build_job = GitLabCIJob(
stage="build",
script=["echo 'Building...'", "make build"],
artifacts={
"paths": ["dist/"],
"expire_in": "1 week"
}
)
# Create CI configuration
ci = GitLabCI(
stages=["build", "test", "deploy"],
variables={"DOCKER_DRIVER": "overlay2"}
)
# Add job to configuration
ci.add_job("build", build_job)
# Validate dependencies
errors = ci.validate_job_dependencies()
if errors:
for error in errors:
print(f"Error: {error}")
```
## Why Pydantic GitLab?
### Comparison with Plain YAML Parsing
Using plain YAML parsing:
```python
import yaml
# Plain YAML - no validation, no type hints
with open(".gitlab-ci.yml") as f:
config = yaml.safe_load(f)
# Risky - might fail at runtime
job_script = config["build"]["script"] # KeyError?
job_image = config["build"]["image"] # KeyError?
```
Using Pydantic GitLab:
```python
from pydantic_gitlab import GitLabCI
# Type-safe with validation
with open(".gitlab-ci.yml") as f:
data = yaml.safe_load(f)
ci = GitLabCI(**data)
# IDE autocompletion, type checking
if build_job := ci.get_job("build"):
print(build_job.script) # Guaranteed to exist
print(build_job.image) # Optional[str] - might be None
```
### Benefits
- **🛡️ Validation**: Catch configuration errors before running pipelines
- **🔍 Type Safety**: Full type hints for better IDE support and fewer runtime errors
- **📝 Documentation**: Each field is documented with GitLab CI reference
- **🚀 Productivity**: Autocomplete for all GitLab CI keywords
- **🧪 Testing**: Easily create and validate CI configurations in tests
## Development
### Setup
```bash
# Clone the repository
git clone https://github.com/johnlepikhin/pydantic-gitlab.git
cd pydantic-gitlab
# Install in development mode
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
```
### Running Tests
```bash
pytest
```
### Code Quality
```bash
# Run linting
ruff check .
# Run type checking
mypy src
# Format code
ruff format .
```
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": null,
"name": "pydantic-gitlab",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ci-cd, continuous-integration, devops, gitlab, gitlab-ci, gitlab-pipeline, parser, pydantic, type-safety, validation, yaml",
"author": null,
"author_email": "Evgenii Lepikhin <johnlepikhin@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c1/ba/280586fed650a3d54c671374ec9a5297754074492e81a786f7fe1a37794e/pydantic_gitlab-0.2.5.tar.gz",
"platform": null,
"description": "# Pydantic GitLab\n\n[](https://badge.fury.io/py/pydantic-gitlab)\n[](https://pypi.org/project/pydantic-gitlab/)\n[](https://github.com/johnlepikhin/pydantic-gitlab/actions)\n[](https://opensource.org/licenses/MIT)\n\nA modern Python library for parsing and validating GitLab CI YAML files using Pydantic dataclasses.\n\n## Features\n\n- \u2705 Full support for GitLab CI YAML syntax\n- \ud83d\udd0d Comprehensive validation with helpful error messages\n- \ud83d\udce6 Type-safe dataclasses for all GitLab CI structures\n- \ud83d\udc0d Python 3.9+ support\n- \ud83d\udcdd Excellent IDE support with autocompletion\n\n## Installation\n\n```bash\npip install pydantic-gitlab\n```\n\n## Quick Start\n\n```python\nimport yaml\nfrom pydantic_gitlab import GitLabCI\n\n# Load your .gitlab-ci.yml file\nwith open(\".gitlab-ci.yml\", \"r\") as f:\n yaml_content = yaml.safe_load(f)\n\n# Parse and validate\ntry:\n ci_config = GitLabCI(**yaml_content)\n print(\"\u2705 Valid GitLab CI configuration!\")\n \n # Access configuration\n for job_name, job in ci_config.jobs.items():\n print(f\"Job: {job_name}\")\n print(f\" Stage: {job.stage}\")\n print(f\" Script: {job.script}\")\n \nexcept Exception as e:\n print(f\"\u274c Invalid configuration: {e}\")\n```\n\n## Supported GitLab CI Features\n\n- \u2705 Jobs with all keywords (script, image, services, artifacts, etc.)\n- \u2705 Stages and dependencies\n- \u2705 Rules and conditions\n- \u2705 Variables (global and job-level)\n- \u2705 Include configurations\n- \u2705 Workflow rules\n- \u2705 Caching\n- \u2705 Artifacts and reports\n- \u2705 Environments and deployments\n- \u2705 Parallel jobs and matrix builds\n- \u2705 Trigger jobs\n- \u2705 Pages job\n\n## Example\n\n```python\nfrom pydantic_gitlab import GitLabCI, GitLabCIJob, WhenType\n\n# Create a job programmatically\nbuild_job = GitLabCIJob(\n stage=\"build\",\n script=[\"echo 'Building...'\", \"make build\"],\n artifacts={\n \"paths\": [\"dist/\"],\n \"expire_in\": \"1 week\"\n }\n)\n\n# Create CI configuration\nci = GitLabCI(\n stages=[\"build\", \"test\", \"deploy\"],\n variables={\"DOCKER_DRIVER\": \"overlay2\"}\n)\n\n# Add job to configuration\nci.add_job(\"build\", build_job)\n\n# Validate dependencies\nerrors = ci.validate_job_dependencies()\nif errors:\n for error in errors:\n print(f\"Error: {error}\")\n```\n\n## Why Pydantic GitLab?\n\n### Comparison with Plain YAML Parsing\n\nUsing plain YAML parsing:\n```python\nimport yaml\n\n# Plain YAML - no validation, no type hints\nwith open(\".gitlab-ci.yml\") as f:\n config = yaml.safe_load(f)\n \n# Risky - might fail at runtime\njob_script = config[\"build\"][\"script\"] # KeyError?\njob_image = config[\"build\"][\"image\"] # KeyError?\n```\n\nUsing Pydantic GitLab:\n```python\nfrom pydantic_gitlab import GitLabCI\n\n# Type-safe with validation\nwith open(\".gitlab-ci.yml\") as f:\n data = yaml.safe_load(f)\nci = GitLabCI(**data)\n\n# IDE autocompletion, type checking\nif build_job := ci.get_job(\"build\"):\n print(build_job.script) # Guaranteed to exist\n print(build_job.image) # Optional[str] - might be None\n```\n\n### Benefits\n\n- **\ud83d\udee1\ufe0f Validation**: Catch configuration errors before running pipelines\n- **\ud83d\udd0d Type Safety**: Full type hints for better IDE support and fewer runtime errors\n- **\ud83d\udcdd Documentation**: Each field is documented with GitLab CI reference\n- **\ud83d\ude80 Productivity**: Autocomplete for all GitLab CI keywords\n- **\ud83e\uddea Testing**: Easily create and validate CI configurations in tests\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/johnlepikhin/pydantic-gitlab.git\ncd pydantic-gitlab\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Quality\n\n```bash\n# Run linting\nruff check .\n\n# Run type checking\nmypy src\n\n# Format code\nruff format .\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bugtrack_url": null,
"license": null,
"summary": "Pydantic models for parsing and validating GitLab CI/CD YAML configuration files",
"version": "0.2.5",
"project_urls": {
"Documentation": "https://pydantic-gitlab.readthedocs.io",
"Homepage": "https://github.com/johnlepikhin/pydantic-gitlab",
"Issues": "https://github.com/johnlepikhin/pydantic-gitlab/issues",
"Repository": "https://github.com/johnlepikhin/pydantic-gitlab"
},
"split_keywords": [
"ci-cd",
" continuous-integration",
" devops",
" gitlab",
" gitlab-ci",
" gitlab-pipeline",
" parser",
" pydantic",
" type-safety",
" validation",
" yaml"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "da2531143d069e5499fd1e8377ff907e364fe757998fffd9072844abe5343697",
"md5": "f875ab63a83b21a3ecabf71a5f6f4825",
"sha256": "71b8370f6607743cfcb402ec82d9cf5565e1ac4e4c53ece252a0398598a64ba3"
},
"downloads": -1,
"filename": "pydantic_gitlab-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f875ab63a83b21a3ecabf71a5f6f4825",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 30757,
"upload_time": "2025-08-28T17:29:47",
"upload_time_iso_8601": "2025-08-28T17:29:47.191127Z",
"url": "https://files.pythonhosted.org/packages/da/25/31143d069e5499fd1e8377ff907e364fe757998fffd9072844abe5343697/pydantic_gitlab-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c1ba280586fed650a3d54c671374ec9a5297754074492e81a786f7fe1a37794e",
"md5": "f56d772b2fab975d69c9294df01279a9",
"sha256": "514a484a9026da4646ee552c6703ab3173cd38cf9cd75760feee32dfac2c201e"
},
"downloads": -1,
"filename": "pydantic_gitlab-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "f56d772b2fab975d69c9294df01279a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 22747,
"upload_time": "2025-08-28T17:29:48",
"upload_time_iso_8601": "2025-08-28T17:29:48.509627Z",
"url": "https://files.pythonhosted.org/packages/c1/ba/280586fed650a3d54c671374ec9a5297754074492e81a786f7fe1a37794e/pydantic_gitlab-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 17:29:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "johnlepikhin",
"github_project": "pydantic-gitlab",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pydantic-gitlab"
}
JSON
