Python API Reference
====================

This page documents the PyDrime Python API for programmatic access to Drime Cloud.

DrimeClient
-----------

.. autoclass:: pydrime.api.DrimeClient
   :members:
   :undoc-members:
   :show-inheritance:

Quick Start
-----------

.. code-block:: python

   from pydrime import DrimeClient
   from pathlib import Path

   # Initialize the client
   client = DrimeClient(api_key="your_api_key_here")

   # Or use environment variable DRIME_API_KEY
   client = DrimeClient()

Upload Operations
-----------------

Upload a File
~~~~~~~~~~~~~

.. code-block:: python

   from pathlib import Path

   # Simple upload
   result = client.upload_file(Path("myfile.txt"))
   print(f"File uploaded: {result['fileEntry']['id']}")

   # Upload with custom path
   result = client.upload_file(
       Path("myfile.txt"),
       relative_path="folder/subfolder/myfile.txt"
   )

   # Upload to workspace
   result = client.upload_file(
       Path("myfile.txt"),
       workspace_id=123
   )

Upload with Progress Callback
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   def progress_callback(bytes_uploaded, total_bytes):
       percent = (bytes_uploaded / total_bytes) * 100
       print(f"Progress: {percent:.1f}%")

   result = client.upload_file(
       Path("largefile.zip"),
       progress_callback=progress_callback
   )

Multipart Upload
~~~~~~~~~~~~~~~~

For files larger than 30MB, multipart upload is used automatically:

.. code-block:: python

   # Automatically uses multipart for large files
   result = client.upload_file(Path("largefile.zip"))

   # Force multipart upload threshold
   result = client.upload_file(
       Path("myfile.txt"),
       use_multipart_threshold=10 * 1024 * 1024  # 10MB
   )

File Entry Operations
---------------------

List Files
~~~~~~~~~~

.. code-block:: python

   # List all files
   result = client.get_file_entries()
   for entry in result['data']:
       print(f"{entry['name']} - {entry['type']}")

   # List files in specific folder
   result = client.get_file_entries(parent_ids=[12345])

   # Search files
   result = client.get_file_entries(query="report")

   # Filter by type
   result = client.get_file_entries(entry_type="image")

   # Convenience method
   result = client.list_files(parent_id=12345, query="test")

Update File Entry
~~~~~~~~~~~~~~~~~

.. code-block:: python

   # Rename file
   result = client.update_file_entry(
       entry_id=12345,
       name="New Name.txt"
   )

   # Update description
   result = client.update_file_entry(
       entry_id=12345,
       description="Updated description"
   )

Delete Files
~~~~~~~~~~~~

.. code-block:: python

   # Move to trash
   result = client.delete_file_entries([12345, 67890])

   # Delete permanently
   result = client.delete_file_entries(
       [12345],
       delete_forever=True
   )

Move and Duplicate
~~~~~~~~~~~~~~~~~~

.. code-block:: python

   # Move files to folder
   result = client.move_file_entries(
       entry_ids=[12345, 67890],
       destination_id=99999
   )

   # Move to root
   result = client.move_file_entries(
       entry_ids=[12345],
       destination_id=None
   )

   # Duplicate files
   result = client.duplicate_file_entries(
       entry_ids=[12345],
       destination_id=99999
   )

Restore from Trash
~~~~~~~~~~~~~~~~~~

.. code-block:: python

   result = client.restore_file_entries([12345, 67890])

Folder Operations
-----------------

Create Folder
~~~~~~~~~~~~~

.. code-block:: python

   # Create in root
   result = client.create_folder("My Folder")
   folder_id = result['folder']['id']

   # Create in parent folder
   result = client.create_folder(
       name="Subfolder",
       parent_id=12345
   )

   # Convenience method
   result = client.create_directory("My Directory")

Download Operations
-------------------

Download File
~~~~~~~~~~~~~

.. code-block:: python

   from pathlib import Path

   # Download by hash
   saved_path = client.download_file("abc123hash")
   print(f"Downloaded to: {saved_path}")

   # Download to specific path
   saved_path = client.download_file(
       "abc123hash",
       output_path=Path("/path/to/save/file.txt")
   )

Sharing Operations
------------------

Share with Users
~~~~~~~~~~~~~~~~

.. code-block:: python

   # Share file with users
   result = client.share_entry(
       entry_id=12345,
       emails=["user1@example.com", "user2@example.com"],
       permissions=["view", "download"]
   )

   # Change permissions
   result = client.change_permissions(
       entry_id=12345,
       user_id=67890,
       permissions=["view", "edit", "download"]
   )

   # Unshare
   result = client.unshare_entry(
       entry_id=12345,
       user_id=67890
   )

Shareable Links
~~~~~~~~~~~~~~~

.. code-block:: python

   # Create shareable link
   result = client.create_shareable_link(entry_id=12345)
   link_hash = result['link']['hash']
   print(f"Share link: https://dri.me/{link_hash}")

   # With password
   result = client.create_shareable_link(
       entry_id=12345,
       password="secret123"
   )

   # With expiration
   result = client.create_shareable_link(
       entry_id=12345,
       expires_at="2025-12-31T23:59:59.000000Z"
   )

   # With permissions
   result = client.create_shareable_link(
       entry_id=12345,
       allow_edit=True,
       allow_download=True
   )

   # Get existing link
   result = client.get_shareable_link(entry_id=12345)

   # Update link
   result = client.update_shareable_link(
       entry_id=12345,
       password="newpassword"
   )

   # Delete link
   result = client.delete_shareable_link(entry_id=12345)

Starring Operations
-------------------

.. code-block:: python

   # Star files
   result = client.star_entries([12345, 67890])

   # Unstar files
   result = client.unstar_entries([12345, 67890])

   # List starred files
   result = client.get_file_entries(starred_only=True)

Workspace Operations
--------------------

.. code-block:: python

   # Get user workspaces
   result = client.get_workspaces()
   for workspace in result['workspaces']:
       print(f"{workspace['name']} (ID: {workspace['id']})")

   # Get logged user info
   user_info = client.get_logged_user()
   print(f"Logged in as: {user_info['user']['email']}")

Authentication
--------------

Login
~~~~~

.. code-block:: python

   # Login to get access token
   result = client.login(
       email="user@example.com",
       password="password123",
       device_name="my-app"
   )
   access_token = result['user']['access_token']

   # Use token for subsequent requests
   client = DrimeClient(api_key=access_token)

Register
~~~~~~~~

.. code-block:: python

   # Register new account
   result = client.register(
       email="newuser@example.com",
       password="password123",
       device_name="my-app"
   )
   access_token = result['user']['access_token']

Advanced Usage
--------------

Custom API URL
~~~~~~~~~~~~~~

.. code-block:: python

   client = DrimeClient(
       api_key="your_key",
       api_url="https://custom.api.url/v1"
   )

Session Management
~~~~~~~~~~~~~~~~~~

The client uses a ``requests.Session`` object internally, which reuses connections for better performance:

.. code-block:: python

   # The session is automatically managed
   client = DrimeClient(api_key="your_key")

   # Multiple requests reuse the same connection
   client.upload_file(Path("file1.txt"))
   client.upload_file(Path("file2.txt"))
   client.upload_file(Path("file3.txt"))

Type Hints
----------

The API includes comprehensive type hints:

.. code-block:: python

   from typing import Optional
   from pathlib import Path
   from pydrime import DrimeClient

   def upload_files(client: DrimeClient, files: list[Path]) -> list[dict]:
       results = []
       for file_path in files:
           result = client.upload_file(file_path)
           results.append(result)
       return results
