# MyPackage

A production-ready Python package demonstrating best practices for packaging, semantic versioning, and multi-environment publishing to PyPI.

[![CI/CD](https://github.com/yourusername/mypackage/workflows/CI/badge.svg)](https://github.com/yourusername/mypackage/actions)
[![PyPI version](https://badge.fury.io/py/mypackage.svg)](https://badge.fury.io/py/mypackage)
[![Python versions](https://img.shields.io/pypi/pyversions/mypackage.svg)](https://pypi.org/project/mypackage/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

This package includes:
- 🧮 **Calculator**: Basic arithmetic operations (add, subtract, multiply, divide)
- 📝 **Text Utils**: String manipulation functions (capitalize, reverse, count words)
- 📊 **Data Processor**: List and number processing utilities (filter, sum, statistics)

## Multi-Environment Strategy

This package supports three environments with the **same version number** across all:

| Environment | Package Name | Purpose |
|------------|--------------|---------|
| **Production** | `mypackage` | Stable releases for production use |
| **QA** | `mypackage-qa` | Testing and quality assurance |
| **Development** | `mypackage-dev` | Latest development features |

## Installation

### Production Environment
```bash
pip install mypackage
```

### QA Environment
```bash
pip install mypackage-qa
```

### Development Environment
```bash
pip install mypackage-dev
```

## Quick Start

```python
from mypackage import add, subtract, capitalize_words, filter_even, get_statistics

# Calculator functions
result = add(10, 5)  # 15
result = multiply(3, 4)  # 12

# Text utilities
text = capitalize_words("hello world")  # "Hello World"
reversed_text = reverse_string("Python")  # "nohtyP"

# Data processing
evens = filter_even([1, 2, 3, 4, 5])  # [2, 4]
stats = get_statistics([1, 2, 3, 4, 5])
# {'min': 1, 'max': 5, 'mean': 3.0, 'sum': 15, 'count': 5}
```

## Development Setup

### Prerequisites
- Python 3.8 or higher
- Poetry (for dependency management)

### Installation

1. Clone the repository:
```bash
git clone https://github.com/yourusername/mypackage.git
cd mypackage
```

2. Install dependencies using Poetry:
```bash
poetry install
```

3. Activate the virtual environment:
```bash
poetry shell
```

### Running Tests

Run all tests with coverage:
```bash
poetry run pytest
```

Run specific test file:
```bash
poetry run pytest tests/test_calculator.py
```

### Code Quality

Format code:
```bash
poetry run black src tests scripts
poetry run isort src tests scripts
```

Run linting:
```bash
poetry run flake8 src tests
```

Type checking:
```bash
poetry run mypy src
```

Run all validations:
```bash
python scripts/validate.py
```

## Semantic Versioning

This package follows [Semantic Versioning](https://semver.org/) (SemVer):
- **MAJOR** version for incompatible API changes
- **MINOR** version for backward-compatible functionality additions
- **PATCH** version for backward-compatible bug fixes

### Bumping Version

Use the provided script to bump versions:

```bash
# Bump patch version (0.1.0 -> 0.1.1)
python scripts/bump_version.py patch

# Bump minor version (0.1.0 -> 0.2.0)
python scripts/bump_version.py minor

# Bump major version (0.1.0 -> 1.0.0)
python scripts/bump_version.py major
```

The version will be automatically updated in:
- `pyproject.toml`
- `src/mypackage/__init__.py`
- Git tag will be created

## Publishing to PyPI

### Prerequisites

1. Create a PyPI account at [https://pypi.org](https://pypi.org)
2. Generate an API token from your PyPI account settings
3. Configure Poetry with your token:
```bash
poetry config pypi-token.pypi <your-token>
```

### Publishing Process

1. **Validate your package**:
```bash
python scripts/validate.py
```

2. **Bump the version** (if needed):
```bash
python scripts/bump_version.py [major|minor|patch]
```

3. **Publish to specific environment**:
```bash
# Publish to dev
python scripts/publish.py dev

# Publish to qa
python scripts/publish.py qa

# Publish to prod
python scripts/publish.py prod

# Publish to all environments
python scripts/publish.py all
```

4. **Dry run** (test without publishing):
```bash
python scripts/publish.py all --dry-run
```

### Version Consistency

The same version number is maintained across all three environments (dev, qa, prod). Only the package name differs:
- `mypackage-dev` version 0.1.0
- `mypackage-qa` version 0.1.0
- `mypackage` version 0.1.0

## Project Structure

```
first_python_package/
├── src/
│   └── mypackage/
│       ├── __init__.py
│       ├── calculator.py
│       ├── text_utils.py
│       └── data_processor.py
├── tests/
│   ├── __init__.py
│   ├── test_calculator.py
│   ├── test_text_utils.py
│   └── test_data_processor.py
├── scripts/
│   ├── bump_version.py
│   ├── publish.py
│   └── validate.py
├── .github/
│   └── workflows/
│       └── ci.yml
├── pyproject.toml
├── .bumpversion.cfg
├── .gitignore
├── .pre-commit-config.yaml
├── LICENSE
└── README.md
```

## API Documentation

### Calculator Module

- `add(a, b)` - Add two numbers
- `subtract(a, b)` - Subtract b from a
- `multiply(a, b)` - Multiply two numbers
- `divide(a, b)` - Divide a by b (raises ValueError if b is zero)

### Text Utils Module

- `capitalize_words(text)` - Capitalize first letter of each word
- `reverse_string(text)` - Reverse a string
- `count_words(text)` - Count words in a string

### Data Processor Module

- `filter_even(numbers)` - Filter even numbers from a list
- `sum_list(numbers)` - Calculate sum of numbers
- `get_statistics(numbers)` - Get min, max, mean, sum, and count

## CI/CD Pipeline

The project includes a GitHub Actions workflow that:
- Runs on Python 3.8, 3.9, 3.10, 3.11, and 3.12
- Executes linting and type checking
- Runs all tests with coverage reporting
- Validates the package build
- (Optional) Automatically publishes on version tags

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and validation (`python scripts/validate.py`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## Best Practices Implemented

✅ **Poetry** for modern dependency management  
✅ **Semantic Versioning** with automated version bumping  
✅ **Multi-environment** support (dev, qa, prod)  
✅ **Type hints** throughout the codebase  
✅ **Comprehensive test suite** with pytest  
✅ **Code quality tools** (black, isort, flake8, mypy)  
✅ **Pre-commit hooks** for automated checks  
✅ **CI/CD pipeline** with GitHub Actions  
✅ **Detailed documentation** with examples  
✅ **Proper package structure** following Python standards  

## License

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

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and changes.

## Support

For issues and questions:
- 🐛 [Report bugs](https://github.com/yourusername/mypackage/issues)
- 💡 [Request features](https://github.com/yourusername/mypackage/issues)
- 📧 Email: your.email@example.com

## Acknowledgments

This package was created as a demonstration of Python packaging best practices, including:
- Multi-environment deployment strategy
- Semantic versioning
- Modern tooling with Poetry
- Comprehensive testing and validation
