sqlalchemy-file 0.4.0.dev0__tar.gz → 0.5.0__tar.gz

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/.gitignore

@@ -7,10 +7,11 @@ poetry.lock
 dist
 htmlcov
 *.egg-info
-.coverage
+.coverage*
 coverage.xml
 site
 *.db
 .cache
 __pycache__/
 .pytest_cache/
+upload_dir/

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sqlalchemy-file
-Version: 0.4.0.dev0
+Version: 0.5.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
@@ -27,28 +27,27 @@ 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<1.5,>=1.4
+Requires-Dist: sqlalchemy<2.1,>=1.4
 Provides-Extra: dev
-Requires-Dist: pre-commit<3.0.0,>=2.20.0; extra == 'dev'
-Requires-Dist: uvicorn<0.21.0,>=0.20.0; 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.21.0,>=0.19.0; extra == 'doc'
+Requires-Dist: mkdocstrings[python]<0.23.0,>=0.19.0; extra == 'doc'
 Provides-Extra: test
-Requires-Dist: black==22.12.0; extra == 'test'
-Requires-Dist: coverage<7.1.0,>=7.0.0; extra == 'test'
-Requires-Dist: fastapi<0.93,>=0.92; 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==0.991; extra == 'test'
-Requires-Dist: pillow<9.5.0,>=9.4.0; 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.3.0,>=7.2.0; extra == 'test'
-Requires-Dist: python-multipart==0.0.5; extra == 'test'
-Requires-Dist: ruff==0.0.215; extra == 'test'
-Requires-Dist: sqlmodel==0.0.8; 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'
 Description-Content-Type: text/markdown
 
 # sqlalchemy-file
@@ -154,8 +153,8 @@ class Attachment(Base):
 
 
 # Configure Storage
-os.makedirs("/tmp/storage/attachment", 0o777, exist_ok=True)
-container = LocalStorageDriver("/tmp/storage").get_container("attachment")
+os.makedirs("./upload_dir/attachment", 0o777, exist_ok=True)
+container = LocalStorageDriver("./upload_dir").get_container("attachment")
 StorageManager.add_storage("default", container)
 
 # Save your model
@@ -164,8 +163,8 @@ engine = create_engine(
 )
 Base.metadata.create_all(engine)
 
-with Session(engine) as session:
-    session.add(Attachment(name="attachment1", content=open("./example.txt", "rb")))
+with Session(engine) as session, open("./example.txt", "rb") as local_file:
+    session.add(Attachment(name="attachment1", content=local_file))
     session.add(Attachment(name="attachment2", content=b"Hello world"))
     session.add(Attachment(name="attachment3", content="Hello world"))
     file = File(content="Hello World", filename="hello.txt", content_type="text/plain")

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/README.md

@@ -101,8 +101,8 @@ class Attachment(Base):
 
 
 # Configure Storage
-os.makedirs("/tmp/storage/attachment", 0o777, exist_ok=True)
-container = LocalStorageDriver("/tmp/storage").get_container("attachment")
+os.makedirs("./upload_dir/attachment", 0o777, exist_ok=True)
+container = LocalStorageDriver("./upload_dir").get_container("attachment")
 StorageManager.add_storage("default", container)
 
 # Save your model
@@ -111,8 +111,8 @@ engine = create_engine(
 )
 Base.metadata.create_all(engine)
 
-with Session(engine) as session:
-    session.add(Attachment(name="attachment1", content=open("./example.txt", "rb")))
+with Session(engine) as session, open("./example.txt", "rb") as local_file:
+    session.add(Attachment(name="attachment1", content=local_file))
     session.add(Attachment(name="attachment2", content=b"Hello world"))
     session.add(Attachment(name="attachment3", content="Hello world"))
     file = File(content="Hello World", filename="hello.txt", content_type="text/plain")

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/pyproject.toml

@@ -30,7 +30,7 @@ classifiers = [
     "Topic :: Database :: Database Engines/Servers",
 ]
 dependencies = [
-    "SQLAlchemy >=1.4, <1.5",
+    "SQLAlchemy >=1.4, <2.1",
     "apache-libcloud >=3.6, <3.8",
 ]
 dynamic = ["version"]
@@ -43,28 +43,27 @@ Changelog = "https://jowilf.github.io/sqlalchemy-file/changelog/"
 
 [project.optional-dependencies]
 test = [
-    "pytest >=7.2.0, <7.3.0",
-    "mypy ==0.991",
-    "ruff ==0.0.215",
-    "black ==22.12.0",
-    "coverage >=7.0.0, <7.1.0",
+    "pytest >=7.2.0, <7.5.0",
+    "mypy ==1.4.1",
+    "ruff ==0.0.278",
+    "black ==23.7.0",
+    "coverage >=7.0.0, <7.3.0",
     "fasteners ==0.18",
     "PyMySQL[rsa] >=1.0.2, <1.1.0",
     "psycopg2-binary >=2.9.5, <3.0.0",
-    "Pillow >=9.4.0, <9.5.0",
-    "sqlmodel ==0.0.8",
-    "python-multipart ==0.0.5",
-    "fastapi >=0.92, <0.93",
+    "Pillow >=9.4.0, <10.1.0",
+    "python-multipart ==0.0.6",
+    "fastapi >=0.92, <0.96",
     "Flask >=2.2, <2.3",
     "Flask-SQLAlchemy >=3.0,<3.1"
 ]
 doc = [
     "mkdocs-material >=9.0.0, <10.0.0",
-    "mkdocstrings[python] >=0.19.0, <0.21.0"
+    "mkdocstrings[python] >=0.19.0, <0.23.0"
 ]
 dev = [
-    "pre-commit >=2.20.0, <3.0.0",
-    "uvicorn >=0.20.0, <0.21.0",
+    "pre-commit >=2.20.0, <4.0.0",
+    "uvicorn >=0.20.0, <0.22.0",
 ]
 
 [tool.hatch.envs.default]
@@ -74,7 +73,7 @@ features = [
 ]
 [tool.hatch.envs.default.scripts]
 format = [
-    "ruff sqlalchemy_file tests docs_src --fix",
+    "ruff sqlalchemy_file tests --fix",
     "black ."
 ]
 
@@ -88,13 +87,27 @@ lint = [
     "ruff sqlalchemy_file tests",
     "black . --check"
 ]
-all = "coverage run -m pytest tests"
+run = "coverage run -m pytest tests"
 cov = [
     "coverage combine",
     "coverage report --show-missing",
     "coverage xml"
 ]
 
+[[tool.hatch.envs.test.matrix]]
+sqla_version = ["1.4.x", "2.0.x"]
+
+[tool.hatch.envs.test.overrides]
+matrix.sqla_version.dependencies = [
+    { value = "SQLAlchemy >=2.0, <2.1", if = ["2.0.x"] },
+    { value = "SQLAlchemy >=1.4, <1.5", if = ["1.4.x"] },
+    { value = "sqlmodel ==0.0.8", if = ["1.4.x"] },
+]
+matrix.sqla_version.scripts = [
+    { key = "run", value = 'coverage run -m pytest tests --ignore=tests/test_sqlmodel.py', if = ["2.0.x"] },
+    { key = "cov", value = '', if = ["2.0.x"] },
+]
+
 [tool.hatch.envs.docs]
 features = [
     "doc",
@@ -122,20 +135,42 @@ source = ["sqlalchemy_file", "tests"]
 
 [tool.ruff]
 select = [
+    "B", # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "C90", # mccabe
+    "D", # pydocstyle
     "E", # pycodestyle errors
-    "W", # pycodestyle warnings
+    "ERA", # eradicate
     "F", # pyflakes
     "I", # isort
-    "C", # flake8-comprehensions
-    "B", # flake8-bugbear
+    "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"]
+ignore = ["E501", "B904", "B008", "D100", "D101", "D102", "D103", "D104", "D105", "D106", "D107", "D205"]
+target-version = "py38"
+
+[tool.ruff.pydocstyle]
+convention = "google"
 
 [tool.ruff.isort]
 known-third-party = ["sqlalchemy_file"]
 
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["F401"]
+"docs_src/**" = ["N999"]
+
 [tool.mypy]
 strict = true
+warn_unused_ignores = false
 
 [tool.hatch.build.targets.wheel]
 [tool.hatch.build.targets.sdist]

sqlalchemy_file-0.5.0/sqlalchemy_file/__init__.py

@@ -0,0 +1,4 @@
+__version__ = "0.5.0"
+
+from .file import File
+from .types import FileField, ImageField

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/sqlalchemy_file/base.py

@@ -3,8 +3,9 @@ from typing import Any
 
 
 class BaseFile(typing.Dict[str, Any]):
-    """
-    Base class for file object. It keeps information on a content related to a specific storage.
+    """Base class for file object.
+
+    It keeps information on a content related to a specific storage.
     It is a specialized dictionary that provides also attribute style access,
     the dictionary parent permits easy encoding/decoding to JSON.
 

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/sqlalchemy_file/exceptions.py

@@ -2,11 +2,11 @@ class ValidationError(Exception):
     """Base class for ValidationError
     Parameters:
         key: Current Column key
-        msg: Validation error message
+        msg: Validation error message.
     """
 
     def __init__(self, key: str, msg: str):  # pragma: no cover
-        super().__init__("{}: {}".format(key, msg))
+        super().__init__(f"{key}: {msg}")
         self.key = key
         self.msg = msg
 

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/sqlalchemy_file/file.py

@@ -17,15 +17,13 @@ from sqlalchemy_file.validators import Validator
 
 
 class File(BaseFile):
-    """
-    Takes a file as content and uploads it to the appropriate storage
+    """Takes a file as content and uploads it to the appropriate storage
     according to the attached Column and file information into the
     database as JSON.
 
     Default attributes provided for all ``File`` include:
 
     Attributes:
-
         filename (str):  This is the name of the uploaded file
         file_id:   This is the generated UUID for the uploaded file
         upload_storage:   Name of the storage used to save the uploaded file
@@ -69,7 +67,7 @@ class File(BaseFile):
             self._thaw()
 
     def apply_validators(self, validators: List[Validator], key: str = "") -> None:
-        """Apply validators to current file"""
+        """Apply validators to current file."""
         for validator in validators:
             validator.process(self, key)
 
@@ -78,13 +76,13 @@ class File(BaseFile):
         processors: List[Processor],
         upload_storage: Optional[str] = None,
     ) -> None:
-        """Apply processors to current file"""
+        """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:
-        """Save current file into provided `upload_storage`"""
+        """Save current file into provided `upload_storage`."""
         extra = self.get("extra", {})
         extra.update({"content_type": self.content_type})
 
@@ -93,6 +91,7 @@ class File(BaseFile):
             warnings.warn(
                 'metadata attribute is deprecated. Use extra={"meta_data": ...} instead',
                 DeprecationWarning,
+                stacklevel=1,
             )
             extra.update({"meta_data": metadata})
 
@@ -111,7 +110,7 @@ class File(BaseFile):
         self["file_id"] = stored_file.name
         self["upload_storage"] = upload_storage
         self["uploaded_at"] = datetime.utcnow().isoformat()
-        self["path"] = "{}/{}".format(upload_storage, stored_file.name)
+        self["path"] = f"{upload_storage}/{stored_file.name}"
         self["url"] = stored_file.get_cdn_url()
         self["saved"] = True
 
@@ -125,7 +124,7 @@ class File(BaseFile):
         headers: Optional[Dict[str, str]] = None,
     ) -> StoredFile:
         """Store content into provided `upload_storage`
-        with additional `metadata`. Can be use by processors
+        with additional `metadata`. Can be used by processors
         to store additional files.
         """
         name = name or str(uuid.uuid4())
@@ -137,7 +136,7 @@ class File(BaseFile):
             extra=extra,
             headers=headers,
         )
-        self["files"].append("{}/{}".format(upload_storage, name))
+        self["files"].append(f"{upload_storage}/{name}")
         return stored_file
 
     def encode(self) -> Dict[str, Any]:

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/sqlalchemy_file/helpers.py

@@ -4,7 +4,7 @@ import os
 import re
 from builtins import RuntimeError
 from tempfile import SpooledTemporaryFile
-from typing import Any, Dict, Union
+from typing import Any, Dict, List, Union
 
 INMEMORY_FILESIZE = 1024 * 1024
 LOCAL_STORAGE_DRIVER_NAME = "Local Storage"
@@ -18,7 +18,8 @@ def get_metadata_file_obj(metadata: Dict[str, Any]) -> "SpooledTemporaryFile[byt
 
 
 def get_content_from_file_obj(fileobj: Any) -> Any:
-    """Provides a real file object from file content
+    """Provides a real file object from file content.
+
     Converts ``str`` and ``bytes`` to an actual file.
     """
     if isinstance(fileobj, (str, bytes)):
@@ -26,7 +27,7 @@ def get_content_from_file_obj(fileobj: Any) -> Any:
         f.write(fileobj.encode() if isinstance(fileobj, str) else fileobj)
         f.seek(0)
         return f
-    elif getattr(fileobj, "file", None) is not None:
+    if getattr(fileobj, "file", None) is not None:
         return fileobj.file
     return fileobj
 
@@ -34,7 +35,7 @@ def get_content_from_file_obj(fileobj: Any) -> Any:
 def get_filename_from_fileob(fileobj: Any) -> Any:
     if getattr(fileobj, "filename", None) is not None:
         return fileobj.filename
-    elif getattr(fileobj, "name", None) is not None:
+    if getattr(fileobj, "name", None) is not None:
         return os.path.basename(fileobj.name)
     return "unnamed"
 
@@ -64,9 +65,7 @@ def get_content_size_from_fileobj(file: Any) -> Any:
 
 def convert_size(size: Union[str, int]) -> int:
     # convert size to number of bytes ex: 1k -> 1000; 1Ki->1024
-    if isinstance(size, int):
-        return size
-    elif isinstance(size, str):
+    if isinstance(size, str):
         pattern = re.compile(r"^(\d+)\s*(k|([KM]i?))$")
         m = re.fullmatch(pattern, size)
         if m is None:
@@ -74,3 +73,9 @@ def convert_size(size: Union[str, int]) -> int:
         value, si, _ = m.groups()
         si_map = {"k": 1000, "K": 1000, "M": 1000**2, "Ki": 1024, "Mi": 1024**2}
         return int(value) * si_map[si]
+    return size
+
+
+def flatmap(lists: List[List[Any]]) -> List[Any]:
+    """Flattens a list of lists into a single list."""
+    return [value for _list in lists for value in _list]

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/sqlalchemy_file/mutable_list.py

@@ -7,8 +7,7 @@ T = TypeVar("T", bound=Any)
 
 
 class MutableList(Mutable, typing.List[T]):
-    """
-    A list type that implements :class:`Mutable`.
+    """A list type that implements :class:`Mutable`.
 
     The :class:`MutableList` object implements a list that will
     emit change events to the underlying mapping when the contents of
@@ -32,8 +31,7 @@ class MutableList(Mutable, typing.List[T]):
                 return MutableList(value)
             # this call will raise ValueError
             return Mutable.coerce(key, value)  # pragma: no cover
-        else:
-            return value  # pragma: no cover
+        return value  # pragma: no cover
 
     @no_type_check
     def __reduce_ex__(self, proto):  # pragma: no cover
@@ -50,20 +48,14 @@ class MutableList(Mutable, typing.List[T]):
 
     def __setitem__(self, index: Any, value: Any) -> None:
         """Detect list set events and emit change events."""
-        if isinstance(index, slice):
-            old_value = self[index]
-        else:
-            old_value = [self[index]]
+        old_value = self[index] if isinstance(index, slice) else [self[index]]
         list.__setitem__(self, index, value)
         self.changed()
         self._removed.extend(old_value)
 
     def __delitem__(self, index: Any) -> None:
         """Detect list del events and emit change events."""
-        if isinstance(index, slice):
-            old_value = self[index]
-        else:
-            old_value = [self[index]]
+        old_value = self[index] if isinstance(index, slice) else [self[index]]
         list.__delitem__(self, index)
         self.changed()
         self._removed.extend(old_value)

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/sqlalchemy_file/processors.py

@@ -10,8 +10,7 @@ if TYPE_CHECKING:
 
 
 class Processor:
-    """
-    Interface that must be implemented by file processors.
+    """Interface that must be implemented by file processors.
     Can be used to add additional data to the stored file or change it.
     When file processors are run the file has already been stored.
 
@@ -21,21 +20,18 @@ class Processor:
     def process(
         self, file: "File", upload_storage: Optional[str] = None
     ) -> None:  # pragma: no cover
-        """
-        Should be overridden in inherited class
+        """Should be overridden in inherited class
         Parameters:
             file: [File][sqlalchemy_file.file.File] object,
                 Use file.original_content to access uploaded file
             upload_storage: pass this to
                 [file.store_content()][sqlalchemy_file.file.File.store_content]
-                to attach additional files to the original file
+                to attach additional files to the original file.
         """
-        pass
 
 
 class ThumbnailGenerator(Processor):
-    """
-    Generate thumbnail from original content.
+    """Generate thumbnail from original content.
 
     The default thumbnail format and size are `PNG@128x128`, those can be changed
     by giving custom `thumbnail_size` and `thumbnail_format`
@@ -124,7 +120,7 @@ class ThumbnailGenerator(Processor):
                 "height": height,
             }
         )
-        extra.update({"meta_data": metadata})
+        extra.update({"content_type": content_type, "meta_data": metadata})
         stored_file = file.store_content(
             output, upload_storage, extra=extra, headers=file.get("headers", None)
         )
@@ -135,7 +131,7 @@ class ThumbnailGenerator(Processor):
                     "width": width,
                     "height": height,
                     "upload_storage": upload_storage,
-                    "path": "{}/{}".format(upload_storage, stored_file.name),
+                    "path": f"{upload_storage}/{stored_file.name}",
                     "url": stored_file.get_cdn_url(),
                 }
             }

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/sqlalchemy_file/storage.py

@@ -1,5 +1,6 @@
+import contextlib
 import warnings
-from typing import Any, Dict, Iterator, Optional
+from typing import Any, ClassVar, Dict, Iterator, Optional
 
 from libcloud.storage.base import Container
 from libcloud.storage.types import ObjectDoesNotExistError
@@ -8,8 +9,7 @@ from sqlalchemy_file.stored_file import StoredFile
 
 
 class StorageManager:
-    """
-    Takes care of managing the whole Storage environment for the application.
+    """Takes care of managing the whole Storage environment for the application.
 
     Use [add_storage][sqlalchemy_file.storage.StorageManager.add_storage] method
     to add new `libcloud.storage.base.Container`and associate a name which
@@ -23,46 +23,45 @@ class StorageManager:
 
     """
 
-    _default_storage_name: Optional[str] = None
-    _storages: Dict[str, Container] = {}
+    _default_storage_name: ClassVar[Optional[str]] = None
+    _storages: ClassVar[Dict[str, Container]] = {}
 
     @classmethod
     def set_default(cls, name: str) -> None:
-        """Replaces the current application default storage"""
+        """Replaces the current application default storage."""
         if name not in cls._storages:
-            raise RuntimeError("{} storage has not been added".format(name))
+            raise RuntimeError(f"{name} storage has not been added")
         cls._default_storage_name = name
 
     @classmethod
     def get_default(cls) -> str:
-        """Gets the current application default storage"""
+        """Gets the current application default storage."""
         if cls._default_storage_name is None:
             raise RuntimeError("No default storage has been added")
         return cls._default_storage_name
 
     @classmethod
     def add_storage(cls, name: str, container: Container) -> None:
-        """Add new storage"""
+        """Add new storage."""
         assert isinstance(container, Container), "Invalid container"
         if name in cls._storages:
-            raise RuntimeError("Storage {} has already been added".format(name))
+            raise RuntimeError(f"Storage {name} has already been added")
         if cls._default_storage_name is None:
             cls._default_storage_name = name
         cls._storages[name] = container
 
     @classmethod
     def get(cls, name: Optional[str] = None) -> Container:
-        """
-        Gets the container instance associate to the name,
-        return default if name isn't provided
+        """Gets the container instance associate to the name,
+        return default if name isn't provided.
         """
         if name is None and cls._default_storage_name is None:
             raise RuntimeError("No default storage have been added")
-        elif name is None:
+        if name is None:
             name = cls._default_storage_name
         if name in cls._storages:
             return cls._storages[name]
-        raise RuntimeError("{} storage has not been added".format(name))
+        raise RuntimeError(f"{name} storage has not been added")
 
     @classmethod
     def save_file(
@@ -78,6 +77,7 @@ class StorageManager:
             warnings.warn(
                 'metadata attribute is deprecated. Use extra={"meta_data": ...} instead',
                 DeprecationWarning,
+                stacklevel=1,
             )
             extra = {
                 "meta_data": metadata,
@@ -110,30 +110,28 @@ class StorageManager:
     @classmethod
     def get_file(cls, path: str) -> StoredFile:
         """Retrieve the file with `provided` path,
-        path is expected to be `storage_name/file_id`
+        path is expected to be `storage_name/file_id`.
         """
         upload_storage, file_id = path.split("/")
         return StoredFile(StorageManager.get(upload_storage).get_object(file_id))
 
     @classmethod
     def delete_file(cls, path: str) -> bool:
-        """Delete the file with `provided` path
-        path is expected to be `storage_name/file_id`
+        """Delete the file with `provided` path.
+
+        The path is expected to be `storage_name/file_id`.
         """
         upload_storage, file_id = path.split("/")
         obj = StorageManager.get(upload_storage).get_object(file_id)
         if obj.driver.name == LOCAL_STORAGE_DRIVER_NAME:
             """Try deleting associated metadata file"""
-            try:
+            with contextlib.suppress(ObjectDoesNotExistError):
                 obj.container.get_object(f"{obj.name}.metadata.json").delete()
-            except ObjectDoesNotExistError:
-                pass
+
         return obj.delete()
 
     @classmethod
     def _clear(cls) -> None:
-        """
-        This is only for testing pourposes, resets the StorageManager
-        """
+        """This is only for testing pourposes, resets the StorageManager."""
         cls._default_storage_name = None
         cls._storages = {}

sqlalchemy_file-0.5.0/sqlalchemy_file/stored_file.py

@@ -0,0 +1,71 @@
+import io
+import json
+from typing import Optional
+
+from libcloud.storage.base import Object
+from libcloud.storage.types import ObjectDoesNotExistError
+from sqlalchemy_file.helpers import LOCAL_STORAGE_DRIVER_NAME
+
+
+class StoredFile(io.IOBase):
+    """Represents a file that has been stored in a database. This class provides
+    a file-like interface for reading the file content.
+
+    Attributes:
+        name: The name of the file (Same as file_id).
+        filename: The original name of the uploaded file.
+        content_type: The content type of the uploaded file.
+        object: The `Object` representing the file in the storage service.
+    """
+
+    def __init__(self, obj: Object) -> None:
+        if obj.driver.name == LOCAL_STORAGE_DRIVER_NAME:
+            """Retrieve metadata from associated metadata file"""
+            try:
+                metadata_obj = obj.container.get_object(f"{obj.name}.metadata.json")
+                with open(metadata_obj.get_cdn_url()) as metadata_file:
+                    obj.meta_data = json.load(metadata_file)
+            except ObjectDoesNotExistError:
+                pass
+        self.name = obj.name
+        self.filename = obj.meta_data.get("filename", "unnamed")
+        self.content_type = obj.extra.get(
+            "content_type",
+            obj.meta_data.get("content_type", "application/octet-stream"),
+        )
+        self.object = obj
+
+    def get_cdn_url(self) -> Optional[str]:
+        """Retrieves the CDN URL of the file if available."""
+        try:
+            return self.object.get_cdn_url()
+        except NotImplementedError:
+            return None
+
+    def read(self, n: int = -1, chunk_size: Optional[int] = None) -> bytes:
+        """Reads the content of the file.
+
+        Arguments:
+            n: The number of bytes to read. If not specified or set to -1,
+                it reads the entire content of the file. Defaults to -1.
+            chunk_size: The size of the chunks to read at a time.
+                If not specified, the default chunk size of the storage provider will be used.
+
+        """
+        return next(
+            self.object.range_as_stream(
+                0, end_bytes=n if n > 0 else None, chunk_size=chunk_size
+            )
+        )
+
+    def close(self) -> None:
+        pass  # No need to close;
+
+    def seekable(self) -> bool:
+        return False  # Seeking is not supported ; pragma: no cover
+
+    def writable(self) -> bool:
+        return False  # Writing is not supported ; pragma: no cover
+
+    def readable(self) -> bool:
+        return True  # Reading is supported ; pragma: no cover

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/sqlalchemy_file/types.py

@@ -1,10 +1,11 @@
-from typing import Any, Dict, List, Optional, Set, Tuple, Type, Union
+from typing import Any, ClassVar, Dict, List, Optional, Set, Tuple, Type, Union
 
 from sqlalchemy import event, inspect, orm, types
 from sqlalchemy.engine import Connection, Dialect
 from sqlalchemy.orm import ColumnProperty, Mapper, Session, SessionTransaction
 from sqlalchemy.orm.attributes import get_history
 from sqlalchemy_file.file import File
+from sqlalchemy_file.helpers import flatmap
 from sqlalchemy_file.mutable_list import MutableList
 from sqlalchemy_file.processors import Processor, ThumbnailGenerator
 from sqlalchemy_file.storage import StorageManager
@@ -12,9 +13,7 @@ from sqlalchemy_file.validators import ImageValidator, Validator
 
 
 class FileField(types.TypeDecorator):  # type: ignore
-
-    """
-    Provides support for storing attachments to **SQLAlchemy** models.
+    """Provides support for storing attachments to **SQLAlchemy** models.
 
     [FileField][sqlalchemy_file.types.FileField] can be used as a Column type to
     store files into the model. The actual file itself will be uploaded to a specific
@@ -34,7 +33,7 @@ class FileField(types.TypeDecorator):  # type: ignore
     """
 
     impl = types.JSON
-    cache_ok = True
+    cache_ok = False
 
     def __init__(
         self,
@@ -48,18 +47,17 @@ class FileField(types.TypeDecorator):  # type: ignore
         headers: Optional[Dict[str, str]] = None,
         **kwargs: Dict[str, Any],
     ) -> None:
-        """
-        Parameters:
-              upload_storage: storage to use
-              validators: List of validators to apply
-              processors: List of validators to apply
-              upload_type: File class to use, could be
-                        used to set custom File class
-              multiple: Use this to save multiple files
-              extra: Extra attributes (driver specific)
-              headers: Additional request headers,
-                such as CORS headers. For example:
-                headers = {'Access-Control-Allow-Origin': 'http://mozilla.com'}
+        """Parameters:
+        upload_storage: storage to use
+        validators: List of validators to apply
+        processors: List of validators to apply
+        upload_type: File class to use, could be
+        used to set custom File class
+        multiple: Use this to save multiple files
+        extra: Extra attributes (driver specific)
+        headers: Additional request headers,
+        such as CORS headers. For example:
+        headers = {'Access-Control-Allow-Origin': 'http://mozilla.com'}.
         """
         super().__init__(*args, **kwargs)
         if processors is None:
@@ -85,7 +83,7 @@ class FileField(types.TypeDecorator):  # type: ignore
             raise ValueError(f"Expected {self.upload_type}, received: {type(value)}")
         if self.multiple and not (
             isinstance(value, list)
-            and all([isinstance(v, self.upload_type) for v in value])
+            and all(isinstance(v, self.upload_type) for v in value)
         ):  # pragma: no cover
             raise ValueError(
                 f"Expected MutableList[{self.upload_type}], received: {type(value)}"
@@ -111,7 +109,7 @@ class ImageField(FileField):
     but also validates that the uploaded object is a valid image.
     """
 
-    cache_ok = True
+    cache_ok = False
 
     def __init__(
         self,
@@ -127,20 +125,19 @@ class ImageField(FileField):
         headers: Optional[Dict[str, str]] = None,
         **kwargs: Dict[str, Any],
     ) -> None:
-        """
-        Parameters:
-            upload_storage: storage to use
-            image_validator: ImageField use default image
-                  validator, Use this property to customize it.
-            thumbnail_size: If set, a thumbnail will be generated
-                from original image using [ThumbnailGenerator]
-                [sqlalchemy_file.processors.ThumbnailGenerator]
-            validators: List of additional validators to apply
-            processors: List of validators to apply
-            upload_type: File class to use, could be
-                        used to set custom File class
-            multiple: Use this to save multiple files
-            extra: Extra attributes (driver specific)
+        """Parameters
+        upload_storage: storage to use
+        image_validator: ImageField use default image
+        validator, Use this property to customize it.
+        thumbnail_size: If set, a thumbnail will be generated
+        from original image using [ThumbnailGenerator]
+        [sqlalchemy_file.processors.ThumbnailGenerator]
+        validators: List of additional validators to apply
+        processors: List of validators to apply
+        upload_type: File class to use, could be
+        used to set custom File class
+        multiple: Use this to save multiple files
+        extra: Extra attributes (driver specific).
         """
         if validators is None:
             validators = []
@@ -165,7 +162,7 @@ class ImageField(FileField):
 
 
 class FileFieldSessionTracker:
-    mapped_entities: Dict[Type[Any], List[str]] = {}
+    mapped_entities: ClassVar[Dict[Type[Any], List[str]]] = {}
 
     @classmethod
     def delete_files(cls, paths: Set[str], ctx: str) -> None:
@@ -190,20 +187,18 @@ class FileFieldSessionTracker:
         session._old_files.update(paths)  # type: ignore
 
     @classmethod
-    def extract_files_from_history(
-        cls, data: List[Union[MutableList[File], File]]
-    ) -> List[str]:
+    def extract_files_from_history(cls, data: Union[Tuple[()], List[Any]]) -> List[str]:
         paths = []
         for item in data:
             if isinstance(item, list):
-                paths.extend([f["path"] for f in item])
+                paths.extend([f["files"] for f in item])
             elif isinstance(item, File):
-                paths.append(item["path"])
-        return paths
+                paths.append(item["files"])
+        return flatmap(paths)
 
     @classmethod
-    def _mapper_configured(cls, mapper: Mapper, class_: Any) -> None:
-        """Detect and listen all class with FileField Column"""
+    def _mapper_configured(cls, mapper: Mapper, class_: Any) -> None:  # type: ignore[type-arg]
+        """Detect and listen all class with FileField Column."""
         for mapper_property in mapper.iterate_properties:
             if isinstance(mapper_property, ColumnProperty) and isinstance(
                 mapper_property.columns[0].type, FileField
@@ -219,7 +214,7 @@ class FileFieldSessionTracker:
 
     @classmethod
     def _after_configured(cls) -> None:
-        for entity in cls.mapped_entities.keys():
+        for entity in cls.mapped_entities:
             event.listen(entity, "before_insert", cls._before_insert)
             event.listen(entity, "before_update", cls._before_update)
             event.listen(entity, "after_update", cls._after_update)
@@ -227,21 +222,20 @@ class FileFieldSessionTracker:
 
     @classmethod
     def _after_commit(cls, session: Session) -> None:
-        """After commit, old files are automatically deleted"""
+        """After commit, old files are automatically deleted."""
         cls.delete_files(getattr(session, "_old_files", set()), "after_commit")
         cls.clear_session(session)
 
     @classmethod
     def _after_soft_rollback(cls, session: Session, _: SessionTransaction) -> None:
-        """After rollback, new files are automatically deleted"""
+        """After rollback, new files are automatically deleted."""
         cls.delete_files(getattr(session, "_new_files", set()), "after_soft_rollback")
         cls.clear_session(session)
 
     @classmethod
-    def _after_delete(cls, mapper: Mapper, _: Connection, obj: Any) -> None:
-        """
-        After delete mark all linked files as old in order to delete
-        them when after session is committed
+    def _after_delete(cls, mapper: Mapper, _: Connection, obj: Any) -> None:  # type: ignore[type-arg]
+        """After delete mark all linked files as old in order to delete
+        them when after session is committed.
         """
         tracked_columns: List[str] = cls.mapped_entities.get(mapper.class_, [])
         for key in tracked_columns:
@@ -249,17 +243,18 @@ class FileFieldSessionTracker:
             if value is not None:
                 cls.add_old_files_to_session(
                     inspect(obj).session,
-                    [
-                        f["path"]
-                        for f in (value if isinstance(value, list) else [value])
-                    ],
+                    flatmap(
+                        [
+                            f["files"]
+                            for f in (value if isinstance(value, list) else [value])
+                        ]
+                    ),
                 )
 
     @classmethod
-    def _after_update(cls, mapper: Mapper, _: Connection, obj: Any) -> None:
-        """
-        After update, mark all edited files as old
-        in order to delete them when after session is committed
+    def _after_update(cls, mapper: Mapper, _: Connection, obj: Any) -> None:  # type: ignore[type-arg]
+        """After update, mark all edited files as old
+        in order to delete them when after session is committed.
         """
         tracked_columns: List[str] = cls.mapped_entities.get(mapper.class_, [])
         for key in tracked_columns:
@@ -269,9 +264,8 @@ class FileFieldSessionTracker:
             )
 
     @classmethod
-    def _before_update(cls, mapper: Mapper, _: Connection, obj: Any) -> None:
-        """
-        Before updating values, validate and save files. For multiple fields,
+    def _before_update(cls, mapper: Mapper, _: Connection, obj: Any) -> None:  # type: ignore[type-arg]
+        """Before updating values, validate and save files. For multiple fields,
         mark all removed files as old, as _removed attribute will be
         reinitialised after update.
         """
@@ -289,13 +283,15 @@ class FileFieldSessionTracker:
                     )
                 if isinstance(value, MutableList):
                     _removed = getattr(value, "_removed", ())
-                    cls.add_old_files_to_session(session, [f["path"] for f in _removed])
+                    cls.add_old_files_to_session(
+                        session, flatmap([f["files"] for f in _removed])
+                    )
 
     @classmethod
-    def _before_insert(cls, mapper: Mapper, _: Connection, obj: Any) -> None:
+    def _before_insert(cls, mapper: Mapper, _: Connection, obj: Any) -> None:  # type: ignore[type-arg]
         """Before inserting values, mark all created files as new. They will be
-        automatically removed when session rollback"""
-
+        automatically removed when session rollback.
+        """
         tracked_columns: List[str] = cls.mapped_entities.get(mapper.class_, [])
         for key in tracked_columns:
             value = getattr(obj, key)
@@ -308,26 +304,39 @@ class FileFieldSessionTracker:
 
     @classmethod
     def prepare_file_attr(
-        cls, mapper: Mapper, obj: Any, key: str
+        cls, mapper: Mapper, obj: Any, key: str  # type: ignore[type-arg]
     ) -> Tuple[bool, Union[File, List[File]]]:
-        """
-        Prepare file before saved to database, convert bytes and string,
-        saved file into the upload_storage, apply validators and processors
+        """Prepare file(s) for saving into the database by converting bytes or strings into
+        File objects, applying validators, uploading the file(s) to the upload storage,
+        and applying processors.
+
+        Arguments:
+            mapper (Mapper): The mapper instance associated with the object.
+            obj (Any): The object containing the file attribute.
+            key (str): The name of the file attribute.
+
+        Returns:
+            Tuple[bool, Union[File, List[File]]]: A tuple containing a boolean flag indicating
+            whether the file(s) were changed, and the prepared file object(s). If the column type
+            allows multiple files, the prepared file objects are returned as a list.
         """
         value = getattr(obj, key)
 
-        """Become True when it is new file for single field,
-        or when new items is added for multiple field"""
+        """
+        The `changed` flag becomes True in two cases:
+        1. For a single-field attribute, when a new file is assigned, replacing the previous file.
+        2. For a multiple-field attribute, when new file objects are added to the existing ones.
+        """
         changed = False
 
-        column_type = mapper.attrs.get(key).columns[0].type
+        column_type = mapper.attrs.get(key).columns[0].type  # type: ignore[misc,union-attr]
         assert isinstance(column_type, FileField)
         upload_type = column_type.upload_type
 
         prepared_values: List[File] = []
         for v in value if isinstance(value, list) else [value]:
             if not isinstance(v, upload_type):
-                v = upload_type(v)
+                v = upload_type(v)  # noqa: PLW2901
             if not getattr(v, "saved", False):
                 changed = True
                 v.apply_validators(column_type.validators, key)
@@ -351,8 +360,8 @@ class FileFieldSessionTracker:
 
     @classmethod
     def setup(cls) -> None:
-        event.listen(orm.mapper, "mapper_configured", cls._mapper_configured)
-        event.listen(orm.mapper, "after_configured", cls._after_configured)
+        event.listen(orm.Mapper, "mapper_configured", cls._mapper_configured)
+        event.listen(orm.Mapper, "after_configured", cls._after_configured)
         event.listen(Session, "after_commit", cls._after_commit)
         event.listen(Session, "after_soft_rollback", cls._after_soft_rollback)
 

{sqlalchemy_file-0.4.0.dev0 → sqlalchemy_file-0.5.0}/sqlalchemy_file/validators.py

@@ -15,8 +15,8 @@ if TYPE_CHECKING:
 
 
 class Validator:
-    """
-    Interface that must be implemented by file validators.
+    """Interface that must be implemented by file validators.
+
     File validators get executed before a file is stored on the database
     using one of the supported fields. Can be used to add additional data
     to file object or change it.
@@ -25,19 +25,17 @@ class Validator:
 
     @abstractmethod
     def process(self, file: "File", attr_key: str) -> None:  # pragma: no cover
-        """
-        Should be overridden in inherited class
+        """Should be overridden in inherited class.
 
         Parameters:
            file: [File][sqlalchemy_file.file.File] object
            attr_key: current SQLAlchemy column key. Can be passed to
                [ValidationError][sqlalchemy_file.exceptions.ValidationError]
         """
-        pass
 
 
 class SizeValidator(Validator):
-    """Validate file maximum size
+    """Validate file maximum size.
 
     Attributes:
         max_size:
@@ -56,6 +54,7 @@ class SizeValidator(Validator):
 
             For more information, view
             [Wikipedia: Binary prefix](https://en.wikipedia.org/wiki/Binary_prefix)
+
     Example:
         ```Python
         class Attachment(Base):
@@ -79,8 +78,7 @@ class SizeValidator(Validator):
         if file.size > convert_size(self.max_size):
             raise SizeValidationError(
                 attr_key,
-                "The file is too large (%s bytes). Allowed maximum size is %s."
-                % (file.size, self.max_size),
+                f"The file is too large ({file.size} bytes). Allowed maximum size is {self.max_size}.",
             )
 
 
@@ -119,13 +117,12 @@ class ContentTypeValidator(Validator):
         ):
             raise ContentTypeValidationError(
                 attr_key,
-                "File content_type %s is not allowed. Allowed content_types are: %s"
-                % (file.content_type, self.allowed_content_types),
+                f"File content_type {file.content_type} is not allowed. Allowed content_types are: {self.allowed_content_types}",
             )
 
 
 class ImageValidator(ContentTypeValidator):
-    """Default Validator for ImageField
+    """Default Validator for ImageField.
 
     Attributes:
         min_wh: Minimum allowed dimension (w, h).

sqlalchemy_file-0.4.0.dev0/sqlalchemy_file/__init__.py

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

sqlalchemy_file-0.4.0.dev0/sqlalchemy_file/stored_file.py

@@ -1,38 +0,0 @@
-import json
-import tempfile
-from typing import Optional
-
-from libcloud.storage.base import Object
-from libcloud.storage.types import ObjectDoesNotExistError
-from sqlalchemy_file.helpers import LOCAL_STORAGE_DRIVER_NAME
-
-
-class StoredFile:
-    def __init__(self, obj: Object) -> None:
-        if obj.driver.name == LOCAL_STORAGE_DRIVER_NAME:
-            """Retrieve metadata from associated metadata file"""
-            try:
-                metadata_obj = obj.container.get_object(f"{obj.name}.metadata.json")
-                obj.meta_data = json.load(open(metadata_obj.get_cdn_url()))
-            except ObjectDoesNotExistError:
-                pass
-        self.name = obj.name
-        self.filename = obj.meta_data.get("filename", "unnamed")
-        self.content_type = obj.extra.get(
-            "content_type",
-            obj.meta_data.get("content_type", "application/octet-stream"),
-        )
-        self.object = obj
-
-    def get_cdn_url(self) -> Optional[str]:
-        try:
-            return self.object.get_cdn_url()
-        except NotImplementedError:
-            return None
-
-    def read(self, n: int = -1) -> bytes:
-        if self.object.driver.name == LOCAL_STORAGE_DRIVER_NAME:
-            return open(self.object.get_cdn_url(), "rb").read(n)
-        _file = tempfile.NamedTemporaryFile()
-        self.object.download(_file.name, overwrite_existing=True)
-        return _file.read(n)