API Reference

Main API

The main entry-point into pyschlage is through the pyschlage.Schlage object. From there you can access the locks associated with a Schlage account, and interact with them directly.

class pyschlage.Schlage(auth: Auth)

API for interacting with the Schlage WiFi cloud service.

__init__(auth: Auth) → None

Instantiates a Schlage API object.

Parameters:

auth (pyschlage.Auth) – Authentication and transport for the API.

locks() → list[pyschlage.lock.Lock]

Retrieves all locks associated with this account.

Return type:

list[Lock]

Raises:
users() → list[pyschlage.user.User]

Retrieves all users associated with this account’s locks.

Return type:

list[User]

Raises:

Authentication

Creating a Schlage object first requires creating an authentication and transport object, which is encapsulated in the pyschlage.Auth object.

class pyschlage.Auth(username: str, password: str)

Handles authentication for the Schlage WiFi cloud service.

__init__(username: str, password: str) → None

Initializes an Auth object.

Parameters:

  • username (str) – The username associated with the Schlage account.

  • password (str) – The password for the account.

authenticate()

Performs authentication with AWS.

Raises:
property user_id: str

Returns the unique user id for the authenticated user.

Locks

The Schlage object provides access to Lock objects. Each instance of a Lock itself can fetch additional data such as access codes and log entries.

class pyschlage.lock.Lock(_auth: Auth | None = None, device_id: str = '', name: str = '', model_name: str = '', device_type: str = '', battery_level: int | None = None, is_locked: bool | None = False, is_jammed: bool | None = False, firmware_version: str | None = None, _cat: str = '')

A Schlage WiFi lock.

access_codes() → list[pyschlage.code.AccessCode]

Fetches access codes for this lock.

Return type:

list[pyschlage.code.AccessCode]

Raises:
add_access_code(code: AccessCode)

Adds an access code to the lock.

Parameters:

code (pyschlage.code.AccessCode) – The access code to add.

Raises:
lock()

Locks the device.

Raises:
logs(limit: int | None = None, sort_desc: bool = False) → list[pyschlage.log.LockLog]

Fetches activity logs for the lock.

Parameters:

  • limit (int | None) – The number of log entries to return.

  • sort_desc (bool (defaults to False)) – Whether to sort entries in descending order.

Return type:

list[pyschlage.log.LockLog]

Raises:
refresh()

Refreshes the Lock state.

Raises:
unlock()

Unlocks the device.

Raises:
battery_level: int | None = None

The remaining battery level of the lock.

This is an integer between 0 and 100 or None if lock is unavailable.

device_id: str = ''

Schlage-generated unique device identifier.

device_type: str = ''

The device type of the lock.

Also see known device types in device.py.

firmware_version: str | None = None

The firmware version installed on the lock or None if lock is unavailable.

is_jammed: bool | None = False

Whether the lock has identified itself as jammed or None if lock is unavailable.

is_locked: bool | None = False

Whether the device is currently locked or None if lock is unavailable.

model_name: str = ''

The model name of the lock.

name: str = ''

User-specified name of the lock.

class pyschlage.code.AccessCode(_auth: Auth | None = None, name: str = '', code: str = '', schedule: TemporarySchedule | RecurringSchedule | None = None, notify_on_use: bool = False, disabled: bool = False, device_id: str | None = None, access_code_id: str | None = None)

An access code for a lock.

delete()

Deletes the access code.

Raises:
refresh()

Refreshes the AccessCode state.

Raises:
save()

Commits changes to the access code.

Raises:
access_code_id: str | None = None

Unique identifier for the access code.

code: str = ''

The access code.

device_id: str | None = None

Unique identifier for the device the access code is associated with.

disabled: bool = False

Whether the code is disabled.

name: str = ''

User-specified name for the access code.

notify_on_use: bool = False

Whether to notify the user’s phone app when the code is used.

schedule: TemporarySchedule | RecurringSchedule | None = None

Optional schedule at which the code is enabled.

class pyschlage.code.TemporarySchedule(start: datetime, end: datetime)

A temporary schedule for when an AccessCode is enabled.

end: datetime

The time at which the schedule should end.

start: datetime

The time at which the schedule should start.

class pyschlage.code.RecurringSchedule(days_of_week: ~pyschlage.code.DaysOfWeek = <factory>, start_hour: int = 0, start_minute: int = 0, end_hour: int = 23, end_minute: int = 59)

A recurring schedule for when an AccessCode is enabled.

days_of_week: DaysOfWeek

Days of the week on which the access code is enabled.

end_hour: int = 23

Hour at which the access code is disabled.

end_minute: int = 59

Minute at which the access code is disabled.

start_hour: int = 0

Hour at which the access code is enabled.

start_minute: int = 0

Minute at which the access code is enabled.

class pyschlage.code.DaysOfWeek(sun: bool = True, mon: bool = True, tue: bool = True, wed: bool = True, thu: bool = True, fri: bool = True, sat: bool = True)

Enabled status for each day of the week.

fri: bool = True
mon: bool = True
sat: bool = True
sun: bool = True
thu: bool = True
tue: bool = True
wed: bool = True
class pyschlage.log.LockLog(created_at: datetime, accessor_id: str | None, access_code_id: str | None, message: str)

A lock log entry.

access_code_id: str | None

Unique identifier for the access code that triggered the log entry.

accessor_id: str | None

Unique identifier for the user that triggered the log entry.

created_at: datetime

The time at which the log entry was created.

message: str

The human-readable message associated with the log entry.

Exceptions

Exceptions used in pyschlage.

exception pyschlage.exceptions.Error

Base error class.

exception pyschlage.exceptions.NotAuthenticatedError

Raised when a request is made to an unauthenticated object.

exception pyschlage.exceptions.NotAuthorizedError

Raised when invalid credentials are used.

exception pyschlage.exceptions.UnknownError

Raised when an unknown problem occurs.