from typing import TypedDict, List, Dict, NotRequired
from datetime import datetime

class FXTimeseries(TypedDict, total=False):
    # Required keys
    locationId: str
    parameterId: str
    timesteps: List[datetime]
    values: List[float]
    # Optional / conditional keys
    qualifierId: NotRequired[str]
    flags: NotRequired[List[str]]  # FEWS flags are typically strings, not floats
    timestepsPattern: NotRequired[str]
    type: NotRequired[str]
    timeStepSize: NotRequired[int]
    startDateTime: NotRequired[datetime]
    endDateTime: NotRequired[datetime]
    missVal: NotRequired[str]
    stationName: NotRequired[str]
    units: NotRequired[str]
    creationDateTime: NotRequired[datetime]
    extraHeader: NotRequired[Dict[str, str]]  # storage for additional header properties not explicitly typed

class FXData(TypedDict, total=False):
    """
    A dictionary representing a document to be read/written by the library.

    Fields:

    - timeseries (List[FXTimeseries]): A list of FXTimeseries to be written to the driver XML (only needed for write operation)
    - inputFilePath (str): File path of the input XML file (only needed for read operation)
    - outputFilePath (str): File path of the driver XML file (only needed for write operation)
    """
    pi: NotRequired[str]
    xsi: NotRequired[str]
    version: NotRequired[str]
    timeZone: NotRequired[str]
    schemaLocation: NotRequired[str]
    ns: NotRequired[str]  # namespace used when reading
    timestepsPatterns: NotRequired[Dict[str, List[datetime]]]
    timeseries: NotRequired[List[FXTimeseries]]
    outputFilePath: NotRequired[str]
    inputFilePath: NotRequired[str]
