# 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[Lock]

    Retrieves all locks associated with this account.

    Return type:

      list[Lock]

    Raises:

      - pyschlage.exceptions.NotAuthorizedError – When authentication fails.

      - pyschlage.exceptions.UnknownError – On other errors.

  users() → list[User]

    Retrieves all users associated with this account’s locks.

    Return type:

      list[User]

    Raises:

      - pyschlage.exceptions.NotAuthorizedError – When authentication fails.

      - pyschlage.exceptions.UnknownError – On other errors.

## 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:

      - pyschlage.exceptions.NotAuthorizedError – When authentication fails.

      - pyschlage.exceptions.UnknownError – On other errors.

  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:

      - pyschlage.exceptions.NotAuthorizedError – When authentication fails.

      - pyschlage.exceptions.UnknownError – On other errors.

  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:

      - pyschlage.exceptions.NotAuthorizedError – When authentication fails.

      - pyschlage.exceptions.UnknownError – On other errors.

  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:

      - pyschlage.exceptions.NotAuthorizedError – When authentication fails.

      - pyschlage.exceptions.UnknownError – On other errors.

  refresh() → None

    Refreshes the Lock state.

    Raises:

      - pyschlage.exceptions.NotAuthorizedError – When authentication fails.

      - pyschlage.exceptions.UnknownError – On other errors.

  refresh_access_codes() → None

    Fetches access codes for this lock.

    Raises:

      - pyschlage.exceptions.NotAuthorizedError – When authentication fails.

      - pyschlage.exceptions.UnknownError – On other errors.

  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:

      - pyschlage.exceptions.NotAuthorizedError – When authentication fails.

      - pyschlage.exceptions.UnknownError – On other errors.

  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:

      - pyschlage.exceptions.NotAuthenticatedError – When the user is not authenticated.

      - pyschlage.exceptions.NotAuthorizedError – When authentication fails.

      - pyschlage.exceptions.UnknownError – On other errors.

  save()

    Commits changes to the access code.

    Raises:

      - pyschlage.exceptions.NotAuthenticatedError – When the user is not authenticated.

      - pyschlage.exceptions.NotAuthorizedError – When authentication fails.

      - pyschlage.exceptions.UnknownError – On other errors.

  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.