AGBCLOUD

Appearance

File System API Reference ​

Overview ​

The File System module provides comprehensive file and directory operations within the AGB cloud environment. It supports file upload, download, and manipulation.

FileChangeEvent ​

python
class FileChangeEvent()

Represents a single file change event.

FileInfoResult ​

python
class FileInfoResult(ApiResponse)

Result of file info operations.

DirectoryListResult ​

python
class DirectoryListResult(ApiResponse)

Result of directory listing operations.

FileContentResult ​

python
class FileContentResult(ApiResponse)

Result of file read operations.

MultipleFileContentResult ​

python
class MultipleFileContentResult(ApiResponse)

Result of multiple file read operations.

FileSearchResult ​

python
class FileSearchResult(ApiResponse)

Result of file search operations.

FileChangeResult ​

python
class FileChangeResult(ApiResponse)

Result of file change detection operations.

has_changes ​

python
def has_changes() -> bool

Check if there are any file changes.

get_modified_files ​

python
def get_modified_files() -> List[str]

Get list of modified file paths.

get_created_files ​

python
def get_created_files() -> List[str]

Get list of created file paths.

get_deleted_files ​

python
def get_deleted_files() -> List[str]

Get list of deleted file paths.

FileSystem ​

python
class FileSystem(BaseService)

FileSystem provides file system operations for the session.

transfer_path ​

python
def transfer_path() -> Optional[str]

Get the path for file transfer operations.

This method ensures the context ID is loaded and returns the associated context path that was retrieved from GetAndLoadInternalContext API.

Returns:

Optional[str]: The transfer path if available, None otherwise.

upload ​

python
def upload(
        local_path: str,
        remote_path: str,
        *,
        content_type: Optional[str] = None,
        wait: bool = True,
        wait_timeout: float = 30.0,
        poll_interval: float = 1.5,
        progress_cb: Optional[Callable[[int], None]] = None) -> UploadResult

Upload a file from local to remote path using pre-signed URLs.

Arguments:

local_path: Local file path to upload
remote_path: Remote file path to upload to
content_type: Optional content type for the file
wait: Whether to wait for the sync operation to complete
wait_timeout: Timeout for waiting for sync completion
poll_interval: Interval between polling for sync completion
progress_cb: Callback for upload progress updates

Returns:

UploadResult: Result of the upload operation

Example:

python
remote_path = session.file.transfer_path() + "/file.txt"
upload_result = session.file.upload("/local/file.txt", remote_path)

download ​

python
def download(
        remote_path: str,
        local_path: str,
        *,
        overwrite: bool = True,
        wait: bool = True,
        wait_timeout: float = 30.0,
        poll_interval: float = 1.5,
        progress_cb: Optional[Callable[[int], None]] = None) -> DownloadResult

Download a file from remote path to local path using pre-signed URLs.

Arguments:

remote_path: Remote file path to download from
local_path: Local file path to download to
overwrite: Whether to overwrite existing local file
wait: Whether to wait for the sync operation to complete
wait_timeout: Timeout for waiting for sync completion
poll_interval: Interval between polling for sync completion
progress_cb: Callback for download progress updates

Returns:

DownloadResult: Result of the download operation

Example:

python
remote_path = session.file.transfer_path() + "/file.txt"
download_result = session.file.download(remote_path, "/local/file.txt")

DEFAULT_CHUNK_SIZE ​

python
DEFAULT_CHUNK_SIZE = 50 * 1024

mkdir ​

python
def mkdir(path: str) -> BoolResult

Create a new directory at the specified path.

Arguments:

  • path str - The path of the directory to create.

Returns:

BoolResult: Result object containing success status and error message if

any.

edit ​

python
def edit(path: str,
         edits: List[Dict[str, str]],
         dry_run: bool = False) -> BoolResult

Edit a file by replacing occurrences of oldText with newText.

Arguments:

  • path str - The path of the file to edit.
  • edits List[Dict[str, str]] - A list of dictionaries specifying oldText and newText.
  • dry_run bool - If True, preview changes without applying them. Defaults to False.

Returns:

BoolResult: Result object containing success status and error message if

any.

info ​

python
def info(path: str) -> FileInfoResult

Get information about a file or directory.

Arguments:

  • path str - The path of the file or directory to inspect.

Returns:

FileInfoResult: Result object containing file info and error message if any.

list ​

python
def list(path: str) -> DirectoryListResult

List the contents of a directory.

Arguments:

  • path str - The path of the directory to list.

Returns:

DirectoryListResult: Result object containing directory entries and error

message if any.

move ​

python
def move(source: str, destination: str) -> BoolResult

Move a file or directory from source path to destination path.

Arguments:

  • source str - The source path of the file or directory.
  • destination str - The destination path.

Returns:

BoolResult: Result object containing success status and error message if

any.

remove ​

python
def remove(path: str) -> BoolResult

Delete a file at the specified path.

Arguments:

  • path str - The path of the file to delete.

Returns:

BoolResult: Result object containing success status and error message if any.

Example:

python
session = (agb.create()).session
session.file.write("/tmp/to_delete.txt", "hello")
delete_result = session.file.remove("/tmp/to_delete.txt")
session.delete()

read ​

python
@overload
def read(path: str) -> FileContentResult

read ​

python
@overload
def read(path: str, *, format: Literal["text"]) -> FileContentResult

read ​

python
@overload
def read(path: str, *, format: Literal["bytes"]) -> BinaryFileContentResult

read ​

python
def read(
        path: str,
        *,
        format: str = "text"
) -> Union[FileContentResult, BinaryFileContentResult]

Read the contents of a file. Automatically handles large files by chunking.

Arguments:

  • path str - The path of the file to read.
  • format str - Format to read the file in. "text" (default) or "bytes".
    • "text": Returns FileContentResult with content as string (UTF-8)
    • "bytes": Returns BinaryFileContentResult with content as bytes

Returns:

FileContentResult: For text format, contains file content as string.
BinaryFileContentResult: For bytes format, contains file content as bytes.

Raises:

FileError: If the file does not exist or is a directory.

Example:

python
session = (agb.create()).session

# Read text file (default)
text_result = session.file.read("/tmp/test.txt")
print(text_result.content)  # str

# Read binary file
binary_result = session.file.read("/tmp/image.png", format="bytes")
print(binary_result.content)  # bytes

session.delete()

Notes:

  • Automatically handles large files by reading in chunks (default 50KB per chunk)
  • Returns empty string/bytes for empty files
  • Returns error if path is a directory
  • Binary files are returned as bytes (backend uses base64 encoding internally)

See Also:

FileSystem.write, FileSystem.list, FileSystem.info

write ​

python
def write(path: str, content: str, mode: str = "overwrite") -> BoolResult

Write content to a file. Automatically handles large files by chunking.

Arguments:

  • path str - The path of the file to write.
  • content str - The content to write to the file.
  • mode str - The write mode ("overwrite" or "append"). Defaults to "overwrite".

Returns:

BoolResult: Result object containing success status and error message if

any.

read_batch ​

python
def read_batch(paths: List[str]) -> MultipleFileContentResult

Read the contents of multiple files at once.

Arguments:

  • paths List[str] - A list of file paths to read.

Returns:

MultipleFileContentResult: Result object containing a dictionary mapping

file paths to contents, and error message if any.

python
def search(path: str,
           pattern: str,
           exclude_patterns: Optional[List[str]] = None) -> FileSearchResult

Search for files in the specified path using a pattern.

Arguments:

  • path str - The base directory path to search in.
  • pattern str - The glob pattern to search for.
  • exclude_patterns Optional[List[str]] - Optional list of patterns to exclude from the search. Defaults to None.

Returns:

FileSearchResult: Result object containing matching file paths and error

message if any.

watch_dir ​

python
def watch_dir(
        path: str,
        callback: Callable[[List[FileChangeEvent]], None],
        interval: float = 1.0,
        stop_event: Optional[threading.Event] = None) -> threading.Thread

Watch a directory for file changes and call the callback function when changes occur.

Arguments:

  • path str - The directory path to monitor for file changes.
  • callback Callable[[List[FileChangeEvent]], None] - Callback function that will be called with a list of FileChangeEvent objects when changes are detected.
  • interval float - Polling interval in seconds. Defaults to 1.0.
  • stop_event Optional[threading.Event] - Optional threading.Event to stop the monitoring. If not provided, a new Event will be created and returned via the thread object. Defaults to None.

Returns:

threading.Thread: The monitoring thread. Call thread.start() to begin monitoring.

Use the thread's stop_event attribute to stop monitoring.

Best Practices ​

  1. Always check file permissions before operations
  2. Use appropriate file paths and handle path separators correctly
  3. Clean up temporary files after operations
  4. Handle file operation errors gracefully
  5. Use streaming for large file operations

Documentation generated automatically from source code using pydoc-markdown.