Files.com Python Client

Common errors

• files_com.exceptions.UnauthorizedException: Authentication failed

  cause The API Key or Base URL is incorrect, missing, or the key lacks necessary permissions for the requested operation.
  fix Verify the `FILESCOM_API_KEY` and `FILESCOM_BASE_URL` environment variables are correctly set. Ensure the API key is active and has sufficient permissions for the requested operation on the specified base URL.

• files_com.exceptions.NotFoundException: Not Found

  cause The specified resource (e.g., user ID, file path) does not exist on the Files.com account, or the `base_url` points to an incorrect or non-existent Files.com instance.
  fix Double-check the identifiers and paths used in the API call against your Files.com account. Confirm `files_com.base_url` is accurate (e.g., `https://app.files.com` or your custom domain).

• List method (e.g., `User.list()`) only returns a subset of my data.

  cause The API uses cursor-based pagination, and by default, only the first page of results is returned.
  fix Implement a loop to fetch all pages. For example, to get all users: ```python import files_com all_users = [] next_cursor = None while True: # The 'cursor' parameter should be the ID of the last item from the previous page page = files_com.User.list(cursor=next_cursor, per_page=100) # Adjust per_page as needed if not page: # No more items break all_users.extend(page) next_cursor = page[-1].id # Set cursor to the ID of the last item for the next page # all_users now contains all users for user in all_users: print(f"User: {user.username} (ID: {user.id})") ```

Warnings

• gotcha The `files_com.api_key` and `files_com.base_url` are configured globally at the module level. This global state can lead to issues in multi-threaded applications, complex testing scenarios, or when managing multiple Files.com accounts/environments within a single process.
  Fix: For isolated configurations, ensure that `files_com.api_key` and `files_com.base_url` are set immediately before each specific API call context where different credentials or endpoints are needed, or manage separate processes. The SDK does not currently provide an instance-based API client for full context isolation.
• gotcha Many API list methods (e.g., `User.list()`, `File.list_for()`) return paginated results by default. Not explicitly handling pagination will result in only the first page of data being returned, leading to incomplete datasets.
  Fix: To retrieve all records, you must manually iterate through pages using the `cursor` and `per_page` parameters. The `cursor` for the next page is typically the `id` of the last item received in the current page. See the 'Problems' section for a code example.

Install

• pip install files-com Install latest version

Imports

• files_com

  import files_com

• Configuration

  from files_com import Configuration

Quickstart

This quickstart demonstrates how to configure the Files.com Python client using environment variables for API key and base URL, then perform basic operations like listing users and creating/deleting a folder. It includes basic error handling for common API exceptions.

import files_com
import os

# Configure API Key and Base URL (highly recommended to use environment variables)
files_com.api_key = os.environ.get('FILESCOM_API_KEY', '') # Replace '' with your actual API key for local testing
files_com.base_url = os.environ.get('FILESCOM_BASE_URL', 'https://app.files.com') # Replace with your custom domain if applicable

if not files_com.api_key:
    print("Error: FILESCOM_API_KEY environment variable not set or API key not provided.")
    exit(1)

try:
    # Example: List users
    print("Listing users...")
    users = files_com.User.list(per_page=10) # Fetch up to 10 users
    if users:
        for user in users:
            print(f"  User ID: {user.id}, Username: {user.username}, Email: {user.email}")
    else:
        print("  No users found.")

    # Example: Create a new folder (adjust name as needed)
    print("\nCreating a new folder...")
    try:
        new_folder = files_com.Folder.create(path='/my_test_folder', name='MyNewFolder123')
        print(f"  Folder '{new_folder.path}' created successfully (ID: {new_folder.id}).")
        
        # Example: Delete the created folder
        print(f"\nDeleting folder '{new_folder.path}'...")
        files_com.Folder.delete(path=new_folder.path)
        print(f"  Folder '{new_folder.path}' deleted successfully.")
    except files_com.exceptions.ApiError as e:
        print(f"  Failed to create/delete folder: {e.message}")

except files_com.exceptions.UnauthorizedException as e:
    print(f"Authentication failed: {e.message}. Check your API key and base URL.")
except files_com.exceptions.NotFoundException as e:
    print(f"Resource not found: {e.message}. Check paths and IDs.")
except files_com.exceptions.ApiError as e:
    print(f"An API error occurred: {e.message}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")