chewy-attachment 0.1.0__py3-none-any.whl

chewy_attachment/__init__.py

@@ -0,0 +1,3 @@
+"""ChewyAttachment - 通用图片/附件管理插件"""
+
+__version__ = "0.1.0"

chewy_attachment/core/__init__.py

@@ -0,0 +1,21 @@
+"""Core business logic layer - framework agnostic"""
+
+from .exceptions import (
+    FileNotFoundException,
+    PermissionDeniedException,
+    StorageException,
+    InvalidFileException,
+)
+from .storage import FileStorageEngine
+from .permissions import PermissionChecker
+from .schemas import FileMetadata
+
+__all__ = [
+    "FileNotFoundException",
+    "PermissionDeniedException",
+    "StorageException",
+    "InvalidFileException",
+    "FileStorageEngine",
+    "PermissionChecker",
+    "FileMetadata",
+]

chewy_attachment/core/exceptions.py

@@ -0,0 +1,38 @@
+"""Custom exceptions for ChewyAttachment"""
+
+
+class ChewyAttachmentException(Exception):
+    """Base exception for ChewyAttachment"""
+
+    pass
+
+
+class FileNotFoundException(ChewyAttachmentException):
+    """Raised when a file is not found"""
+
+    def __init__(self, file_id: str):
+        self.file_id = file_id
+        super().__init__(f"File not found: {file_id}")
+
+
+class PermissionDeniedException(ChewyAttachmentException):
+    """Raised when permission is denied"""
+
+    def __init__(self, action: str, file_id: str):
+        self.action = action
+        self.file_id = file_id
+        super().__init__(f"Permission denied: cannot {action} file {file_id}")
+
+
+class StorageException(ChewyAttachmentException):
+    """Raised when storage operation fails"""
+
+    def __init__(self, message: str):
+        super().__init__(f"Storage error: {message}")
+
+
+class InvalidFileException(ChewyAttachmentException):
+    """Raised when file is invalid"""
+
+    def __init__(self, message: str):
+        super().__init__(f"Invalid file: {message}")

chewy_attachment/core/permissions.py

@@ -0,0 +1,136 @@
+"""Permission checking logic for ChewyAttachment"""
+
+import importlib
+from typing import Optional, Type
+
+from .schemas import FileMetadata, UserContext
+
+
+class PermissionChecker:
+    """
+    Permission checker for file operations.
+
+    Rules:
+    - View/Download: is_public=True OR owner_id == current_user_id
+    - Delete: owner_id == current_user_id
+    """
+
+    @staticmethod
+    def can_view(file: FileMetadata, user: UserContext) -> bool:
+        """
+        Check if user can view file metadata.
+
+        Args:
+            file: File metadata
+            user: User context
+
+        Returns:
+            True if user can view the file
+        """
+        if file.is_public:
+            return True
+
+        if user.is_authenticated and user.user_id == file.owner_id:
+            return True
+
+        return False
+
+    @staticmethod
+    def can_download(file: FileMetadata, user: UserContext) -> bool:
+        """
+        Check if user can download file content.
+
+        Same rules as can_view.
+        """
+        return PermissionChecker.can_view(file, user)
+
+    @staticmethod
+    def can_delete(file: FileMetadata, user: UserContext) -> bool:
+        """
+        Check if user can delete file.
+
+        Only owner can delete.
+
+        Args:
+            file: File metadata
+            user: User context
+
+        Returns:
+            True if user can delete the file
+        """
+        if not user.is_authenticated:
+            return False
+
+        return user.user_id == file.owner_id
+
+    @staticmethod
+    def check_view_permission(
+        file: FileMetadata,
+        user: UserContext,
+    ) -> Optional[str]:
+        """
+        Check view permission and return error message if denied.
+
+        Returns:
+            None if allowed, error message if denied
+        """
+        if PermissionChecker.can_view(file, user):
+            return None
+        return "You do not have permission to view this file"
+
+    @staticmethod
+    def check_download_permission(
+        file: FileMetadata,
+        user: UserContext,
+    ) -> Optional[str]:
+        """
+        Check download permission and return error message if denied.
+
+        Returns:
+            None if allowed, error message if denied
+        """
+        if PermissionChecker.can_download(file, user):
+            return None
+        return "You do not have permission to download this file"
+
+    @staticmethod
+    def check_delete_permission(
+        file: FileMetadata,
+        user: UserContext,
+    ) -> Optional[str]:
+        """
+        Check delete permission and return error message if denied.
+
+        Returns:
+            None if allowed, error message if denied
+        """
+        if PermissionChecker.can_delete(file, user):
+            return None
+        return "Only the file owner can delete this file"
+
+
+def load_permission_class(import_path: str) -> Type:
+    """
+    Dynamically load a permission class from import path.
+
+    Args:
+        import_path: Full import path like "myapp.permissions.MyPermissionClass"
+
+    Returns:
+        The permission class
+
+    Raises:
+        ImportError: If module or class cannot be imported
+        AttributeError: If class not found in module
+
+    Example:
+        >>> perm_class = load_permission_class("myapp.permissions.CustomPermission")
+    """
+    try:
+        module_path, class_name = import_path.rsplit(".", 1)
+        module = importlib.import_module(module_path)
+        return getattr(module, class_name)
+    except (ValueError, ImportError, AttributeError) as e:
+        raise ImportError(
+            f"Could not import permission class '{import_path}': {e}"
+        ) from e

chewy_attachment/core/schemas.py

@@ -0,0 +1,61 @@
+"""Common data schemas for ChewyAttachment"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+
+@dataclass
+class FileMetadata:
+    """File metadata structure"""
+
+    id: str
+    original_name: str
+    storage_path: str
+    mime_type: str
+    size: int
+    owner_id: str
+    is_public: bool
+    created_at: datetime
+
+    def to_dict(self, include_storage_path: bool = False) -> dict:
+        """Convert to dictionary for API response"""
+        result = {
+            "id": self.id,
+            "original_name": self.original_name,
+            "mime_type": self.mime_type,
+            "size": self.size,
+            "owner_id": self.owner_id,
+            "is_public": self.is_public,
+            "created_at": self.created_at.isoformat(),
+        }
+        if include_storage_path:
+            result["storage_path"] = self.storage_path
+        return result
+
+
+@dataclass
+class FileUploadResult:
+    """Result of file upload operation"""
+
+    storage_path: str
+    size: int
+    mime_type: str
+
+
+@dataclass
+class UserContext:
+    """User context for permission checking"""
+
+    user_id: Optional[str] = None
+    is_authenticated: bool = False
+
+    @classmethod
+    def anonymous(cls) -> "UserContext":
+        """Create anonymous user context"""
+        return cls(user_id=None, is_authenticated=False)
+
+    @classmethod
+    def authenticated(cls, user_id: str) -> "UserContext":
+        """Create authenticated user context"""
+        return cls(user_id=user_id, is_authenticated=True)

chewy_attachment/core/storage.py

@@ -0,0 +1,158 @@
+"""File storage engine for ChewyAttachment"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from .exceptions import StorageException
+from .schemas import FileUploadResult
+from .utils import detect_mime_type, generate_uuid, get_file_extension, safe_filename
+
+
+class FileStorageEngine:
+    """
+    File storage engine that handles physical file operations.
+
+    Files are stored in a date-based directory structure:
+    <storage_root>/YYYY/MM/DD/<uuid>.<ext>
+    """
+
+    def __init__(self, storage_root: str | Path):
+        """
+        Initialize storage engine.
+
+        Args:
+            storage_root: Root directory for file storage
+        """
+        self.storage_root = Path(storage_root)
+        self._ensure_storage_root()
+
+    def _ensure_storage_root(self) -> None:
+        """Ensure storage root directory exists"""
+        try:
+            self.storage_root.mkdir(parents=True, exist_ok=True)
+        except Exception as e:
+            raise StorageException(f"Cannot create storage root: {e}")
+
+    def _generate_storage_path(self, original_name: str) -> str:
+        """
+        Generate storage path for a file.
+
+        Returns relative path from storage root: YYYY/MM/DD/<uuid>.<ext>
+        """
+        now = datetime.now()
+        date_path = f"{now.year:04d}/{now.month:02d}/{now.day:02d}"
+        file_id = generate_uuid()
+        ext = get_file_extension(safe_filename(original_name))
+        filename = f"{file_id}{ext}" if ext else file_id
+        return f"{date_path}/{filename}"
+
+    def _get_full_path(self, storage_path: str) -> Path:
+        """Get full filesystem path from relative storage path"""
+        full_path = (self.storage_root / storage_path).resolve()
+        if not str(full_path).startswith(str(self.storage_root.resolve())):
+            raise StorageException("Invalid storage path: directory traversal detected")
+        return full_path
+
+    def save_file(
+        self,
+        content: bytes,
+        original_name: str,
+        storage_path: Optional[str] = None,
+    ) -> FileUploadResult:
+        """
+        Save file content to storage.
+
+        Args:
+            content: File content as bytes
+            original_name: Original filename
+            storage_path: Optional custom storage path (relative)
+
+        Returns:
+            FileUploadResult with storage_path, size, and mime_type
+        """
+        if storage_path is None:
+            storage_path = self._generate_storage_path(original_name)
+
+        full_path = self._get_full_path(storage_path)
+
+        try:
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+            full_path.write_bytes(content)
+        except Exception as e:
+            raise StorageException(f"Failed to save file: {e}")
+
+        mime_type = detect_mime_type(content, original_name)
+        size = len(content)
+
+        return FileUploadResult(
+            storage_path=storage_path,
+            size=size,
+            mime_type=mime_type,
+        )
+
+    def get_file(self, storage_path: str) -> bytes:
+        """
+        Read file content from storage.
+
+        Args:
+            storage_path: Relative path to file
+
+        Returns:
+            File content as bytes
+        """
+        full_path = self._get_full_path(storage_path)
+
+        if not full_path.exists():
+            raise StorageException(f"File not found: {storage_path}")
+
+        try:
+            return full_path.read_bytes()
+        except Exception as e:
+            raise StorageException(f"Failed to read file: {e}")
+
+    def get_file_path(self, storage_path: str) -> Path:
+        """
+        Get full filesystem path for a file.
+
+        Args:
+            storage_path: Relative path to file
+
+        Returns:
+            Full Path object
+        """
+        full_path = self._get_full_path(storage_path)
+
+        if not full_path.exists():
+            raise StorageException(f"File not found: {storage_path}")
+
+        return full_path
+
+    def delete_file(self, storage_path: str) -> bool:
+        """
+        Delete file from storage.
+
+        Args:
+            storage_path: Relative path to file
+
+        Returns:
+            True if deleted, False if file didn't exist
+        """
+        full_path = self._get_full_path(storage_path)
+
+        if not full_path.exists():
+            return False
+
+        try:
+            full_path.unlink()
+            return True
+        except Exception as e:
+            raise StorageException(f"Failed to delete file: {e}")
+
+    def file_exists(self, storage_path: str) -> bool:
+        """Check if file exists in storage"""
+        try:
+            full_path = self._get_full_path(storage_path)
+            return full_path.exists()
+        except StorageException:
+            return False

chewy_attachment/core/utils.py

@@ -0,0 +1,56 @@
+"""Utility functions for ChewyAttachment"""
+
+import mimetypes
+import uuid
+from pathlib import Path
+from typing import Optional
+
+try:
+    import magic
+
+    HAS_MAGIC = True
+except ImportError:
+    HAS_MAGIC = False
+
+
+def generate_uuid() -> str:
+    """Generate a UUID string for file ID"""
+    return str(uuid.uuid4())
+
+
+def detect_mime_type(content: bytes, filename: Optional[str] = None) -> str:
+    """
+    Detect MIME type of file content.
+
+    Uses python-magic if available, falls back to mimetypes based on filename.
+    """
+    if HAS_MAGIC:
+        try:
+            mime = magic.Magic(mime=True)
+            return mime.from_buffer(content)
+        except Exception:
+            pass
+
+    if filename:
+        guessed_type, _ = mimetypes.guess_type(filename)
+        if guessed_type:
+            return guessed_type
+
+    return "application/octet-stream"
+
+
+def get_file_extension(filename: str) -> str:
+    """Extract file extension from filename"""
+    path = Path(filename)
+    return path.suffix.lower() if path.suffix else ""
+
+
+def safe_filename(filename: str) -> str:
+    """
+    Sanitize filename to prevent directory traversal and other issues.
+
+    Returns only the basename without any directory components.
+    """
+    name = Path(filename).name
+    name = name.replace("\x00", "")
+    return name if name else "unnamed"

chewy_attachment/django_app/__init__.py

@@ -0,0 +1,3 @@
+"""Django implementation of ChewyAttachment"""
+
+default_app_config = "chewy_attachment.django_app.apps.ChewyAttachmentConfig"

chewy_attachment/django_app/admin.py

@@ -0,0 +1,16 @@
+"""Django admin configuration for ChewyAttachment"""
+
+from django.contrib import admin
+
+from .models import Attachment
+
+
+@admin.register(Attachment)
+class AttachmentAdmin(admin.ModelAdmin):
+    """Admin configuration for Attachment model"""
+
+    list_display = ["id", "original_name", "mime_type", "size", "owner_id", "is_public", "created_at"]
+    list_filter = ["is_public", "mime_type", "created_at"]
+    search_fields = ["original_name", "owner_id"]
+    readonly_fields = ["id", "storage_path", "mime_type", "size", "created_at"]
+    ordering = ["-created_at"]

chewy_attachment/django_app/apps.py

@@ -0,0 +1,11 @@
+"""Django app configuration for ChewyAttachment"""
+
+from django.apps import AppConfig
+
+
+class ChewyAttachmentConfig(AppConfig):
+    """Django app configuration"""
+
+    name = "chewy_attachment.django_app"
+    verbose_name = "Chewy Attachment"
+    default_auto_field = "django.db.models.BigAutoField"

chewy_attachment/django_app/migrations/0001_initial.py

@@ -0,0 +1,33 @@
+# Generated by Django 6.0.1 on 2026-01-13 10:12
+
+import uuid
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Attachment',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('original_name', models.CharField(max_length=255)),
+                ('storage_path', models.CharField(max_length=500)),
+                ('mime_type', models.CharField(max_length=100)),
+                ('size', models.BigIntegerField()),
+                ('owner_id', models.CharField(db_index=True, max_length=100)),
+                ('is_public', models.BooleanField(db_index=True, default=False)),
+                ('created_at', models.DateTimeField(auto_now_add=True, db_index=True)),
+            ],
+            options={
+                'db_table': 'chewy_attachment_files',
+                'ordering': ['-created_at'],
+                'indexes': [models.Index(fields=['owner_id', 'created_at'], name='chewy_attac_owner_i_9ee24d_idx')],
+            },
+        ),
+    ]

chewy_attachment/django_app/models.py

@@ -0,0 +1,64 @@
+"""Django models for ChewyAttachment"""
+
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+from ..core.schemas import FileMetadata, UserContext
+
+
+def get_storage_root():
+    """Get storage root from Django settings"""
+    from pathlib import Path
+
+    chewy_settings = getattr(settings, "CHEWY_ATTACHMENT", {})
+    if "STORAGE_ROOT" in chewy_settings:
+        return chewy_settings["STORAGE_ROOT"]
+
+    base_dir = getattr(settings, "BASE_DIR", Path.cwd())
+    return Path(base_dir) / "media" / "attachments"
+
+
+class Attachment(models.Model):
+    """Attachment model for storing file metadata"""
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    original_name = models.CharField(max_length=255)
+    storage_path = models.CharField(max_length=500)
+    mime_type = models.CharField(max_length=100)
+    size = models.BigIntegerField()
+    owner_id = models.CharField(max_length=100, db_index=True)
+    is_public = models.BooleanField(default=False, db_index=True)
+    created_at = models.DateTimeField(auto_now_add=True, db_index=True)
+
+    class Meta:
+        db_table = "chewy_attachment_files"
+        ordering = ["-created_at"]
+        indexes = [
+            models.Index(fields=["owner_id", "created_at"]),
+        ]
+
+    def __str__(self):
+        return f"{self.original_name} ({self.id})"
+
+    def to_file_metadata(self) -> FileMetadata:
+        """Convert to FileMetadata for permission checking"""
+        return FileMetadata(
+            id=str(self.id),
+            original_name=self.original_name,
+            storage_path=self.storage_path,
+            mime_type=self.mime_type,
+            size=self.size,
+            owner_id=self.owner_id,
+            is_public=self.is_public,
+            created_at=self.created_at,
+        )
+
+    @staticmethod
+    def get_user_context(request) -> UserContext:
+        """Extract UserContext from Django request"""
+        if hasattr(request, "user") and request.user.is_authenticated:
+            user_id = str(request.user.id)
+            return UserContext.authenticated(user_id)
+        return UserContext.anonymous()

chewy_attachment/django_app/permissions.py

@@ -0,0 +1,36 @@
+"""DRF permission classes for ChewyAttachment"""
+
+from rest_framework import permissions
+
+from ..core.permissions import PermissionChecker
+from .models import Attachment
+
+
+class IsOwnerOrPublicReadOnly(permissions.BasePermission):
+    """
+    Permission class for attachment access.
+
+    - View/Download: public files OR owner
+    - Delete: owner only
+    """
+
+    def has_object_permission(self, request, view, obj: Attachment):
+        user_context = Attachment.get_user_context(request)
+        file_metadata = obj.to_file_metadata()
+
+        if request.method in permissions.SAFE_METHODS:
+            return PermissionChecker.can_view(file_metadata, user_context)
+
+        if request.method == "DELETE":
+            return PermissionChecker.can_delete(file_metadata, user_context)
+
+        return False
+
+
+class IsAuthenticatedForUpload(permissions.BasePermission):
+    """Permission class requiring authentication for upload"""
+
+    def has_permission(self, request, view):
+        if view.action == "create":
+            return request.user and request.user.is_authenticated
+        return True

chewy_attachment/django_app/serializers.py

@@ -0,0 +1,35 @@
+"""DRF serializers for ChewyAttachment"""
+
+from rest_framework import serializers
+
+from .models import Attachment
+
+
+class AttachmentSerializer(serializers.ModelSerializer):
+    """Serializer for Attachment model (read operations)"""
+
+    class Meta:
+        model = Attachment
+        fields = [
+            "id",
+            "original_name",
+            "mime_type",
+            "size",
+            "owner_id",
+            "is_public",
+            "created_at",
+        ]
+        read_only_fields = fields
+
+
+class AttachmentUploadSerializer(serializers.Serializer):
+    """Serializer for file upload"""
+
+    file = serializers.FileField(required=True)
+    is_public = serializers.BooleanField(default=False, required=False)
+
+    def validate_file(self, value):
+        """Validate uploaded file"""
+        if not value:
+            raise serializers.ValidationError("No file provided")
+        return value