flatfs 0.0.0__tar.gz → 0.2.0__tar.gz

{flatfs-0.0.0 → flatfs-0.2.0}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: flatfs
-Version: 0.0.0
+Version: 0.2.0
 Summary: Minimal filesystem abstraction with pluggable backends, treating paths as keys and file contents as values.
 License: MIT
+License-File: LICENSE.txt
 Keywords: flat,filesystem,abstraction,library
 Author: Maciej Wiatrzyk
 Author-email: maciej.wiatrzyk@gmail.com

flatfs-0.2.0/flatfs/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{flatfs-0.0.0 → flatfs-0.2.0}/flatfs/_utils.py

@@ -1,4 +1,5 @@
 import asyncio
+import datetime
 import functools
 from typing import Callable, TypeVar
 
@@ -50,3 +51,8 @@ async def run_blocking(func: Callable[..., T], *args, **kwargs) -> T:
     """
     wrapped_func = functools.partial(func, *args, **kwargs)
     return await asyncio.get_running_loop().run_in_executor(None, wrapped_func)
+
+
+def utcnow() -> datetime.datetime:
+    """Get the current date and time in UTC."""
+    return datetime.datetime.now(datetime.timezone.utc)

{flatfs-0.0.0 → flatfs-0.2.0}/flatfs/backends.py

@@ -1,4 +1,6 @@
 import asyncio
+import dataclasses
+import datetime
 import fnmatch
 import os
 import pathlib
@@ -6,7 +8,7 @@ from queue import Queue
 from typing import AsyncGenerator, AsyncIterable, Generator, Iterable, Iterator, Optional
 
 from flatfs.exc import PathAccessError, PathNotFoundError
-from flatfs.interface import FlatFsReaderWriter
+from flatfs.interface import FlatFsReaderWriter, Stat
 
 from . import _utils, _export
 
@@ -80,11 +82,21 @@ class LocalFlatFs:
     def scan(self) -> Iterator[str]:
         return self.__walk(self.__root_dir, "")
 
+    def stat(self, path: str) -> Stat:
+        abspath = self.__make_abspath(path)
+        if not abspath.is_file():
+            raise PathNotFoundError(path)
+        stat_result = abspath.stat()
+        return Stat(
+            modified=datetime.datetime.fromtimestamp(stat_result.st_mtime, datetime.timezone.utc),
+            size=stat_result.st_size,
+        )
+
     def exists(self, path: str) -> bool:
         abspath = self.__make_abspath(path)
         return abspath.is_file()
 
-    def read_chunks(self, path: str, chunk_size: int = 65535) -> Iterator[bytes]:
+    def read_chunks(self, path: str, chunk_size: int = 65535) -> Generator[bytes, None, None]:
         abspath = self.__make_abspath(path)
         if not abspath.is_file():
             raise PathNotFoundError(path)
@@ -95,12 +107,14 @@ class LocalFlatFs:
                     break
                 yield chunk
 
-    def write_chunks(self, path: str, chunks: Iterable[bytes]):
+    def write_chunks(self, path: str, chunks: Iterable[bytes]) -> int:
         abspath = self.__make_abspath(path)
         abspath.parent.mkdir(parents=True, exist_ok=True)
+        total_bytes = 0
         with abspath.open("wb") as fd:
             for chunk in chunks:
-                fd.write(chunk)
+                total_bytes += fd.write(chunk)
+        return total_bytes
 
     def remove(self, path: str):
         abspath = self.__make_abspath(path)
@@ -117,8 +131,13 @@ class InMemoryFlatFs:
     disk usage.
     """
 
+    @dataclasses.dataclass
+    class _File:
+        payload: bytes
+        stat: Stat
+
     def __init__(self) -> None:
-        self.__storage: dict[str, bytes] = {}
+        self.__storage: dict[str, InMemoryFlatFs._File] = {}
 
     def __make_key(self, path: str) -> str:
         normalized_key = _utils.normalize_path(path)
@@ -127,21 +146,34 @@ class InMemoryFlatFs:
     def scan(self) -> Iterator[str]:
         return iter(self.__storage.keys())
 
+    def stat(self, path: str) -> Stat:
+        key = self.__make_key(path)
+        if key not in self.__storage:
+            raise PathNotFoundError(path)
+        return self.__storage[key].stat
+
     def exists(self, path: str) -> bool:
         return self.__make_key(path) in self.__storage
 
-    def read_chunks(self, path: str, chunk_size: int = 65535) -> Iterator[bytes]:
+    def read_chunks(self, path: str, chunk_size: int = 65535) -> Generator[bytes, None, None]:
         key = self.__make_key(path)
         if key not in self.__storage:
             raise PathNotFoundError(path)
-        data_left = self.__storage[key]
+        data_left = self.__storage[key].payload
         while len(data_left) > 0:
             chunk = data_left[:chunk_size]
             data_left = data_left[chunk_size:]
             yield chunk
 
-    def write_chunks(self, path: str, chunks: Iterable[bytes]):
-        self.__storage[self.__make_key(path)] = b"".join(chunks)
+    def write_chunks(self, path: str, chunks: Iterable[bytes]) -> int:
+        payload = b"".join(chunks)
+        now = _utils.utcnow()
+        stat = Stat(
+            modified=now,
+            size=len(payload),
+        )
+        self.__storage[self.__make_key(path)] = self._File(payload, stat)
+        return stat.size
 
     def remove(self, path: str):
         key = self.__make_key(path)
@@ -186,6 +218,9 @@ class AsyncFlatFsAdapter:
     async def exists(self, path: str) -> bool:
         return await _utils.run_blocking(self.__target.exists, path)
 
+    async def stat(self, path: str) -> Stat:
+        return await _utils.run_blocking(self.__target.stat, path)
+
     async def read_chunks(self, path: str, chunk_size: int = 65535) -> AsyncGenerator[bytes, None]:
 
         def reader():
@@ -207,7 +242,7 @@ class AsyncFlatFsAdapter:
                 raise chunk_or_exc
             yield chunk_or_exc
 
-    async def write_chunks(self, path: str, chunks: AsyncIterable[bytes]):
+    async def write_chunks(self, path: str, chunks: AsyncIterable[bytes]) -> int:
 
         def gen() -> Generator[bytes, None, None]:
             while True:
@@ -221,7 +256,7 @@ class AsyncFlatFsAdapter:
         async for chunk in chunks:
             queue.put(chunk)
         queue.put(b"")
-        await task
+        return await task
 
     async def remove(self, path: str):
         await _utils.run_blocking(self.__target.remove, path)

{flatfs-0.0.0 → flatfs-0.2.0}/flatfs/helpers.py

@@ -29,10 +29,12 @@ def read_bytes(fs: SupportsReadChunks, path: str, chunk_size: int = 65535) -> by
 
 
 @export
-def write_bytes(fs: SupportsWriteChunks, path: str, data: bytes, chunk_size: int = 65535):
+def write_bytes(fs: SupportsWriteChunks, path: str, data: bytes, chunk_size: int = 65535) -> int:
     """Write given data to file at given path either creating the file, or
     replacing with new content.
 
+    Returns the number of bytes written.
+
     :param fs:
         FlatFS object to write to.
 
@@ -60,7 +62,7 @@ def write_bytes(fs: SupportsWriteChunks, path: str, data: bytes, chunk_size: int
             data_left = data_left[chunk_size:]
             yield chunk
 
-    fs.write_chunks(path, gen())
+    return fs.write_chunks(path, gen())
 
 
 @export
@@ -93,7 +95,7 @@ async def async_read_bytes(fs: SupportsAsyncReadChunks, path: str, chunk_size: i
 
 
 @export
-async def async_write_bytes(fs: SupportsAsyncWriteChunks, path: str, data: bytes, chunk_size: int = 65535):
+async def async_write_bytes(fs: SupportsAsyncWriteChunks, path: str, data: bytes, chunk_size: int = 65535) -> int:
     """Same as :func:`write_bytes`, but for async code."""
 
     async def gen():
@@ -105,7 +107,7 @@ async def async_write_bytes(fs: SupportsAsyncWriteChunks, path: str, data: bytes
             data_left = data_left[chunk_size:]
             yield chunk
 
-    await fs.write_chunks(path, gen())
+    return await fs.write_chunks(path, gen())
 
 
 @export
@@ -122,3 +124,35 @@ async def async_write_text(
 ):
     """Same as :func:`write_text`, but for async code."""
     await async_write_bytes(fs, path, data.encode(encoding), chunk_size)
+
+
+@export
+class BinaryReader:
+    """Helper for reading bytes from a file."""
+
+    def __init__(self, fs: SupportsReadChunks, path: str, chunk_size: int = 65535):
+        self.__chunk_gen = fs.read_chunks(path, chunk_size)
+        self.__current_chunk = b""
+
+    def read(self, count: int) -> bytes:
+        """Read at most *count* bytes from an open file.
+
+        :param count:
+            The maximum number of bytes to read.
+        """
+        if not self.__current_chunk:
+            self.__current_chunk = next(self.__chunk_gen, b"")
+        fragment = self.__current_chunk[:count]
+        self.__current_chunk = self.__current_chunk[count:]
+        return fragment
+
+    def close(self):
+        """Close this reader.
+
+        This also closes the underlying file that is opened by flat filesystem
+        object given in the constructor.
+
+        This method is idempotent.
+        """
+        self.__current_chunk = b""
+        self.__chunk_gen.close()

{flatfs-0.0.0 → flatfs-0.2.0}/flatfs/interface.py

@@ -1,15 +1,29 @@
-from typing import AsyncGenerator, AsyncIterable, Iterable, Iterator, Protocol
+import dataclasses
+import datetime
+from typing import AsyncGenerator, AsyncIterable, Generator, Iterable, Iterator, Protocol
 
 from . import _export
 
 __all__ = export = _export.Export()  # type: ignore
 
 
+@export
+@dataclasses.dataclass
+class Stat:
+    """Object containing file stats."""
+
+    #: The file last modification date and time (in UTC).
+    modified: datetime.datetime
+
+    #: The file size in bytes.
+    size: int
+
+
 @export
 class SupportsReadChunks(Protocol):
     """Protocol for objects that support chunked reading."""
 
-    def read_chunks(self, path: str, chunk_size: int = 65535) -> Iterator[bytes]:
+    def read_chunks(self, path: str, chunk_size: int = 65535) -> Generator[bytes, None, None]:
         """Read file in chunks and return iterator yielding chunks.
 
         This method can be safely used with large files without the risk of
@@ -33,10 +47,13 @@ class SupportsReadChunks(Protocol):
 class SupportsWriteChunks(Protocol):
     """Protocol for object that support writing in chunks."""
 
-    def write_chunks(self, path: str, chunks: Iterable[bytes]):
+    def write_chunks(self, path: str, chunks: Iterable[bytes]) -> int:
         """Create or overwrite file at given *path* and write chunks of data
         generated by provided *chunks* iterable.
 
+        Returns the total number of bytes written, which is equal to the size
+        of a resulting file.
+
         :param path:
             The path to a file to create or modify.
 
@@ -58,8 +75,23 @@ class FlatFsReader(SupportsReadChunks, Protocol):
         """
         ...
 
+    def stat(self, path: str) -> Stat:
+        """Get stats of a file at given *path*.
+
+        If the file does not exist, :exc:`flatfs.exc.PathNotFoundError` will be
+        raised.
+
+        :param path:
+            The path to a file.
+        """
+        ...
+
     def exists(self, path: str) -> bool:
-        """Check if *path* points to an existing file."""
+        """Check if *path* points to an existing file.
+
+        :param path:
+            The path to a file.
+        """
         ...
 
 
@@ -103,10 +135,13 @@ class SupportsAsyncReadChunks(Protocol):
 
 @export
 class SupportsAsyncWriteChunks(Protocol):
-    async def write_chunks(self, path: str, chunks: AsyncIterable[bytes]):
+    async def write_chunks(self, path: str, chunks: AsyncIterable[bytes]) -> int:
         """Create or overwrite file at given *path* and write chunks of data
         generated by provided *chunks* iterable.
 
+        Returns the total number of bytes written, which is equal to the size
+        of a resulting file.
+
         :param path:
             The path to a file to create or modify.
 
@@ -128,6 +163,17 @@ class AsyncFlatFsReader(SupportsAsyncReadChunks, Protocol):
         """
         ...
 
+    async def stat(self, path: str) -> Stat:
+        """Get stats of a file at given *path*.
+
+        If the file does not exist, :exc:`flatfs.exc.PathNotFoundError` will be
+        raised.
+
+        :param path:
+            The path to a file.
+        """
+        ...
+
     async def exists(self, path: str) -> bool:
         """Check if *path* points to an existing file."""
         ...

{flatfs-0.0.0 → flatfs-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flatfs"
-version = "0.0.0"
+version = "0.2.0"
 description = "Minimal filesystem abstraction with pluggable backends, treating paths as keys and file contents as values."
 authors = [
     {name = "Maciej Wiatrzyk", email = "maciej.wiatrzyk@gmail.com"}
@@ -35,3 +35,4 @@ mockify = "^0.14.0"
 pytest-cov = "^7.1.0"
 ruff = "^0.15.12"
 mypy = "^2.0.0"
+bumpify = "^0.5.1"