syft-perm 0.3.0

Minimal utilities for managing SyftBox file permissions

SyftPerm

File permission management for SyftBox made simple.

SyftPerm provides intuitive Python APIs for managing SyftBox file permissions with powerful pattern matching, inheritance, and debugging capabilities.

📚 Complete Documentation

👆 Visit our comprehensive documentation website for tutorials, API reference, and examples.

Quick Links

• 🚀 5-Minute Quick Start - Get productive immediately
• 📖 Comprehensive Tutorials - Master advanced features
• 🔧 API Reference - Complete Python API docs
• ⚙️ Installation Guide - Setup instructions

Overview

SyftPerm transforms complex SyftBox permission management into simple, readable Python code. Set permissions on individual files or entire folder hierarchies with powerful glob patterns, debug permission issues with built-in tools, and manage permissions through a beautiful web interface.

Key Features

• 🎯 Intuitive Permission Hierarchy - Read → Create → Write → Admin levels that build naturally
• 🌟 Powerful Pattern Matching - Use *.py, docs/**/*.md to control hundreds of files with one rule
• 🔍 Nearest-Node Algorithm - Predictable inheritance that finds the "closest" permission rules
• 🐛 Built-in Debugging - Trace exactly why permissions work or don't work
• 📁 Folder-Level Efficiency - Set permissions once on directories, files inherit automatically
• 🎮 Interactive Web Editor - Google Drive-style permission management interface

Installation

# Basic installation
pip install syft-perm

# Full installation with web editor and rich display
pip install "syft-perm[server,display]"

Quick Example

import syft_perm

# Open a file or folder
file = syft_perm.open("my_data.txt")
project = syft_perm.open("my_project/")

# Grant permissions with the hierarchy (higher includes lower)
file.grant_read_access("[e-mail]")
file.grant_write_access("[e-mail]")  # Gets read + write
file.grant_admin_access("[e-mail]")       # Gets everything

# Use powerful patterns for multiple files
project.grant_write_access("*.py", "[e-mail]")
project.grant_read_access("docs/**/*.md", "*")  # Public docs

# Debug permissions easily
print(file.explain_permissions("[e-mail]"))
# Output: "[e-mail] has WRITE access: Explicitly granted write in ."

# Check access programmatically  
if file.has_write_access("[e-mail]"):
    print("Colleague can modify this file")

# Use the web editor for non-technical users
editor_url = syft_perm.get_editor_url("my_project/")
print(f"Manage permissions at: {editor_url}")

Permission Hierarchy

SyftPerm uses a 4-level hierarchy where higher permissions include all lower ones:

• Read - View file contents
• Create - Read + create new files
• Write - Read + Create + modify existing files
• Admin - Read + Create + Write + manage permissions

# Grant write access - user automatically gets read and create too
file.grant_write_access("[e-mail]")

print(file.has_read_access("[e-mail]"))    # True
print(file.has_create_access("[e-mail]"))  # True  
print(file.has_write_access("[e-mail]"))   # True
print(file.has_admin_access("[e-mail]"))   # False

Pattern Matching

Control multiple files with glob patterns:

project = syft_perm.open("research_project/")

# File extensions
project.grant_write_access("*.py", "[e-mail]")
project.grant_read_access("*.md", "*")  # Public documentation

# Recursive patterns with **
project.grant_read_access("data/**/*.csv", "[e-mail]")
project.grant_admin_access("src/**", "[e-mail]")

# Specific patterns
project.grant_write_access("tests/test_*.py", "[e-mail]")

Folder Inheritance

Set permissions on folders and files automatically inherit:

# Set permissions once on the folder
project = syft_perm.open("climate_research/")
project.grant_read_access("[e-mail]")
project.grant_write_access("[e-mail]")

# ALL files in the project now have these permissions
# Even files created later will inherit them automatically

Debugging

Never guess why permissions work or don't work:

file = syft_perm.open("project/src/analysis.py")

# Get human-readable explanation
explanation = file.explain_permissions("[e-mail]")
print(explanation)

# Get detailed reasoning for debugging
has_access, reasons = file._check_permission_with_reasons("[e-mail]", "write")
print(f"Has write access: {has_access}")
for reason in reasons:
    print(f"  - {reason}")

Web-Based Permission Editor

For non-technical team members, SyftPerm includes a beautiful web interface:

# Get editor URL for any file or folder
url = syft_perm.get_editor_url("my_project/")
print(f"Edit permissions at: {url}")

# Server starts automatically when needed
# Or start manually: syft_perm.start_permission_server()

Learn More

🚀 New to SyftPerm?

Start with our 5-Minute Quick Start to learn the essentials.

📚 Want to Master It?

Work through our Comprehensive Tutorial Series:

1. Fundamentals - Core concepts and hierarchy
2. Patterns & Matching - Glob patterns and specificity
3. Inheritance & Hierarchy - Multi-level permission flow
4. Terminal Nodes & Limits - Advanced control features
5. Mastery & Complex Scenarios - Expert techniques

🔧 Need API Details?

Browse our Complete API Reference with examples and parameters.

Real-World Use Cases

• 🔬 Research Collaboration - External reviewers, junior researchers, senior staff, PIs
• 💼 Enterprise Data Science - Different teams accessing different file types
• 📊 Data Publishing - Public datasets with controlled modification rights
• 🏗️ Software Projects - Developers, QA, documentation writers, managers

Requirements

• Python 3.9+
• Works on Windows, macOS, and Linux
• Optional: FastAPI for web editor (pip install "syft-perm[server]")
• Optional: Rich display formatting (pip install "syft-perm[display]")

Contributing

1. Check out our GitHub Issues
2. Read the Contributing Guide
3. Join the OpenMined Community

License

MIT License - see LICENSE file for details.

Related Projects

• SyftBox - The privacy-first data science platform
• OpenMined - Privacy-preserving AI community
• PySyft - Federated learning framework