Install & Compatibility
Where this runs
tested against v25.9.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.864s · 37.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.4s · import 0.794s · 37MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Polytomic
✓ from polytomic.client import Polytomic
AsyncPolytomic
✓ from polytomic.client import AsyncPolytomic
For asynchronous API calls.
BulkSchedule
✓ from polytomic import BulkSchedule
Example of an imported model for API request bodies.
This quickstart demonstrates how to initialize the Polytomic client and make a basic API call to list bulk syncs. It uses an environment variable for the API token for security best practices. To run the commented-out `create` example, you would need valid connection IDs from your Polytomic account.
import os
from polytomic.client import Polytomic
from polytomic import BulkSchedule
# Best practice: Load token from environment variable
POLYTOMIC_TOKEN = os.environ.get('POLYTOMIC_TOKEN', 'YOUR_POLYTOMIC_API_KEY')
if POLYTOMIC_TOKEN == 'YOUR_POLYTOMIC_API_KEY':
print("Please set the POLYTOMIC_TOKEN environment variable or replace 'YOUR_POLYTOMIC_API_KEY'.")
else:
try:
client = Polytomic(token=POLYTOMIC_TOKEN)
# Example: Listing bulk syncs (replace with actual API call relevant to your use case)
bulk_syncs = client.bulk_sync.list()
print(f"Successfully connected. Found {len(bulk_syncs.data)} bulk syncs.")
# Example of creating a bulk sync (dummy data for illustration, needs valid IDs)
# try:
# new_sync = client.bulk_sync.create(
# destination_connection_id="248df4b7-aa70-47b8-a036-33ac447e668d", # Replace with actual ID
# mode="replicate",
# name="My New Bulk Sync",
# schedule=BulkSchedule(frequency="manual"),
# source_connection_id="248df4b7-aa70-47b8-a036-33ac447e668d", # Replace with actual ID
# )
# print(f"Created new bulk sync with ID: {new_sync.data.id}")
# except Exception as e:
# print(f"Error creating bulk sync: {e}")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
gotchaThe Polytomic Python library is programmatically generated from an OpenAPI specification. Direct contributions to the generated code will not be merged as-is and will be overwritten in subsequent releases. Users are advised to open an issue first to discuss desired changes or contribute to the README.fixFor feature requests or bug fixes, open an issue on the GitHub repository to discuss with the Polytomic team. For documentation improvements, direct PRs to the README are welcome.
affects: All versions
breakingA behavioral change was introduced for bulk syncs to Databricks. Previously, the destination table was replaced *before* data was written. As of Release 2025.02.20, data will be staged in a temporary table and then renamed during a resync, if possible. Syncs to default `hive_metastore` (where renaming is unsupported) will continue to replace the table at the start of the sync.fixReview Databricks bulk sync workflows and adapt any downstream dependencies that relied on the previous 'replace before write' behavior for tables that support temporary staging and renaming. For `hive_metastore` destinations, the behavior remains unchanged.
affects: >=2025.02.20
deprecatedThe `type` parameter in the `connections/connect` API endpoint has been deprecated. While it may still function, its use is discouraged and it may be removed in future API versions.fixInstead of using the `type` parameter, use the `whitelist` parameter, which accepts a list of connection types that are allowed to be created.
affects: API versions 2024-02-08 and later
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'polytomic'
The `polytomic` library has not been installed in your Python environment or there is a typo in the import statement.
fixRun `pip install polytomic` to install the library. Verify the spelling of the import statement.
polytomic.client.ApiException: (401)
Reason: Unauthorized
The Polytomic API token provided to the client is either missing, invalid, or has insufficient permissions for the requested operation.
fixEnsure that the `token` parameter passed to the `Polytomic` client constructor is a valid and active API key with the necessary permissions. Double-check for typos or ensure the environment variable `POLYTOMIC_TOKEN` is correctly set if using that method.
TypeError: object of type 'NoneType' has no len()
Often occurs when an API call returns `None` (e.g., if a resource is not found or an error occurred, and the response parsing expects an iterable or an object with a length) but the code attempts to access it as if it were a valid data structure. This can happen if `client.some_endpoint.list().data` is `None`.
fixAlways check if the `data` attribute or other response fields are not `None` before attempting to access their properties or iterating over them. Implement robust error handling for API responses.
Upgrade
Version history
25.9.2latest on PyPI · released Apr 29, 2026
Audit
Dependencies
pythonrequiredRequires Python version 3.8 or higher, but less than 4.0.