# opsgenielib

A Python library for interacting with the Opsgenie API.

**Documentation:** https://opsgenielib.readthedocs.org/en/latest

## Installation

Install from PyPI:

```bash
pip install opsgenielib
```

Or install from source:

```bash
git clone https://github.com/yourusername/opsgenielib.git
cd opsgenielib
pip install .
```

## Usage

```python
from opsgenielib import Opsgenie

# Initialize with your API key
opsgenie = Opsgenie(api_key='your-api-key')

# List teams
teams = opsgenie.list_teams()

# Get alerts
alerts = opsgenie.query_alerts('status: open')

# Create an alert
opsgenie.create_alert(
    message='Server is down',
    description='Production server not responding',
    priority='P1'
)
```

## Development Setup

This project uses [uv](https://docs.astral.sh/uv/) for fast, reliable Python package management.

### Prerequisites

Install uv:

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip
pip install uv
```

### Getting Started

1. Clone the repository:

```bash
git clone <repository-url>
cd opsgenielib
```

2. Sync dependencies (creates .venv automatically):

```bash
uv sync
```

3. Activate the virtual environment:

```bash
# macOS/Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate
```

## Development Workflow

### Running Tests

Run tests with pytest:

```bash
uv run pytest
```

Run tests with coverage:

```bash
uv run pytest --cov=opsgenielib --cov-report=html --cov-report=term
```

Run tox for multi-version testing:

```bash
uv run tox
```

### Linting

Run ruff for fast, comprehensive linting:

```bash
uv run ruff check opsgenielib
```

Format code with ruff:

```bash
uv run ruff format opsgenielib
```

The linting configuration is in `pyproject.toml` under `[tool.ruff]`.

### Building the Package

Build source and wheel distributions:

```bash
uv build
```

This creates distributions in the `dist/` directory.

### Publishing to PyPI

1. Build the package:

```bash
uv build
```

2. Upload to PyPI:

```bash
uv publish
```

3. Or upload to TestPyPI first:

```bash
uv publish --publish-url https://test.pypi.org/legacy/
```

Note: You can set credentials via environment variables `UV_PUBLISH_USERNAME` and `UV_PUBLISH_PASSWORD`, or use `UV_PUBLISH_TOKEN` for token-based authentication.

### Version Management

Version is stored in the `.VERSION` file. To bump the version:

1. Update the version in `.VERSION`
2. Update `HISTORY.md` with changes
3. Commit and tag:

```bash
git add .VERSION HISTORY.md
git commit -m "Bump version to X.Y.Z"
git tag vX.Y.Z
git push origin main --tags
```

### Generating Documentation

Build documentation with Sphinx:

```bash
cd docs
uv run sphinx-build -b html . _build/html
```

View the documentation by opening `docs/_build/html/index.html`.

### Adding Dependencies

Add a runtime dependency:

```bash
uv add package-name
```

Add a development dependency:

```bash
uv add --dev package-name
```

Remove a dependency:

```bash
uv remove package-name
```

Lock dependencies after changes:

```bash
uv lock
```

## Best Practices

### Development

- Always use `uv run` to execute commands in the project environment
- Run tests before committing: `uv run pytest`
- Run linting before committing: `uv run ruff check opsgenielib`
- Format code before committing: `uv run ruff format opsgenielib`
- Keep dependencies up to date: `uv lock --upgrade`

### Building and Publishing

- Use `uv build` to build distributions
- Test on TestPyPI before publishing to production PyPI
- Always update `HISTORY.md` before releasing
- Tag releases with semantic versioning (vX.Y.Z)

## Configuration Files

- `pyproject.toml` - Project metadata and dependencies
- `.VERSION` - Current version number
- `pyproject.toml` (`[tool.ruff]` section) - Linting and formatting configuration
- `tox.ini` - Tox testing configuration
- `uv.lock` - Locked dependency versions (auto-generated)

## Quick Reference

Common commands:

```bash
# Setup
uv sync                          # Install dependencies

# Development
uv run pytest                     # Run tests
uv run ruff check opsgenielib     # Lint code
uv run ruff format opsgenielib    # Format code
uv run pytest --cov=opsgenielib   # Run tests with coverage

# Dependencies
uv add requests                  # Add dependency
uv add --dev pytest              # Add dev dependency
uv lock                          # Update lockfile

# Building
uv build                         # Build package

# Publishing
uv publish                       # Upload to PyPI
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

MIT License - see LICENSE file for details.

## Credits

**Development Lead:** Yorick Hoorneman <yhoorneman@schubergphilis.com>
