Layers (weather)

Bases: ScrubbedSessionState

Client for weather data and grid-image generation.

static_base_url selects the public catalog host. api_key, base_url and gateway_base_url are accepted for construction compatibility with the other service clients and are unused: the catalog is public, and no credential ever goes to that host.

logger instance-attribute

logger: Logger = logger

Logger used for fetch, retry and debug messages.

base_url instance-attribute

base_url: str = base_url

The service base URL passed at construction (unused by this client).

close

close() -> None

Close the static reader's session.

get_weather_file_from_location

get_weather_file_from_location(
*, lat: Latitude, lon: Longitude, radius: Optional[int] = None
)

Return the nearest public weather stations, nearest first.

Parameters:

Returns:

Raises:

get_weather_file_from_identifier

get_weather_file_from_identifier(*, identifier: str)

Return one public weather station's data by uuid or fileName.

Parameters:

Returns:

Raises:

parse_epw

parse_epw(source, **options)

Read one local .epw file and validate it.

The bring-your-own weather entry point, and the only one for a file that is not in the public catalog. Nothing is uploaded, nothing is registered and no request leaves this process. Pass the returned WeatherDocument straight to from_weatherfile_payload and keep it for the retry, because its identity is what proves a resume uses the same weather.

Parameters:

Returns:

Raises:

filter_weather_data

filter_weather_data(
*,
identifier: Optional[str] = None,
weather: Any = None,
time_period: TimePeriod,
)

Return weather filtered to time_period, one record per hour.

Give EITHER identifier (a public catalog station, by uuid or fileName) OR weather (a WeatherDocument from parse_epw). The BYO document is accepted everywhere a station id is, runs entirely on your machine and makes no request at all; the window means the same thing for both.

Parameters:

Returns:

Raises:

gen_grid_image

gen_grid_image(
*,
grid: Sequence[Sequence[Any]],
analysis_type: Optional[str] = None,
criteria: Optional[str] = None,
subtype: Optional[str] = None,
max_long_axis_px: Optional[int] = DEFAULT_MAX_LONG_AXIS_PX,
renderer: Any = REMOVED,
)

Render a result grid to a PNG and return the raw PNG bytes.

The grid is coloured with the public colour registry (registry.infrared.city; no API key, cached per process) for the analysis type you name. The image is 1:1, one pixel per grid cell, up to a 960 px long axis. A failure raises WeatherServiceError; you never get a fallback-coloured image when the registry colours cannot be loaded.

Parameters:

Returns:

Raises:

Bases: ValueError

An EPW file that was refused, with the reason.

A ValueError subclass, so a caller that already catches ValueError around parse_epw keeps working. The named type is what lets a caller separate a bad FILE from a bad request.

One validated EPW file.

Hold it, pass it to a payload builder, and keep it for the retry: its identity is what proves a resumed run uses the same weather as the run it resumes.

Warnings

The identity is computed on every read, never cached. The document is a plain dict you can reach and change, and if you edit it after submitting, the retry is refused rather than served a stale digest that says the weather is unchanged. Computing it hashes the weather columns; it does not re-parse the file.

Attributes:

identity property

identity: str

The versioned weather identity, "sha256:".

It covers the validated values, their order, the location, the calendar columns and the hour basis, and never the file name, a station id or the raw text, so two differently formatted files with the same readings share one identity.

Raises:

location property

location: Mapping[str, Any]

The EPW LOCATION header, as the document records it.

period property

period: Mapping[str, Any]

Row count, records per hour, leap-year and full-year verdicts.

rows property

rows: int

Data rows in the file, before any window is applied.

to_dict

to_dict() -> Dict[str, Any]

Return the document itself, as plain data.

Serialise it with json.dumps.

filter_hours

filter_hours(time_period: TimePeriod) -> List[WeatherDataPoint]

Return the file's hours inside time_period, one record per hour.

The same shape WeatherServiceClient.filter_weather_data returns for a public station, from a local file and with no network call. The window is a date span with a daily hour range, exactly the hours the model counts. A window that crosses the year end (for example 1 December to 28 February) keeps its hours in calendar order of the year: January, February, then December.

Parameters:

Returns:

Raises:

model_inputs

model_inputs(
*,
analysis_type: str,
time_period: TimePeriod,
subtype: Optional[str] = None,
solar_model: Optional[str] = None,
) -> Dict[str, Any]

Return the snake_case weather arrays one model reads, for one window.

The window is applied first, then the required fields are checked on the FILTERED rows, then the period rule, so a gap outside the window is harmless, a gap inside it raises, and a model that needs a full year raises on a shorter one.

solar_model belongs to analysis_type="energy-balance", the one analysis that reads it; on any other analysis it raises, because nothing would read it there. solar_model="irradiance" selects the interior-irradiance input set and its full-year rule; omitted, or "legacy-flat", selects the two climate arrays that model reads.

To RUN energy-balance with a file, use from_weather, which calls this method with the full-year window and the request's own solar_model.

Parameters:

Returns:

Raises:

Bases: ValueError

The document cannot supply what the requested model needs.

Raised for a gap in a required column inside the selected window, for a window shorter than a full year where the model needs one, and for an analysis that has no weather input set. Always raised before submission.

parse_epw(
source: Union[str, bytes, bytearray, PathLike],
*,
max_bytes: Optional[int] = None,
max_rows: Optional[int] = None,
) -> WeatherDocument

Read and validate one .epw file, and return its document.

Parameters:

Returns:

Raises: