barecat 0.3.2__py3-none-any.whl

barecat/__init__.py

@@ -0,0 +1,108 @@
+"""Barecat is a fast random-access, mountable archive format for storing and accessing many small
+files."""
+
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = '0.0.0.dev0'
+
+# Core classes
+from .core.barecat import Barecat
+from .core.index import Index
+from .core.sharder import Sharder
+
+# Data types
+from .core.types import (
+    BarecatDirInfo,
+    BarecatEntryInfo,
+    BarecatFileInfo,
+    Order,
+    SHARD_SIZE_UNLIMITED,
+)
+
+# File objects
+from .io.fileobj import (
+    BarecatFileObject,
+    BarecatReadOnlyFileObject,
+    BarecatReadWriteFileObject,
+)
+
+# Codec view
+from .io.codecs import DecodedView
+
+# Exceptions
+from .exceptions import (
+    BarecatError,
+    BarecatIntegrityError,
+    DirectoryNotEmptyBarecatError,
+    FileExistsBarecatError,
+    FileNotFoundBarecatError,
+    FileTooLargeBarecatError,
+    IsADirectoryBarecatError,
+    NotADirectoryBarecatError,
+    NotEnoughSpaceBarecatError,
+)
+
+# CLI utilities (for programmatic use)
+from .cli.impl import (
+    archive2barecat,
+    barecat2archive,
+    extract,
+    merge,
+    merge_symlink,
+    read_index,
+    write_index,
+)
+from .cli.completions import get_completion_script
+
+# Archive utilities
+from .util.misc import exists, remove
+
+# Convenience API
+from ._api import get_cached_reader, open
+
+__all__ = [
+    # Version
+    '__version__',
+    # Core classes
+    'Barecat',
+    'Index',
+    'Sharder',
+    # Data types
+    'BarecatDirInfo',
+    'BarecatEntryInfo',
+    'BarecatFileInfo',
+    'Order',
+    'SHARD_SIZE_UNLIMITED',
+    # File objects
+    'BarecatFileObject',
+    'BarecatReadOnlyFileObject',
+    'BarecatReadWriteFileObject',
+    # Codec view
+    'DecodedView',
+    # Exceptions
+    'BarecatError',
+    'BarecatIntegrityError',
+    'DirectoryNotEmptyBarecatError',
+    'FileExistsBarecatError',
+    'FileNotFoundBarecatError',
+    'FileTooLargeBarecatError',
+    'IsADirectoryBarecatError',
+    'NotADirectoryBarecatError',
+    'NotEnoughSpaceBarecatError',
+    # CLI utilities
+    'archive2barecat',
+    'barecat2archive',
+    'extract',
+    'merge',
+    'merge_symlink',
+    'read_index',
+    'write_index',
+    'get_completion_script',
+    # Archive utilities
+    'exists',
+    'remove',
+    # Convenience API
+    'get_cached_reader',
+    'open',
+]

barecat/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running barecat as a module: python -m barecat"""
+
+from .cli.main import main
+
+main()

barecat/_api.py

@@ -0,0 +1,143 @@
+"""High-level convenience functions for opening Barecat archives."""
+
+import functools
+import warnings
+
+from .core.barecat import Barecat
+
+
+def open(path, mode='r', auto_codec=False, threadsafe_reader=True):
+    """Open a Barecat archive.
+
+    .. deprecated::
+        Use ``Barecat(path, readonly=True)`` or ``Barecat(path, readonly=False)`` directly.
+
+    Args:
+        path: Path to the archive (without suffix).
+        mode: 'r' (read), 'r+' (read-write), 'w+' (overwrite), 'a+' (append), 'x+' (exclusive create).
+        auto_codec: **Deprecated.** Use :class:`DecodedView` instead. Will be removed in 1.0.
+        threadsafe_reader: Use thread-local storage for read mode. Default: True.
+
+    Returns:
+        Barecat: The opened archive.
+    """
+    warnings.warn(
+        'barecat.open() is deprecated and will be removed in version 1.0. '
+        'Use Barecat(path, readonly=True) or Barecat(path, readonly=False) directly.',
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    if auto_codec:
+        warnings.warn(
+            'auto_codec is deprecated and will be removed in version 1.0. '
+            "Use DecodedView instead: dec = DecodedView(bc); dec['file.json'] = data",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    if mode == 'r':
+        return Barecat(path, readonly=True, threadsafe=threadsafe_reader, auto_codec=auto_codec)
+    elif mode == 'w+':
+        return Barecat(
+            path,
+            readonly=False,
+            overwrite=True,
+            exist_ok=True,
+            append_only=False,
+            auto_codec=auto_codec,
+        )
+    elif mode == 'r+':
+        return Barecat(
+            path,
+            readonly=False,
+            overwrite=False,
+            exist_ok=True,
+            append_only=False,
+            auto_codec=auto_codec,
+        )
+    elif mode == 'a+':
+        return Barecat(
+            path,
+            readonly=False,
+            overwrite=False,
+            exist_ok=True,
+            append_only=True,
+            auto_codec=auto_codec,
+        )
+    elif mode == 'ax+':
+        return Barecat(
+            path,
+            readonly=False,
+            overwrite=False,
+            exist_ok=False,
+            append_only=True,
+            auto_codec=auto_codec,
+        )
+    elif mode == 'x+':
+        return Barecat(
+            path,
+            readonly=False,
+            overwrite=False,
+            exist_ok=False,
+            append_only=False,
+            auto_codec=auto_codec,
+        )
+    else:
+        raise ValueError(f'Invalid mode: {mode}')
+
+
+def get_cached_reader(path, auto_codec=None):
+    """Get a thread-locally cached read-only Barecat reader.
+
+    Each thread/process gets its own cached instance. Useful for multi-threaded
+    data loading where each worker needs its own Barecat handle.
+
+    Args:
+        path: Path to the archive.
+        auto_codec: Whether to automatically decode files based on extension.
+            Currently defaults to True for backwards compatibility, but the default
+            will change to False in version 1.0. Pass True or False explicitly to
+            silence the deprecation warning. Use DecodedView for new code.
+    """
+    import multiprocessing_utils
+
+    if auto_codec is None:
+        warnings.warn(
+            'get_cached_reader() currently defaults to auto_codec=True, but this '
+            'default will change to False in version 1.0. Pass auto_codec=True '
+            'explicitly to keep the current behavior, or auto_codec=False '
+            '(and use DecodedView) to adopt the new default.',
+            FutureWarning,
+            stacklevel=2,
+        )
+        auto_codec = True
+    elif auto_codec:
+        warnings.warn(
+            'auto_codec=True in get_cached_reader() is deprecated and will be removed '
+            'in version 1.0. Use DecodedView instead.',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+    return _cached_reader_open(path, auto_codec)
+
+
+def _threadlocal_decorate(decorator):
+    import multiprocessing_utils
+
+    def my_decorator(fun):
+        local = multiprocessing_utils.local()
+
+        @functools.wraps(fun)
+        def wrapper(*args, **kwargs):
+            if not hasattr(local, 'fn'):
+                local.fn = decorator(fun)
+            return local.fn(*args, **kwargs)
+
+        return wrapper
+
+    return my_decorator
+
+
+@_threadlocal_decorate(functools.lru_cache())
+def _cached_reader_open(path, auto_codec=True):
+    return Barecat(path, readonly=True, auto_codec=auto_codec)

barecat/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.2'
+__version_tuple__ = version_tuple = (0, 3, 2)
+
+__commit_id__ = commit_id = None