{"id":7224,"library":"files-com","title":"Files.com Python Client","description":"The `files-com` Python client provides official Python bindings for interacting with the Files.com API. It enables developers to programmatically manage files, folders, users, permissions, and other resources on the Files.com platform. As of version `1.6.348`, it offers direct access to API endpoints through a convenient object-oriented interface and is actively maintained.","status":"active","version":"1.6.348","language":"en","source_language":"en","source_url":"https://github.com/FilesCom/files-com-python-sdk","tags":["files-com","cloud storage","api client","file management","sdk"],"install":[{"cmd":"pip install files-com","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"files_com","correct":"import files_com"},{"symbol":"Configuration","correct":"from files_com import Configuration"}],"quickstart":{"code":"import files_com\nimport os\n\n# Configure API Key and Base URL (highly recommended to use environment variables)\nfiles_com.api_key = os.environ.get('FILESCOM_API_KEY', '') # Replace '' with your actual API key for local testing\nfiles_com.base_url = os.environ.get('FILESCOM_BASE_URL', 'https://app.files.com') # Replace with your custom domain if applicable\n\nif not files_com.api_key:\n    print(\"Error: FILESCOM_API_KEY environment variable not set or API key not provided.\")\n    exit(1)\n\ntry:\n    # Example: List users\n    print(\"Listing users...\")\n    users = files_com.User.list(per_page=10) # Fetch up to 10 users\n    if users:\n        for user in users:\n            print(f\"  User ID: {user.id}, Username: {user.username}, Email: {user.email}\")\n    else:\n        print(\"  No users found.\")\n\n    # Example: Create a new folder (adjust name as needed)\n    print(\"\\nCreating a new folder...\")\n    try:\n        new_folder = files_com.Folder.create(path='/my_test_folder', name='MyNewFolder123')\n        print(f\"  Folder '{new_folder.path}' created successfully (ID: {new_folder.id}).\")\n        \n        # Example: Delete the created folder\n        print(f\"\\nDeleting folder '{new_folder.path}'...\")\n        files_com.Folder.delete(path=new_folder.path)\n        print(f\"  Folder '{new_folder.path}' deleted successfully.\")\n    except files_com.exceptions.ApiError as e:\n        print(f\"  Failed to create/delete folder: {e.message}\")\n\nexcept files_com.exceptions.UnauthorizedException as e:\n    print(f\"Authentication failed: {e.message}. Check your API key and base URL.\")\nexcept files_com.exceptions.NotFoundException as e:\n    print(f\"Resource not found: {e.message}. Check paths and IDs.\")\nexcept files_com.exceptions.ApiError as e:\n    print(f\"An API error occurred: {e.message}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions using the Files.com API's pagination model"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The API Key or Base URL is incorrect, missing, or the key lacks necessary permissions for the requested operation.","error":"files_com.exceptions.UnauthorizedException: Authentication failed"},{"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).","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.","error":"files_com.exceptions.NotFoundException: Not Found"},{"fix":"Implement a loop to fetch all pages. For example, to get all users:\n```python\nimport files_com\n\nall_users = []\nnext_cursor = None\nwhile True:\n    # The 'cursor' parameter should be the ID of the last item from the previous page\n    page = files_com.User.list(cursor=next_cursor, per_page=100) # Adjust per_page as needed\n    if not page: # No more items\n        break\n    all_users.extend(page)\n    next_cursor = page[-1].id # Set cursor to the ID of the last item for the next page\n# all_users now contains all users\nfor user in all_users:\n    print(f\"User: {user.username} (ID: {user.id})\")\n```","cause":"The API uses cursor-based pagination, and by default, only the first page of results is returned.","error":"List method (e.g., `User.list()`) only returns a subset of my data."}]}