pydrawise.hybrid

pydrawise.hybrid

Client library for interacting with Hydrawise APIs.

This utilizes both the GraphQL and REST APIs.

HybridClient 

HybridClient(auth: HybridAuth, app_id: str = DEFAULT_APP_ID, gql_client: Hydrawise | None = None, gql_throttle: Throttler | None = None, rest_throttle: Throttler | None = None)

Bases: HydrawiseBase

Client library that uses both the GraphQL and REST Hydrawise APIs.

Prefers the GraphQL API, but falls back to (and caches results from) the REST API when GraphQL requests are throttled. This is useful for applications that poll frequently and want to stay within Hydrawise's GraphQL rate limits.

Should be instantiated with a HybridAuth object that handles authentication and low-level transport for both APIs.

Initializes the client.

Parameters:
  • auth (HybridAuth) –

    Handles authentication and transport for both APIs.

  • app_id (str, default: DEFAULT_APP_ID ) –

    Unique identifier for the application accessing the Hydrawise API.

  • gql_client (Hydrawise | None, default: None ) –

    GraphQL client to use. If not specified, one will be created.

  • gql_throttle (Throttler | None, default: None ) –

    Throttler controlling how often the GraphQL API may be called.

  • rest_throttle (Throttler | None, default: None ) –

    Throttler controlling how often the REST API may be called.

delete_zone_suspension async 

delete_zone_suspension(suspension: ZoneSuspension) -> None

Removes a specific zone suspension. Always uses the GraphQL API.

Useful when there are multiple suspensions for a zone in effect.

Parameters:

get_controller async 

get_controller(controller_id: int) -> Controller

Retrieves a single controller by its unique identifier.

Uses the GraphQL API while it has throttle budget; otherwise returns the cached controller.

Parameters:
  • controller_id (int) –

    Unique identifier for the controller to retrieve.

get_controllers async 

get_controllers(fetch_zones: bool = True, fetch_sensors: bool = True) -> list[Controller]

Retrieves all controllers associated with the currently authenticated user.

Uses the GraphQL API while it has throttle budget, refreshing zones from the REST API otherwise. Results are cached and returned from the cache on subsequent calls once throttled.

Parameters:
  • fetch_zones (bool, default: True ) –

    Whether to include zones in the response.

  • fetch_sensors (bool, default: True ) –

    Whether to include sensors in the response.

get_sensors async 

get_sensors(controller: Controller) -> list[Sensor]

Retrieves sensors associated with the given controller.

Always uses the GraphQL API, throttled: once the GraphQL throttle is exhausted, the last result for this controller is returned instead, or ThrottledError is raised if there is none yet.

Parameters:
  • controller (Controller) –

    Controller whose sensors to fetch.

get_user async 

get_user(fetch_zones: bool = True) -> User

Retrieves the currently authenticated user.

Uses the GraphQL API while it has throttle budget, refreshing zones from the REST API otherwise.

Parameters:
  • fetch_zones (bool, default: True ) –

    Whether to include zones in the controller response.

get_water_flow_summary async 

get_water_flow_summary(controller: Controller, sensor: Sensor, start: datetime, end: datetime) -> SensorFlowSummary

Retrieves the water flow summary for a given sensor. Always uses the GraphQL API.

Parameters:
  • controller (Controller) –

    Controller that controls the sensor.

  • sensor (Sensor) –

    Sensor for which a water flow summary is fetched.

  • start (datetime) –
  • end (datetime) –

get_water_use_summary async 

get_water_use_summary(controller: Controller, start: datetime, end: datetime) -> ControllerWaterUseSummary

Calculate the water use for the given controller and time period.

Always uses the GraphQL API.

Parameters:
  • controller (Controller) –

    The controller whose water use to report.

  • start (datetime) –

    Start time

  • end (datetime) –

    End time.

get_watering_report async 

get_watering_report(controller: Controller, start: datetime, end: datetime) -> list[WateringReportEntry]

Retrieves a watering report for the given controller and time period.

Always uses the GraphQL API.

Parameters:
  • controller (Controller) –

    The controller whose watering report to generate.

  • start (datetime) –

    Start time.

  • end (datetime) –

    End time.

get_zone async 

get_zone(zone_id: int) -> Zone

Retrieves a zone by its unique identifier.

Always uses the GraphQL API (the REST API has no way to fetch a single zone), throttled: once the GraphQL throttle is exhausted, the last result for this zone id is returned instead, or ThrottledError is raised if there is none yet.

Parameters:
  • zone_id (int) –

    The zone's unique identifier.

get_zones async 

get_zones(controller: Controller) -> list[Zone]

Retrieves zones associated with the given controller.

Uses the GraphQL API while it has throttle budget, refreshing from the REST API otherwise.

Parameters:
  • controller (Controller) –

    Controller whose zones to fetch.

resume_all_zones async 

resume_all_zones(controller: Controller) -> None

Resumes the schedule of all zones attached to the given controller.

Always uses the GraphQL API.

Parameters:
  • controller (Controller) –

    The controller whose zones to resume.

resume_zone async 

resume_zone(zone: Zone) -> None

Resumes a zone's schedule. Always uses the GraphQL API.

Parameters:
  • zone (Zone) –

    The zone whose schedule to resume.

start_all_zones async 

start_all_zones(controller: Controller, mark_run_as_scheduled: bool = False, custom_run_duration: int = 0) -> None

Starts all zones attached to a controller. Always uses the GraphQL API.

Parameters:
  • controller (Controller) –

    The controller whose zones to start.

  • mark_run_as_scheduled (bool, default: False ) –

    Whether to mark the zones as having run as scheduled.

  • custom_run_duration (int, default: 0 ) –

    Duration (in seconds) to run the zones. If not specified (or zero), will run for each zone's default configured time.

start_zone async 

start_zone(zone: Zone, mark_run_as_scheduled: bool = False, custom_run_duration: int = 0) -> None

Starts a zone's run cycle. Always uses the GraphQL API.

Parameters:
  • zone (Zone) –

    The zone to start.

  • mark_run_as_scheduled (bool, default: False ) –

    Whether to mark the zone as having run as scheduled.

  • custom_run_duration (int, default: 0 ) –

    Duration (in seconds) to run the zone. If not specified (or zero), will run for its default configured time.

stop_all_zones async 

stop_all_zones(controller: Controller) -> None

Stops all zones attached to a controller. Always uses the GraphQL API.

Parameters:
  • controller (Controller) –

    The controller whose zones to stop.

stop_zone async 

stop_zone(zone: Zone) -> None

Stops a zone. Always uses the GraphQL API.

Parameters:
  • zone (Zone) –

    The zone to stop.

suspend_all_zones async 

suspend_all_zones(controller: Controller, until: datetime) -> None

Suspends the schedule of all zones attached to a given controller.

Always uses the GraphQL API.

Parameters:
  • controller (Controller) –

    The controller whose zones to suspend.

  • until (datetime) –

    When the suspension should end.

suspend_zone async 

suspend_zone(zone: Zone, until: datetime) -> None

Suspends a zone's schedule. Always uses the GraphQL API.

Parameters:
  • zone (Zone) –

    The zone to suspend.

  • until (datetime) –

    When the suspension should end.