Metadata-Version: 2.4
Name: itw_python_builder
Version: 0.1.0
Summary: Standardized Django deployment pipeline with Docker, testing, and SonarQube integration
Author-email: IT-Works <contact@it-works.io>
License: MIT
Project-URL: Homepage, https://git.it-works.io/
Project-URL: Repository, https://git.it-works.io/
Project-URL: Issues, https://git.it-works.io/
Keywords: django,deployment,docker,ci-cd,sonarqube
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: invoke>=2.0.0
Requires-Dist: pylint>=3.0.0
Requires-Dist: pylint-django>=2.5.0
Dynamic: license-file

# ITW Python Builder

Standardized Django deployment pipeline with Docker, testing, SonarQube integration, automatic changelog generation, and code quality enforcement.

## Features

- Automated deployment with semantic versioning
- Docker/Podman-based build and push pipeline
- Automated testing with coverage
- SonarQube static code analysis
- Pylint linting with SonarQube integration
- Quality gates - deploy only when tests pass
- Automatic changelog generation from commit trailers
- Support for local and production pipelines
- Global CLI tool
- Automatic venv detection per project

## Installation
```bash
pip install itw_python_builder
```

Install globally (outside any project venv). The `itw` command becomes available system-wide.

## Quick Start

1. Navigate to your Django project directory (must have a `.venv` or `venv`):

2. Initialize versioning:
```bash
itw tag-init
```

3. Run local pipeline:
```bash
itw pipelinelocal
```

4. Deploy to staging:
```bash
itw incrementrc
```

5. Deploy to production:
```bash
itw incrementpatch
```

## Available Commands

### Deployment Commands

- `itw incrementpatch` — Increment patch version and deploy
- `itw incrementminor` — Increment minor version and deploy
- `itw incrementmajor` — Increment major version and deploy
- `itw incrementrc` — Increment release candidate (staging)
- `itw release` — Promote RC to stable release (master)

### Local Development Commands

- `itw pipelinelocal` — Run full local pipeline (lint → test → analyze → build)
- `itw lintlocal` — Run pylint with human-readable output
- `itw lint` — Run pylint and generate SonarQube report files
- `itw buildlocal` — Build Docker image locally
- `itw testlocal` — Run tests locally
- `itw analyzelocal` — Run SonarQube analysis locally
- `itw changelog` — Generate changelog manually
- `itw tag-init` — Initialize version tagging

### Skip Pipeline
```bash
itw incrementpatch --skip-pipeline
```

## Virtual Environment Detection

`itw` is installed globally but automatically detects the project's virtual environment (`.venv` or `venv`) in the current directory. Tasks that need Python/Django dependencies (test, lint, analyze) activate the venv automatically — no need to manually activate it.

If no venv is found, those tasks will error with a clear message. Tasks that only use git (like `changelog`, `tag-init`, `buildlocal`) work without a venv.

## Linting

The pipeline runs pylint automatically on every deployment and generates report files for SonarQube. The `.pylintrc` configuration is shipped with the package — no config files needed in your project.
```bash
# Review issues with human-readable output
itw lintlocal

# Generate report files for SonarQube
itw lint
```

Add this to your `sonar-project.properties`:
```properties
sonar.python.pylint.reportPaths=pylint-report.txt
```

## Changelog Generation

Changelog entries are generated automatically on every deployment based on commit messages. To categorize a commit, add a `Changelog:` trailer to the commit body:
```
add user authentication

Changelog: added
```

Available categories: `added`, `fixed`, `changed`, `deprecated`, `removed`, `security`, `performance`, `tests`, `docs`, `refactor`

Commits without a trailer appear under `Other Changes`. The `CHANGELOG.md` file is committed and pushed automatically with each deployment.

## Requirements

- Python 3.10+
- Podman
- Git
- SonarQube server

## Configuration

### Environment Variables

Add to your project `.env`:
```
SONAR_HOST_URL=https://your-sonar-server
SONAR_TOKEN=your-token
GIT_DEPTH=0
```

### Project Files Required

- Git repository with `develop`, `staging`, and `master` branches
- `VERSION` file in project root
- `Dockerfile`
- `sonar-project.properties`

## License

MIT
