pydrawise

pydrawise

API for interacting with Hydrawise sprinkler controllers.

Auth 

Auth(username: str, password: str)

Bases: BaseAuth

Authentication support for the Hydrawise GraphQL API.

Initializer.

Parameters:
  • username (str) –

    The username to use for authenticating with the Hydrawise service.

  • password (str) –

    The password to use for authenticating with the Hydrawise service.

check async 

check() -> bool

Validates that the credentials are valid.

check_token async 

check_token()

Checks a token and refreshes if necessary.

token async 

token() -> str

Retrieves an authentication token for the current user.

Error

Bases: Exception

Base error class.

Hydrawise 

Hydrawise(auth: Auth, app_id: str = DEFAULT_APP_ID)

Bases: HydrawiseBase

Client library for interacting with Hydrawise sprinkler controllers.

Should be instantiated with an Auth object that handles authentication and low-level transport.

Initializes the client.

Parameters:
  • auth (Auth) –

    Handles authentication and transport.

  • app_id (str, default: DEFAULT_APP_ID ) –

    Unique identifier for the application accessing the Hydrawise API.

delete_zone_suspension async 

delete_zone_suspension(suspension: ZoneSuspension) -> None

Removes a specific zone suspension.

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.

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.

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.

Parameters:
  • controller (Controller) –

    Controller whose sensors to fetch.

get_user async 

get_user(fetch_zones: bool = True) -> User

Retrieves the currently authenticated user.

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.

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.

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.

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.

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.

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.

Parameters:
  • controller (Controller) –

    The controller whose zones to resume.

resume_zone async 

resume_zone(zone: Zone) -> None

Resumes a zone's schedule.

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.

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.

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.

Parameters:
  • controller (Controller) –

    The controller whose zones to stop.

stop_zone async 

stop_zone(zone: Zone) -> None

Stops a zone.

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.

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.

Parameters:
  • zone (Zone) –

    The zone to suspend.

  • until (datetime) –

    When the suspension should end.

update_master_valve async 

update_master_valve(controller: Controller, zone: Zone) -> None

Updates the controller's master valve.

Parameters:
  • controller (Controller) –

    Controller whose master valve to update.

  • zone (Zone) –

    Zone to use as the controller's master valve.

HydrawiseBase

Bases: ABC

Base class for Hydrawise client APIs.

delete_zone_suspension abstractmethod async 

delete_zone_suspension(suspension: ZoneSuspension) -> None

Removes a specific zone suspension.

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

Parameters:

get_controller abstractmethod async 

get_controller(controller_id: int) -> Controller

Retrieves a single controller by its unique identifier.

Parameters:
  • controller_id (int) –

    Unique identifier for the controller to retrieve.

get_controllers abstractmethod async 

get_controllers() -> list[Controller]

Retrieves all controllers associated with the currently authenticated user.

get_sensors abstractmethod async 

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

Retrieves sensors associated with the given controller.

Parameters:
  • controller (Controller) –

    Controller whose sensors to fetch.

get_user abstractmethod async 

get_user(fetch_zones: bool = True) -> User

Retrieves the currently authenticated user.

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

    When True, also fetch zones.

get_water_flow_summary abstractmethod async 

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

Retrieves the water flow summary for a given sensor.

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 abstractmethod async 

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

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

Parameters:
  • controller (Controller) –

    The controller whose water use to report.

  • start (datetime) –

    Start time

  • end (datetime) –

    End time.

get_watering_report abstractmethod async 

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

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

Parameters:
  • controller (Controller) –

    The controller whose watering report to generate.

  • start (datetime) –

    Start time.

  • end (datetime) –

    End time.

get_zone abstractmethod async 

get_zone(zone_id: int) -> Zone

Retrieves a zone by its unique identifier.

Parameters:
  • zone_id (int) –

    The zone's unique identifier.

get_zones abstractmethod async 

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

Retrieves zones associated with the given controller.

Parameters:
  • controller (Controller) –

    Controller whose zones to fetch.

resume_all_zones abstractmethod async 

resume_all_zones(controller: Controller) -> None

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

Parameters:
  • controller (Controller) –

    The controller whose zones to resume.

resume_zone abstractmethod async 

resume_zone(zone: Zone) -> None

Resumes a zone's schedule.

Parameters:
  • zone (Zone) –

    The zone whose schedule to resume.

start_all_zones abstractmethod 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.

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 abstractmethod async 

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

Starts a zone's run cycle.

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 abstractmethod async 

stop_all_zones(controller: Controller) -> None

Stops all zones attached to a controller.

Parameters:
  • controller (Controller) –

    The controller whose zones to stop.

stop_zone abstractmethod async 

stop_zone(zone: Zone) -> None

Stops a zone.

Parameters:
  • zone (Zone) –

    The zone to stop.

suspend_all_zones abstractmethod async 

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

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

Parameters:
  • controller (Controller) –

    The controller whose zones to suspend.

  • until (datetime) –

    When the suspension should end.

suspend_zone abstractmethod async 

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

Suspends a zone's schedule.

Parameters:
  • zone (Zone) –

    The zone to suspend.

  • until (datetime) –

    When the suspension should end.

MutationError

Bases: Error

Raised when there is an error performing a mutation.

NotAuthenticatedError

Bases: Error

Raised when a request is made to an unathenticated object.

NotAuthorizedError

Bases: Error

Raised when invalid credentials are used.

UnknownError

Bases: Error

Raised when an unknown problem occurs.