Async Client

flowerhub_portal_api_client.async_client.AsyncFlowerhubClient

Async client for Flowerhub Portal API.

Provides Home Assistant–friendly async methods with built-in token refresh, retries, timeouts, and optional callbacks for authentication and API errors.

Configure per-call behavior using raise_on_error, retry_5xx_attempts, and timeout_total. Results are plain dicts conforming to TypedDict contracts defined in flowerhub_portal_api_client.types.

__aenter__() async

Enter async context manager; returns the client itself.

__aexit__(exc_type, exc, tb) async

Exit async context manager, ensuring cleanup via close().

async_fetch_asset(asset_id=None, *, raise_on_error=True, retry_5xx_attempts=None, timeout_total=None) async

Fetch asset information and update flowerhub_status.

Parameters:

Name	Type	Description	Default
asset_id	Optional[int]	Asset identifier. Defaults to self.asset_id.	None
raise_on_error	bool	If True, raises ApiError on HTTP/validation errors.	True
retry_5xx_attempts	Optional[int]	Optional number of retries for 5xx; None disables.	None
timeout_total	Optional[float]	Optional total timeout override in seconds.	None

Returns:

Name	Type	Description
AssetFetchResult	AssetFetchResult	{status_code, asset_info, flowerhub_status, error}.

Raises:

Type	Description
ValueError	If asset id is not provided.
ApiError	On invalid response, missing flowerHubStatus, or HTTP errors when raise_on_error=True.

async_fetch_asset_id(asset_owner_id=None, *, raise_on_error=True) async

Fetch asset ID for an asset owner.

Parameters:

Name	Type	Description	Default
asset_owner_id	Optional[int]	Asset owner identifier. Defaults to self.asset_owner_id.	None
raise_on_error	bool	If True, raises ApiError on validation/HTTP errors.	True

Returns:

Name	Type	Description
AssetIdResult	AssetIdResult	{status_code, asset_id, error}.

Raises:

Type	Description
ValueError	If asset owner id is not provided.
ApiError	When parsing/validation fails and raise_on_error=True.

async_fetch_asset_owner(asset_owner_id=None, *, raise_on_error=True, retry_5xx_attempts=None, timeout_total=None) async

Fetch asset owner details including installer, distributor, asset, and compensation.

Parameters:

Name	Type	Description	Default
asset_owner_id	Optional[int]	Asset owner identifier. Defaults to self.asset_owner_id.	None
raise_on_error	bool	If True, raises ApiError on invalid payload/HTTP errors.	True
retry_5xx_attempts	Optional[int]	Optional number of retries for 5xx.	None
timeout_total	Optional[float]	Optional total timeout override in seconds.	None

Returns:

Name	Type	Description
AssetOwnerDetailsResult	AssetOwnerDetailsResult	{status_code, details, json, text, error}.

Raises:

Type	Description
ValueError	If asset owner id is not provided.
ApiError	If payload is not a dict (when raise_on_error=True).

async_fetch_asset_owner_profile(asset_owner_id=None, *, raise_on_error=True, retry_5xx_attempts=None, timeout_total=None) async

Fetch asset owner profile details.

Parameters:

Name	Type	Description	Default
asset_owner_id	Optional[int]	Asset owner identifier. Defaults to self.asset_owner_id.	None
raise_on_error	bool	If True, raises ApiError on invalid payload/HTTP errors.	True
retry_5xx_attempts	Optional[int]	Optional number of retries for 5xx.	None
timeout_total	Optional[float]	Optional total timeout override in seconds.	None

Returns:

Name	Type	Description
ProfileResult	ProfileResult	{status_code, profile, json, text, error}.

Raises:

Type	Description
ValueError	If asset owner id is not provided.
ApiError	If payload is not a dict (when raise_on_error=True).

async_fetch_available_uptime_months(asset_id=None, *, raise_on_error=True, retry_5xx_attempts=None, timeout_total=None) async

Fetch available uptime months for the given asset.

Parameters:

Name	Type	Description	Default
asset_id	Optional[int]	Asset identifier. Defaults to self.asset_id.	None
raise_on_error	bool	If True, raises ApiError on invalid payload/HTTP errors.	True
retry_5xx_attempts	Optional[int]	Optional number of retries for 5xx.	None
timeout_total	Optional[float]	Optional total timeout override in seconds.	None

Returns:

Name	Type	Description
UptimeAvailableMonthsResult	UptimeAvailableMonthsResult	{status_code, months, json, text, error}.

Raises:

Type	Description
ValueError	If asset id is not provided.
ApiError	If payload is not a list (when raise_on_error=True).

async_fetch_consumption(asset_owner_id=None, *, raise_on_error=True, retry_5xx_attempts=None, timeout_total=None) async

Fetch consumption data for the given asset owner.

Parameters:

Name	Type	Description	Default
asset_owner_id	Optional[int]	Asset owner identifier. Defaults to self.asset_owner_id.	None
raise_on_error	bool	If True, raises ApiError on invalid payload/HTTP errors.	True
retry_5xx_attempts	Optional[int]	Optional number of retries for 5xx.	None
timeout_total	Optional[float]	Optional total timeout override in seconds.	None

Returns:

Name	Type	Description
ConsumptionResult	ConsumptionResult	{status_code, consumption, json, text, error}.

Raises:

Type	Description
ValueError	If asset owner id is not provided.
ApiError	If payload is not a list (when raise_on_error=True).

async_fetch_electricity_agreement(asset_owner_id=None, *, raise_on_error=True, retry_5xx_attempts=None, timeout_total=None) async

Fetch electricity agreement details for the given asset owner.

Parameters:

Name	Type	Description	Default
asset_owner_id	Optional[int]	Asset owner identifier. Defaults to self.asset_owner_id.	None
raise_on_error	bool	If True, raises ApiError on invalid payload/HTTP errors.	True
retry_5xx_attempts	Optional[int]	Optional number of retries for 5xx.	None
timeout_total	Optional[float]	Optional total timeout override in seconds.	None

Returns:

Name	Type	Description
AgreementResult	AgreementResult	{status_code, agreement, json, text, error}.

Raises:

Type	Description
ValueError	If asset owner id is not provided.
ApiError	If payload is not a dict (when raise_on_error=True).

async_fetch_invoices(asset_owner_id=None, *, raise_on_error=True, retry_5xx_attempts=None, timeout_total=None) async

Fetch invoice information for the given asset owner.

Parameters:

Name	Type	Description	Default
asset_owner_id	Optional[int]	Asset owner identifier. Defaults to self.asset_owner_id.	None
raise_on_error	bool	If True, raises ApiError on invalid payload/HTTP errors.	True
retry_5xx_attempts	Optional[int]	Optional number of retries for 5xx.	None
timeout_total	Optional[float]	Optional total timeout override in seconds.	None

Returns:

Name	Type	Description
InvoicesResult	InvoicesResult	{status_code, invoices, json, text, error}.

Raises:

Type	Description
ValueError	If asset owner id is not provided.
ApiError	If payload is not a list (when raise_on_error=True).

async_fetch_revenue(asset_id=None, *, raise_on_error=True, retry_5xx_attempts=None, timeout_total=None) async

Fetch revenue summary for the last invoice of an asset.

Parameters:

Name	Type	Description	Default
asset_id	Optional[int]	Asset identifier. Defaults to self.asset_id.	None
raise_on_error	bool	If True, raises ApiError on invalid payload/HTTP errors.	True
retry_5xx_attempts	Optional[int]	Optional number of retries for 5xx.	None
timeout_total	Optional[float]	Optional total timeout override in seconds.	None

Returns:

Name	Type	Description
RevenueResult	RevenueResult	{status_code, revenue, json, text, error}.

Raises:

Type	Description
ValueError	If asset id is not provided.
ApiError	If payload is not a dict (when raise_on_error=True).

async_fetch_system_notification(slug='active-flower', *, raise_on_error=True, retry_5xx_attempts=None, timeout_total=None) async

Fetch a system-notification payload by slug.

Parameters:

Name	Type	Description	Default
slug	str	Notification identifier (e.g., "active-flower").	'active-flower'
raise_on_error	bool	If True, raises ApiError on HTTP errors.	True
retry_5xx_attempts	Optional[int]	Optional number of retries for 5xx.	None
timeout_total	Optional[float]	Optional total timeout override in seconds.	None

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: {status_code, json, text}.

Raises:

Type	Description
ApiError	On HTTP errors when raise_on_error=True.

async_fetch_uptime_history(asset_id=None, *, raise_on_error=True, retry_5xx_attempts=None, timeout_total=None) async

Fetch uptime ratio history per month for the given asset.

Parameters:

Name	Type	Description	Default
asset_id	Optional[int]	Asset identifier. Defaults to self.asset_id.	None
raise_on_error	bool	If True, raises ApiError on invalid payload/HTTP errors.	True
retry_5xx_attempts	Optional[int]	Optional number of retries for 5xx.	None
timeout_total	Optional[float]	Optional total timeout override in seconds.	None

Returns:

Name	Type	Description
UptimeHistoryResult	UptimeHistoryResult	{status_code, history, json, text, error}.

Raises:

Type	Description
ValueError	If asset id is not provided.
ApiError	If payload is not a list (when raise_on_error=True).

async_fetch_uptime_pie(asset_id=None, *, period=None, raise_on_error=True, retry_5xx_attempts=None, timeout_total=None) async

Fetch uptime pie-chart data for a period (seconds per category).

Parameters:

Name	Type	Description	Default
asset_id	Optional[int]	Asset identifier. Defaults to self.asset_id.	None
period	Optional[str]	Period in YYYY-MM format (e.g., "2026-01"). Defaults to current month.	None
raise_on_error	bool	If True, raises ApiError on invalid payload/HTTP errors.	True
retry_5xx_attempts	Optional[int]	Optional number of retries for 5xx.	None
timeout_total	Optional[float]	Optional total timeout override in seconds.	None

Returns:

Name	Type	Description
UptimePieResult	UptimePieResult	{status_code, uptime, downtime, noData, uptime_ratio_total, uptime_ratio_actual, json, text, error}.

Raises:

Type	Description
ValueError	If asset id is not provided or period format is invalid.
ApiError	If payload is not a list (when raise_on_error=True).

async_login(username, password, *, raise_on_error=True) async

Authenticate and initialize asset_owner_id when available.

Parameters:

Name	Type	Description	Default
username	str	Account username (email).	required
password	str	Account password.	required
raise_on_error	bool	If True, raises ApiError on HTTP errors.	True

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: {"status_code": int, "json": Any} from login.

Raises:

Type	Description
RuntimeError	If no aiohttp ClientSession is configured.
ApiError	When raise_on_error=True and an HTTP error occurs.

async_readout_sequence(asset_owner_id=None, *, raise_on_error=True, retry_5xx_attempts=None, timeout_total=None) async

Run readout: discover asset ID then fetch asset.

Parameters:

Name	Type	Description	Default
asset_owner_id	Optional[int]	Asset owner identifier. Defaults to self.asset_owner_id.	None
raise_on_error	bool	If True, raises ApiError on HTTP/validation errors.	True
retry_5xx_attempts	Optional[int]	Optional number of retries for 5xx during fetch.	None
timeout_total	Optional[float]	Optional total timeout override in seconds.	None

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: {asset_owner_id, asset_id, with_asset_resp, asset_resp, uptime_pie_resp}.

Raises:

Type	Description
ValueError	If asset owner id is not provided.
ApiError	On HTTP/validation errors when raise_on_error=True.

close() async

Cancel background tasks; does not close an injected session.

is_asset_fetch_running()

Return True if the periodic asset fetch task is active.

set_max_concurrency(max_requests)

Set a simple semaphore rate limiter for concurrent requests.

Parameters:

Name	Type	Description	Default
max_requests	int	Maximum concurrent in-flight HTTP requests. Pass 0/None to disable.	required

start_periodic_asset_fetch(interval_seconds=60.0, run_immediately=False, on_update=None, result_queue=None)

Start a background task that periodically fetches the asset.

Parameters:

Name	Type	Description	Default
interval_seconds	float	Fetch interval (minimum 5 seconds).	60.0
run_immediately	bool	If True, perform one fetch before scheduling.	False
on_update	Optional[Callable[[FlowerHubStatus], None]]	Optional callback invoked with FlowerHubStatus after fetch.	None
result_queue	Optional[Queue]	Optional queue where FlowerHubStatus is pushed.	None

Returns:

Type	Description
Task	asyncio.Task: The created periodic task.

Raises:

Type	Description
ValueError	If interval is below 5 seconds.
RuntimeError	If a periodic fetch is already running.

stop_periodic_asset_fetch()

Cancel the periodic asset fetch task if running.