publish-lib-ghp

A professional Python library demonstrating best practices for packaging and publishing to PyPI using modern tools and automated CI/CD.

🚀 Features

• Professional packaging with Poetry and pyproject.toml
• Automated CI/CD with GitHub Actions
• Comprehensive testing with pytest
• Semantic versioning with automated releases
• Dynamic versioning using importlib.metadata
• Automated release script (commit.py) for easy publishing
• Template ready - Use as base for your own Python packages
• Multiple classes - Greeting and Operations functionality

📦 Installation

pip install publish-lib-ghp

🔧 Usage

from publish_lib_ghp import Greeting, Operations

# Create instances
greeting = Greeting()
operations = Operations()

# Basic greeting functionality
message = greeting.say_hello("World")
print(message)  # Output: Hello, World!

# Time-specific greetings
morning_msg = greeting.get_greeting_with_time("Alice", "morning")
print(morning_msg)  # Output: Good morning, Alice!

# Say goodbye
goodbye_msg = greeting.say_goodbye("Bob")
print(goodbye_msg)  # Output: Goodbye, Bob!

# Mathematical operations
result = operations.add(5, 3)
print(result)  # Output: 8

🛠️ Development

Prerequisites

• Python 3.11+
• Poetry

Setup

# Clone the repository
git clone https://github.com/ghpascon/publish_lib_ghp.git
cd publish_lib_ghp

# Install dependencies
poetry install

Testing

# Run all tests
poetry run pytest

# Run specific test file
poetry run pytest tests/test_greeting.py
poetry run pytest tests/test_operations.py

Building

# Build the package
poetry build

# Check the build
poetry run twine check dist/*

📋 API Reference

Greeting Class

say_hello(name: str) -> str

Say hello to someone.

Parameters:

• name (str): The name of the person to greet

Returns:

• str: A greeting message

Raises:

• ValueError: If name is empty or not a string

say_goodbye(name: str) -> str

Say goodbye to someone.

Parameters:

• name (str): The name of the person to say goodbye to

Returns:

• str: A goodbye message

Raises:

• ValueError: If name is empty or not a string

get_greeting_with_time(name: str, time_of_day: str) -> str

Get a time-specific greeting.

Parameters:

• name (str): The name of the person to greet
• time_of_day (str): Time of day ('morning', 'afternoon', 'evening')

Returns:

• str: A time-specific greeting message

Raises:

• ValueError: If name is invalid or time_of_day is not recognized

Operations Class

add(a: int, b: int) -> int

Perform addition of two integers.

Parameters:

• a (int): The first number
• b (int): The second number

Returns:

• int: The sum of a and b

Example:

ops = Operations()
result = ops.add(5, 3)  # Returns 8

🚀 Release Process

This project uses automated releases via GitHub Actions. Use the included commit.py script for easy releases!

Automated Release (Recommended)

# Use the automated script
python commit.py

The script will:

1. Ask for version type (patch, minor, major)
2. Ask for commit message
3. Update version automatically
4. Commit and create tag
5. Trigger GitHub Actions to publish

Manual Release

# Update version
poetry version patch  # or minor/major

# Commit and tag
git add .
git commit -m "Your commit message"
git push origin main
git tag "v$(poetry version --short)"
git push origin "v$(poetry version --short)"

The CI/CD pipeline will automatically:

1. Run tests across multiple Python versions (3.11, 3.12, 3.13)
2. Build the package
3. Publish to PyPI

📝 Documentation

• Setup Guide - How to use this project as a template
• Release Process - How to create and publish releases
• Publishing Guide - Comprehensive guide for package publishing
• PyPI Setup - PyPI configuration instructions
• Contributing - How to contribute to this project
• Security Policy - Security guidelines and reporting
• Changelog - Project history and changes

🏗️ Project Structure

publish_lib_ghp/
├── .github/
│   └── workflows/          # GitHub Actions CI/CD pipelines
├── src/
│   └── publish_lib_ghp/    # Main package code
│       ├── __init__.py     # Package initialization
│       ├── greeting.py     # Greeting functionality
│       └── operations.py   # Mathematical operations
├── tests/                  # Test suite
│   ├── test_greeting.py    # Tests for Greeting class
│   └── test_operations.py  # Tests for Operations class
├── commit.py              # Automated release script
├── pyproject.toml         # Project configuration
├── README.md              # This file
├── SETUP_GUIDE.md         # Template usage guide
├── CHANGELOG.md           # Version history
└── LICENSE                # MIT License

🔐 Security

This project follows security best practices:

• ✅ No hardcoded secrets or API tokens
• ✅ Secure publishing to PyPI via GitHub Actions
• ✅ Automated testing across multiple Python versions
• ✅ Clean and minimal dependencies

See our Security Policy for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run tests: poetry run pytest
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

🎯 Using as Template

Want to create your own Python package? See SETUP_GUIDE.md for step-by-step instructions on how to use this project as a template.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Poetry for modern Python packaging
• GitHub Actions for CI/CD
• PyPI for package distribution
• pytest for testing framework

📊 Project Status

• ✅ Active Development: This project is actively maintained
• ✅ Production Ready: Suitable for production use
• ✅ Well Tested: Comprehensive test coverage
• ✅ Documented: Complete documentation available
• ✅ Secure: Follows security best practices

---

Author: Gabriel Henrique Pascon
Email: gh.pascon@gmail.com
GitHub: @ghpascon