{"id":7794,"library":"TM1py","title":"TM1py","description":"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]","status":"active","version":"2.2.4","language":"en","source_language":"en","source_url":"https://github.com/cubewise-code/tm1py","tags":["tm1","planning analytics","ibm","cubewise","rest api","olap","etl","automation"],"install":[{"cmd":"pip install --upgrade TM1py","lang":"bash","label":"Standard Install"},{"cmd":"pip install --upgrade \"TM1py[pandas]\"","lang":"bash","label":"Install with Pandas support"}],"dependencies":[{"reason":"Runtime environment","package":"python","version":">=3.7"},{"reason":"HTTP client for REST API communication","package":"requests"},{"reason":"Optional, for SSPI (Windows Integrated Authentication)","package":"requests_negotiate_sspi"},{"reason":"Optional, for DataFrame integration with TM1 data","package":"pandas","optional":true},{"reason":"Optional, for graph-related functionality","package":"networkx","optional":true}],"imports":[{"symbol":"TM1Service","correct":"from TM1py.Services import TM1Service"},{"symbol":"Dimension","correct":"from TM1py.Objects import Dimension"},{"symbol":"Cube","correct":"from TM1py.Objects import Cube"}],"quickstart":{"code":"import os\nfrom TM1py.Services import TM1Service\n\n# --- On-premise TM1 Connection ---\nTM1_ADDRESS_ONPREM = os.environ.get('TM1_ADDRESS_ONPREM', 'localhost')\nTM1_PORT_ONPREM = int(os.environ.get('TM1_PORT_ONPREM', '8001'))\nTM1_USER_ONPREM = os.environ.get('TM1_USER_ONPREM', 'admin')\nTM1_PASSWORD_ONPREM = os.environ.get('TM1_PASSWORD_ONPREM', 'apple')\nTM1_SSL_ONPREM = os.environ.get('TM1_SSL_ONPREM', 'True').lower() == 'true'\n\ntry:\n    with TM1Service(\n        address=TM1_ADDRESS_ONPREM,\n        port=TM1_PORT_ONPREM,\n        user=TM1_USER_ONPREM,\n        password=TM1_PASSWORD_ONPREM,\n        ssl=TM1_SSL_ONPREM\n    ) as tm1_onprem:\n        version_onprem = tm1_onprem.server.get_product_version()\n        print(f\"Successfully connected to on-premise TM1: {version_onprem}\")\nexcept Exception as e:\n    print(f\"Failed to connect to on-premise TM1: {e}\")\n\n# --- IBM Planning Analytics Cloud (PAaaS / TM1 v12) Connection ---\n# Note: For PAaaS, typically an API Key is used with 'user=\"apikey\"'\nTM1_BASE_URL_CLOUD = os.environ.get('TM1_BASE_URL_CLOUD', 'https://us-east-1.planninganalytics.saas.ibm.com/api/<TenantId>/v0/tm1/<DatabaseName>/')\nTM1_API_KEY_CLOUD = os.environ.get('TM1_API_KEY_CLOUD', '')\nTM1_IAM_URL_CLOUD = os.environ.get('TM1_IAM_URL_CLOUD', 'https://iam.cloud.ibm.com')\nTM1_TENANT_CLOUD = os.environ.get('TM1_TENANT_CLOUD', '') # Required for API Key authentication\n\nif TM1_API_KEY_CLOUD:\n    try:\n        with TM1Service(\n            base_url=TM1_BASE_URL_CLOUD,\n            user=\"apikey\",\n            password=TM1_API_KEY_CLOUD,\n            iam_url=TM1_IAM_URL_CLOUD,\n            tenant=TM1_TENANT_CLOUD,\n            ssl=True,\n            verify=True,\n            async_requests_mode=True\n        ) as tm1_cloud:\n            version_cloud = tm1_cloud.server.get_product_version()\n            print(f\"Successfully connected to PA Cloud: {version_cloud}\")\n    except Exception as e:\n        print(f\"Failed to connect to PA Cloud: {e}\")\nelse:\n    print(\"Skipping PA Cloud connection: TM1_API_KEY_CLOUD not set.\")","lang":"python","description":"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]"},"warnings":[{"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]","message":"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]","severity":"breaking","affected_versions":"TM1py < 2.0 when connecting to TM1 v12/PAaaS"},{"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]","message":"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]","severity":"gotcha","affected_versions":"All"},{"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]","message":"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]","severity":"gotcha","affected_versions":"TM1py < 1.11, or 1.11+ without `use_blob=True`"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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]","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]","error":"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."},{"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]","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]","error":"Failed to connect to TM1 server: Text: '{ \"error\":\"access_denied\", \"error_description\":\"Failed to verify OAuth information. Transaction ID=...\" }' - Status Code: 401 - Reason: 'Unauthorized'"},{"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]","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]","error":"requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))"}]}