flatfs 0.0.0__tar.gz

flatfs-0.0.0/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright 2026 Maciej Wiatrzyk <maciej.wiatrzyk@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flatfs-0.0.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.3
+Name: flatfs
+Version: 0.0.0
+Summary: Minimal filesystem abstraction with pluggable backends, treating paths as keys and file contents as values.
+License: MIT
+Keywords: flat,filesystem,abstraction,library
+Author: Maciej Wiatrzyk
+Author-email: maciej.wiatrzyk@gmail.com
+Requires-Python: >=3.10,<4
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Project-URL: Bug Tracker, https://github.com/mwiatrzyk/flatfs/issues
+Project-URL: Repository, https://github.com/mwiatrzyk/flatfs
+Description-Content-Type: text/markdown
+
+# FlatFS
+
+Minimal filesystem abstraction with pluggable backends, treating paths as keys
+and file contents as values.
+
+## About
+
+FlatFS provides minimalistic protocol-based API for accessing files. The API
+allows you to:
+
+* create files using generator of binary chunks as source of data
+* read files in chunks
+* checking if file exists
+* removing file from the filesystem
+* scanning filesystem to retrieve all the files that are available
+
+The API from above is supplied with a rich set of helpers that can simplify
+common actions, like writing/reading whole files in text or binary mode,
+reading files line-by-line, reading exact amount of bytes etc.
+
+FlatFS does not use directories; those are just used to organize paths (aka
+keys) and some implementations may use real directories, and the other may not.
+
+The library is implemented in a way allowing it to be used with large files
+thanks to the generator-based core API.
+
+## Installation
+
+The project can be installed directly from PyPI:
+
+```shell
+$ pip install flatfs
+```
+
+You can alternatively use any of the existing Python package management tools
+(e.g. Poetry or uv) to install the library directly to your project.
+
+## Examples
+
+Here are some practical examples of how this library can be used:
+
+1. Access ``/tmp`` directory:
+
+    ```python
+    import pathlib
+
+    from flatfs.api import LocalFlatFs, FlatFsReaderWriter, write_text, read_text
+
+    def make_temp_fs() -> FlatFsReaderWriter:
+        return LocalFlatFs(pathlib.Path("/tmp"))
+
+    temp_fs = make_temp_fs()
+    write_text(temp_fs, "/foo/bar.txt", "content of file")  # Creates text file at /tmp/foo/bar.txt
+    content = read_text(temp_fs, "/foo/bar.txt")  # Read the content back
+    ```
+
+2. Create in-memory flat filesystem (this implementation can be used during testing):
+
+    ```python
+    from flatfs.api import InMemoryFlatFs
+
+    fs = InMemoryFlatFs()
+    fs.write_chunks("foo.txt", [b"spam"])
+    paths = list(fs.scan())  # Will return: ["/foo.txt"]
+    ```
+
+3. Wrap flat filesystem created earlier with async interface:
+
+    ```python
+    from flatfs.api import AsyncFlatFsAdapter, async_read_text
+
+    async_temp_fs = AsyncFlatFsAdapter(temp_fs)
+    content = await async_read_text(async_temp_fs, "foo/bar.txt")  # Paths are normalized and leading / is automatically added
+    print(content)  # Would print: content of file
+    ```
+
+## Rationale
+
+During developing of various systems and tools that follow clean architecture
+and layered design (business logic, use case interactors, data ports and
+gateways etc.) I found myself writing similar tool as one of the port/gateway
+pair over and over again. This library was created to have such toolkit a bit
+more advanced, based on chunk generators and producers, backed up with
+comprehensive set of helpers, just to avoid writing it again for the (N+1)th
+time.
+
+## Author
+
+Maciej Wiatrzyk <maciej.wiatrzyk@gmail.com>
+
+## License
+
+This project is released under the terms of the MIT license.
+
+See LICENSE.txt for more details.
+

flatfs-0.0.0/README.md

@@ -0,0 +1,95 @@
+# FlatFS
+
+Minimal filesystem abstraction with pluggable backends, treating paths as keys
+and file contents as values.
+
+## About
+
+FlatFS provides minimalistic protocol-based API for accessing files. The API
+allows you to:
+
+* create files using generator of binary chunks as source of data
+* read files in chunks
+* checking if file exists
+* removing file from the filesystem
+* scanning filesystem to retrieve all the files that are available
+
+The API from above is supplied with a rich set of helpers that can simplify
+common actions, like writing/reading whole files in text or binary mode,
+reading files line-by-line, reading exact amount of bytes etc.
+
+FlatFS does not use directories; those are just used to organize paths (aka
+keys) and some implementations may use real directories, and the other may not.
+
+The library is implemented in a way allowing it to be used with large files
+thanks to the generator-based core API.
+
+## Installation
+
+The project can be installed directly from PyPI:
+
+```shell
+$ pip install flatfs
+```
+
+You can alternatively use any of the existing Python package management tools
+(e.g. Poetry or uv) to install the library directly to your project.
+
+## Examples
+
+Here are some practical examples of how this library can be used:
+
+1. Access ``/tmp`` directory:
+
+    ```python
+    import pathlib
+
+    from flatfs.api import LocalFlatFs, FlatFsReaderWriter, write_text, read_text
+
+    def make_temp_fs() -> FlatFsReaderWriter:
+        return LocalFlatFs(pathlib.Path("/tmp"))
+
+    temp_fs = make_temp_fs()
+    write_text(temp_fs, "/foo/bar.txt", "content of file")  # Creates text file at /tmp/foo/bar.txt
+    content = read_text(temp_fs, "/foo/bar.txt")  # Read the content back
+    ```
+
+2. Create in-memory flat filesystem (this implementation can be used during testing):
+
+    ```python
+    from flatfs.api import InMemoryFlatFs
+
+    fs = InMemoryFlatFs()
+    fs.write_chunks("foo.txt", [b"spam"])
+    paths = list(fs.scan())  # Will return: ["/foo.txt"]
+    ```
+
+3. Wrap flat filesystem created earlier with async interface:
+
+    ```python
+    from flatfs.api import AsyncFlatFsAdapter, async_read_text
+
+    async_temp_fs = AsyncFlatFsAdapter(temp_fs)
+    content = await async_read_text(async_temp_fs, "foo/bar.txt")  # Paths are normalized and leading / is automatically added
+    print(content)  # Would print: content of file
+    ```
+
+## Rationale
+
+During developing of various systems and tools that follow clean architecture
+and layered design (business logic, use case interactors, data ports and
+gateways etc.) I found myself writing similar tool as one of the port/gateway
+pair over and over again. This library was created to have such toolkit a bit
+more advanced, based on chunk generators and producers, backed up with
+comprehensive set of helpers, just to avoid writing it again for the (N+1)th
+time.
+
+## Author
+
+Maciej Wiatrzyk <maciej.wiatrzyk@gmail.com>
+
+## License
+
+This project is released under the terms of the MIT license.
+
+See LICENSE.txt for more details.

flatfs-0.0.0/flatfs/_export.py

@@ -0,0 +1,12 @@
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+class Export(list):
+    """Helper for creating ``__all__`` module properties."""
+
+    def __call__(self, func_or_cls: T) -> T:
+        name = getattr(func_or_cls, "__name__")
+        self.append(name)
+        return func_or_cls

flatfs-0.0.0/flatfs/_utils.py

@@ -0,0 +1,52 @@
+import asyncio
+import functools
+from typing import Callable, TypeVar
+
+from flatfs.exc import PathAccessError
+
+T = TypeVar("T")
+
+
+def normalize_path(path: str) -> str:
+    """Normalizes path by removing duplicated slash characters and by
+    evaluating relative path components (e.g. ``../`` or ``./``).
+
+    Returns normalized path, or raises :exc:`flatfs.exc.FileAccessError` if
+    final path would go beyond filesystem bounds.
+
+    :param path:
+        The path to normalize.
+    """
+    parts: list[str] = []
+    for part in path.split("/"):
+        if not part or part == ".":
+            continue
+        if part == "..":
+            if not parts:
+                raise PathAccessError(path)
+            parts.pop()
+        else:
+            parts.append(part)
+    out = "/".join(parts)
+    if out[0] == "/":
+        return out
+    return "/" + out
+
+
+async def run_blocking(func: Callable[..., T], *args, **kwargs) -> T:
+    """Run blocking (i.e. non-async) task in an event loop's default
+    executor.
+
+    On success, return *func*'s result, on failure raise *func*'s exception.
+
+    :param func:
+        The non-async callable to run.
+
+    :param `*args`:
+        Positional args to be passed to *func*.
+
+    :param `**kwargs`:
+        Named args to be passed to *func*.
+    """
+    wrapped_func = functools.partial(func, *args, **kwargs)
+    return await asyncio.get_running_loop().run_in_executor(None, wrapped_func)

flatfs-0.0.0/flatfs/api.py

@@ -0,0 +1,13 @@
+"""The all-in-one import helper for FlatFS public API."""
+
+from .backends import __all__ as _backends_all
+from .exc import __all__ as _exc_all
+from .helpers import __all__ as _helpers_all
+from .interface import __all__ as _interface_all
+
+from .backends import *
+from .exc import *
+from .helpers import *
+from .interface import *
+
+__all__ = _backends_all + _exc_all + _helpers_all + _interface_all  # type: ignore

flatfs-0.0.0/flatfs/backends.py

@@ -0,0 +1,227 @@
+import asyncio
+import fnmatch
+import os
+import pathlib
+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 . import _utils, _export
+
+__all__ = export = _export.Export()  # type: ignore
+
+
+@export
+class LocalFlatFs:
+    """FlatFS implementation using local filesystem to store files.
+
+    You can use this to access files from an existing directory (the paths are
+    then relative to *root_dir*), or to create a completely new filesystem
+    inside an empty directory.
+
+    :param root_dir:
+        The path to the root directory where files will be stored.
+
+    :param exclude:
+        The glob patterns of paths to exclude.
+
+        For example, you may want to exclude ``.git`` directory when you use
+        FlatFS to access content of some Git repository.
+
+        For more details on pattern syntax used check :mod:`fnmatch` which is
+        used underneath.
+
+    :param include:
+        The glob patterns of paths to include.
+
+        These can only be paths from inside root directory. For example, you
+        may wish to allow just ``src`` and ``test`` dirs, not all files.
+
+        For more details on pattern syntax used check :mod:`fnmatch` which is
+        used underneath.
+    """
+
+    def __init__(self, root_dir: pathlib.Path, exclude: Optional[set[str]] = None, include: Optional[set[str]] = None):
+        self.__root_dir = root_dir
+        self.__exclude = exclude or set()
+        self.__include = include or set()
+
+    def __is_excluded(self, normalized_path: str) -> bool:
+        for pattern in self.__exclude:
+            if fnmatch.fnmatch(normalized_path, pattern):
+                return True
+        return False
+
+    def __is_included(self, normalized_path: str) -> bool:
+        if not self.__include:
+            return True
+        for pattern in self.__include:
+            if fnmatch.fnmatch(normalized_path, pattern):
+                return True
+        return False
+
+    def __make_abspath(self, path: str) -> pathlib.Path:
+        normalized_path = _utils.normalize_path(path)
+        if self.__is_excluded(normalized_path):
+            raise PathAccessError(path)
+        return self.__root_dir / normalized_path[1:]
+
+    def __walk(self, path: pathlib.Path, relpath: str):
+        for name in os.listdir(path):
+            fullpath = path / name
+            fullrelpath = f"{relpath}/{name}"
+            if fullpath.is_dir():
+                yield from self.__walk(fullpath, fullrelpath)
+            elif not self.__is_excluded(fullrelpath) and self.__is_included(fullrelpath):
+                yield fullrelpath
+
+    def scan(self) -> Iterator[str]:
+        return self.__walk(self.__root_dir, "")
+
+    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]:
+        abspath = self.__make_abspath(path)
+        if not abspath.is_file():
+            raise PathNotFoundError(path)
+        with abspath.open("rb") as fd:
+            while True:
+                chunk = fd.read(chunk_size)
+                if not chunk:
+                    break
+                yield chunk
+
+    def write_chunks(self, path: str, chunks: Iterable[bytes]):
+        abspath = self.__make_abspath(path)
+        abspath.parent.mkdir(parents=True, exist_ok=True)
+        with abspath.open("wb") as fd:
+            for chunk in chunks:
+                fd.write(chunk)
+
+    def remove(self, path: str):
+        abspath = self.__make_abspath(path)
+        if not abspath.is_file():
+            raise PathNotFoundError(path)
+        abspath.unlink()
+
+
+@export
+class InMemoryFlatFs:
+    """In-memory FlatFS implementation.
+
+    This is mostly suitable for use during testing to avoid unnecessary I/O and
+    disk usage.
+    """
+
+    def __init__(self) -> None:
+        self.__storage: dict[str, bytes] = {}
+
+    def __make_key(self, path: str) -> str:
+        normalized_key = _utils.normalize_path(path)
+        return normalized_key
+
+    def scan(self) -> Iterator[str]:
+        return iter(self.__storage.keys())
+
+    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]:
+        key = self.__make_key(path)
+        if key not in self.__storage:
+            raise PathNotFoundError(path)
+        data_left = self.__storage[key]
+        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 remove(self, path: str):
+        key = self.__make_key(path)
+        if key not in self.__storage:
+            raise PathNotFoundError(path)
+        del self.__storage[key]
+
+
+@export
+class AsyncFlatFsAdapter:
+    """Adapter that wraps given :class:`flatfs.interface.FlatFsReaderWriter`
+    with async interface.
+
+    You can use this to adapt e.g. :class:`LocalFlatFs` or
+    :class:`InMemoryFlatFs` objects with async interface allowing for
+    convenient use with async code. The blocking calls are dispatched to
+    background worker which communicates with the caller using queues.
+
+    :param target:
+        The target FlatFS reader-writer to wrap.
+    """
+
+    def __init__(self, target: FlatFsReaderWriter):
+        self.__target = target
+
+    async def scan(self) -> AsyncGenerator[str, None]:
+
+        def scanner():
+            for path in self.__target.scan():
+                loop.call_soon_threadsafe(queue.put_nowait, path)
+            loop.call_soon_threadsafe(queue.put_nowait, "")
+
+        loop = asyncio.get_running_loop()
+        asyncio.create_task(_utils.run_blocking(scanner))
+        queue: asyncio.Queue[str] = asyncio.Queue()
+        while True:
+            path = await queue.get()
+            if not path:
+                break
+            yield path
+
+    async def exists(self, path: str) -> bool:
+        return await _utils.run_blocking(self.__target.exists, path)
+
+    async def read_chunks(self, path: str, chunk_size: int = 65535) -> AsyncGenerator[bytes, None]:
+
+        def reader():
+            try:
+                for chunk in self.__target.read_chunks(path, chunk_size):
+                    loop.call_soon_threadsafe(queue.put_nowait, chunk)
+                loop.call_soon_threadsafe(queue.put_nowait, b"")
+            except Exception as e:
+                loop.call_soon_threadsafe(queue.put_nowait, e)
+
+        loop = asyncio.get_running_loop()
+        queue: asyncio.Queue[bytes | Exception] = asyncio.Queue()
+        asyncio.create_task(_utils.run_blocking(reader))
+        while True:
+            chunk_or_exc = await queue.get()
+            if not chunk_or_exc:
+                break
+            if isinstance(chunk_or_exc, Exception):
+                raise chunk_or_exc
+            yield chunk_or_exc
+
+    async def write_chunks(self, path: str, chunks: AsyncIterable[bytes]):
+
+        def gen() -> Generator[bytes, None, None]:
+            while True:
+                chunk = queue.get()
+                if not chunk:
+                    return
+                yield chunk
+
+        queue: Queue[bytes] = Queue()
+        task = asyncio.create_task(_utils.run_blocking(self.__target.write_chunks, path, gen()))
+        async for chunk in chunks:
+            queue.put(chunk)
+        queue.put(b"")
+        await task
+
+    async def remove(self, path: str):
+        await _utils.run_blocking(self.__target.remove, path)

flatfs-0.0.0/flatfs/exc.py

@@ -0,0 +1,42 @@
+from typing import Optional
+
+from . import _export
+
+__all__ = export = _export.Export()  # type: ignore
+
+
+@export
+class FlatFsError(Exception):
+    """Base class for exceptions raised by this library."""
+
+    #: Message template or ``None`` to use default ``__str__`` implementation.
+    __message_template__: Optional[str] = None
+
+    def __str__(self) -> str:
+        if self.__message_template__ is None:
+            return super().__str__()
+        return self.__message_template__.format(self=self)
+
+
+@export
+class PathError(FlatFsError):
+    """Base class for path-related errors."""
+
+    __message_template__ = "{self.path}"
+
+    #: Path that caused error.
+    path: str
+
+    def __init__(self, path: str):
+        super().__init__()
+        self.path = path
+
+
+@export
+class PathNotFoundError(PathError):
+    """Raised when file was not found."""
+
+
+@export
+class PathAccessError(PathError):
+    """Raised when file that is tried to be accessed lays beyond filesystem bounds."""

flatfs-0.0.0/flatfs/helpers.py

@@ -0,0 +1,124 @@
+from . import _export
+from .interface import SupportsAsyncReadChunks, SupportsAsyncWriteChunks, SupportsReadChunks, SupportsWriteChunks
+
+__all__ = export = _export.Export()  # type: ignore
+
+
+@export
+def read_bytes(fs: SupportsReadChunks, path: str, chunk_size: int = 65535) -> bytes:
+    """Read whole file and return as bytes.
+
+    :param fs:
+        FlatFS object to read from.
+
+    :param path:
+        Path to a file to read.
+
+    :param chunk_size:
+        The chunk size to use during read.
+
+        This is the maximum number of bytes to read from a file per single read
+        operation.
+
+        Defaults to 64kB.
+    """
+    out = b""
+    for chunk in fs.read_chunks(path, chunk_size):
+        out += chunk
+    return out
+
+
+@export
+def write_bytes(fs: SupportsWriteChunks, path: str, data: bytes, chunk_size: int = 65535):
+    """Write given data to file at given path either creating the file, or
+    replacing with new content.
+
+    :param fs:
+        FlatFS object to write to.
+
+    :param path:
+        The path to a file to create or replace.
+
+    :param data:
+        The data to write.
+
+    :param chunk_size:
+        The chunk size to use during writing.
+
+        If *data* length is greater, it will be split into chunks and written
+        chunk by chunk, with each chunk having at most *chunk_size* bytes.
+
+        Defaults to 64kB.
+    """
+
+    def gen():
+        data_left = data
+        while True:
+            chunk = data_left[:chunk_size]
+            if not chunk:
+                break
+            data_left = data_left[chunk_size:]
+            yield chunk
+
+    fs.write_chunks(path, gen())
+
+
+@export
+def read_text(fs: SupportsReadChunks, path: str, encoding: str = "utf-8", chunk_size: int = 65535) -> str:
+    """Read whole text file and return as string.
+
+    Uses :func:`read_bytes` underneath and then just decodes its output using
+    provided *encoding*, which is ``utf-8`` by default.
+    """
+    return read_bytes(fs, path, chunk_size).decode(encoding)
+
+
+@export
+def write_text(fs: SupportsWriteChunks, path: str, data: str, encoding: str = "utf-8", chunk_size: int = 65535):
+    """Create new text file or replace existing with given text data.
+
+    Uses :func:`write_bytes` underneath and just encodes given *data* with
+    provided *encoding*, which is ``utf-8`` by default.
+    """
+    return write_bytes(fs, path, data.encode(encoding), chunk_size)
+
+
+@export
+async def async_read_bytes(fs: SupportsAsyncReadChunks, path: str, chunk_size: int = 65535) -> bytes:
+    """Same as :func:`read_bytes`, but for async code."""
+    out = b""
+    async for chunk in fs.read_chunks(path, chunk_size):
+        out += chunk
+    return out
+
+
+@export
+async def async_write_bytes(fs: SupportsAsyncWriteChunks, path: str, data: bytes, chunk_size: int = 65535):
+    """Same as :func:`write_bytes`, but for async code."""
+
+    async def gen():
+        data_left = data
+        while True:
+            chunk = data_left[:chunk_size]
+            if not chunk:
+                break
+            data_left = data_left[chunk_size:]
+            yield chunk
+
+    await fs.write_chunks(path, gen())
+
+
+@export
+async def async_read_text(
+    fs: SupportsAsyncReadChunks, path: str, encoding: str = "utf-8", chunk_size: int = 65535
+) -> str:
+    """Same as :func:`read_text`, but for async code."""
+    return (await async_read_bytes(fs, path, chunk_size)).decode(encoding)
+
+
+@export
+async def async_write_text(
+    fs: SupportsAsyncWriteChunks, path: str, data: str, encoding: str = "utf-8", chunk_size: int = 65535
+):
+    """Same as :func:`write_text`, but for async code."""
+    await async_write_bytes(fs, path, data.encode(encoding), chunk_size)

flatfs-0.0.0/flatfs/interface.py

@@ -0,0 +1,149 @@
+from typing import AsyncGenerator, AsyncIterable, Iterable, Iterator, Protocol
+
+from . import _export
+
+__all__ = export = _export.Export()  # type: ignore
+
+
+@export
+class SupportsReadChunks(Protocol):
+    """Protocol for objects that support chunked reading."""
+
+    def read_chunks(self, path: str, chunk_size: int = 65535) -> Iterator[bytes]:
+        """Read file in chunks and return iterator yielding chunks.
+
+        This method can be safely used with large files without the risk of
+        getting out of memory.
+
+        If *path* does not point to an existing file,
+        :exc:`flatfs.exc.PathNotFoundError` will be raised.
+
+        :param path:
+            The path to a file to read.
+
+        :param chunk_size:
+            The maximum chunk size (in bytes).
+
+            This is the maximum length of a single generated bytes object.
+        """
+        ...
+
+
+@export
+class SupportsWriteChunks(Protocol):
+    """Protocol for object that support writing in chunks."""
+
+    def write_chunks(self, path: str, chunks: Iterable[bytes]):
+        """Create or overwrite file at given *path* and write chunks of data
+        generated by provided *chunks* iterable.
+
+        :param path:
+            The path to a file to create or modify.
+
+        :param chunks:
+            Iterable providing chunks of bytes to write to a file.
+        """
+        ...
+
+
+@export
+class FlatFsReader(SupportsReadChunks, Protocol):
+    """Read-only interface to access files in the flat filesystem."""
+
+    def scan(self) -> Iterator[str]:
+        """Scan filesystem and generate paths to existing files.
+
+        Each yielded path can later be used with other methods of this
+        interface.
+        """
+        ...
+
+    def exists(self, path: str) -> bool:
+        """Check if *path* points to an existing file."""
+        ...
+
+
+@export
+class FlatFsReaderWriter(FlatFsReader, SupportsWriteChunks, Protocol):
+    """Read-write interface to access files in the flat filesystem."""
+
+    def remove(self, path: str):
+        """Remove file at given *path*.
+
+        Raises :exc:`flatfs.exc.PathNotFoundError` if there was no file to
+        remove at given *path*.
+
+        :param path:
+            The path to a file to remove.
+        """
+        ...
+
+
+@export
+class SupportsAsyncReadChunks(Protocol):
+    def read_chunks(self, path: str, chunk_size: int = 65535) -> AsyncGenerator[bytes, None]:
+        """Read file in chunks and return iterator yielding chunks.
+
+        This method can be safely used with large files without the risk of
+        getting out of memory.
+
+        If *path* does not point to an existing file,
+        :exc:`flatfs.exc.PathNotFoundError` will be raised.
+
+        :param path:
+            The path to a file to read.
+
+        :param chunk_size:
+            The maximum chunk size (in bytes).
+
+            This is the maximum length of a single generated bytes object.
+        """
+        ...
+
+
+@export
+class SupportsAsyncWriteChunks(Protocol):
+    async def write_chunks(self, path: str, chunks: AsyncIterable[bytes]):
+        """Create or overwrite file at given *path* and write chunks of data
+        generated by provided *chunks* iterable.
+
+        :param path:
+            The path to a file to create or modify.
+
+        :param chunks:
+            Iterable providing chunks of bytes to write to a file.
+        """
+        ...
+
+
+@export
+class AsyncFlatFsReader(SupportsAsyncReadChunks, Protocol):
+    """Async read-only interface to access files in the flat filesystem."""
+
+    def scan(self) -> AsyncGenerator[str, None]:
+        """Scan filesystem and generate paths to existing files.
+
+        Each yielded path can later be used with other methods of this
+        interface.
+        """
+        ...
+
+    async def exists(self, path: str) -> bool:
+        """Check if *path* points to an existing file."""
+        ...
+
+
+@export
+class AsyncFlatFsReaderWriter(AsyncFlatFsReader, SupportsAsyncWriteChunks, Protocol):
+    """Async read-write interface to access files in the flat filesystem."""
+
+    async def remove(self, path: str):
+        """Remove file at given *path*.
+
+        Raises :exc:`flatfs.exc.PathNotFoundError` if there was no file to
+        remove at given *path*.
+
+        :param path:
+            The path to a file to remove.
+        """
+        ...

flatfs-0.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "flatfs"
+version = "0.0.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"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+keywords = ["flat", "filesystem", "abstraction", "library"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    #"Development Status :: 5 - Production/Stable"  <- Use this for first 1.x version
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries",
+]
+requires-python = ">=3.10,<4"
+dependencies = [
+]
+
+[project.urls]
+repository = "https://github.com/mwiatrzyk/flatfs"
+"Bug Tracker" = "https://github.com/mwiatrzyk/flatfs/issues"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.0.3"
+invoke = "^3.0.3"
+pytest-asyncio = "^1.3.0"
+mockify = "^0.14.0"
+pytest-cov = "^7.1.0"
+ruff = "^0.15.12"
+mypy = "^2.0.0"