Skip to main content

6. Python Library

The LUCA BDS Python library provides an interface to interact with the platform's API.

note

Documentation and download of the library: PyPI.

Installation​

To install the library, ensure you have Python installed and run:

pip install python-luca-bds

Documentation​

Class: LucaConnector​

Class that defines the connection model with a LUCA BDS installation.

Structure:

conn = LucaConnector(server_url, username, password, keycloak_connection=None)

Input Variables:

  • server_url (str): Base URL of the LUCA server.
  • username (str): Username.
  • password (str): Password.
  • keycloak_connection (KeycloakConnection): Existing Keycloak connection. If None, the constructor creates a new connection for the /auth endpoint of the domain provided in server_url.

Methods:

  • info(return_pd=True): Returns license information in pd.Series or dict.

Example:

luca_conn = LucaConnector(
    server_url='https://luca-bds-domain/luca-api',
    username='user',
    password='pass'
    keycloak_connection=None
)

Class: KeycloakConnector​

Class for authentication using Keycloak.

Structure:

KeycloakConnector(server_url, realm_name='luca-bds', client_id='luca-bds-web', client_secret_key='', verify_ssl=True)

Input Variables:

  • server_url (str): Base URL of the Keycloak server.
  • realm_name (str, optional): Name of the Keycloak realm. Defaults to luca-bds.
  • client_id (str, optional): Client ID in Keycloak. Defaults to luca-bds-web.
  • client_secret_key (str, optional): Client secret key. Defaults to an empty string.
  • verify_ssl (bool, optional): Verifies SSL certificates. Defaults to True.

Methods:

  • create_token(username, password): Creates a new Keycloak token.
  • refresh_token(): Refreshes the current token.
  • get_token(username, password): Obtains a valid access token, creating or refreshing it as necessary.

Example:

keycloak_conn = KeycloakConnector(
    server_url='https://keycloak-domain/auth',
    realm_name='realm-name',
    client_id='client-id',
    client_secret_key='client-secret'
)

Function: get_queries​

Gets a list of queries from the LUCA system.

Structure:

get_queries(conn, name=None, description=None, user=None, page=1, size=25, return_pd=True)

Input Variables:

  • conn (object): Connection object, with server URL and headers.
  • name (str, optional): Filters by query name.
  • description (str, optional): Filters by query description.
  • user (int, optional): Filters by user ID.
  • page (int, optional): Page number for pagination.
  • size (int, optional): Page size for pagination.
  • return_pd (bool, optional): Returns data as pandas structure if True.

Returns:

  • list | DataFrame | Series: Query information, including IDs and metadata.

Example:

queries = get_queries(
    conn = luca_conn,
    name='my_query',
    description='my_query description',
    user=123
)

Function: get_query​

Executes a query by name or ID in a specific environment.

Structure:

get_query(conn, id, return_pd=True)

Input Variables:

  • conn (object): Connection object, with server URL and headers.
  • id (int): Unique ID of the query.
  • return_pd (bool, optional): Returns data as pandas structure if True.

Returns:

  • dict | Series: Query details, such as name or description.

Example:

query_details = get_query(
    conn=luca_conn,
    id=123
)

Function: execute_query​

Executes a query in a specified environment with optional input variables.

Structure:

execute_query(conn, id, environment_id, input_variables=[], page=1, size=25, commit=True, return_pd=True)

Input Variables:

  • conn (object): Connection object, with server URL and headers.
  • id (int): Unique identifier of the query.
  • environment_id (str): Environment where the query will be executed.
  • input_variables (list, optional): Variables to be passed as input.
  • page (int, optional): Page number for pagination.
  • size (int, optional): Page size for pagination.
  • commit (bool, optional): Indicates whether to commit the query transaction.
  • return_pd (bool, optional): Returns data as pandas structure if True.

Returns:

  • list | dict | DataFrame | Series: The result of the query (DataFrame or Series), pagination information, and state of the query.

Example:

data, pagination, state = execute_query(
    conn=luca_conn,
    id=123,
    environment_id='env',
    input_variables=[{'key': 'var1', 'value': 'value1'}]
)

Function: query​

Executes a query by name or ID in a specific environment, using optional input variables.

Structure:

query(conn, environment, name=None, id=None, input_variables={}, page=1, size=25, commit=True, return_pd=True)

Input Variables:

  • conn (object): Connection object, with server URL and headers.
  • environment (str): Name of the environment where the query will be executed.
  • name (str, optional): Name of the query to search.
  • id (int, optional): ID of the query to search.
  • input_variables (dict, optional): Key-value pairs for the input variables of the query.
  • page (int, optional): Page number for pagination.
  • size (int, optional): Page size for pagination.
  • commit (bool, optional): Indicates whether to commit the query transaction.
  • return_pd (bool, optional): Returns data as pandas structure if True.

Returns:

  • tuple (list | dict | DataFrame | Series): The result of the query (DataFrame or Series), pagination information, and state of the query.

Example:

result, pagination, state = query(
    conn=luca_conn,
    environment='env',
    name='my_query',
    input_variables={'var1': 'value1', 'var2': ['value1', 'value2']}
)

Function: get_charts​

Gets charts from the server based on filtering parameters.

Structure:

get_charts(conn, name=None, description=None, user=None, query=None, page=1, size=25, return_pd=True)

Input Variables:

  • conn (object): Connection object, with server URL and headers.
  • name (str, optional): Filters by chart name.
  • description (str, optional): Filters by chart description.
  • user (str, optional): Filters by user.
  • query (int, optional): Filters by query ID.
  • page (int, optional): Page number for pagination.
  • size (int, optional): Page size for pagination.
  • return_pd (bool, optional): Returns data as pandas structure if True.

Returns:

  • list | DataFrame | Series: Chart information, including IDs and metadata.

Example:

charts = get_charts(
    conn=luca_conn,
    name='chart_name',
    description='description'
)

Function: get_chart​

Gets a specific chart by its ID and returns its detailed data.

Structure:

get_chart(conn, id, return_pd=True)

Input Variables:

  • conn (object): Connection object, with server URL and headers.
  • id (str): Unique identifier of the chart.
  • return_pd (bool, optional): Returns data as pandas structure if True.

Returns:

  • dict | Series: Chart details, such as name or description.

Example:

chart_details = get_chart(
    conn=luca_conn,
    id=123
)

Function: get_datasources​

Gets data sources from the server based on filtering parameters.

Structure:

get_datasources(conn, type=None, system=None, page=1, size=25, return_pd=True)

Input Variables:

  • conn (object): Connection object, with server URL and headers.
  • type (str, optional): Filters by data source type.
  • system (int, optional): Filters by system ID.
  • page (int, optional): Page number for pagination.
  • size (int, optional): Page size for pagination.
  • return_pd (bool, optional): Returns data as pandas structure if True.

Returns:

  • list | DataFrame | Series: Information on data sources, including IDs and metadata.

Example:

datasources = get_datasources(
    conn=luca_conn,
    type='rest',
    system=123
)

Function: get_datasource​

Gets a specific data source by its ID and returns its detailed data.

Structure:

get_datasource(conn, id, return_pd=True)

Input Variables:

  • conn (object): Connection object, with server URL and headers.
  • id (int): Unique identifier of the data source.
  • return_pd (bool, optional): Returns data as pandas structure if True.

Returns:

  • dict | Series: Data source details, such as name or description.

Example:

datasource_details = get_datasource(
    conn=luca_conn,
    id=123
)

Function: get_systems​

Gets systems from the server based on filtering parameters.

Structure:

get_systems(conn, type=None, datasourceType=None, user=None, enabled=True, page=1, size=25, return_pd=True)

Input Variables:

  • conn (object): Connection object, with server URL and headers.
  • type (str, optional): Filters by system type.
  • datasourceType (str, optional): Filters by data source type of the system (e.g., bd, soap, rest, log).
  • user (int, optional): Filters by user ID.
  • enabled (bool, optional): Filters by enabled status.
  • page (int, optional): Page number for pagination.
  • size (int, optional): Page size for pagination.
  • return_pd (bool, optional): Returns data as pandas structure if True.

Returns:

  • list | DataFrame | Series: Information on systems, including IDs and metadata.

Example:

systems = get_systems(
    conn=luca_conn,
    type='mysql',
    datasourceType='bd',
    enabled=True
)

Function: get_system​

Gets a specific system by its ID and returns its detailed data.

Structure:

get_system(conn, id, return_pd=True)

Input Variables:

  • conn (object): Connection object, with server URL and headers.
  • id (int): Unique identifier of the system.
  • return_pd (bool, optional): Returns data as pandas structure if True.

Returns:

  • dict | Series: System details, including name, type, and associated data sources.

Example:

system_details = get_system(
    conn=luca_conn,
    id=123
)

Function: get_users​

Gets users from the server based on filtering parameters.

Structure:

get_users(conn, username=None, email=None, enabled=True, page=1, size=25, return_pd=True)

Input Variables:

  • conn (object): Connection object, with server URL and headers.
  • username (str, optional): Filters by username.
  • email (str, optional): Filters by email.
  • enabled (bool, optional): Filters by enabled status.
  • page (int, optional): Page number for pagination.
  • size (int, optional): Page size for pagination.
  • return_pd (bool, optional): Returns data as pandas structure if True.

Returns:

  • list | DataFrame | Series: Information on users, including IDs and metadata.

Example:

users = get_users(
    conn=luca_conn,
    username='user_name',
    email='email@email.com',
    enabled=True
)

Function: get_user​

Gets a specific user by its ID and returns its detailed data.

Structure:

get_user(conn, id, return_pd=True)

Input Variables:

  • conn (object): Connection object, with server URL and headers.
  • id (int): Unique identifier of the user.
  • return_pd (bool, optional): Returns data as pandas structure if True.

Returns:

  • dict | Series: User details, including name, email, and permissions.

Example:

user_details = get_user(
    conn=luca_conn,
    id=123
)

Usage Example​

Below is an example of how to use the LUCA BDS client to connect to the server and test some functionality:

from luca.connectors import LucaConnector
from luca.querys import query

# LUCA connection configuration
luca_conn = LucaConnector(
    server_url='https://luca-bds-domain/luca-api',
    username='user',
    password='pass'
)

# Retrieve connection information
info = luca_conn.info()
print(info)

# Execute a query by name
result, pag, state = query(
    conn=luca_conn,
    name='name',
    environment='env'
)
print(result)

# Execute a query by ID
result, pag, state = query(
    conn=luca_conn,
    id=123,
    environment='env',
    input_variables=[{'User': 'user', 'System': 'sys'}]
)
print(result)
print(pag)
print(state)