fastar 0.5.0__cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl

fastar/__init__.py

@@ -0,0 +1,5 @@
+from .fastar import *
+
+__doc__ = fastar.__doc__
+if hasattr(fastar, "__all__"):
+    __all__ = fastar.__all__

fastar/__init__.pyi

@@ -0,0 +1,163 @@
+from os import PathLike
+from pathlib import Path
+from typing import Literal, Optional, Union, overload
+
+from typing_extensions import Self
+
+class FastarError(Exception):
+    """Base exception for all fastar errors."""
+
+class ArchiveClosedError(FastarError):
+    """Exception raised when attempting to use a closed archive."""
+
+class ArchiveUnpackingError(FastarError):
+    """Exception raised when unpacking an archive fails."""
+
+class ArchiveAppendingError(FastarError):
+    """Exception raised when appending to an archive fails."""
+
+class NameDerivationError(ArchiveAppendingError):
+    """Exception raised when a file name cannot be derived from a path."""
+
+class ArchiveWriter:
+    """A tar archive writer that supports compressed and uncompressed formats."""
+
+    @classmethod
+    def open(
+        cls, path: Union[str, Path, PathLike[str]], mode: Literal["w", "w:gz"] = "w:gz"
+    ) -> Self:
+        """
+        Open a tar archive for writing.
+
+        Args:
+            path: Path to the archive file to create
+            mode: Write mode - 'w' for uncompressed, 'w:gz' for gzip compressed (default)
+
+        Returns:
+            An ArchiveWriter instance
+
+        Raises:
+            ValueError: If an unsupported mode is provided
+            OSError: If the file cannot be opened
+        """
+
+    def append(
+        self,
+        path: Union[str, Path, PathLike[str]],
+        arcname: Optional[Union[str, Path, PathLike[str]]] = None,
+        recursive: bool = True,
+        dereference: bool = False,
+    ) -> None:
+        """
+        Append a file or directory to the archive.
+
+        Args:
+            path: Path to the file or directory to append
+            arcname: Name to use in the archive (defaults to the filename)
+            recursive: If True and path is a directory, append all contents recursively
+            dereference: If True, append the target of symlinks instead of the symlink itself
+
+        Raises:
+            ArchiveClosedError: If the archive is already closed
+            ArchiveAppendingError: If the target cannot be appended to the archive
+            OSError: If there's an error reading the target file or directory
+        """
+
+    def close(self) -> None:
+        """
+        Close the archive and flush all pending writes.
+
+        Raises:
+            OSError: If there's an error flushing the archive
+        """
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+
+    def __exit__(self, exc_type, exc_value, traceback) -> bool:
+        """Exit the context manager, closing the archive."""
+
+class ArchiveReader:
+    """A tar archive reader that supports compressed and uncompressed formats."""
+
+    @classmethod
+    def open(
+        cls, path: Union[str, Path, PathLike[str]], mode: Literal["r", "r:gz"] = "r:gz"
+    ) -> Self:
+        """
+        Open a tar archive for reading.
+
+        Args:
+            path: Path to the archive file to read
+            mode: Read mode - 'r' for uncompressed, 'r:gz' for gzip compressed (default)
+
+        Returns:
+            An ArchiveReader instance
+
+        Raises:
+            ValueError: If an unsupported mode is provided
+            OSError: If the file cannot be opened
+        """
+
+    def unpack(
+        self, to: Union[str, Path, PathLike[str]], preserve_mtime: bool = True
+    ) -> None:
+        """
+        Unpack all contents of the archive and put them into the specified directory.
+
+        Args:
+            to: Destination directory path
+            preserve_mtime: whether to preserve file modification times
+
+        Raises:
+            ArchiveClosedError: If the archive is already closed
+            ArchiveUnpackingError: If the archive cannot be unpacked
+            OSError: If unpacking fails due to I/O errors
+        """
+
+    def close(self) -> None:
+        """Close the archive."""
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+
+    def __exit__(self, exc_type, exc_value, traceback) -> bool:
+        """Exit the context manager, closing the archive."""
+
+@overload
+def open(
+    path: Union[str, Path, PathLike[str]], mode: Literal["w", "w:gz"]
+) -> ArchiveWriter:
+    """
+    Open a tar archive for writing.
+
+    Args:
+        path: Path to the archive file to create
+        mode: Write mode - 'w' for uncompressed, 'w:gz' for gzip compressed
+
+    Returns:
+        An ArchiveWriter instance
+
+    Raises:
+        ValueError: If an unsupported mode is provided
+        OSError: If the file cannot be opened
+    """
+
+@overload
+def open(
+    path: Union[str, Path, PathLike[str]], mode: Literal["r", "r:gz"]
+) -> ArchiveReader:
+    """
+    Open a tar archive for reading.
+
+    Args:
+        path: Path to the archive file to read
+        mode: Read mode - 'r' for uncompressed, 'r:gz' for gzip compressed
+
+    Returns:
+        An ArchiveReader instance
+
+    Raises:
+        ValueError: If an unsupported mode is provided
+        OSError: If the file cannot be opened
+    """

fastar-0.5.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: fastar
+Version: 0.5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+License-File: LICENSE
+Summary: High-level bindings for the Rust tar crate
+Author-email: Jonathan Ehwald <github@ehwald.info>
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: homepage, https://github.com/DoctorJohn/fastar
+Project-URL: repository, https://github.com/DoctorJohn/fastar
+Project-URL: documentation, https://github.com/DoctorJohn/fastar
+
+# Fastar
+
+[![Versions][versions-image]][versions-url]
+[![PyPI][pypi-image]][pypi-url]
+[![Downloads][downloads-image]][downloads-url]
+[![License][license-image]][license-url]
+[![CodSpeed][codspeed-image]][codspeed-url]
+
+[versions-image]: https://img.shields.io/pypi/pyversions/fastar
+[versions-url]: https://github.com/DoctorJohn/fastar/blob/main/pyproject.toml
+[pypi-image]: https://img.shields.io/pypi/v/fastar
+[pypi-url]: https://pypi.org/project/fastar/
+[downloads-image]: https://img.shields.io/pypi/dm/fastar
+[downloads-url]: https://pypi.org/project/fastar/
+[license-image]: https://img.shields.io/pypi/l/fastar
+[license-url]: https://github.com/DoctorJohn/fastar/blob/main/LICENSE
+[codspeed-image]: https://img.shields.io/endpoint?url=https://codspeed.io/badge.json
+[codspeed-url]: https://codspeed.io/DoctorJohn/fastar
+
+The `fastar` library wraps the Rust [tar](https://crates.io/crates/tar) and [flate2](https://crates.io/crates/flate2) crates, providing a high-performance way to work with compressed and uncompressed tar archives in Python.
+
+## Installation
+
+```sh
+pip install fastar
+```
+
+## Usage
+
+This section shows basic examples of how to create and extract tar archives using Fastar. For more usage examples, please refer directly to the test cases in the [tests](https://github.com/DoctorJohn/fastar/tree/main/tests) directory.
+
+### Working with uncompressed tar archives
+
+```python
+import fastar
+from pathlib import Path
+
+
+input_file = Path("file.txt")
+input_file.write_text("Hello, Fastar!")
+
+
+with fastar.open("archive.tar", "w") as archive:
+    archive.append(input_file)
+
+
+with fastar.open("archive.tar", "r") as archive:
+    archive.unpack("output/")
+
+
+unpacked_file = Path("output/file.txt")
+print(unpacked_file.read_text())  # Hello, Fastar!
+```
+
+### Working with gzip-compressed tar archives
+
+```python
+import fastar
+from pathlib import Path
+
+
+input_file = Path("file.txt")
+input_file.write_text("Hello, Fastar!")
+
+
+with fastar.open("archive.tar.gz", "w:gz") as archive:
+    archive.append(input_file)
+
+
+with fastar.open("archive.tar.gz", "r:gz") as archive:
+    archive.unpack("output/")
+
+
+unpacked_file = Path("output/file.txt")
+print(unpacked_file.read_text())  # Hello, Fastar!
+```
+
+## Development
+
+1. Install dependencies into a virtual env: `uv sync`
+2. Make changes to the code and tests
+3. Build the package: `uv run maturin develop`
+4. Run the tests: `uv run pytest`
+

fastar-0.5.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+fastar-0.5.0.dist-info/METADATA,sha256=LrUR4goV7xjxI-HAQRqr3U9WfsdC66BktJIXwP0wBXk,3779
+fastar-0.5.0.dist-info/WHEEL,sha256=tN9njFMg_hRkKh0E3JD9YyQoNPQ_jabwiTiGkG_bgTQ,145
+fastar-0.5.0.dist-info/licenses/LICENSE,sha256=rYGQpMiiUoV5IPve_SRv0E-Ci8BMj0TaNs5jSu3d6xo,1054
+fastar/__init__.py,sha256=mU2iZJ--coorw9PWKBK1JbU9C_N5EqCZQ-b7YvPFBWw,107
+fastar/__init__.pyi,sha256=mukg31ozAocMs0y2B1XUBI2OCzCuNSzRNzMFNzMelGo,4952
+fastar/fastar.cpython-312-s390x-linux-gnu.so,sha256=tF3J0p7nUuoRZdNYUo5d01wWh7Kd6UwB7QQLf2lPux4,1058848
+fastar/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastar-0.5.0.dist-info/RECORD,,

fastar-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: maturin (1.10.1)
+Root-Is-Purelib: false
+Tag: cp312-cp312-manylinux_2_17_s390x
+Tag: cp312-cp312-manylinux2014_s390x

fastar-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Jonathan Ehwald
+
+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.