caddis-plugin: Instructions file for GitHub Copilot

Python Coding Standards

CRITICAL: Path Handling (Portability)

NEVER use absolute paths. All code must be portable and work when copied to any location.

from pathlib import Path

# ✅ CORRECT: Relative to script location
PROJECT_ROOT = Path(__file__).parent.parent  # adjust .parent count based on file depth
DATA_DIR = PROJECT_ROOT / "data"
CONFIG_PATH = PROJECT_ROOT / "config.json"

# ❌ WRONG: Absolute paths break portability
DATA_DIR = Path("E:\\Projects\\MyApp\\data")  # NEVER DO THIS
CONFIG_PATH = "/home/user/app/config.json"   # NEVER DO THIS

Standard path resolution pattern:

from pathlib import Path

# Get paths relative to current file
CURRENT_DIR = Path(__file__).parent
PROJECT_ROOT = CURRENT_DIR.parent.parent  # from src/services/file.py → project root

# Common directories
DATA_DIR = PROJECT_ROOT / "data"
LOGS_DIR = PROJECT_ROOT / "logs"
STATIC_DIR = PROJECT_ROOT / "static"

# Ensure directories exist
DATA_DIR.mkdir(exist_ok=True)
LOGS_DIR.mkdir(exist_ok=True)

See portability.instructions.md for complete guidelines.

---

Code Style

PEP 8 Compliance

• Follow PEP 8 style guide
• Line length: 100 characters maximum
• Use 4 spaces for indentation (no tabs)
• Two blank lines between top-level definitions
• One blank line between method definitions

Imports

Organize imports in three groups, alphabetically within each:

# 1. Standard library
import os
import sys
from datetime import datetime, timedelta
from pathlib import Path
from typing import Any, Dict, List, Optional

# 2. Third-party packages
import pandas as pd
import streamlit as st
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
from loguru import logger

# 3. Local imports
from <SHARED_LIBS>.theme import apply_theme        # from project-config.md
from <SHARED_LIBS>.adapters import DatabaseAdapter  # from project-config.md
from config import settings

Type Hints

Use type hints on all functions: