# Period Quick Reference Card

## Basic Syntax

```python
from tradepose_client.batch import Period

# Quarters (fixed)
Period.Q1(2024)  # Jan-Mar
Period.Q2(2024)  # Apr-Jun
Period.Q3(2024)  # Jul-Sep
Period.Q4(2024)  # Oct-Dec

# Years
Period.from_year(year, n_years=1)
Period.from_year(2024)           # 2024 only
Period.from_year(2024, 3)        # 2024-2026 (3 years forward)
Period.from_year(2024, -2)       # 2023-2024 (2 years back)

# Months
Period.from_month(year, month, n_months=1, n_years=0)
Period.from_month(2024, 3)       # March 2024
Period.from_month(2024, 3, 3)    # Mar-May 2024 (3 months)
Period.from_month(2024, 3, -3)   # Jan-Mar 2024 (3 months back)
Period.from_month(2024, 1, 6, 1) # Jan 2024 - Jun 2025 (6m + 1y)

# Custom
Period(start="2024-01-15", end="2024-02-15")
```

## Direction Rules

| Value | Direction | Reference Point |
|-------|-----------|-----------------|
| Positive | Forward | START from reference, span forward |
| Negative | Backward | END at reference, span backward |

## Common Patterns

### Rolling Windows
```python
# Last 3/6/12 months from current month
Period.from_month(2024, 12, n_months=-3)   # Oct-Dec 2024
Period.from_month(2024, 12, n_months=-6)   # Jul-Dec 2024
Period.from_month(2024, 12, n_months=-12)  # Jan-Dec 2024
```

### Year-over-Year
```python
# Same period across years
Period.from_month(2023, 1, n_months=3)  # Q1 2023
Period.from_month(2024, 1, n_months=3)  # Q1 2024
```

### Long-term Trends
```python
Period.from_year(2024, n_years=-5)   # 2020-2024 (5-year lookback)
Period.from_year(2020, n_years=10)   # 2020-2029 (10-year trend)
```

### Seasonal Analysis
```python
# Winter (Dec-Feb)
Period.from_month(2024, 2, n_months=-3)  # Dec 2023 - Feb 2024

# Summer (Jun-Aug)
Period.from_month(2024, 6, n_months=3)   # Jun-Aug 2024
```

## Quick Examples

```python
# Quarterly lookback
q_back = Period.from_month(2024, 12, n_months=-3)  # Q4 2024

# Half-year forward
h_forward = Period.from_month(2024, 1, n_months=6)  # H1 2024

# 2-year historical
two_year = Period.from_year(2024, n_years=-2)  # 2023-2024

# Cross-year winter
winter = Period.from_month(2024, 2, n_months=-3)  # Dec 2023 - Feb 2024
```

## Validation

- ✅ `start < end` (automatic)
- ✅ Month: 1-12
- ✅ n_years ≠ 0 (for from_year)
- ✅ n_months ≠ 0 (for from_month)
- ✅ Total duration ≠ 0
- ✅ Leap years (automatic)
- ✅ Cross-year (automatic)
