pyuptimekit 0.1.0

A flexible, extensible Python library for monitoring TCP, HTTP, SSL certificates, domain expiry, DNS, and more

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

pip install pyuptimekit

With Optional Dependencies

# 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

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

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

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

Building the Package

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

# Check package metadata
twine check dist/*

Running Tests

# Run all tests
pytest

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

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

Code Quality

# 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.