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(include_access_codes: bool = False) → list[Lock]

Retrieves all locks associated with this account.

Parameters:

include_access_codes – Whether to also refresh access codes.

Return type:

list[Lock]

Raises:
users() → list[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: ~pyschlage.auth.Auth | None = None, device_id: str = '', device_type: str = '', name: str = '', model_name: str = '', connected: bool = False, battery_level: int | None = None, is_locked: bool | None = False, is_jammed: bool | None = False, lock_state_metadata: ~pyschlage.lock.LockStateMetadata | None = None, beeper_enabled: bool = False, lock_and_leave_enabled: bool = False, auto_lock_time: int = 0, firmware_version: str | None = None, mac_address: str | None = None, users: dict[str, ~pyschlage.user.User] = <factory>, access_codes: dict[str, ~pyschlage.code.AccessCode] | None = None, _cat: str = '', _json: dict[~typing.Any, ~typing.Any] = <factory>)

A Schlage WiFi lock.

add_access_code(code: AccessCode)

Adds an access code to the lock.

Parameters:

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

Raises:
get_access_codes() → list[AccessCode]

Fetches the access codes for this lock.

Rtype list[pyschlage.code.AccessCode]:

Raises:

pyschlage.exceptions.NotAuthorizedError – When authentication fails.

get_diagnostics() → dict[Any, Any]

Returns a redacted dict of the raw JSON for diagnostics purposes.

keypad_disabled(logs: list[LockLog] | None = None) → bool

Returns True if the keypad is currently disabled.

Parameters:

logs (list[LockLog] or None) – Recent logs. If None, new logs will be fetched.

Return type:

bool

last_changed_by(logs: list[LockLog] | None = None) → str | None

Determines the last entity or user that changed the lock state.

Parameters:

logs – Unused. Kept for legacy reasons.

Return type:

str

lock()

Locks the device.

Raises:
logs(limit: int | None = None, sort_desc: bool = False) → list[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(include_access_codes: bool = False) → None

Refreshes the Lock state.

Parameters:

include_access_codes – Whether to also refresh access codes.

Raises:
refresh_access_codes() → None

Fetches access codes for this lock.

Raises:
set_auto_lock_time(auto_lock_time: int)

Sets the auto_lock_time setting. Setting it to 0 turns off the auto-lock feature.

set_beeper(enabled: bool)

Sets the beeper_enabled setting.

set_lock_and_leave(enabled: bool)

Sets the lock_and_leave setting.

unlock()

Unlocks the device.

Raises:
access_codes: dict[str, AccessCode] | None = None

Access codes for this lock, keyed by their ID.

auto_lock_time: int = 0

Time (in seconds) after which the lock will automatically lock itself.

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.

beeper_enabled: bool = False

Whether the keypress beep is enabled.

connected: bool = False

Whether the lock is connected to WiFi.

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.

Returns None if lock is unavailable.

is_locked: bool | None = False

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

lock_and_leave_enabled: bool = False

Whether lock-and-leave (a.k.a. “1-Touch Locking) feature is enabled.

lock_state_metadata: LockStateMetadata | None = None

Metadata about the current lock state.

mac_address: str | None = None

The MAC address for the lock or None if lock is unavailable.

model_name: str = ''

The model name of the lock.

name: str = ''

User-specified name of the lock.

users: dict[str, User]

Users with access to this lock, keyed by their ID.

class pyschlage.code.AccessCode(_auth: ~pyschlage.auth.Auth | None = None, name: str = '', code: str = '', schedule: ~pyschlage.code.TemporarySchedule | ~pyschlage.code.RecurringSchedule | None = None, notify_on_use: bool = False, disabled: bool = False, device_id: str | None = None, access_code_id: str | None = None, _device: ~pyschlage.device.Device | None = None, _notification: ~pyschlage.notification.Notification | None = None, _json: dict[~typing.Any, ~typing.Any] = <factory>)

An access code for a lock.

delete()

Deletes the access code.

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, message: str, accessor_id: str | None = None, access_code_id: str | None = None)

A lock log entry.

access_code_id: str | None = None

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

accessor_id: str | None = 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.