Lib Examples

The Splight Library is a powerful tool that allows you to interact with the Splight API using Python. It simplifies the process of making API requests and handling responses, enabling you to focus on building solutions rather than managing low-level HTTP logic. With just a few lines of code, you can manage various resources within your organization. This library is ideal for automating workflows, integrating with other systems, or performing advanced data analysis using Python.

In this section, you'll learn how to use the Splight Library to perform common tasks such as creating assets, retrieving telemetry data, updating configurations, and more. Each example includes code snippets and clear explanations to help you understand how to use the library effectively. Once familiar, you’ll be able to apply these tools across all Splight resources with ease.

---

Examples of Using Splight Library

Installation

To use the Splight Library, you first need to install it. You can do this using pip:

pip install splight-lib

For more information on how to install the library, refer to the Splight Lib.

Preparing Your Environment

Before using the Splight Library, you need to set up your environment with the proper credentials. These include your access ID and secret key, which you can obtain from the Splight platform.

If you haven't created an access key yet, refer to the Get Your Keys guide for instructions on how to generate one.

Once you have your credentials, we recommend installing the splight-cli tool to simplify the management of your Splight resources. You can install it with:

pip install splight-cli

After installation, create a new workspace with the following command:

splight create < name >

This command initializes a new workspace with the specified name, allowing you to manage your Splight resources in an organized manner. We recommend using a name of your organization or project. To configure the Splight CLI, run:

splight configure

This command will prompt you to enter your access ID and secret key, setting up your environment to use the Splight Library effectively.

For more information on how to configure the Splight CLI, refer to the Splight CLI.

---

Creating an Asset

To create an asset using the Splight Library, you can use the following code snippet. This example demonstrates how to create a new asset with basic details such as name, type, tags, and location.

from splight_lib.models import Asset, AssetKind

asset = Asset(
    name="My New Asset",
    description="This is a test asset created using Splight Library.",
    tags=[{
        "id": "<tag_id>", 
        "name": "tag_name",  
    }],
    geometry={
        "type": "Point",
        "coordinates": [40.7128, -74.0060]  
    },
    centroid_coordinates=(0.0, 0.0),
    kind=AssetKind(
            id="<kind_id>",  
            name="Line" 
        ),
    timezone="UTC"  
)

asset.save()  # Save the asset to the Splight platform

This code snippet creates a new asset with the specified parameters. You can adjust the values according to your requirements.

---

Reading Assets

Listing all Assets

To retrieve all assets in your organization, you can use the following command:

Asset.list()  # Retrieve all assets in the organization

This command fetches all assets and returns them in a list format, allowing you to iterate through them or perform further operations.

Retrieving a single Asset

To retrieve a specific asset by its ID, you can use the following command:

Asset.retrieve("<asset_id>")  # Replace <asset_id> with the actual ID of the asset

This method returns the asset object corresponding to the provided ID, giving you access to its properties and metadata.

If you prefer to retrieve an asset by its name, you can use the list method with a name filter:

Asset.list(name="My New Asset")[0]  # Replace "My New Asset" with the actual name of the asset

This returns a list of assets that match the given name. Since asset names are not unique, this example retrieves the first matching result.

The list method also supports advanced filtering options. For instance, you can filter by tags or use the _icontains operator to find assets whose names contain a specific substring:

Asset.list(name__icontains="New")  # Retrieve assets with names containing "New"

These flexible filters make it easier to find and manage assets based on partial matches or other attributes.

---

Updating an Asset

To update an existing asset, you can modify its properties and then save the changes. Here's an example of how to update an asset's description:

from splight_lib.models import Asset

asset = Asset.retrieve("<asset_id>")  # Replace <asset_id> with the actual ID of the asset
asset.description = "Updated description for the asset."

asset.save()  # Save the updated asset to the Splight platform

This code retrieves the asset by its ID, updates its description and tags, and then saves the changes back to the Splight platform.

---

Deleting an Asset

Before deleting an asset, you should delete any associated telemetry data, configurations, or other resources to avoid orphaned references. Once you have cleaned up the related resources, you can delete the asset using the following command:

from splight_lib.models import Asset

asset = Asset.retrieve("<asset_id>")  # Replace <asset_id> with the actual ID of the asset
asset.delete()  # Delete the asset from the Splight platform