lazr-restfulclient

Common errors

• lazr.restfulclient.errors.Unauthorized: HTTP Error 401: Unauthorized

  cause Attempting to perform an action on a service (e.g., Launchpad) without sufficient authentication or authorization, or trying to access a project you do not own/have permissions for.
  fix Ensure you have correctly configured your authentication (e.g., OAuth credentials, HTTP Basic Auth) for the `ServiceRoot`. If interacting with Launchpad, verify your project name and ownership, and configure 'quickly' with your Launchpad project name.

• HTTP Error 404: Not Found

  cause The requested resource (collection or entry) does not exist at the specified URL on the server.
  fix Double-check the service root URL and the paths to collections and entries. Verify the resource ID or key if you are trying to fetch a specific item.

• ConflictError: HTTP Error 409: Conflict

  cause Attempting to save changes to a resource that has been modified by another client since it was last fetched (e.g., a concurrent modification).
  fix Before saving, refresh the object using `obj.lp_refresh()` to get the latest server-side state. Then, re-apply your changes and attempt to save again. Implement optimistic locking logic if concurrent modifications are common.

Warnings

• breaking The WSGI authentication middleware was moved from `lazr.restful` to `lazr.authentication` in `lazr.restfulclient` version 0.9.9. Direct usage of the old authentication middleware will break.
  Fix: Update to use the `lazr.authentication` library or the updated `lazr.restfulclient` authentication mechanisms if relying on the WSGI authentication middleware.
• gotcha Client-side objects can 're-type' after fetching data. If a collection is initially configured to contain a generic resource type, but the server returns a more specific type upon fetching, the client-side object will adopt the properties of the actual, more specific type. This can be confusing if not expected.
  Fix: Be aware that the object's available attributes and methods might change after a network fetch (`lp_refresh()` or first attribute access) based on the server's response. Inspect `lp_attributes` or `resource_type_link` after fetching to understand the object's current state.
• gotcha The library automatically retries requests on transient server errors (HTTP 502, 503) a configurable number of times. However, it will NOT retry on client-side errors (e.g., HTTP 400 Bad Request or 404 Not Found), escalating them directly as exceptions.
  Fix: Handle client-side HTTP errors (4xx) explicitly in your code, as `lazr.restfulclient` will not attempt to retry them. Use the `max_retries` constructor argument for `ServiceRoot` to adjust retry behavior for server errors if needed.
• gotcha Incompatibilities with `httplib2` versions have occurred. If you encounter unexpected HTTP connection issues or errors related to `httplib2`, ensure your `httplib2` version is compatible with `lazr.restfulclient`.
  Fix: Check `lazr.restfulclient`'s release notes for specific `httplib2` version requirements. As of 0.14.2, it requires `httplib2 >= 0.7.7` for Python 3. If issues persist, try upgrading or downgrading `httplib2` to a version explicitly known to work with your `lazr.restfulclient` version.

Install

• pip install lazr-restfulclient Install latest version

Imports

• ServiceRoot

  from lazr.restfulclient.client import ServiceRoot

  The primary class for instantiating a client to a RESTful service.
• lazr.restfulclient

  import lazr.restfulclient

  For package-level access, e.g., checking __version__.

Quickstart

Demonstrates how to initialize a `ServiceRoot` client and access a top-level collection. This example uses a placeholder URL and assumes a basic RESTful service structure.

import os
from lazr.restfulclient.client import ServiceRoot
from lazr.restfulclient.errors import HTTPError

# Example: Connect to a mock service root (replace with your actual service URL)
# For Launchpad services, the root URL would be like 'https://api.launchpad.net/1.0/'
SERVICE_ROOT_URL = os.environ.get('LAZR_SERVICE_URL', 'https://api.example.com/')

try:
    # Initialize a ServiceRoot. The first argument is typically an authorizer, or None for unauthenticated access.
    service = ServiceRoot(None, SERVICE_ROOT_URL)

    # Attempt to access a top-level collection, e.g., 'users'
    # This will trigger an HTTP GET request to SERVICE_ROOT_URL/users
    # Note: Replace 'users' with an actual collection name for your service
    users_collection = service.users
    print(f"Successfully accessed collection: {users_collection.lp_self_link}")

    # Example: Fetch a specific item from the collection (if it supports key-based lookup)
    # Assuming 'users_collection' can be indexed by ID, e.g., user with ID '123'
    # This will perform another HTTP GET request
    # user = users_collection[123]
    # print(f"Fetched user: {user.display_name}")

except HTTPError as e:
    print(f"HTTP Error encountered: {e.status} - {e.reason}\n{e.response}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")