File Browser#

Preface: Authentication#

Before using the Edge Filer API, you need to authenticate with your Edge device. Below are examples for synchronous and asynchronous usage.

Synchronous login#

Set cterasdk.settings.edge.syn.settings.connector.ssl = False to disable SSL verification.

from cterasdk.edge import Edge

username = "admin"
password = "secret"

with Edge('172.54.3.149') as edge:
    edge.login(username, password)
    # Now you can access files via edge.files

Asynchronous login#

Set cterasdk.settings.edge.asyn.settings.connector.ssl = False to disable SSL verification.

import asyncio
from cterasdk.asynchronous.edge import AsyncEdge

async def main():
   username = "admin"
   password = "secret"

   async with AsyncEdge('172.54.3.149') as edge:
      await edge.login(username, password)
      # Now you can access files via edge.files

asyncio.run(main())

Synchronous API#

Listing Files and Directories#

FileBrowser.listdir(path=None)

List directory contents.

Parameters:

path (str) – Path. Defaults to the root directory.

Returns:

Directory contents.

Return type:

list[cterasdk.cio.edge.types.EdgeResource]

Raises:

cterasdk.exceptions.io.core.GetMetadataError – If the directory was not found.
cterasdk.exceptions.io.core.NotADirectoryException – If the target path is not a directory.
cterasdk.exceptions.io.edge.ListDirectoryError – Raised on error to fetch directory contents.

# List contents of the root directory
for item in edge.files.listdir('/'):
    print(item.name, str(item), item.is_dir, item.size)

FileBrowser.walk(path=None)

Walk directory contents.

Parameters:

path (str, optional) – Path to walk. Defaults to the root directory.

Returns:

A generator of file-system objects.

Return type:

Iterator[cterasdk.cio.edge.types.EdgeResource]

Raises:

cterasdk.exceptions.io.core.GetMetadataError – If the directory was not found.
cterasdk.exceptions.io.core.NotADirectoryException – If the target path is not a directory.

# Walk through all files and directories recursively
for item in edge.files.walk('/'):
    print(item.name, str(item), item.is_dir, item.size)

Inspecting Files#

FileBrowser.properties(path)

Get object properties.

Parameters:: path (str) – Path.
Returns:: Object properties.
Return type:: cterasdk.cio.edge.types.EdgeResource
Raises:: cterasdk.exceptions.io.core.GetMetadataError – Raised on error to obtain object metadata.

# Get file or directory properties
resource = edge.files.properties('cloud/users/Service Account/My Files/Keystone Project.docx')
print(resource.name, str(resource), resource.is_dir, resource.size, resource.last_modified)

FileBrowser.exists(path)

Check whether an item exists.

Parameters:: path (str) – Path.
Returns:: True if the item exists, False otherwise.
Return type:: bool

# Check if a file exists
if edge.files.exists('cloud/users/Service Account/My Files/Keystone Project.docx'):
    print("File exists")

File Handles#

FileBrowser.handle(path)

Get a file handle.

Parameters:: path (str) – Path to a file.
Returns:: File handle.
Return type:: object
Raises:: cterasdk.exceptions.io.edge.OpenError – Raised on error to obtain a file handle.

# Get a handle to a single file
handle = edge.files.handle('cloud/users/Service Account/My Files/Keystone Project.docx')

FileBrowser.handle_many(directory, *objects)

Get a ZIP archive file handle.

Parameters:

directory (str) – Path to a folder.
objects (args) – Files and folders to include.

Returns:

File handle.

Return type:

object

# Get a handle to multiple files/folders as a ZIP
handle = edge.files.handle_many('cloud/users/Service Account/My Files', 'Keystone Project.docx', 'Keystone Model.docx')

Downloading Files#

FileBrowser.download(path, destination=None)

Download a file.

Parameters:

path (str) – The file path on the Edge Filer.
destination (str, optional) – File destination. If a directory is provided, the original filename is preserved. Defaults to the default download directory.

Returns:

Path to the local file.

Return type:

str

Raises:

cterasdk.exceptions.io.edge.OpenError – Raised on error to obtain a file handle.

# Download a single file to default location
local_path = edge.files.download('cloud/users/Service Account/My Files/Keystone Project.docx')

FileBrowser.download_many(target, objects, destination=None)

Download selected files and/or directories as a ZIP archive.

Warning

The provided list of objects is not validated. Only existing files and directories will be included in the resulting ZIP file.

Parameters:

target (str) – Path to the cloud folder containing the files and directories to download.
objects (list[str]) – List of file and/or directory names to include in the download.
destination (str) – Optional. Path to the destination file or directory. If a directory is provided, the original filename is preserved. Defaults to the default download directory.

Returns:

Path to the local file.

Return type:

str

# Download multiple files as a ZIP archive
zip_path = edge.files.download_many('network-share/docs', ['Keystone Project.docx', 'Keystone Model.docx'])

Creating Directories#

FileBrowser.mkdir(path)

Create a new directory.

Parameters:: path (str) – Directory path.
Returns:: Remote directory path.
Return type:: str
Raises:: cterasdk.exceptions.io.edge.CreateDirectoryError – Raised on error to create a directory.

# Create a single directory
edge.files.mkdir('cloud/users/Service Account/My Files/Documents')

FileBrowser.makedirs(path)

Create a directory recursively.

Parameters:: path (str) – Directory path.
Returns:: Remote directory path.
Return type:: str
Raises:: cterasdk.exceptions.io.edge.CreateDirectoryError – Raised on error to create a directory.

# Create directories recursively
edge.files.makedirs('cloud/users/Service Account/My Files/The/quick/brown/fox')

File Operations: Copy, Move, Rename, Delete#

FileBrowser.copy(path, destination=None, overwrite=False)

Copy a file or directory.

Parameters:

path (str) – Source file or directory path.
destination (str) – Destination directory path.
overwrite (bool, optional) – Overwrite on conflict. Defaults to False.

Raises:

cterasdk.exceptions.io.edge.CopyError – Raised on error to copy a file or directory.

# Copy a file to a directory
edge.files.copy('Keystone-Corporation/Project Keystone.docx', destination='Keystone-Coporation/Documents')

# Copy a file and rename the file at the destination
edge.files.copy('Keystone-Corporation/Project Keystone.docx', destination='Keystone-Coporation/Documents/Keystone 2026.docx')

# Copy a file to a directory and overwrite if it exists
edge.files.copy('Keystone-Corporation/Project Keystone.docx', destination='Keystone-Coporation/Documents', overwrite=True)

FileBrowser.move(path, destination=None, overwrite=False)

Move a file or directory.

Parameters:

path (str) – Source file or directory path.
destination (str) – Destination directory path.
overwrite (bool, optional) – Overwrite on conflict. Defaults to False.

Raises:

cterasdk.exceptions.io.edge.MoveError – Raised on error to move a file or directory.

# Move a file to a directory
edge.files.move('Keystone-Corporation/Project Keystone.docx', destination='Keystone-Coporation/Documents')

# Move a file and rename the file at the destination
edge.files.move('Keystone-Corporation/Project Keystone.docx', destination='Keystone-Coporation/Documents/Keystone 2026.docx')

# Move a file to a directory and overwrite if it exists
edge.files.move('Keystone-Corporation/Project Keystone.docx', destination='Keystone-Coporation/Documents', overwrite=True)

FileBrowser.rename(path, new_name, overwrite=False)

Rename a file or directory.

Parameters:

path (str) – Path of the file or directory to rename.
new_name (str) – New name for the file or directory.
overwrite (bool, optional) – Overwrite on conflict. Defaults to False.

Returns:

Remote object path.

Return type:

str

Raises:

cterasdk.exceptions.io.edge.RenameError – Raised on error to rename a file or directory.

# Rename a file or directory
edge.files.rename('Keystone-Corporation/Project Keystone.docx', 'Keystone 2026.docx')

FileBrowser.delete(path)

Delete a file or directory.

Parameters:: path (str) – File or directory path.
Returns:: Deleted object path.
Return type:: str
Raises:: cterasdk.exceptions.io.edge.DeleteError – Raised on error to delete a file or directory.

# Delete a file or directory
edge.files.delete('Keystone-Corporation/Project Keystone.docx')

Uploading Files#

FileBrowser.upload(destination, handle, name=None)

Upload from a file handle.

Parameters:

destination (str) – Remote path.
handle (object) – File-like handle.
name (str, optional) – Filename to use if it cannot be derived from destination

Returns:

Remote file path.

Return type:

str

Raises:

cterasdk.exceptions.io.edge.UploadError – Raised on upload failure.

# Upload from file handle
with open('Keystone Project.docx', 'rb') as f:
    remote_path = edge.files.upload('cloud/users/Service Account/My Files/Keystone Project.docx', f)

# Upload from string or bytes
remote_path = edge.files.upload('cloud/users/Service Account/My Files/Keystone Notes.txt', 'File contents here')

FileBrowser.upload_file(path, destination)

Upload a file.

Parameters:

path (str) – Local path.
destination (str) – Remote path.

Returns:

Remote file path.

Return type:

str

Raises:

cterasdk.exceptions.io.edge.UploadError – Raised on upload failure.

# Upload from a local path to a directory
remote_path = edge.files.upload_file('./Keystone Project.docx', 'cloud/users/Service Account/My Files')

# Upload from a local path and rename the file at the destination
remote_path = edge.files.upload_file('./Keystone Project.docx', 'cloud/users/Service Account/My Files/Keystone 2026.docx')

Asynchronous API#

async FileBrowser.listdir(path)

List directory contents.

Parameters:

path (str) – Path.

Returns:

Directory contents.

Return type:

AsyncIterator[cterasdk.cio.edge.types.EdgeResource]

Raises:

cterasdk.exceptions.io.core.GetMetadataError – If the directory was not found.
cterasdk.exceptions.io.core.NotADirectoryException – If the target path is not a directory.
cterasdk.exceptions.io.edge.ListDirectoryError – Raised on error to fetch directory contents.

async FileBrowser.walk(path=None)

Walk directory contents.

Parameters:

path (str, optional) – Path to walk. Defaults to the root directory.

Returns:

A generator of file-system objects.

Return type:

AsyncIterator[cterasdk.cio.edge.types.EdgeResource]

Raises:

cterasdk.exceptions.io.core.GetMetadataError – If the directory was not found.
cterasdk.exceptions.io.core.NotADirectoryException – If the target path is not a directory.

async FileBrowser.handle(path)

Get file handle.

Parameters:: path (str) – Path to a file.
Returns:: File handle.
Return type:: object
Raises:: cterasdk.exceptions.io.edge.OpenError – Raised on error to obtain a file handle.

async FileBrowser.handle_many(directory, *objects)

Get a ZIP archive file handle.

Parameters:

directory (str) – Path to a folder.
objects (args) – Files and folders to include.

Returns:

File handle.

Return type:

object

async FileBrowser.download(path, destination=None)

Download a file.

Parameters:

path (str) – The file path on the Edge Filer.
destination (str, optional) – File destination. If a directory is provided, the original filename is preserved. Defaults to the default download directory.

Returns:

Path to the local file.

Return type:

str

Raises:

cterasdk.exceptions.io.edge.OpenError – Raised on error to obtain a file handle.

async FileBrowser.download_many(target, objects, destination=None)

Download selected files and/or directories as a ZIP archive.

Warning

The provided list of objects is not validated. Only existing files and directories will be included in the resulting ZIP file.

Parameters:

target (str) – Path to the cloud folder containing the files and directories to download.
objects (list[str]) – List of file and/or directory names to include in the download.
destination (str) – Optional. Path to the destination file or directory. If a directory is provided, the original filename is preserved. Defaults to the default download directory.

Returns:

Path to the local file.

Return type:

str

async FileBrowser.upload(destination, handle, name=None)

Upload from a file handle.

Parameters:

destination (str) – Remote path.
handle (object) – File-like handle.
name (str, optional) – Filename to use if it cannot be derived from destination

Returns:

Remote file path.

Return type:

str

Raises:

cterasdk.exceptions.io.edge.UploadError – Raised on upload failure.

async FileBrowser.upload_file(path, destination)

Upload a file.

Parameters:

path (str) – Local path.
destination (str) – Remote path.

Returns:

Remote file path.

Return type:

str

Raises:

cterasdk.exceptions.io.edge.UploadError – Raised on upload failure.

async FileBrowser.mkdir(path)

Create a new directory.

Parameters:: path (str) – Directory path.
Returns:: Remote directory path.
Return type:: str
Raises:: cterasdk.exceptions.io.edge.CreateDirectoryError – Raised on error to create a directory.

async FileBrowser.makedirs(path)

Create a directory recursively.

Parameters:: path (str) – Directory path.
Returns:: Remote directory path.
Return type:: str
Raises:: cterasdk.exceptions.io.edge.CreateDirectoryError – Raised on error to create a directory.

async FileBrowser.copy(path, destination=None, overwrite=False)

Copy a file or directory.

Parameters:

path (str) – Source file or directory path.
destination (str) – Destination directory path.
overwrite (bool, optional) – Overwrite on conflict. Defaults to False.

Raises:

cterasdk.exceptions.io.edge.CopyError – Raised on error to copy a file or directory.

async FileBrowser.move(path, destination=None, overwrite=False)

Move a file or directory.

Parameters:

path (str) – Source file or directory path.
destination (str) – Destination directory path.
overwrite (bool, optional) – Overwrite on conflict. Defaults to False.

Raises:

cterasdk.exceptions.io.edge.MoveError – Raised on error to move a file or directory.

async FileBrowser.rename(path, name, overwrite=False)

Rename a file or directory.

Parameters:

path (str) – Path of the file or directory to rename.
name (str) – New name for the file or directory.
overwrite (bool, optional) – Overwrite on conflict. Defaults to False.

Returns:

Remote object path.

Return type:

str

Raises:

cterasdk.exceptions.io.edge.RenameError – Raised on error to rename a file or directory.

async FileBrowser.delete(path)

Delete a file or directory.

Parameters:: path (str) – File or directory path.
Raises:: cterasdk.exceptions.io.edge.DeleteError – Raised on error to delete a file or directory.

async FileBrowser.exists(path)

Check whether an item exists.

Parameters:: path (str) – Path.
Returns:: True if the item exists, False otherwise.
Return type:: bool

async FileBrowser.properties(path)

Get object properties.

Parameters:: path (str) – Path.
Returns:: Object properties.
Return type:: cterasdk.cio.edge.types.EdgeResource
Raises:: cterasdk.exceptions.io.core.GetMetadataError – Raised on error to obtain object metadata.

File Browser

Contents

File Browser#

Preface: Authentication#

Synchronous login#

Asynchronous login#

Synchronous API#

Listing Files and Directories#

Inspecting Files#

File Handles#

Downloading Files#

Creating Directories#

File Operations: Copy, Move, Rename, Delete#

Uploading Files#

Asynchronous API#