API Reference

Opens a file or folder with SyftBox permissions. Returns a SyftFile or SyftFolder object that provides methods for managing permissions.

# Open a local file
file = syft_perm.open("data.csv")

# Open a folder
folder = syft_perm.open("my_project/")

# Open a remote file
remote_file = syft_perm.open("syft://alice@datasite.org/data.csv")

Grants read-only access to a user. The user can view the file contents but cannot modify or delete it.

# Grant read access to a specific user
file.grant_read_access("bob@company.com")

# Make file publicly readable
file.grant_read_access("*")

Grants create access to a user. Includes read permission plus the ability to create new files in folders. For files, this is equivalent to read access.

# Allow user to create files in a folder
folder.grant_create_access("alice@company.com")

Grants write access to a user. Includes read and create permissions plus the ability to modify existing files.

# Allow user to edit files
file.grant_write_access("team@company.com")

Grants admin access to a user. Includes all permissions plus the ability to manage permissions for other users.

# Grant full control to admin
file.grant_admin_access("admin@company.com")

Checks if a user has read access to the file or folder.

if file.has_read_access("bob@company.com"):
    print("Bob can read this file")

Checks if a user has create access. For folders, this means they can create new files.

Checks if a user has write access to modify the file.

Checks if a user has admin access to manage permissions.

Revokes read access from a user. This removes all permissions for the user.

Revokes create access from a user. The user retains read access if they had higher permissions.

Revokes write access from a user. The user retains read and create access if they had higher permissions.

Revokes admin access from a user. The user retains read, create, and write access.

Provides a detailed explanation of why a user has or doesn't have specific permissions, including inheritance chains and pattern matches.

explanation = file.explain_permissions("alice@example.com")
print(explanation)
# Output: alice@example.com has the following permissions:
# - read access from: /data/syft.pub.yaml (pattern: '*.csv')

Moves a file to a new location while preserving its permissions. Creates any necessary syft.pub.yaml files to maintain the same access controls.

# Move file and keep permissions
new_file = file.move_file_and_its_permissions("archive/data.csv")

Property that displays an interactive permission sharing widget in Jupyter notebooks. Shows current permissions and allows adding/removing users.

# Display sharing widget in Jupyter
file.share  # Note: property, not method call

Global instance providing access to file browsing functionality (files only). In Jupyter notebooks, displays an interactive file browser widget showing only files.

# Display interactive file browser (files only)
syft_perm.files

Global instance providing access to folder browsing functionality (folders only). In Jupyter notebooks, displays an interactive file browser widget showing only folders.

# Display interactive file browser (folders only)
syft_perm.folders

Global instance providing access to file and folder browsing functionality. In Jupyter notebooks, displays an interactive file browser widget showing both files and folders. This is the original behavior of the old .files API.

# Display interactive file browser (both files and folders)
syft_perm.files_and_folders

Returns all files (not folders) with permissions in your SyftBox datasites directory.

Returns a paginated list of files with permissions.

Search files by query string and/or filter by admin user and file type.

Slice notation for selecting files by index range.

# Get first 10 files
first_ten = syft_perm.files[0:10]

SyftPerm uses a hierarchical permission system where each level includes all permissions from lower levels:

Special user identifiers with specific meanings: