TM1py

2.2.4 · active · verified Thu Apr 16

TM1py is a free and open-source Python package that wraps the IBM Planning Analytics (TM1) REST API into a simple-to-use library, facilitating Python developments for TM1. It enables programmatic interaction with TM1 for tasks like reading/writing data, executing processes, and managing metadata. The library is actively maintained by Cubewise and a community of contributors, with the current version being 2.2.4, and receives regular updates and minor releases. [3, 5, 15]

Common errors

```
ValueError: No response returned from URL: 'https://<ip>:<port>/api/v1/Configuration/ProductVersion/$value'. Please double check your address and port number in the URL.
```
cause TM1py could not receive a response from the specified URL, often due to an incorrect address, port, SSL setting, or the TM1 REST API not being reachable/enabled. [17]

fix Verify the `address`, `port`, and `ssl` parameters in `TM1Service` exactly match your TM1 server configuration. Confirm the TM1 REST API is enabled and accessible from the machine running the Python script. Check for firewall rules. [9, 12, 16, 17]
```
Failed to connect to TM1 server: Text: '{ "error":"access_denied", "error_description":"Failed to verify OAuth information. Transaction ID=..." }' - Status Code: 401 - Reason: 'Unauthorized'
```
cause Authentication failure, usually due to incorrect username/password, API key, IAM URL, tenant ID, or namespace. This is particularly common in cloud environments where specific non-interactive users or API keys are required. [18]

fix Review your credentials and connection parameters carefully. For IBM Cloud PAaaS, ensure the correct `api_key`, `iam_url`, and `tenant` are provided, and `user` is set to 'apikey'. For on-premise, verify `user`, `password`, and `namespace` (if CAM security is used). [5, 18]
```
requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))
```
cause The remote TM1 server unexpectedly closed the connection. This can be caused by network issues, server-side errors, or incorrect SSL/TLS handshake. [9]

fix Check the TM1 server logs for any errors. Ensure network stability between your client and the TM1 server. For SSL/TLS issues, verify `ssl=True` and `verify` parameters in `TM1Service` or investigate server certificates. Consider increasing the `timeout` parameter in `TM1Service` for slow connections. [9, 10, 17]

Warnings

breaking Connecting to TM1 v12/Planning Analytics as a Service (PAaaS) requires a different set of parameters (e.g., `base_url`, `api_key`, `iam_url`, `tenant`) compared to older on-premise TM1 versions. Existing connection patterns for PAaaS will break if not updated to the new authentication scheme introduced around TM1py 2.0. [5, 15]
Fix: Review the TM1py documentation for v12/PAaaS connection specifics. Use `base_url`, `user='apikey'`, `password=api_key`, `iam_url`, and `tenant` parameters in `TM1Service` for PAaaS instances. [5, 18]
gotcha Connection issues are common due to incorrect `TM1Service` parameters (address, port, SSL, user, password, namespace, etc.) or if the TM1 REST API is not correctly enabled on the TM1 server. SSL errors (`SSLError`, `SSLV3_ALERT_HANDSHAKE_FAILURE`) often indicate certificate issues or misconfigured `ssl` / `verify` parameters. [9, 12, 17]
Fix: Double-check all `TM1Service` parameters against your TM1 server configuration (e.g., `tm1s.cfg` for HTTPPortNumber, UseSSL). Ensure the TM1 REST API is enabled. For SSL errors, try setting `verify=False` (though not recommended for production) or provide the correct path to your `.cer` file for `verify`. [10, 16, 17]
gotcha For large read/write operations (e.g., `write` or `write_dataframe`), not utilizing the `use_blob=True` parameter can lead to significantly slower performance compared to using optimized modes available in TM1py v1.11 onwards. [19]
Fix: When performing bulk data operations, especially with pandas DataFrames, pass `use_blob=True` to `tm1.cells.write()` or `tm1.cells.write_dataframe()` for improved performance. [19]

Install

pip install --upgrade TM1py Standard Install
pip install --upgrade "TM1py[pandas]" Install with Pandas support

Imports

TM1Service
```
from TM1py.Services import TM1Service
```
Dimension
```
from TM1py.Objects import Dimension
```
Cube
```
from TM1py.Objects import Cube
```

Quickstart

This quickstart demonstrates how to establish a connection to an on-premise TM1 instance and an IBM Planning Analytics Cloud (PAaaS) instance using TM1py. It retrieves the server product version to confirm connectivity. Environment variables are used for sensitive credentials. For PAaaS, a `base_url`, `api_key`, `iam_url`, and `tenant` are typically required for API Key authentication. [5, 18]

import os
from TM1py.Services import TM1Service

# --- On-premise TM1 Connection ---
TM1_ADDRESS_ONPREM = os.environ.get('TM1_ADDRESS_ONPREM', 'localhost')
TM1_PORT_ONPREM = int(os.environ.get('TM1_PORT_ONPREM', '8001'))
TM1_USER_ONPREM = os.environ.get('TM1_USER_ONPREM', 'admin')
TM1_PASSWORD_ONPREM = os.environ.get('TM1_PASSWORD_ONPREM', 'apple')
TM1_SSL_ONPREM = os.environ.get('TM1_SSL_ONPREM', 'True').lower() == 'true'

try:
    with TM1Service(
        address=TM1_ADDRESS_ONPREM,
        port=TM1_PORT_ONPREM,
        user=TM1_USER_ONPREM,
        password=TM1_PASSWORD_ONPREM,
        ssl=TM1_SSL_ONPREM
    ) as tm1_onprem:
        version_onprem = tm1_onprem.server.get_product_version()
        print(f"Successfully connected to on-premise TM1: {version_onprem}")
except Exception as e:
    print(f"Failed to connect to on-premise TM1: {e}")

# --- IBM Planning Analytics Cloud (PAaaS / TM1 v12) Connection ---
# Note: For PAaaS, typically an API Key is used with 'user="apikey"'
TM1_BASE_URL_CLOUD = os.environ.get('TM1_BASE_URL_CLOUD', 'https://us-east-1.planninganalytics.saas.ibm.com/api/<TenantId>/v0/tm1/<DatabaseName>/')
TM1_API_KEY_CLOUD = os.environ.get('TM1_API_KEY_CLOUD', '')
TM1_IAM_URL_CLOUD = os.environ.get('TM1_IAM_URL_CLOUD', 'https://iam.cloud.ibm.com')
TM1_TENANT_CLOUD = os.environ.get('TM1_TENANT_CLOUD', '') # Required for API Key authentication

if TM1_API_KEY_CLOUD:
    try:
        with TM1Service(
            base_url=TM1_BASE_URL_CLOUD,
            user="apikey",
            password=TM1_API_KEY_CLOUD,
            iam_url=TM1_IAM_URL_CLOUD,
            tenant=TM1_TENANT_CLOUD,
            ssl=True,
            verify=True,
            async_requests_mode=True
        ) as tm1_cloud:
            version_cloud = tm1_cloud.server.get_product_version()
            print(f"Successfully connected to PA Cloud: {version_cloud}")
    except Exception as e:
        print(f"Failed to connect to PA Cloud: {e}")
else:
    print("Skipping PA Cloud connection: TM1_API_KEY_CLOUD not set.")

view raw JSON →