Code Mode Rules

# Code Mode Rules

This file provides non-obvious coding rules for the Home Assistant Statistics Import/Export integration.

## Critical Coding Patterns

### Error Handling (Non-Negotiable)
- ALL validation errors MUST use helpers.handle_error()
- Never raise ValueError, TypeError, or generic exceptions directly
- handle_error() logs warning AND raises HomeAssistantError - this dual behavior is required

### Custom Type: UnitFrom Enum
UnitFrom enum (ENTITY or TABLE) is used throughout:
- Determines if unit column is required/forbidden in DataFrame validation
- External statistics (: format) MUST use TABLE, never ENTITY
- When adding unit to DataFrame, check both source (recorder vs external) AND unit_from_where

### Statistic ID Format Validation
get_source() must be called for ANY statistic_id:
- Returns \
recorder\ for internal (. separator)
- Returns domain name for external (: separator)
- Rejects recorder domain in both formats (explicit validation)
- Uses Home Assistant's valid_entity_id() and valid_statistic_id() functions

### Pandas DataFrame Column Rules
are_columns_valid() enforces strict rules:
- Require: statistic_id, start, and conditionally unit
- Require EITHER all three of (min, max, mean) OR sum - never mix
- Reject ANY unknown columns (typos in column names fail immediately)
- Special case: if unit_from_entity=True, the unit column MUST NOT exist

### Delimiter Handling Edge Case
validate_delimiter() converts:
- None  \\\t\ (tab character)
- String \\\\\t\  \\\t\ (actual tab, not backslash-t)
- Any other single character  unchanged
- Multi-character or empty string  raises error

### Min/Max/Mean Constraint
min_max_mean_are_valid() enforces:
- ALWAYS: min_value  mean_value  max_value
- Raises HomeAssistantError immediately if violated
- Called in validation chain, not optional

### File Path Security (Export Only)
validate_filename() prevents traversal:
- Rejects absolute paths (/ at start)
- Rejects path separators (both / and \\)
- Rejects .. sequences
- Validates resolved path stays within config_dir using Path.relative_to()
- Used only in export; import paths come from config file

### Service Registration Pattern
setup():
- Registers services synchronously
- Import handlers are sync functions
- Export handler is async - must use async def and await for executor jobs
- This mixed pattern is intentional for Home Assistant compatibility

### Timezone Conversion Details
- Use zoneinfo.ZoneInfo (Python 3.12 stdlib), NOT pytz
- Default datetime format: \%d.%m.%Y
%H:%M\ (no seconds, full hours only)
- When parsing input: apply timezone, then convert to UTC with .astimezone(dt.UTC)
- When formatting output: convert to target timezone with .astimezone(tz)

## Ruff Configuration Constraints

- Line length: 160 characters (hard limit)
- Target: Python 3.12
- MCCabe complexity: max 25 per function
- Type hints required (ANN401 ignored for Any only)
- All other rules enforced (see .ruff.toml for ignored rules)