synapse-sdk 1.0.0a11__py3-none-any.whl → 2026.1.1b2__py3-none-any.whl

synapse_sdk/utils/storage/providers/gcs.py

@@ -0,0 +1,168 @@
+"""Google Cloud Storage provider."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from synapse_sdk.utils.storage.config import GCSStorageConfig
+from synapse_sdk.utils.storage.errors import (
+    StorageConnectionError,
+    StorageNotFoundError,
+    StorageUploadError,
+)
+from synapse_sdk.utils.storage.providers.base import _BaseStorageMixin
+
+if TYPE_CHECKING:
+    from upath import UPath
+
+
+class GCSStorage(_BaseStorageMixin):
+    """Storage provider for Google Cloud Storage.
+
+    Requires: universal-pathlib[gcs] (pip install universal-pathlib[gcs])
+
+    Args:
+        config: Configuration dict with GCS credentials.
+
+    Example:
+        >>> storage = GCSStorage({
+        ...     'bucket_name': 'my-bucket',
+        ...     'credentials': '/path/to/service-account.json',
+        ... })
+        >>> storage.upload(Path('/tmp/file.txt'), 'data/file.txt')
+        'gs://my-bucket/data/file.txt'
+    """
+
+    def __init__(self, config: dict[str, Any]):
+        try:
+            from upath import UPath
+        except ImportError as e:
+            raise ImportError(
+                'GCSStorage requires universal-pathlib[gcs]. Install with: pip install universal-pathlib[gcs]'
+            ) from e
+
+        validated = GCSStorageConfig.model_validate(config)
+
+        self._bucket_name = validated.bucket_name
+        upath_kwargs: dict[str, Any] = {'token': validated.credentials}
+        if validated.project:
+            upath_kwargs['project'] = validated.project
+
+        try:
+            self._upath = UPath(
+                f'gs://{validated.bucket_name}',
+                **upath_kwargs,
+            )
+        except Exception as e:
+            raise StorageConnectionError(
+                f'Failed to connect to GCS: {e}',
+                details={'bucket': validated.bucket_name},
+            ) from e
+
+    def upload(self, source: Path, target: str) -> str:
+        """Upload a file to GCS.
+
+        Args:
+            source: Local file path to upload.
+            target: Target path in GCS bucket.
+
+        Returns:
+            gs:// URL of uploaded file.
+        """
+        source_path = Path(source) if isinstance(source, str) else source
+
+        if not source_path.exists():
+            raise StorageNotFoundError(
+                f'Source file not found: {source_path}',
+                details={'source': str(source_path)},
+            )
+
+        target_path = self._normalize_path(target)
+
+        try:
+            with open(source_path, 'rb') as f:
+                (self._upath / target_path).write_bytes(f.read())
+        except Exception as e:
+            raise StorageUploadError(
+                f'Failed to upload to GCS: {e}',
+                details={'source': str(source_path), 'target': target_path},
+            ) from e
+
+        return self.get_url(target)
+
+    def exists(self, target: str) -> bool:
+        """Check if file exists in GCS.
+
+        Args:
+            target: Path to check.
+
+        Returns:
+            True if exists, False otherwise.
+        """
+        target_path = self._normalize_path(target)
+        return (self._upath / target_path).exists()
+
+    def get_url(self, target: str) -> str:
+        """Get gs:// URL for target.
+
+        Args:
+            target: Target path.
+
+        Returns:
+            gs:// URL string.
+        """
+        target_path = self._normalize_path(target)
+        if target_path:
+            return f'gs://{self._bucket_name}/{target_path}'
+        return f'gs://{self._bucket_name}'
+
+    def get_pathlib(self, path: str) -> UPath:
+        """Get UPath object for path.
+
+        Args:
+            path: Path relative to bucket root.
+
+        Returns:
+            UPath object.
+        """
+        normalized = self._normalize_path(path)
+        if not normalized:
+            return self._upath
+        return self._upath / normalized
+
+    def get_path_file_count(self, pathlib_obj: UPath) -> int:
+        """Count files in GCS path.
+
+        Args:
+            pathlib_obj: UPath object from get_pathlib().
+
+        Returns:
+            Number of files.
+        """
+        return self._count_files(pathlib_obj)
+
+    def get_path_total_size(self, pathlib_obj: UPath) -> int:
+        """Calculate total size of files in GCS path.
+
+        Args:
+            pathlib_obj: UPath object from get_pathlib().
+
+        Returns:
+            Total size in bytes.
+        """
+        return self._calculate_total_size(pathlib_obj)
+
+    def glob(self, pattern: str) -> list[UPath]:
+        """Glob pattern matching in GCS.
+
+        Args:
+            pattern: Glob pattern.
+
+        Returns:
+            List of matching UPath objects.
+        """
+        return list(self._upath.glob(pattern))
+
+
+__all__ = ['GCSStorage']

synapse_sdk/utils/storage/providers/http.py

@@ -0,0 +1,250 @@
+"""HTTP storage provider."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+from urllib.parse import urljoin
+
+import requests
+
+from synapse_sdk.utils.storage.config import HTTPStorageConfig
+from synapse_sdk.utils.storage.errors import (
+    StorageError,
+    StorageNotFoundError,
+    StorageUploadError,
+)
+
+
+class HTTPStorage:
+    """Storage provider for HTTP file servers.
+
+    Note: This provider has limited functionality as HTTP servers typically
+    don't support directory listing. File counting and size calculation
+    are not supported.
+
+    Args:
+        config: Configuration dict with HTTP server details.
+
+    Example:
+        >>> storage = HTTPStorage({
+        ...     'base_url': 'https://files.example.com/uploads/',
+        ...     'timeout': 60,
+        ... })
+        >>> storage.exists('data/file.txt')
+        True
+    """
+
+    def __init__(self, config: dict[str, Any]):
+        validated = HTTPStorageConfig.model_validate(config)
+
+        self._base_url = validated.base_url
+        self._timeout = validated.timeout
+        self._headers = validated.headers
+
+        # Setup session for connection pooling
+        self._session = requests.Session()
+        if self._headers:
+            self._session.headers.update(self._headers)
+
+    def _get_full_url(self, path: str) -> str:
+        """Get full URL for a path."""
+        if path.startswith('/'):
+            path = path[1:]
+        return urljoin(self._base_url, path)
+
+    def upload(self, source: Path, target: str) -> str:
+        """Upload a file to HTTP server.
+
+        Note: Requires server to support PUT or POST for file uploads.
+
+        Args:
+            source: Local file path to upload.
+            target: Target path on server.
+
+        Returns:
+            URL of uploaded file.
+        """
+        source_path = Path(source) if isinstance(source, str) else source
+
+        if not source_path.exists():
+            raise StorageNotFoundError(
+                f'Source file not found: {source_path}',
+                details={'source': str(source_path)},
+            )
+
+        url = self._get_full_url(target)
+
+        try:
+            with open(source_path, 'rb') as f:
+                files = {'file': (os.path.basename(str(source_path)), f)}
+
+                # Try PUT first, fallback to POST
+                response = self._session.put(url, files=files, timeout=self._timeout)
+
+                if response.status_code == 405:
+                    f.seek(0)
+                    response = self._session.post(url, files=files, timeout=self._timeout)
+
+                response.raise_for_status()
+        except requests.RequestException as e:
+            raise StorageUploadError(
+                f'Failed to upload to HTTP server: {e}',
+                details={'url': url},
+            ) from e
+
+        return url
+
+    def exists(self, target: str) -> bool:
+        """Check if file exists on HTTP server.
+
+        Uses HEAD request to check existence.
+
+        Args:
+            target: Path to check.
+
+        Returns:
+            True if file exists (HTTP 200), False otherwise.
+        """
+        url = self._get_full_url(target)
+
+        try:
+            response = self._session.head(url, timeout=self._timeout)
+            return response.status_code == 200
+        except requests.RequestException:
+            return False
+
+    def get_url(self, target: str) -> str:
+        """Get full URL for target.
+
+        Args:
+            target: Target path.
+
+        Returns:
+            Full HTTP URL.
+        """
+        return self._get_full_url(target)
+
+    def get_pathlib(self, path: str) -> HTTPPath:
+        """Get HTTPPath object for path.
+
+        Args:
+            path: Path on server.
+
+        Returns:
+            HTTPPath object (pathlib-like interface).
+        """
+        return HTTPPath(self, path)
+
+    def get_path_file_count(self, pathlib_obj: HTTPPath) -> int:
+        """Not supported for HTTP storage.
+
+        Raises:
+            StorageError: Always, as HTTP servers don't support directory listing.
+        """
+        raise StorageError(
+            'File counting not supported for HTTP storage',
+            details={'reason': 'HTTP servers do not provide directory listing'},
+        )
+
+    def get_path_total_size(self, pathlib_obj: HTTPPath) -> int:
+        """Not supported for HTTP storage.
+
+        Raises:
+            StorageError: Always, as HTTP servers don't support directory listing.
+        """
+        raise StorageError(
+            'Size calculation not supported for HTTP storage',
+            details={'reason': 'HTTP servers do not provide directory listing'},
+        )
+
+
+class HTTPPath:
+    """Pathlib-like interface for HTTP paths.
+
+    Provides a subset of pathlib.Path functionality for HTTP resources.
+    """
+
+    def __init__(self, storage: HTTPStorage, path: str):
+        self._storage = storage
+        self._path = path.strip('/')
+
+    def __str__(self) -> str:
+        return self._storage.get_url(self._path)
+
+    def __repr__(self) -> str:
+        return f"HTTPPath('{self}')"
+
+    def __truediv__(self, other: str) -> HTTPPath:
+        """Join paths using / operator."""
+        new_path = f'{self._path}/{other}' if self._path else str(other)
+        return HTTPPath(self._storage, new_path)
+
+    def joinuri(self, *parts: str) -> HTTPPath:
+        """Join path parts."""
+        all_parts = [self._path] + [str(p).strip('/') for p in parts]
+        new_path = '/'.join(p for p in all_parts if p)
+        return HTTPPath(self._storage, new_path)
+
+    @property
+    def name(self) -> str:
+        """Get the final component of the path."""
+        return os.path.basename(self._path)
+
+    @property
+    def parent(self) -> HTTPPath:
+        """Get the parent directory."""
+        parent_path = os.path.dirname(self._path)
+        return HTTPPath(self._storage, parent_path)
+
+    def exists(self) -> bool:
+        """Check if this path exists."""
+        return self._storage.exists(self._path)
+
+    def is_file(self) -> bool:
+        """Check if this path is a file (assumes exists = is_file for HTTP)."""
+        return self.exists()
+
+    def is_dir(self) -> bool:
+        """Check if this path is a directory.
+
+        Note: HTTP servers don't typically distinguish directories.
+        This always returns False.
+        """
+        return False
+
+    def read_bytes(self) -> bytes:
+        """Read file contents as bytes."""
+        url = self._storage.get_url(self._path)
+        response = self._storage._session.get(url, timeout=self._storage._timeout)
+        response.raise_for_status()
+        return response.content
+
+    def read_text(self, encoding: str = 'utf-8') -> str:
+        """Read file contents as text."""
+        return self.read_bytes().decode(encoding)
+
+    def stat(self) -> HTTPStat:
+        """Get file statistics.
+
+        Note: Only st_size is populated via Content-Length header.
+        """
+        url = self._storage.get_url(self._path)
+        response = self._storage._session.head(url, timeout=self._storage._timeout)
+        response.raise_for_status()
+
+        content_length = response.headers.get('Content-Length')
+        size = int(content_length) if content_length else 0
+
+        return HTTPStat(st_size=size)
+
+
+class HTTPStat:
+    """Minimal stat result for HTTP files."""
+
+    def __init__(self, st_size: int = 0):
+        self.st_size = st_size
+
+
+__all__ = ['HTTPStorage', 'HTTPPath']

synapse_sdk/utils/storage/providers/local.py

@@ -0,0 +1,126 @@
+"""Local filesystem storage provider."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from synapse_sdk.utils.storage.config import LocalStorageConfig
+from synapse_sdk.utils.storage.errors import StorageNotFoundError, StorageUploadError
+from synapse_sdk.utils.storage.providers.base import _BaseStorageMixin
+
+
+class LocalStorage(_BaseStorageMixin):
+    """Storage provider for local filesystem.
+
+    Args:
+        config: Configuration dict with 'location' key.
+
+    Example:
+        >>> storage = LocalStorage({'location': '/data'})
+        >>> storage.upload(Path('/tmp/file.txt'), 'uploads/file.txt')
+        'file:///data/uploads/file.txt'
+    """
+
+    def __init__(self, config: dict[str, Any]):
+        validated = LocalStorageConfig.model_validate(config)
+        self.base_path = Path(validated.location)
+
+    def upload(self, source: Path, target: str) -> str:
+        """Upload a file from source to target location.
+
+        Args:
+            source: Path to source file.
+            target: Target path relative to base path.
+
+        Returns:
+            file:// URL of uploaded file.
+
+        Raises:
+            StorageNotFoundError: If source file doesn't exist.
+            StorageUploadError: If copy operation fails.
+        """
+        source_path = Path(source) if isinstance(source, str) else source
+
+        if not source_path.exists():
+            raise StorageNotFoundError(
+                f'Source file not found: {source_path}',
+                details={'source': str(source_path)},
+            )
+
+        target_path = self.base_path / self._normalize_path(target)
+
+        try:
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(source_path, target_path)
+        except OSError as e:
+            raise StorageUploadError(
+                f'Failed to upload file: {e}',
+                details={'source': str(source_path), 'target': str(target_path)},
+            ) from e
+
+        return self.get_url(target)
+
+    def exists(self, target: str) -> bool:
+        """Check if target file exists.
+
+        Args:
+            target: Target path relative to base path.
+
+        Returns:
+            True if file exists, False otherwise.
+        """
+        target_path = self.base_path / self._normalize_path(target)
+        return target_path.exists()
+
+    def get_url(self, target: str) -> str:
+        """Get file:// URL for target file.
+
+        Args:
+            target: Target path relative to base path.
+
+        Returns:
+            file:// URL string.
+        """
+        target_path = self.base_path / self._normalize_path(target)
+        return f'file://{target_path.absolute()}'
+
+    def get_pathlib(self, path: str) -> Path:
+        """Get pathlib.Path object for the path.
+
+        Args:
+            path: Path relative to storage root.
+
+        Returns:
+            pathlib.Path object.
+        """
+        normalized = self._normalize_path(path)
+        if not normalized:
+            return self.base_path
+        return self.base_path / normalized
+
+    def get_path_file_count(self, pathlib_obj: Path) -> int:
+        """Get file count in the path.
+
+        Args:
+            pathlib_obj: Path object from get_pathlib().
+
+        Returns:
+            Number of files.
+        """
+        return self._count_files(pathlib_obj)
+
+    def get_path_total_size(self, pathlib_obj: Path) -> int:
+        """Get total size of files in the path.
+
+        Args:
+            pathlib_obj: Path object from get_pathlib().
+
+        Returns:
+            Total size in bytes.
+        """
+        return self._calculate_total_size(pathlib_obj)
+
+
+__all__ = ['LocalStorage']