LUSID SDK for Python

Common errors

• ValueError: Missing configuration for API client factory: LUSID_API_URL

  cause The `ApiClientFactory` could not find required environment variables like `LUSID_API_URL` or authentication credentials (e.g., `LUSID_FBN_TOKEN`, `LUSID_CLIENT_ID`, `LUSID_CLIENT_SECRET`).
  fix Ensure all necessary LUSID environment variables (e.g., `LUSID_API_URL`, `LUSID_APP_NAME`, and appropriate authentication credentials) are correctly set in your environment or provided directly to the `ApiClientFactory`.

• finbourne.lusid.sdk.ApiException: (401) Unauthorized

  cause The SDK failed to authenticate with the LUSID API, indicating incorrect or expired credentials.
  fix Verify that your `LUSID_FBN_TOKEN` or OAuth2 client credentials (`LUSID_CLIENT_ID`, `LUSID_CLIENT_SECRET`, `LUSID_TOKEN_URL`) are correct and have the necessary permissions. Also, check that `LUSID_API_URL` is correct.

• AttributeError: 'ApiClientFactory' object has no attribute 'list_portfolios'

  cause You are attempting to call an API method directly on the `ApiClientFactory` instance, instead of on a specific API client built by the factory.
  fix You must first build an API client from the factory for the specific service you want to interact with. For example, `portfolios_api = api_factory.build(PortfoliosApi)` and then call `portfolios_api.list_portfolios()`.

Warnings

• gotcha The recommended authentication and client creation mechanism is `ApiClientFactory`. Direct instantiation of `Configuration` and `ApiClient` objects from `lusid_sdk.configuration` and `lusid_sdk.api_client` is still possible but less robust for managing multiple API clients or complex authentication flows.
  Fix: Always prefer `from lusid_sdk.utilities import ApiClientFactory` and use `api_factory.build(YourApiClass)` to get API clients.
• gotcha Many LUSID API list methods return paginated results. Directly accessing `response.values` will only give the first page. For comprehensive results, you need to iterate through pages or use the SDK's built-in `get_all` helper methods (if available for the specific API endpoint).
  Fix: Check the `list_` method documentation for `get_all_` alternatives or manually handle pagination using `response.paging.next_page` and `limit`/`page` parameters.
• gotcha LUSID is a rapidly evolving platform. The SDK is frequently updated to reflect changes in the underlying LUSID API (new endpoints, modified models, deprecations). Using an outdated SDK version can lead to `AttributeError` for missing fields/methods or unexpected API behaviour.
  Fix: Regularly update `lusid-sdk` to the latest version (`pip install --upgrade lusid-sdk`) to ensure compatibility with the LUSID API and access to the newest features.
• breaking Major version 2.0.0 introduced significant changes to the SDK's internal structure and recommended usage patterns, primarily around how API clients are instantiated and configured. Older code using direct `ApiClient` and `Configuration` setup may break or behave unexpectedly without modification.
  Fix: Migrate existing code to use `ApiClientFactory` for all API client instantiation and configuration. Refer to the official SDK documentation for migration guides.

Install

• pip install lusid-sdk Install `lusid-sdk`

Imports

• ApiClientFactory
  wrong:

  from lusid_sdk.configuration import Configuration

  correct:

  from lusid_sdk.utilities import ApiClientFactory

  While `Configuration` and `ApiClient` exist, `ApiClientFactory` is the recommended and more robust way to set up and manage API clients, especially for authentication.
• PortfoliosApi

  from lusid_sdk.api import PortfoliosApi

  All API clients follow this import pattern, e.g., `TransactionsApi`, `QuotesApi`.

Quickstart

This quickstart demonstrates how to initialize the `ApiClientFactory`, authenticate using environment variables (supporting both Personal Access Token and OAuth2 Client Credentials flows), and make a simple call to list portfolios. Ensure the necessary LUSID environment variables are set before running.

import os
from lusid_sdk.utilities import ApiClientFactory
from lusid_sdk.api import PortfoliosApi

# Configure environment variables for LUSID authentication.
# These can be set in your shell or via a .env file.
# Example for Personal Access Token (PAT):
# export LUSID_FBN_TOKEN='your_finbourne_token'
# export LUSID_API_URL='https://lusid.finbourne.com/api'
# export LUSID_APP_NAME='my-python-app'
#
# Example for OAuth 2.0 Client Credentials:
# export LUSID_CLIENT_ID='your_client_id'
# export LUSID_CLIENT_SECRET='your_client_secret'
# export LUSID_TOKEN_URL='https://identity.finbourne.com/oauth/token'
# export LUSID_API_URL='https://lusid.finbourne.com/api'
# export LUSID_APP_NAME='my-python-app'

try:
    # Create an ApiClientFactory instance. It picks up config from environment variables.
    # For LUSID_FBN_TOKEN, you would use: ApiClientFactory()
    # For OAuth, you might need to pass details if not in env vars, but env vars are preferred.
    api_factory = ApiClientFactory()

    # Get a specific API client, e.g., for portfolios
    portfolios_api: PortfoliosApi = api_factory.build(PortfoliosApi)

    # List all portfolios
    paginated_response = portfolios_api.list_portfolios(
        limit=5,
        scope='default'
    )

    print(f"Successfully connected to LUSID. Found {paginated_response.paging.total_items} portfolios.")
    for portfolio in paginated_response.values:
        print(f"- {portfolio.display_name} ({portfolio.scope}/{portfolio.code})")

except Exception as e:
    print(f"An error occurred: {e}")
    if "401 Unauthorized" in str(e):
        print("Please check your LUSID authentication details (LUSID_FBN_TOKEN or OAuth credentials).")
    elif "Missing configuration" in str(e):
        print("Ensure LUSID_API_URL and authentication environment variables are set.")