# 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/98/06/23a75e6975253ef3b053e4217b2794580f925e3e4f403b23504cf416a125/pydantic_gitlab-0.2.3.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.3",
"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": "79ec21bdd0dd845d5dc81ef1e73f19777c7d2c1f9a70ff47985dc08f9868ddbe",
"md5": "313d16747a5bedf087529fc20b02ce2a",
"sha256": "bd1b607583f01cf3b82ef54984864b4d334ad1360bf0c0a7006522cdba3f5027"
},
"downloads": -1,
"filename": "pydantic_gitlab-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "313d16747a5bedf087529fc20b02ce2a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 30356,
"upload_time": "2025-08-02T10:52:41",
"upload_time_iso_8601": "2025-08-02T10:52:41.360419Z",
"url": "https://files.pythonhosted.org/packages/79/ec/21bdd0dd845d5dc81ef1e73f19777c7d2c1f9a70ff47985dc08f9868ddbe/pydantic_gitlab-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "980623a75e6975253ef3b053e4217b2794580f925e3e4f403b23504cf416a125",
"md5": "a011bc64b6f75fd98a4bfbb49d50c745",
"sha256": "61c4a0ee8179824dd99a6421ed620a27c71783de71c1bf1108ee42df37200635"
},
"downloads": -1,
"filename": "pydantic_gitlab-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "a011bc64b6f75fd98a4bfbb49d50c745",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 22355,
"upload_time": "2025-08-02T10:52:42",
"upload_time_iso_8601": "2025-08-02T10:52:42.569445Z",
"url": "https://files.pythonhosted.org/packages/98/06/23a75e6975253ef3b053e4217b2794580f925e3e4f403b23504cf416a125/pydantic_gitlab-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 10:52:42",
"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
