sqlalchemy-file 0.5.0__tar.gz → 0.7.0__tar.gz

{sqlalchemy_file-0.5.0 → sqlalchemy_file-0.7.0}/.gitignore

@@ -1,6 +1,9 @@
 *.pyc
 env*
 .mypy_cache
+.ty
+.zensical
+.ruff_cache
 .vscode
 .idea
 poetry.lock

{sqlalchemy_file-0.5.0 → sqlalchemy_file-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.5
 Name: sqlalchemy-file
-Version: 0.5.0
+Version: 0.7.0
 Summary: SQLAlchemy-file is a SQLAlchemy extension for attaching files to SQLAlchemy model and uploading them to various storage.
 Project-URL: Homepage, https://jowilf.github.io/sqlalchemy-file
 Project-URL: Documentation, https://jowilf.github.io/sqlalchemy-file
@@ -17,37 +17,24 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Database
 Classifier: Topic :: Database :: Database Engines/Servers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.7
-Requires-Dist: apache-libcloud<3.8,>=3.6
-Requires-Dist: sqlalchemy<2.1,>=1.4
-Provides-Extra: dev
-Requires-Dist: pre-commit<4.0.0,>=2.20.0; extra == 'dev'
-Requires-Dist: uvicorn<0.22.0,>=0.20.0; extra == 'dev'
-Provides-Extra: doc
-Requires-Dist: mkdocs-material<10.0.0,>=9.0.0; extra == 'doc'
-Requires-Dist: mkdocstrings[python]<0.23.0,>=0.19.0; extra == 'doc'
-Provides-Extra: test
-Requires-Dist: black==23.7.0; extra == 'test'
-Requires-Dist: coverage<7.3.0,>=7.0.0; extra == 'test'
-Requires-Dist: fastapi<0.96,>=0.92; extra == 'test'
-Requires-Dist: fasteners==0.18; extra == 'test'
-Requires-Dist: flask-sqlalchemy<3.1,>=3.0; extra == 'test'
-Requires-Dist: flask<2.3,>=2.2; extra == 'test'
-Requires-Dist: mypy==1.4.1; extra == 'test'
-Requires-Dist: pillow<10.1.0,>=9.4.0; extra == 'test'
-Requires-Dist: psycopg2-binary<3.0.0,>=2.9.5; extra == 'test'
-Requires-Dist: pymysql[rsa]<1.1.0,>=1.0.2; extra == 'test'
-Requires-Dist: pytest<7.5.0,>=7.2.0; extra == 'test'
-Requires-Dist: python-multipart==0.0.6; extra == 'test'
-Requires-Dist: ruff==0.0.278; extra == 'test'
+Requires-Python: >=3.11
+Requires-Dist: apache-libcloud>=3.6
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: all
+Requires-Dist: fasteners>=0.15; extra == 'all'
+Requires-Dist: pillow>=9.4; extra == 'all'
+Provides-Extra: local
+Requires-Dist: fasteners>=0.15; extra == 'local'
+Provides-Extra: pillow
+Requires-Dist: pillow>=9.4; extra == 'pillow'
 Description-Content-Type: text/markdown
 
 # sqlalchemy-file
@@ -105,9 +92,7 @@ The key features are:
 
 ## Requirements
 
-A recent and currently supported version of Python (right
-now, <a href="https://www.python.org/downloads/" class="external-link" target="_blank">Python supports versions 3.7 and
-above</a>).
+Python 3.11 or above.
 
 As **SQLAlchemy-file** is based on **Apache Libcloud** and **SQLAlchemy**, it requires them. They will be automatically
 installed when you install SQLAlchemy-file.
@@ -120,12 +105,33 @@ installed when you install SQLAlchemy-file.
 $ pip install sqlalchemy-file
 ```
 
-### Poetry
+### uv
 
 ```shell
-$ poetry add sqlalchemy-file
+$ uv add sqlalchemy-file
 ```
 
+### Optional dependencies (extras)
+
+Some features need third-party packages that are **not** installed by default:
+
+| Extra                          | Installs                                    | Required for                                                        |
+|--------------------------------|---------------------------------------------|---------------------------------------------------------------------|
+| `sqlalchemy-file[pillow]`      | `Pillow`                                    | `ImageField`, `ImageValidator`, `ThumbnailGenerator`                |
+| `sqlalchemy-file[local]`       | `fasteners`                                 | `LocalStorageDriver` backend (required by libcloud's local storage) |
+| `sqlalchemy-file[all]`         | `Pillow` + `fasteners`                      | Everything above                                                    |
+
+```shell
+$ pip install "sqlalchemy-file[local,pillow]"
+```
+
+```shell
+$ uv add "sqlalchemy-file[all]"
+```
+
+Without the matching extra you get an explicit `ImportError` telling you which extra to install
+(e.g. use `ImageField` without `Pillow`, or the local storage driver without `fasteners`).
+
 ## Example
 
 Attaching files to models is as simple as declaring a field on the model itself
@@ -164,13 +170,25 @@ engine = create_engine(
 Base.metadata.create_all(engine)
 
 with Session(engine) as session, open("./example.txt", "rb") as local_file:
+    # from an opened local file
     session.add(Attachment(name="attachment1", content=local_file))
+
+    # from bytes
     session.add(Attachment(name="attachment2", content=b"Hello world"))
+
+    # from string
     session.add(Attachment(name="attachment3", content="Hello world"))
+
+    # from a File object with custom filename and content_type
     file = File(content="Hello World", filename="hello.txt", content_type="text/plain")
     session.add(Attachment(name="attachment4", content=file))
-    session.commit()
 
+    # from a File object specifying a content path
+    session.add(
+        Attachment(name="attachment5", content=File(content_path="./example.txt"))
+    )
+
+    session.commit()
 ```
 
 ## Related projects and inspirations

{sqlalchemy_file-0.5.0 → sqlalchemy_file-0.7.0}/README.md

@@ -53,9 +53,7 @@ The key features are:
 
 ## Requirements
 
-A recent and currently supported version of Python (right
-now, <a href="https://www.python.org/downloads/" class="external-link" target="_blank">Python supports versions 3.7 and
-above</a>).
+Python 3.11 or above.
 
 As **SQLAlchemy-file** is based on **Apache Libcloud** and **SQLAlchemy**, it requires them. They will be automatically
 installed when you install SQLAlchemy-file.
@@ -68,12 +66,33 @@ installed when you install SQLAlchemy-file.
 $ pip install sqlalchemy-file
 ```
 
-### Poetry
+### uv
 
 ```shell
-$ poetry add sqlalchemy-file
+$ uv add sqlalchemy-file
 ```
 
+### Optional dependencies (extras)
+
+Some features need third-party packages that are **not** installed by default:
+
+| Extra                          | Installs                                    | Required for                                                        |
+|--------------------------------|---------------------------------------------|---------------------------------------------------------------------|
+| `sqlalchemy-file[pillow]`      | `Pillow`                                    | `ImageField`, `ImageValidator`, `ThumbnailGenerator`                |
+| `sqlalchemy-file[local]`       | `fasteners`                                 | `LocalStorageDriver` backend (required by libcloud's local storage) |
+| `sqlalchemy-file[all]`         | `Pillow` + `fasteners`                      | Everything above                                                    |
+
+```shell
+$ pip install "sqlalchemy-file[local,pillow]"
+```
+
+```shell
+$ uv add "sqlalchemy-file[all]"
+```
+
+Without the matching extra you get an explicit `ImportError` telling you which extra to install
+(e.g. use `ImageField` without `Pillow`, or the local storage driver without `fasteners`).
+
 ## Example
 
 Attaching files to models is as simple as declaring a field on the model itself
@@ -112,13 +131,25 @@ engine = create_engine(
 Base.metadata.create_all(engine)
 
 with Session(engine) as session, open("./example.txt", "rb") as local_file:
+    # from an opened local file
     session.add(Attachment(name="attachment1", content=local_file))
+
+    # from bytes
     session.add(Attachment(name="attachment2", content=b"Hello world"))
+
+    # from string
     session.add(Attachment(name="attachment3", content="Hello world"))
+
+    # from a File object with custom filename and content_type
     file = File(content="Hello World", filename="hello.txt", content_type="text/plain")
     session.add(Attachment(name="attachment4", content=file))
-    session.commit()
 
+    # from a File object specifying a content path
+    session.add(
+        Attachment(name="attachment5", content=File(content_path="./example.txt"))
+    )
+
+    session.commit()
 ```
 
 ## Related projects and inspirations

sqlalchemy_file-0.7.0/pyproject.toml

@@ -0,0 +1,210 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sqlalchemy-file"
+description = "SQLAlchemy-file is a SQLAlchemy extension for attaching files to SQLAlchemy model and uploading them to various storage."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+keywords = ["sqlalchemy", "sqlmodel", "file-upload", "apache-libcloud"]
+authors = [
+    { name = "Jocelin Hounon", email = "hounonj@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Database",
+    "Topic :: Database :: Database Engines/Servers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "SQLAlchemy >=2.0",
+    "apache-libcloud >=3.6",
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://jowilf.github.io/sqlalchemy-file"
+Documentation = "https://jowilf.github.io/sqlalchemy-file"
+Repository = "https://github.com/jowilf/sqlalchemy-file"
+Changelog = "https://jowilf.github.io/sqlalchemy-file/changelog/"
+
+[project.optional-dependencies]
+# Optional feature dependencies. Install with e.g.
+# `pip install sqlalchemy-file[local,pillow]`.
+pillow = [
+    # Required by ImageField, ImageValidator and ThumbnailGenerator.
+    "Pillow >=9.4",
+]
+local = [
+    # Required by libcloud's LocalStorageDriver backend.
+    "fasteners >=0.15",
+]
+all = [
+    "Pillow >=9.4",
+    "fasteners >=0.15",
+]
+# Dev tooling in PEP 735 groups, managed by uv. Tasks in [tool.poe.tasks];
+# run with `uv run poe <task>`.
+[dependency-groups]
+dev = [
+    "poethepoet >=0.30.0, <0.49.0",
+    "pre-commit >=2.20.0",
+    "uvicorn >=0.20.0",
+]
+lint = [
+    "ruff ==0.17.1",
+    "ty ==0.0.89",
+]
+test = [
+    "pytest >=8",
+    "testcontainers[mysql,postgres,minio] >=4.6",
+    "fasteners >=0.15",
+    "PyMySQL >=1.0.2",
+    "psycopg2-binary >=2.9.5, <3.0.0",
+    "Pillow >=9.4",
+    "python-multipart >=0.0.6",
+    "sqlmodel >=0.0.11",
+    "fastapi >=0.92",
+    "Flask >=2.2",
+    "Flask-SQLAlchemy >=3.0",
+    { include-group = "lint" },
+]
+cov = [
+    "coverage[toml] >=7.4.0",
+]
+docs = [
+    "mkdocstrings[python] >=0.27.0",
+    "zensical ==0.0.71",
+]
+# Mutually exclusive SQLA test environments, see [tool.uv] conflicts.
+sqla20 = [
+    "SQLAlchemy >=2.0, <2.1",
+]
+sqla21 = [
+    "SQLAlchemy >=2.1",
+]
+
+[tool.uv]
+conflicts = [
+    [
+        { group = "sqla20" },
+        { group = "sqla21" },
+    ],
+]
+# sqla21 default so plain `uv sync` tests the 2.1 series. sqla20 is opt-in.
+# conflicting groups require `uv run --no-default-groups --group sqla20 ...`.
+default-groups = ["dev", "lint", "test", "cov", "docs", "sqla21"]
+
+[tool.poe.tasks]
+# Code quality
+format = ["_ruff-fix", "_ruff-format"]
+lint = ["_ty", "_ruff-check", "_ruff-format-check"]
+_ty = "ty check sqlalchemy_file"
+_ruff-check = "ruff check sqlalchemy_file tests"
+_ruff-fix = "ruff check sqlalchemy_file tests --fix"
+_ruff-format = "ruff format sqlalchemy_file tests docs_src examples"
+_ruff-format-check = "ruff format sqlalchemy_file tests docs_src examples --check"
+
+# Tests (sqla tasks re-sync their pinned group)
+test = "coverage run -m pytest tests"
+test-sqla20 = "uv run --no-default-groups --group sqla20 --group test --group cov coverage run -m pytest tests"
+test-sqla21 = "uv run --group sqla21 coverage run -m pytest tests"
+test-matrix = ["test-sqla20", "test-sqla21"]
+
+# Coverage
+cov-report = ["_cov-combine", "_cov-report", "_cov-xml"]
+_cov-combine = "coverage combine"
+_cov-report = "coverage report --show-missing"
+_cov-xml = "coverage xml"
+
+# Docs
+docs-serve = "zensical serve -a localhost:8080"
+docs-build = "zensical build"
+
+# Clean
+clean = "rm -rf .coverage .coverage.* coverage.xml .pytest_cache .ruff_cache .mypy_cache site .zensical"
+
+[tool.hatch.version]
+path = "sqlalchemy_file/__init__.py"
+
+[tool.pytest.ini_options]
+filterwarnings = [
+    "ignore:datetime.datetime.utcnow\\(\\) is deprecated:DeprecationWarning",
+]
+
+[tool.coverage.report]
+fail_under = 99
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "except ImportError"
+]
+
+[tool.coverage.run]
+parallel = true
+command_line = "-m pytest"
+source = ["sqlalchemy_file", "tests"]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "B", # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "C90", # mccabe
+    "D", # pydocstyle
+    "E", # pycodestyle errors
+    "ERA", # eradicate
+    "F", # pyflakes
+    "I", # isort
+    "N", # pep8-naming
+    "PIE", # flake8-pie,
+    "PLC", # pylint - convention
+    "PLE", # pylint - error
+    "PLW", # pylint - warning
+    "Q", # flake8-quotes
+    "RET", # flake8-return,
+    "RUF", # Ruff-specific rules
+    "SIM", # flake8-simplify
+    "UP", # pyupgrade
+    "W", # pycodestyle warnings
+]
+ignore = ["E501", "B904", "B008", "D100", "D101", "D102", "D103", "D104", "D105", "D106", "D107", "D205"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-third-party = ["sqlalchemy_file"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+"docs_src/**" = ["N999"]
+# Test fixtures intentionally keep temp files open for the test body.
+"tests/**" = ["SIM115"]
+
+[tool.ty.src]
+include = ["sqlalchemy_file"]
+
+[tool.ty.rules]
+unused-ignore-comment = "error"
+unused-type-ignore-comment = "error"
+
+[tool.hatch.build.targets.wheel]
+[tool.hatch.build.targets.sdist]
+include = ["sqlalchemy_file"]

sqlalchemy_file-0.7.0/sqlalchemy_file/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.7.0"
+
+from .file import File as File
+from .types import FileField as FileField
+from .types import ImageField as ImageField

{sqlalchemy_file-0.5.0 → sqlalchemy_file-0.7.0}/sqlalchemy_file/base.py

@@ -1,8 +1,7 @@
-import typing
 from typing import Any
 
 
-class BaseFile(typing.Dict[str, Any]):
+class BaseFile(dict[str, Any]):
     """Base class for file object.
 
     It keeps information on a content related to a specific storage.
@@ -37,7 +36,7 @@ class BaseFile(typing.Dict[str, Any]):
             raise AttributeError(name)
 
     def __delitem__(self, key: str) -> None:
-        if object.__getattribute__(self, "_frozen"):
+        if getattr(self, "_frozen", False):
             raise TypeError("Already saved files are immutable")
         dict.__delitem__(self, key)
 

{sqlalchemy_file-0.5.0 → sqlalchemy_file-0.7.0}/sqlalchemy_file/file.py

@@ -1,7 +1,9 @@
+import copy
+import os.path
 import uuid
 import warnings
-from datetime import datetime
-from typing import Any, Dict, List, Optional
+from datetime import UTC, datetime
+from typing import Any
 
 from sqlalchemy_file.base import BaseFile
 from sqlalchemy_file.helpers import (
@@ -39,11 +41,14 @@ class File(BaseFile):
 
     def __init__(
         self,
-        content: Any,
-        filename: Optional[str] = None,
-        content_type: Optional[str] = None,
-        **kwargs: Dict[str, Any],
+        content: Any = None,
+        filename: str | None = None,
+        content_type: str | None = None,
+        content_path: str | None = None,
+        **kwargs: Any,
     ) -> None:
+        if content is None and content_path is None:
+            raise ValueError("Either content or content_path must be specified")
         super().__init__(**kwargs)
         if isinstance(content, dict):
             object.__setattr__(self, "original_content", None)
@@ -51,8 +56,15 @@ class File(BaseFile):
             self.update(content)
             self._freeze()
         else:
-            self.original_content = get_content_from_file_obj(content)
-            filename = filename or get_filename_from_fileob(content)
+            self.content_path = content_path
+            if content_path is not None:
+                self.original_content = None
+                filename = filename or os.path.basename(content_path)
+                size = os.path.getsize(content_path)
+            else:
+                self.original_content = get_content_from_file_obj(content)
+                filename = filename or get_filename_from_fileob(content)
+                size = get_content_size_from_fileobj(self.original_content)
             content_type = content_type or get_content_type_from_fileobj(
                 content, filename
             )
@@ -60,30 +72,32 @@ class File(BaseFile):
                 {
                     "filename": filename,
                     "content_type": content_type,
-                    "size": get_content_size_from_fileobj(self.original_content),
+                    "size": size,
                     "files": [],
                 }
             )
             self._thaw()
 
-    def apply_validators(self, validators: List[Validator], key: str = "") -> None:
+    def apply_validators(self, validators: list[Validator], key: str = "") -> None:
         """Apply validators to current file."""
         for validator in validators:
             validator.process(self, key)
 
     def apply_processors(
         self,
-        processors: List[Processor],
-        upload_storage: Optional[str] = None,
+        processors: list[Processor],
+        upload_storage: str | None = None,
     ) -> None:
         """Apply processors to current file."""
         for processor in processors:
             processor.process(self, upload_storage)
         self._freeze()
 
-    def save_to_storage(self, upload_storage: Optional[str] = None) -> None:
+    def save_to_storage(self, upload_storage: str | None = None) -> None:
         """Save current file into provided `upload_storage`."""
-        extra = self.get("extra", {})
+        # Deep copy `extra`: column-level config must not leak between files.
+        extra = copy.deepcopy(self.get("extra", None) or {})
+
         extra.update({"content_type": self.content_type})
 
         metadata = self.get("metadata", None)
@@ -91,7 +105,7 @@ class File(BaseFile):
             warnings.warn(
                 'metadata attribute is deprecated. Use extra={"meta_data": ...} instead',
                 DeprecationWarning,
-                stacklevel=1,
+                stacklevel=2,
             )
             extra.update({"meta_data": metadata})
 
@@ -101,15 +115,17 @@ class File(BaseFile):
         extra["meta_data"].update(
             {"filename": self.filename, "content_type": self.content_type}
         )
+        self["extra"] = extra
         stored_file = self.store_content(
             self.original_content,
             upload_storage,
             extra=extra,
             headers=self.get("headers", None),
+            content_path=self.content_path,
         )
         self["file_id"] = stored_file.name
         self["upload_storage"] = upload_storage
-        self["uploaded_at"] = datetime.utcnow().isoformat()
+        self["uploaded_at"] = datetime.now(UTC).isoformat()
         self["path"] = f"{upload_storage}/{stored_file.name}"
         self["url"] = stored_file.get_cdn_url()
         self["saved"] = True
@@ -117,17 +133,19 @@ class File(BaseFile):
     def store_content(
         self,
         content: Any,
-        upload_storage: Optional[str] = None,
-        name: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-        extra: Optional[Dict[str, Any]] = None,
-        headers: Optional[Dict[str, str]] = None,
+        upload_storage: str | None = None,
+        name: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        extra: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        content_path: str | None = None,
     ) -> StoredFile:
         """Store content into provided `upload_storage`
         with additional `metadata`. Can be used by processors
         to store additional files.
         """
         name = name or str(uuid.uuid4())
+        upload_storage = upload_storage or StorageManager.get_default()
         stored_file = StorageManager.save_file(
             name=name,
             content=content,
@@ -135,11 +153,12 @@ class File(BaseFile):
             metadata=metadata,
             extra=extra,
             headers=headers,
+            content_path=content_path,
         )
         self["files"].append(f"{upload_storage}/{name}")
         return stored_file
 
-    def encode(self) -> Dict[str, Any]:
+    def encode(self) -> dict[str, Any]:
         return {k: v for k, v in self.items() if k not in ["original_content"]}
 
     @classmethod