mirror of
https://github.com/jpawlowski/hass.tibber_prices.git
synced 2026-03-30 05:13:40 +00:00
docs(agents): remove status tracking, focus on patterns only
Cleaned up AGENTS.md to focus on patterns and conventions: Removed: - "Current State (as of Nov 2025)" section - "Classes that need renaming" outdated list - "Action Required" checklist - Temporal statements about current project state Added: - TypedDict exemption in "When prefix can be omitted" list - Clear rationale: documentation-only, never instantiated Rationale: AGENTS.md documents patterns and conventions that help AI understand the codebase structure. Status tracking belongs in git history or planning documents. The file should be timeless guidance, not a snapshot of work in progress. Impact: Documentation is now focused on "how to write code correctly" rather than "what state is the code in now".
This commit is contained in:
parent
3b11c6721e
commit
36fef2da89
1 changed files with 2 additions and 59 deletions
61
AGENTS.md
61
AGENTS.md
|
|
@ -1718,6 +1718,7 @@ Use semantic prefixes that describe the PURPOSE, not the package location.
|
|||
- 🟡 Type aliases and callbacks (e.g., `TimeServiceCallback` is acceptable)
|
||||
- 🟡 Small NamedTuples used only for internal function returns (e.g., within calculators)
|
||||
- 🟡 Enums that are clearly namespaced (e.g., `QueryType` in `api.queries`)
|
||||
- 🟡 **TypedDict classes**: Documentation-only constructs (never instantiated), used solely for IDE autocomplete - shorter names improve readability (e.g., `IntervalPriceAttributes`, `PeriodAttributes`)
|
||||
|
||||
**Private Classes (Module-Internal):**
|
||||
|
||||
|
|
@ -1732,8 +1733,6 @@ class _InternalHelper:
|
|||
result = _InternalHelper().process()
|
||||
```
|
||||
|
||||
**Important:** Currently (Nov 2025), this project has **NO private classes** - all classes are used across module boundaries and therefore need the `TibberPrices` prefix.
|
||||
|
||||
**When to use private classes:**
|
||||
- ❌ **DON'T** use for code organization alone - if it deserves a class, it's usually public
|
||||
- ✅ **DO** use for internal implementation details (e.g., state machines, internal builders)
|
||||
|
|
@ -1753,63 +1752,7 @@ class _ApiRetryStateMachine:
|
|||
|
||||
In practice, most "helper" logic should be **functions**, not classes. Reserve classes for stateful components.
|
||||
|
||||
**Current State (as of Nov 2025):**
|
||||
|
||||
⚠️ **Known Issue**: Many classes in this project lack the `TibberPrices` prefix. This is a technical debt item that needs addressing.
|
||||
|
||||
**Classes that need renaming:**
|
||||
```python
|
||||
# Coordinator module
|
||||
DataFetcher → TibberPricesDataFetcher
|
||||
DataTransformer → TibberPricesDataTransformer
|
||||
ListenerManager → TibberPricesListenerManager
|
||||
PeriodCalculator → TibberPricesPeriodCalculator
|
||||
TimeService → TibberPricesTimeService
|
||||
CacheData → TibberPricesCacheData
|
||||
|
||||
# Config flow
|
||||
CannotConnectError → TibberPricesCannotConnectError
|
||||
InvalidAuthError → TibberPricesInvalidAuthError
|
||||
|
||||
# Entity utils
|
||||
IconContext → TibberPricesIconContext
|
||||
|
||||
# Sensor calculators (8 classes)
|
||||
BaseCalculator → TibberPricesBaseCalculator
|
||||
IntervalCalculator → TibberPricesIntervalCalculator
|
||||
RollingHourCalculator → TibberPricesRollingHourCalculator
|
||||
DailyStatCalculator → TibberPricesDailyStatCalculator
|
||||
Window24hCalculator → TibberPricesWindow24hCalculator
|
||||
VolatilityCalculator → TibberPricesVolatilityCalculator
|
||||
TrendCalculator → TibberPricesTrendCalculator
|
||||
TimingCalculator → TibberPricesTimingCalculator
|
||||
MetadataCalculator → TibberPricesMetadataCalculator
|
||||
|
||||
# Period handlers (NamedTuples in types.py)
|
||||
IntervalCriteria → TibberPricesIntervalCriteria
|
||||
PeriodConfig → TibberPricesPeriodConfig
|
||||
PeriodData → TibberPricesPeriodData
|
||||
PeriodStatistics → TibberPricesPeriodStatistics
|
||||
ThresholdConfig → TibberPricesThresholdConfig
|
||||
SpikeCandidateContext → TibberPricesSpikeCandidateContext
|
||||
```
|
||||
|
||||
**Action Required:**
|
||||
Before making changes to these classes, plan the refactoring:
|
||||
1. Create a plan in `/planning/class-naming-refactoring.md`
|
||||
2. Use multi_replace_string_in_file for bulk renames
|
||||
3. Run `./scripts/check` after each module
|
||||
4. Update imports across the codebase
|
||||
5. Test thoroughly with `./scripts/develop`
|
||||
|
||||
**When adding NEW classes:**
|
||||
- ✅ ALWAYS use `TibberPrices` prefix for public classes
|
||||
- ✅ Document in docstring if prefix is intentionally omitted (with justification)
|
||||
- ✅ Check HA Core integrations for similar patterns when in doubt
|
||||
|
||||
See `docs/development/coding-guidelines.md` for detailed naming conventions.
|
||||
|
||||
### Ruff and Pyright Configuration
|
||||
### Ruff Code Style Guidelines
|
||||
|
||||
**Ruff config (`pyproject.toml` under `[tool.ruff]`):**
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue