Skip to main content
syft-perm provides a simple, intuitive API for managing file and folder permissions in SyftBox. It’s built on top of syft-permissions and offers a Pythonic interface for common permission operations.

​
Installation

pip install syft-perm

​
When to Use

Use syft-perm when you need to:
  • Grant or revoke access to files and folders
  • Check who has access to your data
  • Share data with specific users or teams
  • Manage permissions in Jupyter notebooks or scripts
  • Browse and filter files by permission level

​
Quick Start

import syft_perm as sp

# Open files and folders
file = sp.open("data.csv")
folder = sp.open("my_project/")
remote = sp.open("syft://[email protected]/data.csv")

# Grant permissions
file.grant_read_access("[email protected]")
file.grant_write_access("[email protected]")
file.grant_admin_access("[email protected]")

# Revoke permissions
file.revoke_read_access("[email protected]")

# Check permissions
if file.has_read_access("[email protected]"):
    print("Bob can read this file")

# Explain permissions
explanation = file.explain_permissions("[email protected]")
print(explanation)

​
API Reference

​
Main Exports

from syft_perm import (
    open,                  # Open files or folders
    files,                 # Browse files
    folders,               # Browse folders
    files_and_folders,     # Browse both
    SyftFile,             # File object
    SyftFolder,           # Folder object
    FilesBrowser,         # File browser API
    PermissionExplanation, # Permission explanation
    SyftPermContext,      # Context manager
)

​
Working with Files

​
Opening Files

import syft_perm as sp

# Local files
file = sp.open("data.csv")
file = sp.open("/absolute/path/to/data.csv")

# Remote files
remote_file = sp.open("syft://[email protected]/data.csv")

​
Granting Access

Each permission level includes all lower levels: 
file = sp.open("data.csv")

# Read access - can view the file
file.grant_read_access("[email protected]")

# Create access - can view + create new files
file.grant_create_access("[email protected]")

# Write access - can view + create + modify
file.grant_write_access("[email protected]")

# Admin access - full control including permission management
file.grant_admin_access("[email protected]")

​
Revoking Access

# Remove all access
file.revoke_read_access("[email protected]")

# Remove create access (keeps read)
file.revoke_create_access("[email protected]")

# Remove write access (keeps read and create)
file.revoke_write_access("[email protected]")

# Remove admin privileges (keeps read, create, and write)
file.revoke_admin_access("[email protected]")

​
Checking Permissions

file = sp.open("data.csv")

# Check specific permission levels
if file.has_read_access("[email protected]"):
    print("Bob can read this file")

if file.has_create_access("[email protected]"):
    print("Alice can create new files")

if file.has_write_access("[email protected]"):
    print("Team can modify this file")

if file.has_admin_access("[email protected]"):
    print("Admin has full control")

​
Understanding Permissions

# Get detailed explanation of permissions
explanation = file.explain_permissions("[email protected]")
print(explanation)

# Example output:
# "[email protected] has READ access to data.csv
#  Granted by rule in /path/to/syftperm.yaml
#  Pattern: **/*.csv"

​
Working with Folders

import syft_perm as sp

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

# Grant permissions to folder (applies to all contents)
folder.grant_read_access("[email protected]")
folder.grant_write_access("[email protected]")

# Check folder permissions
if folder.has_write_access("[email protected]"):
    print("Owner can modify files in this folder")

​
Browsing Files

​
Get All Files

import syft_perm as sp

# Get all files and folders
all_items = sp.files_and_folders.all()

# Get only files
files_only = sp.files.all()

# Get only folders
folders_only = sp.folders.all()

​
Pagination

# Get first 10 files
paginated = sp.files.get(limit=10, offset=0)

# Get next 10 files
next_page = sp.files.get(limit=10, offset=10)

# Using slice notation
first_five = sp.files[0:5]

​
Filtering

# Find files where I'm the admin
my_admin_files = sp.files.search(admin="[email protected]")

# Find files with read access for a specific user
shared_files = sp.files.search(read="[email protected]")

# Find files with write access
writable_files = sp.files.search(write="[email protected]")

​
Moving Files

import syft_perm as sp

file = sp.open("data.csv")

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

print(f"File moved to {new_file}")

​
Permission Hierarchy

Permissions are hierarchical - higher levels include all lower permissions:
  1. READ: View file contents
  2. CREATE: READ + create new files in folders
  3. WRITE: READ + CREATE + modify existing files
  4. ADMIN: READ + CREATE + WRITE + manage permissions
# Granting write access automatically includes read and create
file.grant_write_access("[email protected]")

# These will all return True:
file.has_read_access("[email protected]")   # True
file.has_create_access("[email protected]") # True
file.has_write_access("[email protected]")  # True
file.has_admin_access("[email protected]")  # False (not granted)

​
Using with Context Manager

from syft_perm import SyftPermContext
from pathlib import Path

with SyftPermContext(root_path=Path("/path/to/datasite")) as ctx:
    file = ctx.open("data.csv")
    file.grant_read_access("[email protected]")

​
Common Patterns

​
Share a Dataset with a Team

import syft_perm as sp

team_members = [
    "[email protected]",
    "[email protected]",
    "[email protected]"
]

dataset = sp.open("datasets/customer_data.csv")

for member in team_members:
    dataset.grant_read_access(member)
    print(f"Granted access to {member}")

​
Audit File Permissions

import syft_perm as sp

# Find all files I've given admin access to
admin_files = sp.files.search(admin="[email protected]")

for file in admin_files:
    print(f"File: {file}")
    explanation = file.explain_permissions("[email protected]")
    print(explanation)
    print("---")

​
Temporary Access

import syft_perm as sp

file = sp.open("sensitive_data.csv")

# Grant temporary access
file.grant_read_access("[email protected]")

# ... contractor does their work ...

# Revoke access
file.revoke_read_access("[email protected]")

​
Dependencies

  • syft-permissions - Core ACL permission engine

Build docs developers (and LLMs) love

Get started for freeTalk to us