gauge-pybuild-plugin

Name	gauge-pybuild-plugin JSON
Version	0.1.0 JSON
	download
home_page	None
Summary	Python build plugin for Gauge testing framework - Poetry, UV, and setuptools integration
upload_time	2025-10-08 18:43:24
maintainer	None
docs_url	None
author	None
requires_python	>=3.8
license	Apache-2.0
keywords	automation gauge plugin poetry setuptools testing uv
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Gauge Python Build Plugin

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

A comprehensive Python build plugin for [Gauge](https://gauge.org/) testing framework, inspired by the [Gauge Gradle Plugin](https://github.com/getgauge/gauge-gradle-plugin). This plugin provides seamless integration with UV, Poetry, setuptools, and standalone CLI functionality for running Gauge specifications in Python projects.

## Features

- 🚀 **Multiple Integration Options**: UV, Poetry plugin, setuptools commands, and standalone CLI
- ⚡ **Parallel Execution**: Run specs in parallel with configurable worker nodes
- 🏷️ **Tag-based Filtering**: Execute specific specs using tag expressions
- 🌍 **Environment Support**: Run against different environments (dev, test, prod, etc.)
- ⚙️ **Flexible Configuration**: TOML-based configuration with sensible defaults
- 🔧 **Validation & Formatting**: Built-in project validation and spec formatting
- 📦 **Plugin Management**: Install and manage Gauge plugins
- 🎯 **Gradle-like Experience**: Similar API and workflow as the Gradle plugin
- 🦀 **Modern Tools**: Support for UV (Rust-based, 10-100x faster than pip)

## Prerequisites

Before using this plugin, you need:

1. **Gauge Framework** installed on your system:
   ```bash
   # macOS
   brew install gauge
   
   # Windows (using Chocolatey)
   choco install gauge
   
   # Linux
   curl -SsL https://downloads.gauge.org/stable | sh
   ```
   Verify installation: `gauge version`

2. **Gauge Python Plugin** installed:
   ```bash
   gauge install python
   ```

3. **An existing Gauge project** or create a new one:
   ```bash
   # Create new Gauge project
   gauge init python
   
   # This creates:
   # - manifest.json (Gauge project metadata)
   # - specs/ (test specifications directory)
   # - step_impl/ (step implementations)
   ```

> ⚠️ **Important**: This plugin must be run from within a Gauge project directory (one containing `manifest.json` and `specs/`). It enhances existing Gauge projects with build tool integration.

## Installation

### Using UV (Recommended - Fast!) ⚡

UV is a modern, Rust-based Python package manager that's 10-100x faster than pip.

```bash
# Install UV first (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the plugin
uv pip install gauge-pybuild-plugin

# Or add to your project
uv add gauge-pybuild-plugin
```

### Using Poetry

```bash
poetry add gauge-pybuild-plugin
```

### Using pip

```bash
pip install gauge-pybuild-plugin
```

### Development Installation

```bash
# Clone the repository
git clone https://github.com/lirany1/gauge-pybuild-plugin.git
cd gauge-pybuild-plugin

# Option 1: Using UV (recommended - faster)
uv pip install -e ".[dev]"

# Option 2: Using Poetry
poetry install
```

### Verify Installation

After installation, verify the plugin is working:

```bash
# Check if CLI is available
gauge-py --help

# In a Gauge project directory, try:
gauge-py validate
```

## Quick Start

### 1. UV Integration (Modern & Fast) ⚡

UV automatically manages virtual environments and dependencies:

```bash
# Run Gauge specs
uv run gauge-py run

# Run with options
uv run gauge-py run --parallel --nodes=4 --env=dev --tags="smoke"

# Validate and format
uv run gauge-py validate
uv run gauge-py format

# Install Gauge plugins
uv run gauge-py install python
```

### 2. Poetry Integration

Add the plugin to your `pyproject.toml`:

```toml
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "my-gauge-project"
version = "0.1.0"
description = "My Gauge project"

[tool.poetry.dependencies]
python = "^3.8"
getgauge = "^0.3.7"
gauge-pybuild-plugin = "^0.1.0"

# Gauge configuration
[tool.gauge]
specs_dir = "specs"
in_parallel = false
nodes = 1
env = "default"
additional_flags = "--verbose"

[tool.gauge.environment_variables]
gauge_reports_dir = "reports"
logs_directory = "logs"
```

Run Gauge through Poetry:

```bash
# Run all specs
poetry gauge run

# Run specific specs
poetry gauge run spec1.spec spec2.spec

# Run with options
poetry gauge run --parallel --nodes=4 --env=dev --tags="smoke"

# Validate project
poetry gauge validate

# Format specs
poetry gauge format

# Install plugins
poetry gauge install python
```

### 3. Setuptools Integration

Add to your `setup.py`:

```python
from setuptools import setup

setup(
    name="my-gauge-project",
    version="0.1.0",
    install_requires=[
        "getgauge>=0.3.7",
        "gauge-pybuild-plugin>=0.1.0",
    ],
    entry_points={
        "distutils.commands": [
            "gauge = gauge_pybuild_plugin.setuptools_command:GaugeCommand",
            "gauge_validate = gauge_pybuild_plugin.setuptools_command:GaugeValidateCommand",
            "gauge_format = gauge_pybuild_plugin.setuptools_command:GaugeFormatCommand",
        ]
    }
)
```

Run through setuptools:

```bash
# Run specs
python setup.py gauge

# Run with options
python setup.py gauge --parallel --nodes=4 --env=dev

# Validate and format
python setup.py gauge_validate
python setup.py gauge_format
```

### 4. Standalone CLI

Install the plugin and use the CLI directly:

```bash
# Run specs
gauge-py run

# Run with configuration
gauge-py run --specs-dir=specs --parallel --nodes=4 --env=dev

# Other commands
gauge-py validate
gauge-py format
gauge-py install python
gauge-py config --init
```

## Configuration Options

The plugin supports all the configuration options from the Gradle plugin, with Python-friendly naming:

| Option | CLI Flag | Description | Default |
|--------|----------|-------------|---------|
| `specs_dir` | `--specs-dir` | Gauge specs directory path | `"specs"` |
| `tags` | `--tags` | Filter specs by tags expression | `None` |
| `in_parallel` | `--parallel` | Execute specs in parallel | `false` |
| `nodes` | `--nodes` | Number of parallel execution streams | `1` |
| `env` | `--env` | Gauge environment to run against | `None` |
| `additional_flags` | `--additional-flags` | Additional gauge flags | `None` |
| `project_dir` | `--project-dir` | Path to gauge project directory | Current directory |
| `gauge_root` | `--gauge-root` | Path to gauge installation root | Auto-detected |
| `environment_variables` | N/A | Additional environment variables | `{}` |

### Configuration File Examples

#### Basic Configuration

```toml
[tool.gauge]
specs_dir = "specs"
in_parallel = false
nodes = 1
env = "default"
```

#### Advanced Configuration

```toml
[tool.gauge]
specs_dir = "specifications"
in_parallel = true
nodes = 4
env = "ci"
additional_flags = "--simple-console --verbose"
gauge_root = "/opt/gauge"

[tool.gauge.environment_variables]
gauge_reports_dir = "custom/reports"
logs_directory = "custom/logs"
screenshot_on_failure = "true"
```

#### Multiple Environment Configurations

```toml
# Default configuration
[tool.gauge]
specs_dir = "specs"
in_parallel = false
nodes = 1

# Development environment
[tool.gauge.environments.dev]
env = "dev"
additional_flags = "--verbose"

# CI environment  
[tool.gauge.environments.ci]
env = "ci"
in_parallel = true
nodes = 4
additional_flags = "--simple-console"
```

## Usage Examples

### UV Examples (Fast & Modern) ⚡

```bash
# Basic execution
uv run gauge-py run

# Parallel execution
uv run gauge-py run --parallel --nodes=4

# Tag-based execution
uv run gauge-py run --tags="smoke & !slow"

# Environment-specific execution
uv run gauge-py run --env=dev

# Specific specs
uv run gauge-py run specs/login.spec specs/checkout.spec

# Combined options
uv run gauge-py run --parallel --nodes=8 --env=ci --tags="regression"
```

### Poetry Examples

```bash
# Basic execution
poetry gauge run

# Parallel execution
poetry gauge run --parallel --nodes=4

# Tag-based execution
poetry gauge run --tags="smoke & !slow"

# Environment-specific execution
poetry gauge run --env=dev

# Specific specs
poetry gauge run specs/login.spec specs/checkout.spec

# Combined options
poetry gauge run --parallel --nodes=8 --env=ci --tags="regression" --additional-flags="--simple-console"
```

### CLI Examples

```bash
# Initialize configuration
gauge-py config --init

# Show current configuration
gauge-py config --show

# Run with verbose output
gauge-py --verbose run --parallel --nodes=4

# Run specific specs
gauge-py run specs/api/*.spec

# Install and manage plugins
gauge-py install python --version=0.3.7
gauge-py install html-report
```

### Setuptools Examples

```bash
# Basic execution
python setup.py gauge

# With options
python setup.py gauge --parallel --nodes=4 --env=test

# Validation and formatting
python setup.py gauge_validate
python setup.py gauge_format
```

## Comparison with Gradle Plugin

| Feature | Gradle Plugin | Python Plugin |
|---------|---------------|---------------|
| Build Tool Integration | ✅ Gradle | ✅ Poetry, setuptools |
| Parallel Execution | ✅ | ✅ |
| Tag Filtering | ✅ | ✅ |
| Environment Support | ✅ | ✅ |
| Custom Tasks | ✅ | ✅ (via CLI/API) |
| Configuration | `build.gradle` | `pyproject.toml` |
| CLI Interface | `gradle gauge` | `gauge-py run` |

### Gradle vs Python Syntax

**Gradle Plugin:**
```groovy
// build.gradle
gauge {
    specsDir = 'specs'
    inParallel = true
    nodes = 2
    env = 'dev'
    tags = 'tag1'
    additionalFlags = '--verbose'
}

// Command line
gradle gauge -PspecsDir="specs" -PinParallel=true -Pnodes=4
```

**Python Plugin:**
```toml
# pyproject.toml
[tool.gauge]
specs_dir = "specs"
in_parallel = true
nodes = 2
env = "dev"
tags = "tag1"
additional_flags = "--verbose"
```

```bash
# Command line
poetry gauge run --specs-dir=specs --parallel --nodes=4
gauge-py run --specs-dir=specs --parallel --nodes=4
```

## API Reference

### Core Classes

#### `GaugeConfig`

Configuration management class with validation and command generation.

```python
from gauge_pybuild_plugin import GaugeConfig

config = GaugeConfig(
    specs_dir="specs",
    in_parallel=True,
    nodes=4,
    env="dev"
)

# Generate command arguments
args = config.to_command_args()
# ['--parallel', '--n', '4', '--env', 'dev', 'specs']

# Get environment variables
env = config.get_environment()
```

#### `GaugeTask`

Task execution wrapper for running Gauge commands.

```python
from gauge_pybuild_plugin import GaugeTask, GaugeConfig

config = GaugeConfig(in_parallel=True, nodes=4)
task = GaugeTask(config)

# Run specs
success = task.run()
success = task.run(["spec1.spec", "spec2.spec"])

# Validate project
success = task.validate()

# Format specs
success = task.format_specs()

# Install plugin
success = task.install_plugin("python", "0.3.7")
```

#### `GaugePlugin`

Main plugin orchestrator with configuration loading.

```python
from gauge_pybuild_plugin import GaugePlugin

# Load from config file
plugin = GaugePlugin("pyproject.toml")

# Create tasks
task = plugin.create_task()
task = plugin.create_task({"in_parallel": True})

# High-level operations
plugin.run_specs(in_parallel=True, nodes=4)
plugin.validate_project()
plugin.format_specs()
```

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes
4. Add tests: `pytest tests/`
5. Run linting: `ruff check . && ruff format .`
6. Submit a pull request

### Development Setup

**Using UV (Recommended - 10-100x faster):**

```bash
git clone https://github.com/lirany1/gauge-pybuild-plugin.git
cd gauge-pybuild-plugin

# Install UV first
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies with dev extras
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run linting (using Ruff - modern & fast)
uv run ruff check .
uv run ruff format .
uv run mypy src/

# Install pre-commit hooks
uv run pre-commit install
```

**Using Poetry:**

```bash
git clone https://github.com/lirany1/gauge-pybuild-plugin.git
cd gauge-pybuild-plugin

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Run linting
poetry run ruff check .
poetry run ruff format .
poetry run mypy src/

# Install pre-commit hooks
poetry run pre-commit install
```

## Troubleshooting

### Common Issues

#### "Failed to find Gauge project directory. Missing manifest.json file"
**Cause**: You're not in a Gauge project directory.

**Solution**: 
- Navigate to a directory containing a Gauge project (with `manifest.json`)
- Or create a new Gauge project: `gauge init python`

#### "specs directory 'specs' does not exist"
**Cause**: The Gauge project doesn't have a specs directory.

**Solution**:
- Create the specs directory: `mkdir specs`
- Or initialize a Gauge project properly: `gauge init python`

#### "poetry: command not found"
**Cause**: Poetry is not installed.

**Solution**:
- **Recommended**: Use UV instead: `uv run gauge-py run`
- Or install Poetry: `curl -sSL https://install.python-poetry.org | python3 -`
- Or use the standalone CLI: `gauge-py run`

#### "Slow dependency installation"
**Cause**: Using pip or Poetry for package installation.

**Solution**:
- Switch to UV for 10-100x faster installs:
  ```bash
  # Install UV
  curl -LsSf https://astral.sh/uv/install.sh | sh
  
  # Use UV instead
  uv pip install gauge-pybuild-plugin
  ```

#### "python: command not found" (when running Gauge)
**Cause**: Gauge expects `python` but your system has `python3`.

**Solution**:
```bash
# Create a symlink
sudo ln -s $(which python3) /usr/local/bin/python

# Or modify env/default/python.properties in your Gauge project
```

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Inspired by the [Gauge Gradle Plugin](https://github.com/getgauge/gauge-gradle-plugin)
- Built for the [Gauge](https://gauge.org/) testing framework
- Thanks to the Gauge community for their awesome work

## Support

- 📖 [Gauge Documentation](https://docs.gauge.org/)
- 🐛 [Report Issues](https://github.com/lirany1/gauge-pybuild-plugin/issues)
- 💬 [Gauge Community](https://github.com/getgauge/gauge/discussions)
- 📧 [Contact](mailto:your.email@example.com)
            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "gauge-pybuild-plugin",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "automation, gauge, plugin, poetry, setuptools, testing, uv",
    "author": null,
    "author_email": "Your Name <your.email@example.com>",
    "download_url": "https://files.pythonhosted.org/packages/9e/30/e55f0f7ac205c27af196f2b606c914c7a5d2cd2ef6f0d659beaa7be1f353/gauge_pybuild_plugin-0.1.0.tar.gz",
    "platform": null,
    "description": "# Gauge Python Build Plugin\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n\nA comprehensive Python build plugin for [Gauge](https://gauge.org/) testing framework, inspired by the [Gauge Gradle Plugin](https://github.com/getgauge/gauge-gradle-plugin). This plugin provides seamless integration with UV, Poetry, setuptools, and standalone CLI functionality for running Gauge specifications in Python projects.\n\n## Features\n\n- \ud83d\ude80 **Multiple Integration Options**: UV, Poetry plugin, setuptools commands, and standalone CLI\n- \u26a1 **Parallel Execution**: Run specs in parallel with configurable worker nodes\n- \ud83c\udff7\ufe0f **Tag-based Filtering**: Execute specific specs using tag expressions\n- \ud83c\udf0d **Environment Support**: Run against different environments (dev, test, prod, etc.)\n- \u2699\ufe0f **Flexible Configuration**: TOML-based configuration with sensible defaults\n- \ud83d\udd27 **Validation & Formatting**: Built-in project validation and spec formatting\n- \ud83d\udce6 **Plugin Management**: Install and manage Gauge plugins\n- \ud83c\udfaf **Gradle-like Experience**: Similar API and workflow as the Gradle plugin\n- \ud83e\udd80 **Modern Tools**: Support for UV (Rust-based, 10-100x faster than pip)\n\n## Prerequisites\n\nBefore using this plugin, you need:\n\n1. **Gauge Framework** installed on your system:\n   ```bash\n   # macOS\n   brew install gauge\n   \n   # Windows (using Chocolatey)\n   choco install gauge\n   \n   # Linux\n   curl -SsL https://downloads.gauge.org/stable | sh\n   ```\n   Verify installation: `gauge version`\n\n2. **Gauge Python Plugin** installed:\n   ```bash\n   gauge install python\n   ```\n\n3. **An existing Gauge project** or create a new one:\n   ```bash\n   # Create new Gauge project\n   gauge init python\n   \n   # This creates:\n   # - manifest.json (Gauge project metadata)\n   # - specs/ (test specifications directory)\n   # - step_impl/ (step implementations)\n   ```\n\n> \u26a0\ufe0f **Important**: This plugin must be run from within a Gauge project directory (one containing `manifest.json` and `specs/`). It enhances existing Gauge projects with build tool integration.\n\n## Installation\n\n### Using UV (Recommended - Fast!) \u26a1\n\nUV is a modern, Rust-based Python package manager that's 10-100x faster than pip.\n\n```bash\n# Install UV first (if not already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install the plugin\nuv pip install gauge-pybuild-plugin\n\n# Or add to your project\nuv add gauge-pybuild-plugin\n```\n\n### Using Poetry\n\n```bash\npoetry add gauge-pybuild-plugin\n```\n\n### Using pip\n\n```bash\npip install gauge-pybuild-plugin\n```\n\n### Development Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lirany1/gauge-pybuild-plugin.git\ncd gauge-pybuild-plugin\n\n# Option 1: Using UV (recommended - faster)\nuv pip install -e \".[dev]\"\n\n# Option 2: Using Poetry\npoetry install\n```\n\n### Verify Installation\n\nAfter installation, verify the plugin is working:\n\n```bash\n# Check if CLI is available\ngauge-py --help\n\n# In a Gauge project directory, try:\ngauge-py validate\n```\n\n## Quick Start\n\n### 1. UV Integration (Modern & Fast) \u26a1\n\nUV automatically manages virtual environments and dependencies:\n\n```bash\n# Run Gauge specs\nuv run gauge-py run\n\n# Run with options\nuv run gauge-py run --parallel --nodes=4 --env=dev --tags=\"smoke\"\n\n# Validate and format\nuv run gauge-py validate\nuv run gauge-py format\n\n# Install Gauge plugins\nuv run gauge-py install python\n```\n\n### 2. Poetry Integration\n\nAdd the plugin to your `pyproject.toml`:\n\n```toml\n[build-system]\nrequires = [\"poetry-core\"]\nbuild-backend = \"poetry.core.masonry.api\"\n\n[tool.poetry]\nname = \"my-gauge-project\"\nversion = \"0.1.0\"\ndescription = \"My Gauge project\"\n\n[tool.poetry.dependencies]\npython = \"^3.8\"\ngetgauge = \"^0.3.7\"\ngauge-pybuild-plugin = \"^0.1.0\"\n\n# Gauge configuration\n[tool.gauge]\nspecs_dir = \"specs\"\nin_parallel = false\nnodes = 1\nenv = \"default\"\nadditional_flags = \"--verbose\"\n\n[tool.gauge.environment_variables]\ngauge_reports_dir = \"reports\"\nlogs_directory = \"logs\"\n```\n\nRun Gauge through Poetry:\n\n```bash\n# Run all specs\npoetry gauge run\n\n# Run specific specs\npoetry gauge run spec1.spec spec2.spec\n\n# Run with options\npoetry gauge run --parallel --nodes=4 --env=dev --tags=\"smoke\"\n\n# Validate project\npoetry gauge validate\n\n# Format specs\npoetry gauge format\n\n# Install plugins\npoetry gauge install python\n```\n\n### 3. Setuptools Integration\n\nAdd to your `setup.py`:\n\n```python\nfrom setuptools import setup\n\nsetup(\n    name=\"my-gauge-project\",\n    version=\"0.1.0\",\n    install_requires=[\n        \"getgauge>=0.3.7\",\n        \"gauge-pybuild-plugin>=0.1.0\",\n    ],\n    entry_points={\n        \"distutils.commands\": [\n            \"gauge = gauge_pybuild_plugin.setuptools_command:GaugeCommand\",\n            \"gauge_validate = gauge_pybuild_plugin.setuptools_command:GaugeValidateCommand\",\n            \"gauge_format = gauge_pybuild_plugin.setuptools_command:GaugeFormatCommand\",\n        ]\n    }\n)\n```\n\nRun through setuptools:\n\n```bash\n# Run specs\npython setup.py gauge\n\n# Run with options\npython setup.py gauge --parallel --nodes=4 --env=dev\n\n# Validate and format\npython setup.py gauge_validate\npython setup.py gauge_format\n```\n\n### 4. Standalone CLI\n\nInstall the plugin and use the CLI directly:\n\n```bash\n# Run specs\ngauge-py run\n\n# Run with configuration\ngauge-py run --specs-dir=specs --parallel --nodes=4 --env=dev\n\n# Other commands\ngauge-py validate\ngauge-py format\ngauge-py install python\ngauge-py config --init\n```\n\n## Configuration Options\n\nThe plugin supports all the configuration options from the Gradle plugin, with Python-friendly naming:\n\n| Option | CLI Flag | Description | Default |\n|--------|----------|-------------|---------|\n| `specs_dir` | `--specs-dir` | Gauge specs directory path | `\"specs\"` |\n| `tags` | `--tags` | Filter specs by tags expression | `None` |\n| `in_parallel` | `--parallel` | Execute specs in parallel | `false` |\n| `nodes` | `--nodes` | Number of parallel execution streams | `1` |\n| `env` | `--env` | Gauge environment to run against | `None` |\n| `additional_flags` | `--additional-flags` | Additional gauge flags | `None` |\n| `project_dir` | `--project-dir` | Path to gauge project directory | Current directory |\n| `gauge_root` | `--gauge-root` | Path to gauge installation root | Auto-detected |\n| `environment_variables` | N/A | Additional environment variables | `{}` |\n\n### Configuration File Examples\n\n#### Basic Configuration\n\n```toml\n[tool.gauge]\nspecs_dir = \"specs\"\nin_parallel = false\nnodes = 1\nenv = \"default\"\n```\n\n#### Advanced Configuration\n\n```toml\n[tool.gauge]\nspecs_dir = \"specifications\"\nin_parallel = true\nnodes = 4\nenv = \"ci\"\nadditional_flags = \"--simple-console --verbose\"\ngauge_root = \"/opt/gauge\"\n\n[tool.gauge.environment_variables]\ngauge_reports_dir = \"custom/reports\"\nlogs_directory = \"custom/logs\"\nscreenshot_on_failure = \"true\"\n```\n\n#### Multiple Environment Configurations\n\n```toml\n# Default configuration\n[tool.gauge]\nspecs_dir = \"specs\"\nin_parallel = false\nnodes = 1\n\n# Development environment\n[tool.gauge.environments.dev]\nenv = \"dev\"\nadditional_flags = \"--verbose\"\n\n# CI environment  \n[tool.gauge.environments.ci]\nenv = \"ci\"\nin_parallel = true\nnodes = 4\nadditional_flags = \"--simple-console\"\n```\n\n## Usage Examples\n\n### UV Examples (Fast & Modern) \u26a1\n\n```bash\n# Basic execution\nuv run gauge-py run\n\n# Parallel execution\nuv run gauge-py run --parallel --nodes=4\n\n# Tag-based execution\nuv run gauge-py run --tags=\"smoke & !slow\"\n\n# Environment-specific execution\nuv run gauge-py run --env=dev\n\n# Specific specs\nuv run gauge-py run specs/login.spec specs/checkout.spec\n\n# Combined options\nuv run gauge-py run --parallel --nodes=8 --env=ci --tags=\"regression\"\n```\n\n### Poetry Examples\n\n```bash\n# Basic execution\npoetry gauge run\n\n# Parallel execution\npoetry gauge run --parallel --nodes=4\n\n# Tag-based execution\npoetry gauge run --tags=\"smoke & !slow\"\n\n# Environment-specific execution\npoetry gauge run --env=dev\n\n# Specific specs\npoetry gauge run specs/login.spec specs/checkout.spec\n\n# Combined options\npoetry gauge run --parallel --nodes=8 --env=ci --tags=\"regression\" --additional-flags=\"--simple-console\"\n```\n\n### CLI Examples\n\n```bash\n# Initialize configuration\ngauge-py config --init\n\n# Show current configuration\ngauge-py config --show\n\n# Run with verbose output\ngauge-py --verbose run --parallel --nodes=4\n\n# Run specific specs\ngauge-py run specs/api/*.spec\n\n# Install and manage plugins\ngauge-py install python --version=0.3.7\ngauge-py install html-report\n```\n\n### Setuptools Examples\n\n```bash\n# Basic execution\npython setup.py gauge\n\n# With options\npython setup.py gauge --parallel --nodes=4 --env=test\n\n# Validation and formatting\npython setup.py gauge_validate\npython setup.py gauge_format\n```\n\n## Comparison with Gradle Plugin\n\n| Feature | Gradle Plugin | Python Plugin |\n|---------|---------------|---------------|\n| Build Tool Integration | \u2705 Gradle | \u2705 Poetry, setuptools |\n| Parallel Execution | \u2705 | \u2705 |\n| Tag Filtering | \u2705 | \u2705 |\n| Environment Support | \u2705 | \u2705 |\n| Custom Tasks | \u2705 | \u2705 (via CLI/API) |\n| Configuration | `build.gradle` | `pyproject.toml` |\n| CLI Interface | `gradle gauge` | `gauge-py run` |\n\n### Gradle vs Python Syntax\n\n**Gradle Plugin:**\n```groovy\n// build.gradle\ngauge {\n    specsDir = 'specs'\n    inParallel = true\n    nodes = 2\n    env = 'dev'\n    tags = 'tag1'\n    additionalFlags = '--verbose'\n}\n\n// Command line\ngradle gauge -PspecsDir=\"specs\" -PinParallel=true -Pnodes=4\n```\n\n**Python Plugin:**\n```toml\n# pyproject.toml\n[tool.gauge]\nspecs_dir = \"specs\"\nin_parallel = true\nnodes = 2\nenv = \"dev\"\ntags = \"tag1\"\nadditional_flags = \"--verbose\"\n```\n\n```bash\n# Command line\npoetry gauge run --specs-dir=specs --parallel --nodes=4\ngauge-py run --specs-dir=specs --parallel --nodes=4\n```\n\n## API Reference\n\n### Core Classes\n\n#### `GaugeConfig`\n\nConfiguration management class with validation and command generation.\n\n```python\nfrom gauge_pybuild_plugin import GaugeConfig\n\nconfig = GaugeConfig(\n    specs_dir=\"specs\",\n    in_parallel=True,\n    nodes=4,\n    env=\"dev\"\n)\n\n# Generate command arguments\nargs = config.to_command_args()\n# ['--parallel', '--n', '4', '--env', 'dev', 'specs']\n\n# Get environment variables\nenv = config.get_environment()\n```\n\n#### `GaugeTask`\n\nTask execution wrapper for running Gauge commands.\n\n```python\nfrom gauge_pybuild_plugin import GaugeTask, GaugeConfig\n\nconfig = GaugeConfig(in_parallel=True, nodes=4)\ntask = GaugeTask(config)\n\n# Run specs\nsuccess = task.run()\nsuccess = task.run([\"spec1.spec\", \"spec2.spec\"])\n\n# Validate project\nsuccess = task.validate()\n\n# Format specs\nsuccess = task.format_specs()\n\n# Install plugin\nsuccess = task.install_plugin(\"python\", \"0.3.7\")\n```\n\n#### `GaugePlugin`\n\nMain plugin orchestrator with configuration loading.\n\n```python\nfrom gauge_pybuild_plugin import GaugePlugin\n\n# Load from config file\nplugin = GaugePlugin(\"pyproject.toml\")\n\n# Create tasks\ntask = plugin.create_task()\ntask = plugin.create_task({\"in_parallel\": True})\n\n# High-level operations\nplugin.run_specs(in_parallel=True, nodes=4)\nplugin.validate_project()\nplugin.format_specs()\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests: `pytest tests/`\n5. Run linting: `ruff check . && ruff format .`\n6. Submit a pull request\n\n### Development Setup\n\n**Using UV (Recommended - 10-100x faster):**\n\n```bash\ngit clone https://github.com/lirany1/gauge-pybuild-plugin.git\ncd gauge-pybuild-plugin\n\n# Install UV first\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install dependencies with dev extras\nuv pip install -e \".[dev]\"\n\n# Run tests\nuv run pytest\n\n# Run linting (using Ruff - modern & fast)\nuv run ruff check .\nuv run ruff format .\nuv run mypy src/\n\n# Install pre-commit hooks\nuv run pre-commit install\n```\n\n**Using Poetry:**\n\n```bash\ngit clone https://github.com/lirany1/gauge-pybuild-plugin.git\ncd gauge-pybuild-plugin\n\n# Install dependencies\npoetry install\n\n# Run tests\npoetry run pytest\n\n# Run linting\npoetry run ruff check .\npoetry run ruff format .\npoetry run mypy src/\n\n# Install pre-commit hooks\npoetry run pre-commit install\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### \"Failed to find Gauge project directory. Missing manifest.json file\"\n**Cause**: You're not in a Gauge project directory.\n\n**Solution**: \n- Navigate to a directory containing a Gauge project (with `manifest.json`)\n- Or create a new Gauge project: `gauge init python`\n\n#### \"specs directory 'specs' does not exist\"\n**Cause**: The Gauge project doesn't have a specs directory.\n\n**Solution**:\n- Create the specs directory: `mkdir specs`\n- Or initialize a Gauge project properly: `gauge init python`\n\n#### \"poetry: command not found\"\n**Cause**: Poetry is not installed.\n\n**Solution**:\n- **Recommended**: Use UV instead: `uv run gauge-py run`\n- Or install Poetry: `curl -sSL https://install.python-poetry.org | python3 -`\n- Or use the standalone CLI: `gauge-py run`\n\n#### \"Slow dependency installation\"\n**Cause**: Using pip or Poetry for package installation.\n\n**Solution**:\n- Switch to UV for 10-100x faster installs:\n  ```bash\n  # Install UV\n  curl -LsSf https://astral.sh/uv/install.sh | sh\n  \n  # Use UV instead\n  uv pip install gauge-pybuild-plugin\n  ```\n\n#### \"python: command not found\" (when running Gauge)\n**Cause**: Gauge expects `python` but your system has `python3`.\n\n**Solution**:\n```bash\n# Create a symlink\nsudo ln -s $(which python3) /usr/local/bin/python\n\n# Or modify env/default/python.properties in your Gauge project\n```\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Inspired by the [Gauge Gradle Plugin](https://github.com/getgauge/gauge-gradle-plugin)\n- Built for the [Gauge](https://gauge.org/) testing framework\n- Thanks to the Gauge community for their awesome work\n\n## Support\n\n- \ud83d\udcd6 [Gauge Documentation](https://docs.gauge.org/)\n- \ud83d\udc1b [Report Issues](https://github.com/lirany1/gauge-pybuild-plugin/issues)\n- \ud83d\udcac [Gauge Community](https://github.com/getgauge/gauge/discussions)\n- \ud83d\udce7 [Contact](mailto:your.email@example.com)",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": "Python build plugin for Gauge testing framework - Poetry, UV, and setuptools integration",
    "version": "0.1.0",
    "project_urls": {
        "Documentation": "https://github.com/lirany1/gauge-pybuild-plugin",
        "Homepage": "https://github.com/lirany1/gauge-pybuild-plugin",
        "Issues": "https://github.com/lirany1/gauge-pybuild-plugin/issues",
        "Repository": "https://github.com/lirany1/gauge-pybuild-plugin"
    },
    "split_keywords": [
        "automation",
        " gauge",
        " plugin",
        " poetry",
        " setuptools",
        " testing",
        " uv"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "1dcbcbde765c8e821f3c18bd74df1b618038548f5f808e7bc989959a34a304cf",
                "md5": "eebf26e01c707281cc30ea7204dddfb8",
                "sha256": "f348e50ca8566fb3cf027770f3afb9114a0f482a28d24417afe5dc74b74ec58d"
            },
            "downloads": -1,
            "filename": "gauge_pybuild_plugin-0.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "eebf26e01c707281cc30ea7204dddfb8",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 19617,
            "upload_time": "2025-10-08T18:43:23",
            "upload_time_iso_8601": "2025-10-08T18:43:23.321208Z",
            "url": "https://files.pythonhosted.org/packages/1d/cb/cbde765c8e821f3c18bd74df1b618038548f5f808e7bc989959a34a304cf/gauge_pybuild_plugin-0.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "9e30e55f0f7ac205c27af196f2b606c914c7a5d2cd2ef6f0d659beaa7be1f353",
                "md5": "92ca3fdc060c58859fcb34bcbf94c513",
                "sha256": "0d9bc95ebd2e3c437867e9dd94f1e9414dd6d40751b9e262d4ceacb1fd628b84"
            },
            "downloads": -1,
            "filename": "gauge_pybuild_plugin-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "92ca3fdc060c58859fcb34bcbf94c513",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 29720,
            "upload_time": "2025-10-08T18:43:24",
            "upload_time_iso_8601": "2025-10-08T18:43:24.955719Z",
            "url": "https://files.pythonhosted.org/packages/9e/30/e55f0f7ac205c27af196f2b606c914c7a5d2cd2ef6f0d659beaa7be1f353/gauge_pybuild_plugin-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-08 18:43:24",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "lirany1",
    "github_project": "gauge-pybuild-plugin",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "gauge-pybuild-plugin"
}