Installing or upgrading the LUSID Python SDK

The LUSID Python SDK provides convenient access to the LUSID REST API in Python 3 environments.

Note: Supporting applications in the FINBOURNE platform (such as Drive, Scheduler and Luminesce) have their own Python SDKs.

Note the following:

  • We strongly recommend pinning a SDK to an exact version to control when you take updates and make your builds repeatable.

  • The master/main branch of a SDK may not always have the latest REST API version; there may, for example, also be v2 or v3 branches. We aim to keep master/main updated with the latest API version, but there may be some lead time while we deprecate older endpoints. Once we deprecate older API versions, the latest API version is moved to the master/main branch.

Installing the latest LUSID Python SDK

You can install v2 of the LUSID Python SDK from PyPi using the following command:

$ pip install lusid-sdk

Alternatively, you can download the source from Github.

To authenticate for the first time, you must generate a client ID and secret and store them with the credentials of a valid LUSID user as either environment variables or in a secrets file. The LUSID Python SDK uses these credentials to obtain a short-lived API access token from FINBOURNE's identity provider (Okta) on demand. More information.

For code samples for simple operations such as creating portfolios, upserting transactions and generating holdings, start with the Github readme. For more complex examples, examine the sample Juypter Notebooks available to run in your LUSID domain.

Documentation for SDK methods is available with code samples in Github, or as a searchable package on Readthedocs (the content is the same).

Upgrading to v2 from an earlier version

You can upgrade to v2 of the following packages:

  • LUSID Python SDK

  • Other Python SDKs in the FINBOURNE platform

We recommend upgrading to v2 as soon as possible to ensure you have access to the latest features.

Note that you must upgrade all SDKs used in a particular process to v2 at the same time. A process that uses both the Scheduler and Drive SDKs, for example, must either use v1 of both SDKs or v2 of both SDKs; mixing major versions will lead to dependency conflicts.

LUSID Python SDK

You can upgrade from v1 to v2 of the LUSID Python SDK using the following pip command:

$ pip install lusid-sdk

Users need to update their code to reflect the following v2 changes

Preview SDKs

This release discontinues publishing the LUSID Preview SDK, instead adding the Experimental and Beta lifecycle APIs to a single SDK. Note that making requests to Experimental and Beta APIs requires additional licences; for more details please contact support.

Changes to extensions packages

v1 lusid.utilities package has been renamed as lusid.extensions. The package now supports asynchronous requests using the asyncio library and makes loading configuration more configurable and readable:

  • You can now build an asynchronous client using the ApiClientFactory. To close connections after use, we recommend making requests within a context using a with statement. 

    from lusid import ApiClientFactory, ApplicationMetadataApi
api_client_factory = ApiClientFactory()
async with api_client_factory:
    api_instance = api_client_factory.build(ApplicationMetadataApi)

  • You can now pass in a list of configuration loaders to ApiClientFactory. We currently provide loaders for reading API configuration from environment variables, a secrets file or keyword arguments. For example:

    from lusid import (
    ApiClientFactory,
    ApplicationMetadataApi,
    EnvironmentVariablesConfigurationLoader,
    SecretsFileConfigurationLoader,
    ArgsConfigurationLoader
)
config_loaders = [
    EnvironmentVariablesConfigurationLoader(),
    SecretsFileConfigurationLoader(api_secrets_file="secrets.json"),
    ArgsConfigurationLoader(app_name="LUSIDPythonTest")
]
api_client_factory = ApiClientFactory(config_loaders=config_loaders)
async with api_client_factory:
    api_instance = api_client_factory.build(ApplicationMetadataApi)

    Note the following:

    • Configuration loaders each return a dictionary of configuration keys and values. When keys are found by multiple configuration loaders, the last configuration loader to read the key overrides previous loaders.

    • Custom configuration loaders must implement the load_config method described in the configuration loader protocol.

Model arguments must be named

v2 of the LUSID Python SDK now uses Pydantic to perform runtime type checking on model objects. The v2 upgrade removes positional argument support; model arguments must now be named:

## v1 of the SDK...
python version = 'version_example' 
api_response = api_instance.get_excel_addin(version)

## ...might change as follows for v2 of the SDK...
python version = 'version_example' 
api_response = await api_instance.get_excel_addin(version=version)

Function arguments are type checked

In v2, models are more strict with argument types, and calling a function with incorrect types now throws a validation error, for example: 

 2 validation errors for Model 
 is_required 
     Field required [type=missing, input_value={'list_of_ints': ['1', 2,...ew York'}, 'gt_int': 21}, input_type=dict] 
 gt_int 
     Input should be greater than 42 [type=greater_than, input_value=21, input_type=int]

FINBOURNE SDK Utils replaces LUSID Python Tools

LUSID Python Tools is only available for use with v1 of the LUSID Python SDK. For v2 SDKs, FINBOURNE SDK Utils is introduced as a replacement for LUSID Python Tools.

FINBOURNE SDK Utils contains a set of utility functions for interacting with the v2 LUSID Python SDKs. The package includes all of the capabilities of LUSID Python Tools, in addition to the changes and improvements listed here. Users may need to update their code to reflect the changes.

You can install FINBOURNE SDK Utils for the LUSID Python SDK using the following pip command:

$ pip install finbourne-sdk-utils

Installing v1 of the LUSID Python SDK

Please note v1 of the LUSID Python SDK is now discontinued, but if you do need to install it for any reason then two packages are published:

  • lusid-sdk contains only APIs with a lifecycle status of Production or Early Access. You can install it using the following pip command: 

    $ pip install lusid-sdk<2

  • lusid-sdk-preview contains additional APIs with a lifecycle status of Experimental or Beta. You can install it using the following pip command:

    $ pip install lusid-sdk-preview<2