publish-lib-example 1.1.1
A simple Python library demonstrating how to publish packages to PyPI
License: MIT
Requires Python: <4.0,>=3.11
Keywords: python, library, example, pypi, packaging

# publish-lib-ghp

[![PyPI version](https://badge.fury.io/py/publish-lib-ghp.svg)](https://badge.fury.io/py/publish-lib-ghp)
[![Python versions](https://img.shields.io/pypi/pyversions/publish-lib-ghp.svg)](https://pypi.org/project/publish-lib-ghp/)
[![Tests](https://github.com/ghpascon/publish_lib_ghp/workflows/Test/badge.svg)](https://github.com/ghpascon/publish_lib_ghp/actions?query=workflow%3ATest)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
pip install publish-lib-ghp
```

## 🔧 Usage

```python
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](https://python-poetry.org/docs/#installation)

### Setup

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

# Install dependencies
poetry install
```

### Testing

```bash
# 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

```bash
# 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:**
```python
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)

```bash
# 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

```bash
# 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](SETUP_GUIDE.md) - How to use this project as a template
- [Release Process](RELEASE.md) - How to create and publish releases
- [Publishing Guide](PUBLISHING.md) - Comprehensive guide for package publishing
- [PyPI Setup](PYPI_SETUP.md) - PyPI configuration instructions
- [Contributing](CONTRIBUTING.md) - How to contribute to this project
- [Security Policy](SECURITY.md) - Security guidelines and reporting
- [Changelog](CHANGELOG.md) - 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](SECURITY.md) for details.

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) 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](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](LICENSE) file for details.

## 🙏 Acknowledgments

- [Poetry](https://python-poetry.org/) for modern Python packaging
- [GitHub Actions](https://github.com/features/actions) for CI/CD
- [PyPI](https://pypi.org/) for package distribution
- [pytest](https://pytest.org/) 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](https://github.com/ghpascon)