Metadata-Version: 2.4
Name: pyuptimekit
Version: 0.1.0
Summary: A flexible, extensible Python library for monitoring TCP, HTTP, SSL certificates, domain expiry, DNS, and more
Author: PyUptimeKit Contributors
License: MIT
Project-URL: Homepage, https://github.com/HarikrishnanK9/PyUptimeKit
Keywords: monitoring,uptime,health-check,ssl,tcp,dns,domain-expiry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Provides-Extra: http
Requires-Dist: httpx>=0.27.0; extra == "http"
Provides-Extra: domain
Requires-Dist: python-whois>=0.8.0; extra == "domain"
Provides-Extra: dns
Requires-Dist: dnspython>=2.4.0; extra == "dns"
Provides-Extra: ping
Requires-Dist: ping3>=4.0.0; extra == "ping"
Provides-Extra: all
Requires-Dist: httpx>=0.27.0; extra == "all"
Requires-Dist: python-whois>=0.8.0; extra == "all"
Requires-Dist: dnspython>=2.4.0; extra == "all"
Requires-Dist: ping3>=4.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black>=23.9.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# PyUptimeKit

A flexible, extensible Python library for monitoring infrastructure health. PyUptimeKit provides independent, reusable modules for TCP connectivity, HTTP/HTTPS uptime, SSL certificate validation, domain expiry checks, DNS monitoring, ICMP ping, and content validation.

## Features

- **Modular Design**: Each monitor type is independent and reusable
- **Type-Safe**: Full type hints and Pydantic validation throughout
- **Extensible**: Easy to add custom monitor types via common interfaces
- **Flexible Dependencies**: Optional extras for specific monitor types
- **Alpha Release**: Under active development with comprehensive error handling and result normalization

## Monitor Types

- **TCP**: Raw TCP port connectivity and latency checks
- **HTTP/HTTPS**: Web endpoint monitoring with status code validation
- **SSL Certificate**: Certificate expiry, issuer, and validity checks
- **Domain Expiry**: WHOIS-based domain registration expiry monitoring
- **DNS**: DNS resolution and record validation
- **Ping**: ICMP echo request monitoring (platform-dependent)
- **Keyword**: HTTP response content validation

## Installation

### Core Library

```bash
pip install pyuptimekit
```

### With Optional Dependencies

```bash
# HTTP monitoring
pip install pyuptimekit[http]

# Domain expiry monitoring
pip install pyuptimekit[domain]

# DNS monitoring
pip install pyuptimekit[dns]

# Ping monitoring
pip install pyuptimekit[ping]

# All monitor types
pip install pyuptimekit[all]

# Development tools
pip install pyuptimekit[dev]
```

## Quick Start

### Individual Monitor Usage

```python
from pyuptimekit.monitors.tcp import TcpMonitor
from pyuptimekit.models.target import TcpTarget
from pyuptimekit.models.config import TcpConfig

# Create and run a TCP monitor
target = TcpTarget(host="google.com", port=443)
config = TcpConfig(timeout=5)
monitor = TcpMonitor(target=target, config=config)
result = monitor.run()

print(f"Status: {result.status}")
print(f"Latency: {result.duration_ms}ms")
```

### Batch Monitoring with Engine

```python
from pyuptimekit.engine.runner import MonitoringEngine
from pyuptimekit.monitors.tcp import TcpMonitor
from pyuptimekit.monitors.ssl import SslCertificateMonitor

# Create monitoring engine
engine = MonitoringEngine()

# Register monitors
engine.add_monitor(TcpMonitor(host="google.com", port=443))
engine.add_monitor(SslCertificateMonitor(host="github.com"))

# Run all monitors
results = engine.run_all()

for result in results:
    print(f"{result.target}: {result.status}")
```

## Architecture

PyUptimeKit follows a clean architecture with separation of concerns:

```
pyuptimekit/
├── interfaces/     # Common monitor contracts
├── models/         # Pydantic models for configs, results, targets
├── monitors/       # Individual monitor implementations
├── engine/         # Orchestration and batch execution
├── exceptions/     # Typed exception hierarchy
├── config/         # Default configurations
└── utils/          # Shared utilities
```

Each monitor implements a common interface and returns a standardized `MonitorResult`, making it easy to integrate into dashboards, alerting systems, or custom workflows.

## Development

### Setup

```bash
# Clone the repository (URL will be added when published)
pip install -e ".[dev,all]"
```

### Building the Package

```bash
# Build wheel and source distribution (requires build tool from dev extra)
python -m build

# Check package metadata
twine check dist/*
```

### Running Tests

```bash
# Run all tests
pytest

# Run only unit tests (no network)
pytest -m unit

# Run with coverage
pytest --cov=pyuptimekit --cov-report=html
```

### Code Quality

```bash
# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## License

MIT License - see LICENSE file for details.

## Roadmap

- [ ] Async monitor implementations (currently synchronous only)
- [ ] Parallel execution in monitoring engine
- [ ] Retry strategies with exponential backoff
- [ ] Monitor result history and trend analysis
- [ ] Prometheus metrics export
- [ ] WebSocket monitoring
- [ ] Database connectivity checks
- [ ] Custom monitor plugins system

## Credits

Built with inspiration from monitoring tools like Uptime Kuma, Pingdom, and StatusCake.
