Metadata-Version: 2.4
Name: syft-perm
Version: 0.4.0
Summary: Minimal utilities for managing SyftBox file permissions
Author-email: OpenMined <info@openmined.org>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/OpenMined/syft-perm
Project-URL: Documentation, https://github.com/OpenMined/syft-perm#readme
Project-URL: Repository, https://github.com/OpenMined/syft-perm
Project-URL: Issues, https://github.com/OpenMined/syft-perm/issues
Keywords: syftbox,permissions,privacy,federated-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.104.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: watchdog>=6.0.0
Requires-Dist: websockets>=15.0.1
Requires-Dist: syft-core
Provides-Extra: syftbox
Requires-Dist: syft-core; extra == "syftbox"
Provides-Extra: display
Requires-Dist: tabulate>=0.9.0; extra == "display"
Provides-Extra: server
Requires-Dist: fastapi>=0.104.0; extra == "server"
Requires-Dist: uvicorn>=0.24.0; extra == "server"
Requires-Dist: loguru>=0.7.0; extra == "server"
Requires-Dist: watchdog>=3.0.0; extra == "server"
Requires-Dist: websockets>=12.0; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: nbformat>=5.9.0; extra == "dev"
Requires-Dist: nbconvert>=7.16.0; extra == "dev"
Requires-Dist: ipykernel>=6.29.0; extra == "dev"
Dynamic: license-file

[![CI](https://github.com/OpenMined/syft-perm/actions/workflows/test.yml/badge.svg)](https://github.com/OpenMined/syft-perm/actions/workflows/test.yml)
[![PyPI version](https://img.shields.io/pypi/v/syft-perm.svg)](https://pypi.org/project/syft-perm/)
[![PyPI downloads](https://img.shields.io/pypi/dm/syft-perm.svg)](https://pypi.org/project/syft-perm/)
[![Python versions](https://img.shields.io/pypi/pyversions/syft-perm.svg)](https://pypi.org/project/syft-perm/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![License](https://img.shields.io/github/license/OpenMined/syft-perm.svg)](https://github.com/OpenMined/syft-perm/blob/main/LICENSE)

# 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](https://openmined.github.io/syft-perm/)**

## Installation

```bash
pip install syft-perm
```

## Quick Start - Learn the Entire API in 2 Minutes

```python
import syft_perm as sp

# 1. Opening files and folders
file = sp.open("data.csv")                    # Open a file
folder = sp.open("my_project/")                # Open a folder
remote = sp.open("syft://alice@datasite.org/data.csv")  # Remote files

# 2. Granting permissions (each level includes all lower permissions)
file.grant_read_access("bob@company.com")      # Can view
file.grant_create_access("alice@company.com")  # Can view + create new files
file.grant_write_access("team@company.com")    # Can view + create + modify
file.grant_admin_access("admin@company.com")   # Full control

# 3. Revoking permissions
file.revoke_read_access("bob@company.com")     # Remove all access
file.revoke_create_access("alice@company.com") # Remove create (keeps read)
file.revoke_write_access("team@company.com")   # Remove write (keeps read/create)
file.revoke_admin_access("admin@company.com")  # Remove admin privileges

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

if file.has_create_access("alice@company.com"):
    print("Alice can create new files")

if file.has_write_access("team@company.com"):
    print("Team can modify this file")
    
if file.has_admin_access("admin@company.com"):
    print("Admin has full control")

# 5. Understanding permissions with explain
explanation = file.explain_permissions("bob@company.com")
print(explanation)  # Shows why bob has/doesn't have access

# 6. Working with the Files API
all_files = sp.files.all()                     # Get all permissioned files
paginated = sp.files.get(limit=10, offset=0)   # Get first 10 files
filtered = sp.files.search(admin="me@datasite.org")  # My admin files
sliced = sp.files[0:5]                          # First 5 files using slice

# 7. Moving files while preserving permissions
new_file = file.move_file_and_its_permissions("archive/data.csv")

# 8. Interactive features (Jupyter/web)
file.share                                      # Show sharing widget
```

### Permission Hierarchy Explained
- **Read**: View file contents
- **Create**: Read + create new files in folders
- **Write**: Read + Create + modify existing files  
- **Admin**: Read + Create + Write + manage permissions

## Permission Hierarchy

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

## Learn More

- **[5-Minute Quick Start](https://openmined.github.io/syft-perm/quickstart.html)** - Get productive immediately
- **[Comprehensive Tutorials](https://openmined.github.io/syft-perm/tutorials/)** - Master advanced features
- **[API Reference](https://openmined.github.io/syft-perm/api/)** - Complete Python API docs

## Requirements

- Python 3.9+
- Works on Windows, macOS, and Linux

## Contributing

1. Check out our [GitHub Issues](https://github.com/OpenMined/syft-perm/issues)
2. Read the [Contributing Guide](CONTRIBUTING.md)
3. Join the [OpenMined Community](https://openmined.org/)

## License

Apache 2.0 License - see [LICENSE](LICENSE) file for details.
