discovery: Instructions file for GitHub Copilot

Copilot Instructions for Python API Polling Project

Project Context

This is a Python-based API polling application designed for portability across different environments (local development, Docker containers, and cloud platforms like Azure Discovery).

Code Style Guidelines

Python Standards

• Use Python 3.9+ features and type hints for all function signatures
• Follow PEP 8 naming conventions (snake_case for functions/variables, UPPER_CASE for constants)
• Use pathlib.Path instead of os.path for file operations
• Prefer f-strings for string formatting
• Add docstrings to all functions using Google style format

Configuration Management

• Use environment variables for all configuration with sensible defaults
• Support both .env files (via python-dotenv) and direct environment variables
• Implement configuration precedence: CLI args > env vars > config files > defaults
• Use pydantic Settings classes for configuration validation when possible

API Interaction Patterns

# Always use exponential backoff for retries
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
async def call_api(endpoint: str, **kwargs) -> dict:
    """Make API call with automatic retry logic."""
    pass

Polling Implementation

• Use async/await patterns with asyncio for efficient polling
• Implement configurable poll intervals with jitter to avoid thundering herd
• Always include timeout mechanisms
• Log poll attempts and results at appropriate levels (DEBUG for success, WARNING for retries, ERROR for failures)

Error Handling

• Use custom exception classes for different error scenarios
• Always catch and log exceptions at the appropriate level
• Implement graceful shutdown handling (SIGTERM, SIGINT)
• Return meaningful exit codes (0=success, 1=general error, 2=config error, 3=connection error)

Logging

import logging
import sys

# Configure structured logging
logging.basicConfig(
    level=logging.INFO,
    format='[%(asctime)s] [%(name)s] [%(levelname)s] %(message)s',
    handlers=[logging.StreamHandler(sys.stdout)]
)