homelab/.planning/codebase/CONVENTIONS.md

# Coding Conventions

**Analysis Date:** 2026-02-04

## Naming Patterns

**Files:**
- Python files: lowercase with underscores (e.g., `bot.py`, `credentials`)
- Bash scripts: lowercase with hyphens (e.g., `npm-api`, `uptime-kuma`)
- Helper scripts in `~/bin/`: all lowercase, no extension (e.g., `pve`, `pbs`, `dns`)

**Functions:**
- Python: snake_case (e.g., `cmd_status()`, `get_authorized_users()`, `run_command()`)
- Bash: snake_case with `cmd_` prefix for command handlers (e.g., `cmd_status()`, `cmd_tasks()`)
- Bash: auxiliary functions also use snake_case (e.g., `ssh_pbs()`, `get_token()`)

**Variables:**
- Python: snake_case for local/module vars (e.g., `authorized_users`, `output_lines`)
- Python: UPPERCASE for constants (e.g., `TOKEN`, `INBOX_FILE`, `AUTHORIZED_FILE`, `NODE`, `PBS_HOST`)
- Bash: UPPERCASE for environment variables and constants (e.g., `PBS_HOST`, `TOKEN`, `BASE`, `DEFAULT_ZONE`)
- Bash: lowercase for local variables (e.g., `hours`, `cutoff`, `status_icon`)

**Types/Classes:**
- Python: PascalCase for imported classes (e.g., `ProxmoxAPI`, `Update`, `Application`)
- Dictionary/config keys: lowercase with hyphens or underscores (e.g., `token_name`, `max-mem`)

## Code Style

**Formatting:**
- No automated formatter detected in codebase
- Python: PEP 8 conventions followed informally
  - 4-space indentation
  - Max line length ~90-100 characters (observed in practice)
  - Blank lines: 2 lines before module-level functions, 1 line before methods
- Bash: 4-space indentation (observed)

**Linting:**
- No linting configuration detected (no .pylintrc, .flake8, .eslintrc)
- Code style is manually maintained

**Docstrings:**
- Python: Triple-quoted strings at module level describing purpose
  - Example from `telegram/bot.py`:
  ```python
  """
  Homelab Telegram Bot
  Two-way interactive bot for homelab management and notifications.
  """
  ```
- Python: Function docstrings used for major functions
  - Single-line format for simple functions
  - Example: `"""Handle /start command - first contact with bot."""`
  - Example: `"""Load authorized user IDs."""`

## Import Organization

**Order:**
1. Standard library imports (e.g., `sys`, `os`, `json`, `subprocess`)
2. Third-party imports (e.g., `ProxmoxAPI`, `telegram`, `pocketbase`)
3. Local imports (rarely used in this codebase)

**Path Aliases:**
- No aliases detected
- Absolute imports used throughout

**Credential Loading Pattern:**
All scripts that need credentials follow the same pattern:
```python
# Load credentials
creds_path = Path.home() / ".config" / <service> / "credentials"
creds = {}
with open(creds_path) as f:
    for line in f:
        if '=' in line:
            key, value = line.strip().split('=', 1)
            creds[key] = value
```

Or in Bash:
```bash
source ~/.config/dns/credentials
```

## Error Handling

**Patterns:**
- Python: Try-except with broad exception catching (bare `except:` used in `pve` script lines 70, 82, 95, 101)
  - Not ideal but pragmatic for CLI tools that need to try multiple approaches
  - Example from `pve`:
  ```python
  try:
      status = pve.nodes(NODE).lxc(vmid).status.current.get()
      # ...
      return
  except:
      pass
  ```

- Python: Explicit exception handling in telegram bot
  - Catches `subprocess.TimeoutExpired` specifically in `run_command()` function
  - Example from `telegram/bot.py`:
  ```python
  try:
      result = subprocess.run(...)
      output = result.stdout or result.stderr or "No output"
      if len(output) > 4000:
          output = output[:4000] + "\n... (truncated)"
      return output
  except subprocess.TimeoutExpired:
      return "Command timed out"
  except Exception as e:
      return f"Error: {e}"
  ```

- Bash: Set strict mode with `set -e` in some scripts (`dns` script line 12)
  - Causes script to exit on first error

- Bash: No error handling in most scripts (`pbs`, `beszel`, `kuma`)
  - Relies on exit codes implicitly

**Return Value Handling:**
- Python: Functions return data directly or None on failure
  - Example from `pbs` helper: Returns JSON-parsed data or string output
  - Example from `pve`: Returns nothing (prints output), but uses exceptions for flow control

- Python: Command runner returns error strings: `"Command timed out"`, `"Error: {e}"`

## Logging

**Framework:**
- Python: Standard `logging` module
  - Configured in `telegram/bot.py` lines 18-22:
  ```python
  logging.basicConfig(
      format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
      level=logging.INFO
  )
  logger = logging.getLogger(__name__)
  ```
  - Log level: INFO
  - Format includes timestamp, logger name, level, message

**Patterns:**
- `logger.info()` for general informational messages
  - Example: `logger.info("Starting Homelab Bot...")`
  - Example: `logger.info(f"Inbox message from {user.first_name}: {message[:50]}...")`
  - Example: `logger.info(f"Photo saved from {user.first_name}: {filepath}")`

- Bash: Uses `echo` for output, no structured logging
  - Informational messages for user feedback
  - Error messages sent to stdout (not stderr)

## Comments

**When to Comment:**
- Module-level docstrings at top of file (required for all scripts)
- Usage examples in module docstrings (e.g., `pve`, `pbs`, `kuma`)
- Inline comments for complex logic (e.g., in `pbs` script parsing hex timestamps)
- Comments on tricky regex patterns (e.g., `pbs` tasks parsing)

**Bash Comments:**
- Header comment with script name, purpose, and usage (lines 1-10)
- Inline comments before major sections (e.g., `# Datastore info`, `# Storage stats`)
- No comments in simple expressions

**Python Comments:**
- Header comment with purpose (module docstring)
- Sparse inline comments except for complex sections
- Example from `telegram/bot.py` line 71: `# Telegram has 4096 char limit per message`
- Example from `pve` line 70: `# Try as container first`

## Function Design

**Size:**
- Python: Functions are generally 10-50 lines
  - Smaller functions for simple operations (e.g., `is_authorized()` is 2 lines)
  - Larger functions for command handlers that do setup + API calls (e.g., `status()` is 40 lines)

- Bash: Functions are typically 20-80 lines
  - Longer functions acceptable for self-contained operations like `cmd_status()` in `pbs`

**Parameters:**
- Python: Explicit parameters, typically 1-5 parameters per function
  - Optional parameters with defaults (e.g., `timeout: int = 30`, `port=45876`)
  - Type hints not used consistently (some functions have them, many don't)

- Bash: Parameters passed as positional arguments
  - Some functions take zero parameters and rely on global variables
  - Example: `ssh_pbs()` in `pbs` uses global `$PBS_HOST`

**Return Values:**
- Python: Functions return data (strings, dicts, lists) or None
  - Command handlers often return nothing (implicitly None)
  - Helper functions return computed values (e.g., `is_authorized()` returns bool)

- Bash: Functions print output directly, return exit codes
  - No explicit return values beyond exit codes
  - Output captured by caller with `$()`

## Module Design

**Exports:**
- Python: All functions are module-level, no explicit exports
  - `if __name__ == "__main__":` pattern used in all scripts to guard main execution
  - Example from `beszel` lines 101-152

- Bash: All functions are script-level, called via case statement
  - Main dispatch logic at bottom of script
  - Example from `dns` lines 29-106: `case "$1" in ... esac`

**Async/Await (Telegram Bot Only):**
- Python telegram bot uses `asyncio` and `async def` for all handlers
- All command handlers are async (e.g., `async def start()`)
- Use `await` for async operations (e.g., `await update.message.reply_text()`)
- Example from `telegram/bot.py` lines 81-94:
```python
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Handle /start command - first contact with bot."""
    user = update.effective_user
    chat_id = update.effective_chat.id
    # ... async operations with await
```

**File Structure:**
- Single-file modules: Most helpers are single files
- `telegram/bot.py`: Main bot implementation with all handlers
- `/bin/` scripts: Each script is self-contained with helper functions + main dispatch

## Data Structures

**JSON/Config Files:**
- Credentials files: Simple `KEY=value` format (no JSON)
- PBS task logging: Uses hex-encoded UPID format, parsed with regex
- Telegram bot: Saves messages to text files with timestamp prefix
- JSON output: Parsed with `python3 -c "import sys, json; ..."` in Bash scripts

**Error Response Patterns:**
- API calls: Check for `.get('status') == 'ok'` or similar
- Command execution: Check `returncode == 0`, capture stdout/stderr
- API clients: Let exceptions bubble up, caught at command handler level

## Conditionals and Flow Control

**Python:**
- if/elif/else chains for command dispatch
- Simple truthiness checks: `if not user_id:`, `if not alerts:`
- Example from `telegram/bot.py` line 86-100: Authorization check pattern

**Bash:**
- case/esac for command dispatch (preferred)
- if [[ ]] with regex matching for parsing
- Example from `pbs` lines 122-143: Complex regex with BASH_REMATCH array

## Security Patterns

**Credential Management:**
- Credentials stored in `~/.config/<service>/credentials` with restricted permissions (not enforced in code)
- Telegram token loaded from file, not environment
- Credentials never logged or printed

**Input Validation:**
- Bash: Basic validation with isalnum() check in `ping_host()` function
  - Example: `if not host.replace('.', '').replace('-', '').isalnum():`
- Bash: Whitelist command names from case statements
- No SQL injection risk (no databases used directly)

**Shell Injection:**
- Bash scripts use quoted variables appropriately
- Some inline Python in Bash uses string interpolation (potential risk)
  - Example from `dns` lines 31-37: `curl ... | python3 -c "..."` with variable interpolation

---

*Convention analysis: 2026-02-04*