mypackage-prod 0.2.0

A sample Python package with semantic versioning for multiple environments (Production Environment)

MyPackage

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

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

pip install mypackage

QA Environment

pip install mypackage-qa

Development Environment

pip install mypackage-dev

Quick Start

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:

git clone https://github.com/yourusername/mypackage.git
cd mypackage

2. Install dependencies using Poetry:

poetry install

3. Activate the virtual environment:

poetry shell

Running Tests

Run all tests with coverage:

poetry run pytest

Run specific test file:

poetry run pytest tests/test_calculator.py

Code Quality

Format code:

poetry run black src tests scripts
poetry run isort src tests scripts

Run linting:

poetry run flake8 src tests

Type checking:

poetry run mypy src

Run all validations:

python scripts/validate.py

Semantic Versioning

This package follows Semantic Versioning (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:

# 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
2. Generate an API token from your PyPI account settings
3. Configure Poetry with your token:

poetry config pypi-token.pypi <your-token>

Publishing Process

1. Validate your package:

python scripts/validate.py

2. Bump the version (if needed):

python scripts/bump_version.py [major|minor|patch]

3. Publish to specific environment:

# 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):

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

Documentation

Comprehensive guides are available for all aspects of this project:

Getting Started

• QUICKSTART.md - Quick setup and first steps
• SETUP.md - Detailed development environment setup

Development Workflow

• VERSION_MANAGEMENT.md - Comprehensive version bumping guide 🆕
• BRANCHING_STRATEGY.md - Git workflow and branch management
• RELEASE_NOTES_GUIDE.md - Conventional commits and automated release notes

Deployment & Publishing

• PUBLISHING.md - PyPI publishing process
• CI_CD_SETUP_GUIDE.md - GitHub Actions pipeline setup
• GITHUB_ENVIRONMENTS_SETUP.md - Environment protection rules
• QUICK_DEPLOYMENT_GUIDE.md - Fast deployment reference

Architecture & Design

• PROJECT_OVERVIEW.md - High-level project structure
• PIPELINE_ARCHITECTURE.md - CI/CD pipeline details

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 file for details.

Changelog

See CHANGELOG.md for version history and changes.

Support

For issues and questions:

• 🐛 Report bugs
• 💡 Request features
• 📧 Email: [e-mail]

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