omaster 0.16.0

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

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:

1. Project Validation

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

2. Code Quality Checks

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

3. Change Analysis

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

4. Version Management

   • Automatically bumps version based on changes
   • Follows semantic versioning

5. Build & Publish

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

6. Git Integration

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

Development Guide

Common Development Tasks

1. Running the Tool

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

2. 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
   

3. 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'