Migration guide from seamapi package

[andrii-balitskyi]

Migration Guide: SDK Transition from Handwritten to Auto-Generated Code

Welcome to the migration guide for transitioning from the handwritten version of our SDK to the new auto-generated version. This guide is intended for developers who have been using the previous version of our SDK and need to update their codebase to accommodate the breaking changes introduced in the latest release. Our aim is to ensure a smooth transition by covering all essential updates, including method signature changes, return value modifications, and adjustments in support for third-party components and environment variables.

Summary of Changes

• Updated API Method Signatures: Transition to keyword-only arguments and standardized resource ID arguments.
• Return Value Changes: Modifications in the return types for several API methods.
• Action Attempt Resolution: Introduction of wait_for_action_attempt configuration options.
• Environment Variables: Addition of a new environment variable.
• Third-Party Component Support and Version Changes: Updates to third-party component support and required versions.

New Python package name

Changed the package name from seamapi to seam.

- pip install seamapi
+ pip install seam

Updated API Method Signatures

Method Parameter Changes

We have updated API method signatures to only accept keyword arguments, and standardized resource ID arguments across the SDK:

- seam.access_codes.get("my_access_code_id")
+ seam.access_codes.get(access_code_id="my_access_code_id")

- seam.thermostats.get("my_thermostat_device_id")
+ seam.thermostats.get(device_id="my_thermostat_device_id")

In addition, we've moved from accepting both resource objects and resource ID strings to only accepting resource ID strings, with a renaming scheme for clarity:

- def get(resource: Union[str, Resource]) -> Resource
+ def get(resource_id: str) -> Resource

Usage has been updated accordingly:

- seam.locks.get(device=my_device)
+ seam.locks.get(device_id=my_device.device_id)

Removed method arguments:

• Removed: wait_for_code from access_codes.create. Use the newly-created access_code_id to poll or watch for events.

Return Value Changes

We've changed the return types for some methods to enhance API consistency and reliability:

• Now returning void:
  • access_codes.delete
  • access_codes.unmanaged.delete
  • access_codes.update
  • noise_sensors.noise_thresholds.delete
  • noise_sensors.noise_thresholds.update
  • thermostats.climate_setting_schedules.update
  • access_codes.unmanaged.convert_to_managed.
• Now returning a NoiseThreshold: noise_sensors.noise_thresholds.create. Use the newly-created noise_threshold_id to poll or watch for events.
• Now returning an ActionAttempt: workspaces.reset_sandbox

Action Attempt Resolution

Methods returning action attempts no longer wait for the action attempt to resolve by default. You can configure this behavior on a per-request basis using the wait_for_action_attempt option:

seam.locks.lock_door(
    device_id="my_device_id",
    wait_for_action_attempt=True
)
# Waits for the action attempt to be ready with a default timeout of 5.0 seconds and a default polling interval of 0.5 seconds.

seam.locks.lock_door(
    device_id="my_device_id",
    wait_for_action_attempt={
        "timeout": 10.0,  # Up to 10 seconds.
        "polling_interval": 2.0  # Every 2 seconds.
    }
)
# Waits up to 10 seconds for the action attempt to be ready, checking every 2 seconds.

You can also set the default behavior for the client.

seam = Seam(wait_for_action_attempt=True)

Environment Variables

• Added: Support for the SEAM_ENDPOINT environment variable.

Third-Party Component Support and Version Changes

• Minimum supported Python version: 3.9.
• dataclasses-json Version: Updated to 0.6.4.
• Sentry Support: Removed.
• Replaced requests with niquests version 3.6.4.

[DebbieAtSeam]

Migration guide

Learn how to migrate from the seamapi package to the seam package. This guide includes descriptions of all breaking changes.

The new SDK has fewer dependencies and is generated daily to ensure methods and types are always up-to-date with the latest API changes. It is mostly a drop-in replacement, however some method signatures and options have changed to improve overall consistency with the Seam API.

This guide includes descriptions of all breaking changes. Please refer to the README for updated usage instructions and a complete list of new features.

New Python package name

Changed the package name from seamapi to seam.

- pip install seamapi
+ pip install seam

- from seamapi import Seam
+ from seam import Seam

Updated API method signatures

Keyword arguments

API method signatures now only accept keyword arguments.

- seam.access_codes.get("my_access_code_id")
+ seam.access_codes.get(access_code_id="my_access_code_id")

- seam.thermostats.get("my_thermostat_device_id")
+ seam.thermostats.get(device_id="my_thermostat_device_id")

Standardized resource ID arguments

Changed from accepting both resource objects and resource ID strings to accepting only resource ID strings. Includes a renaming scheme for clarity.

- def get(resource: Union[str, Resource]) -> Resource
+ def get(resource_id: str) -> Resource

Usage

- seam.locks.get(device=my_device)
+ seam.locks.get(device_id=my_device.device_id)

Removed method arguments

Removed wait_for_code from access_codes.create. Use the newly-created access_code_id to poll or watch for events.

Return value changes

Changed the return types for some methods to enhance API consistency and reliability.

The following methods now return void:

• access_codes.delete: Instead, you should wait for the access_code.deleted event.
• access_codes.unmanaged.delete
• access_codes.update: Instead, you should watch for relevant access_code.* events or poll the resource as needed.
• noise_sensors.noise_thresholds.delete: Instead, you should wait for the noise_threshold.deleted event.
• noise_sensors.noise_thresholds.update: Instead, you should watch for relevant noise_threshold.* events or poll the resource as needed.
• thermostats.climate_setting_schedules.update: Instead, you should watch for relevant climate_setting_schedule.* events or poll the resource as needed.
• access_codes.unmanaged.convert_to_managed: Instead, you should wait for the access_code.unmanaged.converted_to_managed and access_code.unmanaged.failed_to_convert_to_managed events.

The following methods now return a NoiseThreshold:

• noise_sensors.noise_thresholds.create: Use the newly-created noise_threshold_id to poll or watch for events.

The following methods now return an ActionAttempt:

• workspaces.reset_sandbox: Instead, you should use the newly-created action_attempt_id to poll the status of the action attempt via the /action_attempt/get endpoint.

Action attempt resolution

Methods returning action attempts still wait for the action attempt to resolve by default. Further, you can now configure this behavior using the wait_for_action_attempt option on a per-request basis. You can also set the default behavior for the client.

Set per request

# Wait for the action attempt to be ready with a default timeout of 5.0 seconds and a default polling interval of 0.5 seconds.
seam.locks.lock_door(
    device_id="my_device_id",
    wait_for_action_attempt=True
)

# Wait up to 10 seconds for the action attempt to be ready, checking every 2 seconds.
seam.locks.lock_door(
    device_id="my_device_id",
    wait_for_action_attempt={
        "timeout": 10.0,  # Up to 10 seconds
        "polling_interval": 2.0  # Every 2 seconds
    }
)

Set default behavior

seam = Seam(wait_for_action_attempt=True)

Environment variables

Added support for the SEAM_ENDPOINT environment variable.

Using Personal Access Tokens without a Workspace ID

Use SeamMultiWorkspace to call the subset of Seam API endpoints that allow authentication with a personal access token without a workspace ID.

- const seam = new Seam({ personal_access_token: 'your-personal-access-token' })
- const workspace = seam.workspaces.create({ company_name: 'Example Inc.' })
+ const seam_multi_workspace = new SeamMultiWorkspace({ personal_access_token: 'your-personal-access-token' })
+ const workspace = seam_multi_workspace.workspaces.create({ company_name: 'Example Inc.' })

Third-party component support and version changes

• Updated the minimum supported Python version to 3.9.
• Updated the dataclasses-json version to 0.6.4.
• Removed Sentry support.
• Replaced requests with niquests version 3.6.4.

[sybohy]

these changes are all around really nice

[razor-x]

Posted at https://github.com/seamapi/python/releases/tag/v1.0.0

[andrii-balitskyi]

API key authentication with from_api_key factory method

Added a new from_api_key factory method for API key authentication of the Seam client.

seam = Seam.from_api_key("your-api-key")

Personal access token authentication

Added support for personal access token (PAT) authentication.

PAT authentication scoped to a single workspace

# Pass as an option to the constructor
seam = Seam(
    personal_access_token="your-personal-access-token",
    workspace_id="your-workspace-id",
)

# Use the factory method
seam = Seam.from_personal_access_token(
    "your-personal-access-token",
    "your-workspace-id",
)

PAT authentication not bound to a specific workspace

For authentication with a personal access token not bound to a specific workspace, use SeamMultiWorkspace.

from seam import SeamMultiWorkspace

seam_multi_workspace = SeamMultiWorkspace(personal_access_token="your-personal-access-token")

workspace = seam_multi_workspace.workspaces.create(company_name="Example Inc.")