itw-python-builder 0.1.0__py3-none-any.whl

itw_python_builder/__init__.py

@@ -0,0 +1,6 @@
+"""
+ITW Python Builder - Standardized Django deployment pipeline
+"""
+
+from .tasks import *
+from .version import Version

itw_python_builder/cli.py

@@ -0,0 +1,9 @@
+from invoke import Program, Collection
+
+from itw_python_builder import tasks
+
+
+def main():
+    namespace = Collection.from_module(tasks)
+    program = Program(namespace=namespace, name='itw')
+    program.run()

itw_python_builder/tasks.py

@@ -0,0 +1,429 @@
+from invoke import task, Context
+from itw_python_builder.version import Version
+import os
+from datetime import datetime
+from pathlib import Path
+
+PYLINTRC = Path(__file__).parent / ".pylintrc"
+_venv_activated = False
+
+def detect_and_activate_venv():
+    """Detect venv in current directory and prepend to PATH. Runs only once."""
+    global _venv_activated
+    if _venv_activated:
+        return
+
+    cwd = os.getcwd()
+    found = []
+    for venv_name in ['.venv', 'venv']:
+        venv_path = os.path.join(cwd, venv_name)
+        if os.path.isdir(venv_path):
+            bin_dir = os.path.join(venv_path, 'bin')
+            if os.path.isdir(bin_dir):
+                found.append(venv_path)
+
+    if len(found) == 0:
+        raise RuntimeError(
+            'No virtual environment found in current directory.\n'
+            'Create one with: python -m venv .venv'
+        )
+    if len(found) > 1:
+        raise RuntimeError(
+            f'Multiple virtual environments found: {", ".join(found)}\n'
+            'Remove one and keep only .venv or venv.'
+        )
+
+    venv_path = found[0]
+    bin_dir = os.path.join(venv_path, 'bin')
+    os.environ['PATH'] = bin_dir + os.pathsep + os.environ.get('PATH', '')
+    os.environ['VIRTUAL_ENV'] = venv_path
+    print(f"[itw] Using venv: {venv_path}")
+    _venv_activated = True
+
+
+def get_current_branch(ctx: Context) -> str:
+    branch_result = ctx.run('git rev-parse --abbrev-ref HEAD')
+    current_branch = branch_result.stdout.splitlines()[0]
+    return current_branch
+
+
+def is_branch_production(branch: str) -> bool:
+    if branch == 'master':
+        return True
+    else:
+        return False
+
+
+def check_branch(ctx: Context) -> bool:
+    current_branch = get_current_branch(ctx)
+    production = is_branch_production(current_branch)
+    changed_result = ctx.run('git diff --quiet HEAD $REF -- $DIR || echo changed')
+    changed = changed_result.stdout.splitlines()  # empty list if not changed
+    if len(changed) > 0:
+        raise RuntimeError(f'You have uncommitted changes in branch {current_branch}.')
+    if production and current_branch != 'master':
+        raise RuntimeError('You must be in master branch to release in production.')
+    elif not production and current_branch != 'staging':
+        raise RuntimeError(f'Cannot tag in branch {current_branch}.')
+    else:
+        return production
+
+
+def get_latest_tag(ctx: Context) -> Version:
+    result = ctx.run('git describe --tags $(git rev-list --tags --max-count=1)')
+    latest_tag = result.stdout.splitlines()[0]
+    return Version.parse(latest_tag)
+
+
+def generate_image_path(ctx: Context, branch: str) -> str:
+    result = ctx.run('git remote get-url origin')
+    result = result.stdout.splitlines()[0]
+    container_registry = result.split(':')[-1].replace('.git', '')
+    container_registry_path = f'gitreg.it-works.io:443/{container_registry}:{branch}-latest'
+    return container_registry_path
+
+
+def commit_version(ctx: Context, version: Version) -> None:
+    ctx.run(f'git add {Version.VERSION_FILE_NAME}')
+    ctx.run('git add CHANGELOG.md')
+    ctx.run(f'git commit -m \'version update to {version}\'')
+
+
+def push_version(ctx: Context) -> None:
+    ctx.run(f'git push origin {get_current_branch(ctx)}')
+
+
+def tag(ctx: Context, version: Version) -> None:
+    ctx.run(f'git tag {version}')
+
+
+def push(ctx: Context):
+    ctx.run('git push origin --tags')
+
+
+def buildimage(ctx: Context):
+    current_branch = get_current_branch(ctx)
+    container_registry_path = generate_image_path(ctx, current_branch)
+    ctx.run(f'podman build . --tag={container_registry_path}')
+
+
+def pushimage(ctx: Context):
+    current_branch = get_current_branch(ctx)
+    container_registry_path = generate_image_path(ctx, current_branch)
+    ctx.run(f'podman push {container_registry_path} --tls-verify=false --compress --compression-level=9')
+
+
+def tag_build_push(ctx: Context, version: Version, skip_pipeline: bool = False) -> None:
+    changelog(ctx, version)
+    if not skip_pipeline:
+        test(ctx)
+        analyze(ctx)
+    tag(ctx, version)
+    buildimage(ctx)
+    pushimage(ctx)
+    push(ctx)
+
+
+@task(name='tag-init')
+def taginit(ctx: Context) -> None:
+    """Initialize version tagging"""
+    check_branch(ctx)
+    version = Version(0, 1, 0, 1)
+    tag(ctx, version)
+    version.save_to_file()
+
+
+@task
+def incrementrc(ctx: Context, skip_pipeline=False) -> None:
+    """Increment release candidate version and deploy"""
+    check_branch(ctx)
+    version = Version.read_from_file()
+    version.increment_release_candidate()
+    lint(ctx)
+    tag_build_push(ctx, version, skip_pipeline)
+    version.save_to_file()
+    commit_version(ctx, version)
+    push_version(ctx)
+
+
+@task
+def incrementpatch(ctx: Context, skip_pipeline=False) -> None:
+    """Increment patch version, build, and deploy"""
+    production = check_branch(ctx)
+    version = Version.read_from_file()
+    version.increment_patch(release=production)
+    tag_build_push(ctx, version, skip_pipeline)
+    version.save_to_file()
+    commit_version(ctx, version)
+    push_version(ctx)
+
+
+@task
+def incrementminor(ctx: Context, skip_pipeline=False) -> None:
+    """Increment minor version, build, and deploy"""
+    production = check_branch(ctx)
+    version = Version.read_from_file()
+    version.increment_minor(release=production)
+    tag_build_push(ctx, version, skip_pipeline)
+    version.save_to_file()
+    commit_version(ctx, version)
+    push_version(ctx)
+
+
+@task
+def incrementmajor(ctx: Context, skip_pipeline=False) -> None:
+    """Increment major version, build, and deploy"""
+    production = check_branch(ctx)
+    version = Version.read_from_file()
+    version.increment_major(release=production)
+    tag_build_push(ctx, version, skip_pipeline)
+    version.save_to_file()
+    commit_version(ctx, version)
+    push_version(ctx)
+
+
+@task
+def release(ctx: Context, skip_pipeline=False) -> None:
+    """Promote release candidate to stable release and deploy"""
+    _ = check_branch(ctx)
+    version = Version.read_from_file()
+    version.reset_release_candidate(release=True)
+    tag_build_push(ctx, version, skip_pipeline)
+    version.save_to_file()
+    commit_version(ctx, version)
+    push_version(ctx)
+
+
+@task
+def test(ctx: Context, settings='backend.test_settings'):
+    """Run Django tests with coverage"""
+    ctx.run(f'coverage run manage.py test --settings={settings} --keepdb')
+    ctx.run('coverage report -m')
+    ctx.run('coverage xml -o coverage.xml')
+
+
+@task
+def lint(ctx: Context):
+    """Run pylint, generate reports for SonarQube"""
+    print("\n" + "=" * 60)
+    print("Running pylint...")
+    print("=" * 60)
+    ctx.run(
+        f'pylint . '
+        f'--exit-zero '
+        f'--rcfile={PYLINTRC} '
+        f'--output-format=parseable '
+        f'--msg-template="{{path}}:{{line}}: [{{msg_id}}({{symbol}}), {{obj}}] {{msg}}" '
+        f'> pylint-report.txt',
+        warn=True
+    )
+    print("✓ pylint done → pylint-report.txt")
+    print("\n✓ Lint reports ready for SonarQube")
+
+
+@task
+def lintlocal(ctx: Context):
+    """Run pylint locally with human-readable output (no report files)"""
+
+    print("\n" + "=" * 60)
+    print("Running pylint...")
+    print("=" * 60)
+    ctx.run(f'pylint . --exit-zero --output-format=parseable --rcfile={PYLINTRC}', warn=True)
+
+
+@task
+def analyze(ctx: Context):
+    """Run SonarQube analysis"""
+    try:
+        version = Version.read_from_file()
+        sonar_version = str(version).lstrip('v.')
+    except:
+        sonar_version = "0.0.0"
+    try:
+        from decouple import config as env_config
+        sonar_host = env_config('SONAR_HOST_URL', default='')
+        sonar_token = env_config('SONAR_TOKEN', default='')
+        git_depth = env_config('GIT_DEPTH', default=0, cast=int)
+    except ImportError:
+        sonar_host = os.environ.get('SONAR_HOST_URL', '')
+        sonar_token = os.environ.get('SONAR_TOKEN', '')
+        git_depth = os.environ.get('GIT_DEPTH', 0)
+    if not sonar_host or not sonar_token:
+        raise RuntimeError('SONAR_HOST_URL and SONAR_TOKEN environment variables must be set.')
+    ctx.run(
+        f'podman run --rm -e SONAR_HOST_URL={sonar_host} -e SONAR_TOKEN={sonar_token} -e GIT_DEPTH={git_depth} --user=root -v $(pwd):/usr/src:Z docker.io/sonarsource/sonar-scanner-cli:latest -X -Dsonar.projectVersion={sonar_version}')
+
+
+@task
+def buildlocal(ctx: Context):
+    """Build Docker image locally without pushing to registry"""
+    current_branch = get_current_branch(ctx)
+    local_tag = f'myapp:{current_branch}-local'
+    ctx.run(f'podman build . --tag={local_tag}')
+    print(f'✓ Built local image: {local_tag}')
+
+
+@task
+def testlocal(ctx: Context, settings='backend.test_settings'):
+    """Run tests locally (not in Docker)"""
+    ctx.run(f'coverage run manage.py test --settings={settings} --keepdb')
+    ctx.run('coverage report -m')
+    ctx.run('coverage xml -o coverage.xml')
+    print("✓ Tests completed")
+
+
+@task
+def analyzelocal(ctx: Context):
+    """Run SonarQube static analysis locally"""
+    print("Running SonarQube analysis...")
+    try:
+        version = Version.read_from_file()
+        sonar_version = str(version).lstrip('v.')
+    except:
+        sonar_version = "0.0.0"
+    try:
+        from decouple import config as env_config
+        sonar_host = env_config('SONAR_HOST_URL', default='')
+        sonar_token = env_config('SONAR_TOKEN', default='')
+        git_depth = env_config('GIT_DEPTH', default=0, cast=int)
+    except ImportError:
+        sonar_host = os.environ.get('SONAR_HOST_URL', '')
+        sonar_token = os.environ.get('SONAR_TOKEN', '')
+        git_depth = os.environ.get('GIT_DEPTH', 0)
+    if not sonar_host or not sonar_token:
+        raise RuntimeError('SONAR_HOST_URL and SONAR_TOKEN environment variables must be set.')
+    ctx.run(
+        f'podman run --rm -e SONAR_HOST_URL={sonar_host} -e SONAR_TOKEN={sonar_token} -e GIT_DEPTH={git_depth} --user=root -v $(pwd):/usr/src:Z docker.io/sonarsource/sonar-scanner-cli:latest -X -Dsonar.projectVersion={sonar_version}',
+        pty=True)
+    print("✓ SonarQube analysis completed")
+
+
+@task
+def pipelinelocal(ctx: Context, settings='backend.test_settings'):
+    """Local pipeline: lint → test → analyze → build"""
+    changelog(ctx)
+
+    print("=" * 60)
+    print("Step 1: Running lint...")
+    print("=" * 60)
+    lint(ctx)
+
+    print("\n" + "=" * 60)
+    print("Step 2: Running tests...")
+    print("=" * 60)
+    testlocal(ctx, settings)
+
+    print("\n" + "=" * 60)
+    print("Step 3: Running SonarQube analysis...")
+    print("=" * 60)
+    analyzelocal(ctx)
+
+    print("\n" + "=" * 60)
+    print("Step 4: Building Docker image locally...")
+    print("=" * 60)
+    buildlocal(ctx)
+
+    print("\n" + "=" * 60)
+    print("✓ Local pipeline completed successfully!")
+    print("=" * 60)
+
+
+@task
+def changelog(ctx: Context, version: Version = None):
+    """Generate changelog from commits with Changelog trailer"""
+
+    try:
+        last_tag_result = ctx.run('git describe --tags --abbrev=0', hide=True)
+        last_tag = last_tag_result.stdout.strip()
+        cmd = f'git log {last_tag}..HEAD --pretty=format:"%s|||%h|||%b|||END"'
+    except:
+        cmd = 'git log --pretty=format:"%s|||%h|||%b|||END"'
+
+    result = ctx.run(cmd, hide=True, warn=True)
+
+    if not result.stdout.strip():
+        print("No new commits since last tag")
+        return
+
+    commits_by_type = {}
+    for entry in result.stdout.strip().split('|||END'):
+        if not entry.strip():
+            continue
+
+        parts = entry.strip().split('|||')
+        if len(parts) < 3:
+            continue
+
+        title = parts[0].strip()
+        hash = parts[1].strip()
+        body = parts[2].strip() if len(parts) > 2 else ""
+
+        changelog_type = None
+        for line in body.split('\n'):
+            if line.strip().lower().startswith('changelog:'):
+                changelog_type = line.split(':', 1)[1].strip().lower()
+                break
+
+        if not changelog_type:
+            changelog_type = 'other'
+
+        type_map = {
+            'added': 'Added',
+            'fixed': 'Fixed',
+            'changed': 'Changed',
+            'deprecated': 'Deprecated',
+            'removed': 'Removed',
+            'security': 'Security',
+            'performance': 'Performance',
+            'tests': 'Tests',
+            'docs': 'Documentation',
+            'refactor': 'Refactoring',
+            'other': 'Other Changes'
+        }
+
+        section = type_map.get(changelog_type, 'Other Changes')
+
+        if section not in commits_by_type:
+            commits_by_type[section] = []
+
+        commits_by_type[section].append(f"- {title} ({hash})")
+
+    if not commits_by_type:
+        print("No commits found")
+        return
+
+    if version is not None:
+        version_str = str(version)
+    else:
+        try:
+            version_str = str(Version.read_from_file())
+        except:
+            version_str = "Unreleased"
+
+    date = datetime.now().strftime('%Y-%m-%d')
+
+    changelog_entry = f"\n## {version_str} - {date}\n\n"
+
+    section_order = ['Added', 'Fixed', 'Changed', 'Deprecated', 'Removed',
+                     'Security', 'Performance', 'Tests', 'Documentation',
+                     'Refactoring', 'Other Changes']
+
+    for section in section_order:
+        if section in commits_by_type:
+            changelog_entry += f"### {section}\n\n"
+            for commit in commits_by_type[section]:
+                changelog_entry += f"{commit}\n"
+            changelog_entry += "\n"
+
+    if not os.path.exists('CHANGELOG.md'):
+        with open('CHANGELOG.md', 'w') as f:
+            f.write('# Changelog\n')
+
+    with open('CHANGELOG.md', 'r') as f:
+        existing = f.read()
+
+    with open('CHANGELOG.md', 'w') as f:
+        f.write('# Changelog' + changelog_entry + existing.replace('# Changelog', ''))
+
+    total = sum(len(v) for v in commits_by_type.values())
+    print(f"✓ Changelog updated with {total} commits")

itw_python_builder/version.py

@@ -0,0 +1,84 @@
+import re
+from typing import Self
+
+
+class Version:
+    RGX_RELEASE = re.compile(r'v(\.\d{0,2}){3}-release')
+    RGX_RELEASE_CANDIDATE = re.compile(r'v(\.\d{0,2}){3}-rc\d{0,2}')
+    VERSION_FILE_NAME = 'VERSION'
+    major: int = 0
+    minor: int = 0
+    patch: int = 0
+    release_candidate: int = 0
+
+    def __init__(self, major: int = 0, minor: int = 1, patch: int = 0, release_candidate: int = 0) -> None:
+        self.major = major
+        self.minor = minor
+        self.patch = patch
+        self.release_candidate = release_candidate
+
+    def reset_release_candidate(self, release: bool = False) -> None:
+        if release:
+            self.release_candidate = 0
+        else:
+            self.release_candidate = 1
+
+    def increment_release_candidate(self) -> None:
+        self.release_candidate += 1
+
+    def increment_patch(self, release: bool = False) -> None:
+        self.patch += 1
+        self.reset_release_candidate(release)
+
+    def increment_minor(self, release: bool = False) -> None:
+        self.minor += 1
+        self.reset_release_candidate(release)
+
+    def increment_major(self, release: bool = False) -> None:
+        self.major += 1
+        self.reset_release_candidate(release)
+
+    def save_to_file(self) -> None:
+        with open(self.VERSION_FILE_NAME, 'w', encoding='utf-8') as fp:
+            fp.write(self.__str__())
+
+    @classmethod
+    def read_from_file(cls):
+        with open(cls.VERSION_FILE_NAME, 'r', encoding='utf-8') as fp:
+            version_line = fp.readline()
+        return cls.parse(version_line)
+
+    @classmethod
+    def match_release(cls: Self, version: str) -> bool:
+        return bool(Version.RGX_RELEASE.match(version))
+
+    @classmethod
+    def match_release_candidate(cls: Self, version: str) -> bool:
+        return bool(Version.RGX_RELEASE_CANDIDATE.match(version))
+
+    @classmethod
+    def parse(cls: Self, version: str) -> Self | None:
+        if Version.match_release_candidate(version):
+            [_, major, minor, patch_release] = version.split('.')
+            major = int(major)
+            minor = int(minor)
+            [patch, release_candidate] = patch_release.split('-')
+            patch = int(patch)
+            release_candidate = int(release_candidate.replace('rc', ''))
+            return Version(major, minor, patch, release_candidate)
+        elif Version.match_release(version):
+            [_, major, minor, patch] = version.split('.')
+            major = int(major)
+            minor = int(minor)
+            [patch, _] = patch.split('-')
+            patch = int(patch)
+            return Version(major, minor, patch, 0)
+        else:
+            raise ValueError(f'Invalid version: {version}')
+
+    def __str__(self):
+        version = f'v.{self.major}.{self.minor}.{self.patch}'
+        if self.release_candidate == 0:
+            return f'{version}-release'
+        else:
+            return f'{version}-rc{self.release_candidate}'

itw_python_builder-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+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