omaster

omaster

A Python package release tool that automates the entire release process with built-in quality checks and AI-powered features.

Features

• Automated release pipeline with quality checks
• AI-powered commit message generation
• Semantic version management
• Code quality analysis
• Build and publish automation
• Git integration

Installation

There are two main ways to use omaster:

1. Production Use (for users)

# Install from PyPI
uv pip install omaster

# Run the tool
uvx omaster [project_path]

2. Development Use (for contributors)

# Clone the repository
git clone https://github.com/yourusername/omaster.git
cd omaster

# Install dependencies
uv pip install -e .

# Run in development mode (recommended during development)
uv run -m omaster.main [project_path]

Note: project_path is optional and defaults to the current directory.

Usage

Why use uv run during development?

When working on omaster itself, always use uv run -m omaster.main because:

• Changes to code are immediately reflected
• No need to reinstall after each change
• Easier debugging and testing
• More reliable development workflow

Release Pipeline

The tool runs a complete release pipeline that includes:

• Project Validation

  • Required fields in pyproject.toml
  • Build system configuration
  • Entry points and dependencies
  • README.md content and structure

• Code Quality Checks

  • Complexity analysis (cyclomatic, cognitive)
  • Dead code detection
  • Code similarity analysis
  • Style checks

• Change Analysis

  • Uses OpenAI to analyze git changes
  • Generates meaningful commit messages
  • Suggests version bump type (major, minor, patch)

• Version Management

  • Automatically bumps version based on changes
  • Follows semantic versioning

• Build & Publish

  • Cleans old build files
  • Builds source and wheel distributions
  • Publishes to PyPI

• Git Integration

  • Commits changes with AI-generated message
  • Pushes to remote repository

Development Guide

Common Development Tasks

• Running the Tool

  # Always use this during development
  uv run -m omaster.main [project_path]
  

• Building and Testing

  # Clean and build
  rm -rf dist/*
  uv build
  
  # Install and test the built package
  uv pip install dist/omaster-*.whl
  uvx omaster  # Test installed version
  

• Running Tests

  uv run pytest
  uv run pytest --cov=omaster  # With coverage
  

Environment Variables

• OPENAI_API_KEY: Required for AI features

  export OPENAI_API_KEY='your-api-key'
  

Configuration

The tool can be configured using a .omaster.yaml file in your project root:

ai:
  model: gpt-4o-mini  # or gpt-4o

quality:
  complexity:
    max_cyclomatic: 15
    max_cognitive: 20
    min_maintainability: 65
  similarity:
    min_lines: 6
    exact_match_threshold: 1.0
    ast_similarity_threshold: 0.7

Available configuration options:

• ai.model: AI model to use for analysis
  • gpt-4o-mini: Faster, more efficient model (default)
  • gpt-4o: More powerful model for complex analysis
• quality: Code quality thresholds and settings
  • complexity: Complexity analysis settings
  • similarity: Code similarity detection settings

Error Handling

The tool uses a standardized error system with helpful messages. Each error includes:

• Error code and title
• Description of what went wrong
• Instructions on how to fix it
• Example solution when available

For example:

🚨 Error 🚨
Code: 600 - OpenAI API Key Missing

Description:
OPENAI_API_KEY environment variable not set

How to fix:
Set OPENAI_API_KEY environment variable

Example:
export OPENAI_API_KEY='your-api-key'