Installation

UnDatasIO Python SDK Documentation

 

💫Welcome to the UnDatasIO Python SDK

Official Website: https://undatas.io/

UnDatasIO provides powerful, cloud-based file parsing capabilities. This Python SDK offers a streamlined, developer-friendly interface for interacting with the UnDatasIO API. It allows you to programmatically manage workspaces, tasks, and files, enabling you to focus on data analysis and application development.

Key Features

---

• Workspace & Task Management: Easily list and navigate through your workspaces and tasks.
• Comprehensive File Handling: Upload new files to specific tasks and list existing ones.
• Asynchronous Parsing: Trigger parsing jobs for one or multiple files with configurable parameters.
• Flexible Result Retrieval: Fetch structured parsing results as text or request a downloadable ZIP archive containing all artifacts.
• Pythonic Design: Methods return data directly (e.g., a list of dictionaries) on success and None on failure, with detailed errors logged for easy debugging.

Installation

---

🤖You can easily install the UnDatasIO Python SDK using pip:

pip install undatasio

Quick Start

---

🥇 The new workflow follows a logical hierarchy: Workspace -> Task -> File. Here’s a complete example demonstrating the entire process:

import time
from undatasio import UnDatasIO
import pandas as pd

# 1. Initialize the UnDatasIO client with your token and the API base URL
client = UnDatasIO(
    token='your_api_key_here'
)

# 2. List available workspaces and select the first one
workspaces = client.workspace_list()
if not workspaces:
    exit("No workspaces found.")
first_workspace_id = workspaces[0]['work_id']
print(f"Using workspace: {first_workspace_id}")

# 3. List tasks within the selected workspace and select the first one
tasks = client.task_list(work_id=first_workspace_id)
if not tasks:
    exit(f"No tasks found in workspace {first_workspace_id}.")
first_task_id = tasks[0]['task_id']
print(f"Using task: {first_task_id}")

# 4. Upload a new file to this task
# Make sure 'path/to/your/document.pdf' exists
if client.upload_file(task_id=first_task_id, file_path='path/to/your/document.pdf'):
    print("File uploaded successfully!")

# 5. List all files in the task to get a file_id
files = client.get_task_files(task_id=first_task_id)
if not files:
    exit("No files found in the task.")
file_to_process = files[0]
file_id = file_to_process['file_id']
print(f"Processing file: {file_to_process['file_name']} (ID: {file_id})")

# 6. Trigger the parsing process for the file
if client.parse_files(task_id=first_task_id, file_ids=[file_id]):
    print("Parsing task successfully triggered. Waiting for completion...")
    # In a real application, you might poll for status. Here, we just wait.
    while True:
        time.sleep(10)
        get_task_files = pd.DataFrame(client.get_task_files(task_id=task_id))
        if len(get_task_files):
            print(get_task_files)
            status = get_task_files[get_task_files['file_id'] == file_id].status.values[0]
            if status == 'parser success':
                break

    # 7. Get the parsed text result
    result_text = client.get_parse_result(task_id=first_task_id, file_id=file_id)
    if result_text:
        print("\n--- Parsed Result (Text) ---")
        print("\n".join(result_text)[:500] + "...") # Print first 500 characters

    # 8. Get the download URL for the result archive
    download_url = client.download_parsed_results(task_id=first_task_id, file_ids=[file_id])
    if download_url:
        print("\n--- Download URL ---")
        print(download_url)

API Reference

---

🔥 The UnDatasIO Python SDK provides the following methods:

• UnDatasIO(token: str)

  • 🛠️ Initializes the client.
    • token (str): Your API key, obtained from the UnDatasIO platform.

• workspace_list(self) -> Optional[List[Dict]]

  • 🏢 Retrieves a list of all workspaces accessible by your API key.
    • file_dir_path (str): The path to the directory containing the files to upload.
    • Returns: A list of dictionaries, where each dictionary represents a workspace, or None on failure.

• task_list(self, work_id: str) -> Optional[List[Dict]]

  • 📋 Retrieves a list of all tasks within a specific workspace.
    • task_id (str): The ID of the target task.
    • Returns: A list of dictionaries representing tasks, or None on failure.

• get_task_files(self, task_id: str) -> Optional[List[Dict]]

  • 📂 Retrieves a list of all files within a specific task.
    • task_id (str): The ID of the target task.
    • Returns: A list of dictionaries representing files, or None on failure.

• upload_file(self, task_id: str, file_path: str) -> bool

  • 📤 Uploads a single file to a specific task.
    • task_id (str): The ID of the task to upload the file to.
    • file_path (str): The local path to the file to be uploaded.
    • Returns: True on successful upload, False on failure.

• parse_files(self, task_id: str, file_ids: List[str], **kwargs) -> bool

  • 🌟 Triggers a parsing job for one or more files.
    • task_id (str): The local path to the file to be uploaded.
    • file_ids (List[str]): The local path to the file to be uploaded.
    • Optional keyword arguments like lang='ch' or parse_mode='fast' can be passed.
    • Returns: True if the parsing job was successfully triggered, False otherwise.

Click to see all supported Mode codes

Mode
fast
accurate
multi-modal

Click to see all supported lang codes

Code	Language
en	English
korean	한국어
japan	日本語
ch	中文
chinese_cht	繁體中文
de	Deutsch
es	Español
id	Bahasa Indonesia
fr	Français
pt	Português
it	Italiano
tr	Türkçe
pl	Polski
cs	Čeština
da	Dansk
hi	हिंदी
ta	தமிழ்
te	తెలుగు
ka	ಕನ್ನಡ
af	Afrikaans
az	Azərbaycan
bs	Bosanski
cy	Cymraeg
et	Eesti
ga	Gaeilge
hr	Hrvatski
hu	Magyar
is	Íslenska
ku	Kurdî
la	Latina
lt	Lietuvių
lv	Latviešu
mi	Māori
ms	Bahasa Melayu
mt	Malti
nl	Nederlands
no	Norsk
oc	Occitan
pi	पालि
ro	Română
rs_latin	Srpski
sk	Slovenčina
sl	Slovenščina
sq	Shqip
sv	Svenska
sw	Kiswahili
tl	Tagalog
uz	O’zbek
vi	Tiếng Việt

• get_parse_result(self, task_id: str, file_id: str) -> Optional[List[str]]

  • 📄 Fetches the parsed text result of a single file.
    • task_id (str): The ID of the task.
    • file_id (str): The ID of the file.
    • Returns: A list of strings, where each string is a block of parsed text, or None on failure.

• download_parsed_results(self, task_id: str, file_ids: List[str]) -> Optional[str]

  • 🔗 Requests a download URL for a ZIP archive containing the full parsing results.
    • task_id (str): The ID of the task.
    • file_ids (List[str]): A list of file IDs to include in the archive.
    • Returns: A string containing the download URL, or None on failure.

Colab Example

---

📄 The following ipynb file is designed to run in a Colab environment. Clicking on it will allow you to run it directly in Colab.

Error Handling

---

📚 This SDK is designed for simplicity. All methods that fetch data will return the data directly on success or None on failure. Methods that perform an action will return True on success or False on failure.

• Check for ``None`` or ``False``. :Always check the return value of a method call to handle potential failures gracefully.
• Check the Logs In case of failure, the SDK will log detailed error information to the console using Python’s standard logging module. This is your primary tool for debugging.

Contact Us

---

If you have any questions or need support, please visit our official website or contact us through our support channels.