syft-perms 0.1.0__tar.gz

syft_perms-0.1.0/.gitignore

@@ -0,0 +1,178 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+credentials/
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+# macOS
+.DS_Store
+
+# Google Drive credentials
+credentials.json
+client_secret*.json
+token.pickle
+token.json
+
+# SyftBox related
+~/SyftBox/
+SyftBox/
+
+# Temporary files
+*.tmp
+*.bak
+*.swp
+*~
+
+# Claude AI settings
+.claude/*
+!.claude/settings.json
+CLAUDE.md
+
+# CI test outputs
+test_outputs/
+test_suite_output.log
+
+
+# Notebooks
+notebooks/e2e/sales_mock.csv
+notebooks/e2e/sales_private.csv
+notebooks/e2e/readme.md

syft_perms-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: syft-perms
+Version: 0.1.0
+Summary: User-facing permission API for Syft datasites
+Author-email: OpenMined <info@openmined.org>
+License: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: syft-permissions

syft_perms-0.1.0/README.md

@@ -0,0 +1,68 @@
+# syft-perms
+
+User-facing permission API for Syft datasites.
+
+## Dev Setup
+
+```bash
+uv pip install -e .
+```
+
+## Quick Start
+
+```python
+import syft_perms 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_items = sp.files_and_folders.all()         # Get all files and folders
+files_only = sp.files.all()                    # Get only files
+folders_only = sp.folders.all()                # Get only folders
+
+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")
+```
+
+### Permission Hierarchy
+
+- **Read**: View file contents
+- **Create**: Read + create new files in folders
+- **Write**: Read + Create + modify existing files
+- **Admin**: Read + Create + Write + manage permissions

syft_perms-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "syft-perms"
+version = "0.1.0"
+description = "User-facing permission API for Syft datasites"
+authors = [{ name = "OpenMined", email = "info@openmined.org" }]
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+
+dependencies = [
+    "syft-permissions",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/syft_perms"]

syft_perms-0.1.0/src/syft_perms/__init__.py

@@ -0,0 +1,18 @@
+from syft_perms.api import files, files_and_folders, folders, open
+from syft_perms.browser import FilesBrowser
+from syft_perms.explain import PermissionExplanation
+from syft_perms.file import SyftFile
+from syft_perms.folder import SyftFolder
+from syft_perms.syftperm_context import SyftPermContext
+
+__all__ = [
+    "SyftPermContext",
+    "SyftFile",
+    "SyftFolder",
+    "PermissionExplanation",
+    "FilesBrowser",
+    "open",
+    "files",
+    "folders",
+    "files_and_folders",
+]

syft_perms-0.1.0/src/syft_perms/api.py

@@ -0,0 +1,35 @@
+"""Top-level convenience functions that auto-detect the datasite."""
+
+from __future__ import annotations
+
+from syft_perms.browser import FilesBrowser
+from syft_perms.datasite_utils import _candidate_syftbox_folders, _find_datasite
+from syft_perms.file import SyftFile
+from syft_perms.folder import SyftFolder
+from syft_perms.syftperm_context import SyftPermContext
+
+
+def _default_context() -> SyftPermContext:
+    candidates = _candidate_syftbox_folders()
+    datasite = _find_datasite(candidates)
+    return SyftPermContext(datasite=datasite)
+
+
+def open(path: str) -> SyftFile | SyftFolder:
+    """Open a file or folder for permission management using auto-detected datasite."""
+    return _default_context().open(path)
+
+
+def files() -> FilesBrowser:
+    """Browse all files using auto-detected datasite."""
+    return _default_context().files
+
+
+def folders() -> FilesBrowser:
+    """Browse all folders using auto-detected datasite."""
+    return _default_context().folders
+
+
+def files_and_folders() -> FilesBrowser:
+    """Browse all files and folders using auto-detected datasite."""
+    return _default_context().files_and_folders

syft_perms-0.1.0/src/syft_perms/browser.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from syft_permissions import PERMISSION_FILE_NAME
+
+if TYPE_CHECKING:
+    from syft_perms.syftperm_context import SyftPermContext
+    from syft_perms.file import SyftFile
+    from syft_perms.folder import SyftFolder
+
+Kind = Literal["files", "folders", "all"]
+
+
+class FilesBrowser:
+    def __init__(self, perm_context: SyftPermContext, kind: Kind):
+        self._perm_context = perm_context
+        self._kind = kind
+
+    def all(self) -> list[SyftFile | SyftFolder]:
+        return self._files_and_folders()
+
+    def get(self, limit: int, offset: int = 0) -> list[SyftFile | SyftFolder]:
+        items = self._files_and_folders()
+        return items[offset : offset + limit]
+
+    def search(self, **kwargs: str) -> list[SyftFile | SyftFolder]:
+        """Search for files/folders by permission.
+
+        Keyword args: read, write, or admin with a user email as value.
+        Example: search(admin="user@example.com")
+        """
+        query_clauses = kwargs
+        items = self._files_and_folders()
+        return [
+            item
+            for item in items
+            if all(
+                _has_access(item, level, user) for level, user in query_clauses.items()
+            )
+        ]
+
+    def __getitem__(self, key: slice) -> list[SyftFile | SyftFolder]:
+        items = self._files_and_folders()
+        return items[key]
+
+    def _files_and_folders(self) -> list[SyftFile | SyftFolder]:
+        from syft_perms.file import SyftFile
+        from syft_perms.folder import SyftFolder
+
+        root = self._perm_context.datasite
+        items: list[SyftFile | SyftFolder] = []
+
+        for p in sorted(root.rglob("*")):
+            if p.name == PERMISSION_FILE_NAME:
+                continue
+            if p.is_dir() and self._kind in ("folders", "all"):
+                items.append(SyftFolder(p, self._perm_context))
+            elif p.is_file() and self._kind in ("files", "all"):
+                items.append(SyftFile(p, self._perm_context))
+
+        return items
+
+
+def _has_access(item: SyftFile | SyftFolder, level: str, user: str) -> bool:
+    if level == "read":
+        return item.has_read_access(user)
+    elif level == "write":
+        return item.has_write_access(user)
+    elif level == "admin":
+        return item.has_admin_access(user)
+    else:
+        raise ValueError(f"Unknown access level: {level}")

syft_perms-0.1.0/src/syft_perms/datasite_utils.py

@@ -0,0 +1,58 @@
+"""Auto-detect the SyftBox datasite folder."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+_SYFTBOX_FOLDER_ENV = "SYFTBOX_FOLDER"
+
+
+def _is_colab() -> bool:
+    try:
+        import google.colab  # noqa: F401
+
+        return True
+    except Exception:
+        return False
+
+
+def _candidate_syftbox_folders() -> list[Path]:
+    """Return candidate SyftBox root folders in priority order."""
+    env = os.environ.get(_SYFTBOX_FOLDER_ENV)
+    if env:
+        return [Path(env)]
+
+    candidates: list[Path] = []
+    if _is_colab():
+        candidates.append(Path("/content"))
+    candidates.append(Path.home() / "SyftBox")
+    return candidates
+
+
+def _find_datasite(candidates: list[Path]) -> Path:
+    """Find a single datasite directory inside the first existing candidate."""
+    for folder in candidates:
+        if not folder.is_dir():
+            continue
+        datasites = [d for d in folder.iterdir() if d.is_dir() and "@" in d.name]
+        if len(datasites) == 1:
+            return datasites[0]
+        if len(datasites) > 1:
+            names = ", ".join(d.name for d in datasites)
+            raise ValueError(
+                f"Multiple datasites found in {folder}: {names}. "
+                "Create a SyftPermContext explicitly:\n"
+                "  ctx = SyftPermContext(datasite='/path/to/datasite')\n"
+                "  ctx.open('file.txt')"
+            )
+    raise ValueError(
+        "Could not auto-detect a SyftBox datasite folder. "
+        "Either:\n"
+        "  1. Set the environment variable: "
+        f"export {_SYFTBOX_FOLDER_ENV}=/path/to/syftbox\n"
+        "  2. Create a SyftPermContext explicitly:\n"
+        "     ctx = SyftPermContext(datasite='/path/to/datasite')\n"
+        "     ctx.open('file.txt')"
+    )

syft_perms-0.1.0/src/syft_perms/explain.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from syft_permissions import PERMISSION_FILE_NAME, ACLRequest, AccessLevel, User
+from syft_permissions.engine.compiled_rule import ACLRule
+
+if TYPE_CHECKING:
+    from syft_perms.syftperm_context import SyftPermContext
+
+
+@dataclass
+class PermissionExplanation:
+    path: str
+    user: str
+    is_owner: bool
+    governing_yaml: str | None
+    matched_rule: str | None
+    read: bool
+    write: bool
+    admin: bool
+    reasons: dict[str, str] = field(default_factory=dict)
+
+    def __repr__(self) -> str:
+        return self.__str__()
+
+    def __str__(self) -> str:
+        lines = [
+            f"Permissions for '{self.path}' (user: {self.user})",
+            f"  Owner: {self.is_owner}",
+            f"  Read:  {self.read} — {self.reasons.get('read', '')}",
+            f"  Write: {self.write} — {self.reasons.get('write', '')}",
+            f"  Admin: {self.admin} — {self.reasons.get('admin', '')}",
+        ]
+        if self.governing_yaml:
+            lines.append(f"  Governing file: {self.governing_yaml}")
+        if self.matched_rule:
+            lines.append(f"  Matched rule: {self.matched_rule}")
+        return "\n".join(lines)
+
+
+def explain(perm: SyftPermContext, rel_path: str, user: str) -> PermissionExplanation:
+    """Build a PermissionExplanation for a given path and user."""
+    if user == perm.service.owner:
+        return _explain_owner(rel_path, user)
+
+    node = perm.service.tree.get_nearest_node(rel_path)
+    if node is None or node.ruleset is None:
+        return _explain_denied(rel_path, user, "No permission file found")
+
+    # NOTE: we are using AccessLevel.READ here because it cannot be empty but its not used
+    compiled_rule = perm.service.tree.get_compiled_rule(
+        ACLRequest(path=rel_path, user=User(id=user), level=AccessLevel.READ)
+    )
+    governing_yaml = str(Path(node.path) / PERMISSION_FILE_NAME)
+    if compiled_rule is not None:
+        return _explain_matched(
+            rel_path, user, governing_yaml, compiled_rule.pattern, compiled_rule
+        )
+
+    return _explain_denied(
+        rel_path, user, "No matching rule in permission file", governing_yaml
+    )
+
+
+def _explain_owner(rel_path: str, user: str) -> PermissionExplanation:
+    reason = "Owner of datasite"
+    return PermissionExplanation(
+        path=rel_path,
+        user=user,
+        is_owner=True,
+        governing_yaml=None,
+        matched_rule=None,
+        read=True,
+        write=True,
+        admin=True,
+        reasons={"read": reason, "write": reason, "admin": reason},
+    )
+
+
+def _explain_denied(
+    rel_path: str,
+    user: str,
+    reason: str,
+    governing_yaml: str | None = None,
+) -> PermissionExplanation:
+    return PermissionExplanation(
+        path=rel_path,
+        user=user,
+        is_owner=False,
+        governing_yaml=governing_yaml,
+        matched_rule=None,
+        read=False,
+        write=False,
+        admin=False,
+        reasons={"read": reason, "write": reason, "admin": reason},
+    )
+
+
+def _explain_matched(
+    rel_path: str,
+    user: str,
+    governing_yaml: str,
+    pattern: str,
+    compiled: ACLRule,
+) -> PermissionExplanation:
+    read = compiled.has_read(user)
+    write = compiled.has_write(user)
+    admin = compiled.has_admin(user)
+    reasons = _build_reasons(pattern, read=read, write=write, admin=admin)
+    return PermissionExplanation(
+        path=rel_path,
+        user=user,
+        is_owner=False,
+        governing_yaml=governing_yaml,
+        matched_rule=pattern,
+        read=read,
+        write=write,
+        admin=admin,
+        reasons=reasons,
+    )
+
+
+def _build_reasons(pattern: str, **levels: bool) -> dict[str, str]:
+    reasons = {}
+    for level_name, has_it in levels.items():
+        if has_it:
+            reasons[level_name] = f"Granted via '{pattern}' in {level_name} list"
+        else:
+            reasons[level_name] = f"Not in {level_name} list for '{pattern}'"
+    return reasons

syft_perms-0.1.0/src/syft_perms/file.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from syft_permissions import (
+    ACLRequest,
+    AccessLevel,
+    User,
+)
+
+from syft_perms.explain import PermissionExplanation, explain
+
+if TYPE_CHECKING:
+    from syft_perms.syftperm_context import SyftPermContext
+
+
+class SyftFile:
+    def __init__(self, abs_path: Path, perm_context: SyftPermContext):
+        self.abs_path = abs_path
+        self._perm_context = perm_context
+
+    @property
+    def _rel_path(self) -> str:
+        return str(self.abs_path.relative_to(self._perm_context.datasite))
+
+    def grant_read_access(self, user: str) -> None:
+        self._perm_context.modifier.add_permission_for_user(
+            self._rel_path, "read", user
+        )
+
+    def grant_write_access(self, user: str) -> None:
+        self._perm_context.modifier.add_permission_for_user(
+            self._rel_path, "write", user
+        )
+
+    def grant_admin_access(self, user: str) -> None:
+        self._perm_context.modifier.add_permission_for_user(
+            self._rel_path, "admin", user
+        )
+
+    def revoke_read_access(self, user: str) -> None:
+        self._perm_context.modifier.remove_permission_for_user(
+            self._rel_path, "read", user
+        )
+
+    def revoke_write_access(self, user: str) -> None:
+        self._perm_context.modifier.remove_permission_for_user(
+            self._rel_path, "write", user
+        )
+
+    def revoke_admin_access(self, user: str) -> None:
+        self._perm_context.modifier.remove_permission_for_user(
+            self._rel_path, "admin", user
+        )
+
+    def has_read_access(self, user: str) -> bool:
+        return self._check(AccessLevel.READ, user)
+
+    def has_write_access(self, user: str) -> bool:
+        return self._check(AccessLevel.WRITE, user)
+
+    def has_admin_access(self, user: str) -> bool:
+        return self._check(AccessLevel.ADMIN, user)
+
+    def explain_permissions(self, user: str) -> PermissionExplanation:
+        return explain(self._perm_context, self._rel_path, user)
+
+    def move_file_and_its_permissions(self, new_path: str) -> SyftFile:
+        new_abs = self._perm_context.datasite / new_path
+        new_abs.parent.mkdir(parents=True, exist_ok=True)
+
+        if self.abs_path.exists():
+            shutil.move(str(self.abs_path), str(new_abs))
+
+        self._perm_context.modifier.copy_permissions(self._rel_path, new_abs)
+        self._perm_context.modifier.remove_all_rules(self._rel_path)
+        self._perm_context._reload()
+
+        return SyftFile(new_abs, self._perm_context)
+
+    def _check(self, level: AccessLevel, user: str) -> bool:
+        request = ACLRequest(
+            path=self._rel_path,
+            level=level,
+            user=User(id=user),
+        )
+        return self._perm_context.service.can_access(request)
+
+    def __repr__(self) -> str:
+        return f"SyftFile({self._rel_path})"