archive-r-python 0.1.0__tar.gz → 0.1.2__tar.gz

{archive_r_python-0.1.0 → archive_r_python-0.1.2}/LICENSE.txt

@@ -1,5 +1,5 @@
 archive_r License
-Version: 0.1.0 (2025-10-25)
+Version: 0.1.2 (2025-12-02)
 
 ----------------------------------------
 Primary License
@@ -44,13 +44,34 @@ License shown above.
    - Purpose: header-only binding generator for the Python extension module.
    - License: BSD-style License (https://github.com/pybind/pybind11)
 
-3. rake (development dependency for Ruby bindings)
-   - Purpose: build and release tasks for the Ruby gem.
-   - License: MIT License (https://github.com/ruby/rake)
+The following components are redistributed only because libarchive (bundled with archive_r) depends on them at runtime:
 
-4. minitest (development dependency for Ruby bindings)
-   - Purpose: unit testing framework for the Ruby gem.
-   - License: MIT License (https://github.com/minitest/minitest)
+3. zlib
+   - Purpose: libarchive dependency providing DEFLATE compression; bundled inside archive_r binaries and wheels because libarchive requires it.
+   - License: zlib License (https://zlib.net/zlib_license.html)
 
+4. bzip2
+   - Purpose: libarchive dependency providing bzip2 compression support; distributed with archive_r artifacts.
+   - License: BSD-style license (https://sourceware.org/bzip2/)
+
+5. liblzma (XZ Utils)
+   - Purpose: libarchive dependency providing LZMA/XZ compression; included with archive_r packages.
+   - License: Public Domain + GNU LGPLv2.1+ (https://tukaani.org/xz/)
+
+6. libxml2
+   - Purpose: libarchive dependency used for archive formats such as xar; distributed alongside archive_r.
+   - License: MIT-style License (http://xmlsoft.org/)
+
+7. zstd
+   - Purpose: libarchive dependency providing Zstandard compression; shipped within archive_r binaries.
+   - License: BSD License (https://github.com/facebook/zstd)
+
+8. OpenSSL 3
+   - Purpose: libarchive dependency providing cryptographic support for encrypted archives; included with archive_r packages.
+   - License: Apache License 2.0 with OpenSSL exception (https://www.openssl.org/source/license.html)
+
+9. libiconv / libcharset
+   - Purpose: libxml2/libarchive dependency for character set conversion; redistributed with archive_r artifacts.
+   - License: GNU LGPLv2.1+ (https://www.gnu.org/software/libiconv/)
 Users of archive_r should review the linked third-party licenses to ensure
 compliance with their terms when redistributing this software.

{archive_r_python-0.1.0/archive_r_python.egg-info → archive_r_python-0.1.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: archive_r_python
-Version: 0.1.0
-Summary: Python bindings for the archive_r traverser library
+Version: 0.1.2
+Summary: Python bindings for archive_r that recursively traverse nested archives without creating temporary extraction files
 Home-page: https://github.com/Raizo-TCS/archive_r
 Author: archive_r Team
 Author-email: raizo.tcs@users.noreply.github.com
@@ -609,4 +609,4 @@ The Python bindings are distributed under the MIT License, consistent with the a
 
 ---
 
-**Note**: This document describes archive_r Python bindings version 0.1.0.
+**Note**: This document describes archive_r Python bindings version 0.1.2.

{archive_r_python-0.1.0 → archive_r_python-0.1.2}/README.md

@@ -580,4 +580,4 @@ The Python bindings are distributed under the MIT License, consistent with the a
 
 ---
 
-**Note**: This document describes archive_r Python bindings version 0.1.0.
+**Note**: This document describes archive_r Python bindings version 0.1.2.

archive_r_python-0.1.2/VERSION

@@ -0,0 +1 @@
+0.1.2

{archive_r_python-0.1.0 → archive_r_python-0.1.2/archive_r_python.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: archive_r_python
-Version: 0.1.0
-Summary: Python bindings for the archive_r traverser library
+Version: 0.1.2
+Summary: Python bindings for archive_r that recursively traverse nested archives without creating temporary extraction files
 Home-page: https://github.com/Raizo-TCS/archive_r
 Author: archive_r Team
 Author-email: raizo.tcs@users.noreply.github.com
@@ -609,4 +609,4 @@ The Python bindings are distributed under the MIT License, consistent with the a
 
 ---
 
-**Note**: This document describes archive_r Python bindings version 0.1.0.
+**Note**: This document describes archive_r Python bindings version 0.1.2.

{archive_r_python-0.1.0 → archive_r_python-0.1.2}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = archive_r_python
-description = Python bindings for the archive_r traverser library
+description = Python bindings for archive_r that recursively traverse nested archives without creating temporary extraction files
 author = archive_r Team
 author_email = raizo.tcs@users.noreply.github.com
 url = https://github.com/Raizo-TCS/archive_r

{archive_r_python-0.1.0 → archive_r_python-0.1.2}/setup.py

@@ -98,7 +98,7 @@ def read_readme() -> str:
     for candidate in paths:
         if candidate.exists():
             return candidate.read_text(encoding='utf-8')
-    return 'Fast archive traversal library with support for nested archives and multipart files.'
+    return 'Python bindings for archive_r that recursively traverse nested archives without creating temporary extraction files.'
 
 
 def resolve_core_paths() -> Tuple[Path, Path]:

{archive_r_python-0.1.0 → archive_r_python-0.1.2}/src/archive_r_py.cc

@@ -4,10 +4,12 @@
 #include "archive_r/data_stream.h"
 #include "archive_r/entry.h"
 #include "archive_r/entry_fault.h"
+#include "archive_r/multi_volume_stream_base.h"
 #include "archive_r/path_hierarchy_utils.h"
 #include "archive_r/traverser.h"
 #include "archive_stack_orchestrator.h"
 #include <cctype>
+#include <cstdio>
 #include <cstring>
 #include <iostream>
 #include <memory>
@@ -66,6 +68,96 @@ py::list path_hierarchy_to_python(const PathHierarchy &hierarchy) {
   return result;
 }
 
+PathEntry python_path_entry_from_object(const py::handle &obj) {
+  if (py::isinstance<py::str>(obj)) {
+    return PathEntry::single(obj.cast<std::string>());
+  }
+
+  py::list sequence;
+  try {
+    sequence = py::list(py::reinterpret_borrow<py::object>(obj));
+  } catch (const py::cast_error &) {
+    throw std::invalid_argument("PathEntry must be string or nested sequence");
+  }
+
+  if (sequence.size() == 0) {
+    throw std::invalid_argument("PathEntry sequence cannot be empty");
+  }
+
+  bool all_strings = true;
+  for (py::handle item : sequence) {
+    if (!py::isinstance<py::str>(item)) {
+      all_strings = false;
+      break;
+    }
+  }
+
+  if (all_strings) {
+    std::vector<std::string> parts;
+    parts.reserve(static_cast<size_t>(sequence.size()));
+    for (py::handle item : sequence) {
+      parts.emplace_back(item.cast<std::string>());
+    }
+    return PathEntry::multi_volume(std::move(parts));
+  }
+
+  PathEntry::NodeList nodes;
+  nodes.reserve(static_cast<size_t>(sequence.size()));
+  for (py::handle item : sequence) {
+    nodes.emplace_back(python_path_entry_from_object(item));
+  }
+  return PathEntry::nested(std::move(nodes));
+}
+
+PathHierarchy python_path_hierarchy_from_object(const py::handle &obj) {
+  if (py::isinstance<py::str>(obj)) {
+    return make_single_path(obj.cast<std::string>());
+  }
+
+  py::list sequence;
+  try {
+    sequence = py::list(py::reinterpret_borrow<py::object>(obj));
+  } catch (const py::cast_error &) {
+    throw std::invalid_argument("path hierarchy must be string or sequence");
+  }
+
+  if (sequence.size() == 0) {
+    throw std::invalid_argument("path hierarchy cannot be empty");
+  }
+
+  PathHierarchy hierarchy;
+  hierarchy.reserve(static_cast<size_t>(sequence.size()));
+  for (py::handle component : sequence) {
+    hierarchy.emplace_back(python_path_entry_from_object(component));
+  }
+  return hierarchy;
+}
+
+std::vector<PathHierarchy> python_normalize_paths(const py::object &paths_obj) {
+  if (py::isinstance<py::str>(paths_obj)) {
+    return { make_single_path(paths_obj.cast<std::string>()) };
+  }
+
+  py::list path_list;
+  try {
+    path_list = py::list(paths_obj);
+  } catch (const py::cast_error &) {
+    throw std::invalid_argument("paths must be a string or a sequence of path hierarchies");
+  }
+
+  if (path_list.size() == 0) {
+    throw std::invalid_argument("paths cannot be empty");
+  }
+
+  std::vector<PathHierarchy> result;
+  result.reserve(static_cast<size_t>(path_list.size()));
+  for (py::handle item : path_list) {
+    result.emplace_back(python_path_hierarchy_from_object(item));
+  }
+
+  return result;
+}
+
 py::dict entry_fault_to_python(const EntryFault &fault) {
   py::dict result;
   result[py::str("message")] = py::str(fault.message);
@@ -93,42 +185,98 @@ FaultCallback make_python_fault_callback(const py::object &callable) {
   };
 }
 
-class PyObjectStream : public IDataStream {
+class PyUserStream : public MultiVolumeStreamBase {
 public:
-  PyObjectStream(py::object io, PathHierarchy hierarchy)
-      : io_(std::move(io))
-      , hierarchy_(std::move(hierarchy))
-      , at_end_(false)
-      , seekable_(py::hasattr(io_, "seek"))
-      , tellable_(py::hasattr(io_, "tell"))
-      , has_custom_rewind_(py::hasattr(io_, "rewind")) {
-    if (!py::hasattr(io_, "read")) {
-      throw py::type_error("stream objects must provide a read() method");
+  PyUserStream(PathHierarchy hierarchy, bool supports_seek)
+      : MultiVolumeStreamBase(std::move(hierarchy), supports_seek)
+      , active_io_(py::none())
+      , io_seekable_(false)
+      , io_tellable_(false)
+      , io_closeable_(false)
+      , self_reference_(nullptr) {}
+  
+    ~PyUserStream() override {
+      py::gil_scoped_acquire gil;
+      release_active_io();
+      if (self_reference_ != nullptr) {
+        Py_DECREF(self_reference_);
+        self_reference_ = nullptr;
+      }
     }
-    if (!has_custom_rewind_ && !seekable_) {
-      throw py::type_error("stream objects must provide either rewind() or seek()");
+
+    void retain_python_owner(const py::object &owner) {
+      PyObject *new_owner = owner.ptr();
+      if (new_owner == self_reference_) {
+        return;
+      }
+      Py_XINCREF(new_owner);
+      if (self_reference_ != nullptr) {
+        Py_DECREF(self_reference_);
+      }
+      self_reference_ = new_owner;
     }
-  }
 
-  ~PyObjectStream() override {
+protected:
+  void open_single_part(const PathHierarchy &single_part) override {
     py::gil_scoped_acquire gil;
-    if (py::hasattr(io_, "close")) {
-      try {
-        io_.attr("close")();
-      } catch (const py::error_already_set &) {
-        PyErr_Clear();
+    py::object open_io = py::get_override(this, "open_part_io");
+    if (open_io) {
+      py::object result = open_io(path_hierarchy_to_python(single_part));
+      if (result.is_none()) {
+        throw py::value_error("open_part_io must return an IO-like object");
       }
+      activate_io(std::move(result));
+      return;
+    }
+
+    py::object override = py::get_override(this, "open_part");
+    if (!override) {
+      throw py::type_error("Stream subclasses must implement open_part_io() or open_part()");
     }
+    override(path_hierarchy_to_python(single_part));
   }
 
-  ssize_t read(void *buffer, size_t size) override {
+  void close_single_part() override {
+    py::gil_scoped_acquire gil;
+    release_active_io();
+    py::object override = py::get_override(this, "close_part");
+    if (override) {
+      override();
+    }
+  }
+
+  ssize_t read_from_single_part(void *buffer, size_t size) override {
     if (size == 0) {
       return 0;
     }
     py::gil_scoped_acquire gil;
-    py::object result = io_.attr("read")(py::int_(size));
+    if (!active_io_.is_none()) {
+      py::object result = active_io_.attr("read")(py::int_(size));
+      if (result.is_none()) {
+        return 0;
+      }
+      py::bytes data = py::reinterpret_borrow<py::bytes>(py::bytes(result));
+      Py_ssize_t length = PyBytes_Size(data.ptr());
+      if (length < 0) {
+        throw py::error_already_set();
+      }
+      if (length == 0) {
+        return 0;
+      }
+      char *raw = PyBytes_AsString(data.ptr());
+      if (!raw) {
+        throw py::error_already_set();
+      }
+      std::memcpy(buffer, raw, static_cast<size_t>(length));
+      return static_cast<ssize_t>(length);
+    }
+
+    py::object override = py::get_override(this, "read_part");
+    if (!override) {
+      throw py::type_error("Stream subclasses must implement open_part_io() or read_part(size)");
+    }
+    py::object result = override(py::int_(size));
     if (result.is_none()) {
-      at_end_ = true;
       return 0;
     }
     py::bytes data = py::reinterpret_borrow<py::bytes>(py::bytes(result));
@@ -137,7 +285,6 @@ public:
       throw py::error_already_set();
     }
     if (length == 0) {
-      at_end_ = true;
       return 0;
     }
     char *raw = PyBytes_AsString(data.ptr());
@@ -148,61 +295,82 @@ public:
     return static_cast<ssize_t>(length);
   }
 
-  void rewind() override {
+  int64_t seek_within_single_part(int64_t offset, int whence) override {
     py::gil_scoped_acquire gil;
-    if (has_custom_rewind_) {
-      io_.attr("rewind")();
-    } else if (seekable_) {
-      io_.attr("seek")(py::int_(0));
-    } else {
-      throw py::type_error("stream object does not support rewind");
+    if (!active_io_.is_none() && io_seekable_) {
+      py::object result = active_io_.attr("seek")(py::int_(offset), py::int_(whence));
+      return result.cast<int64_t>();
     }
-    at_end_ = false;
-  }
-
-  bool at_end() const override { return at_end_; }
-
-  int64_t seek(int64_t offset, int whence) override {
-    if (!seekable_) {
+    py::object override = py::get_override(this, "seek_part");
+    if (!override) {
       return -1;
     }
-    py::gil_scoped_acquire gil;
-    py::object result = io_.attr("seek")(py::int_(offset), py::int_(whence));
-    at_end_ = false;
+    py::object result = override(py::int_(offset), py::int_(whence));
     return result.cast<int64_t>();
   }
 
-  int64_t tell() const override {
-    if (!tellable_) {
+  int64_t size_of_single_part(const PathHierarchy &single_part) override {
+    py::gil_scoped_acquire gil;
+    if (!active_io_.is_none()) {
+      if (io_seekable_ && io_tellable_) {
+        py::object current = active_io_.attr("tell")();
+        active_io_.attr("seek")(py::int_(0), py::int_(SEEK_END));
+        py::object end_pos = active_io_.attr("tell")();
+        active_io_.attr("seek")(current, py::int_(SEEK_SET));
+        return end_pos.cast<int64_t>();
+      }
+    }
+
+    py::object override = py::get_override(this, "part_size");
+    if (!override) {
       return -1;
     }
-    py::gil_scoped_acquire gil;
-    py::object result = io_.attr("tell")();
+    py::object result = override(path_hierarchy_to_python(single_part));
     return result.cast<int64_t>();
   }
 
-  bool can_seek() const override { return seekable_; }
-
-  PathHierarchy source_hierarchy() const override { return hierarchy_; }
-
 private:
-  py::object io_;
-  PathHierarchy hierarchy_;
-  mutable bool at_end_;
-  bool seekable_;
-  bool tellable_;
-  bool has_custom_rewind_;
-};
-
-std::shared_ptr<IDataStream> stream_from_python_result(const py::object &result, const PathHierarchy &requested) {
-  if (result.is_none()) {
-    return nullptr;
+  void activate_io(py::object io) {
+    if (!py::hasattr(io, "read")) {
+      throw py::type_error("open_part_io must return an object with read()");
+    }
+    release_active_io();
+    active_io_ = std::move(io);
+    io_seekable_ = py::hasattr(active_io_, "seek");
+    io_tellable_ = py::hasattr(active_io_, "tell");
+    io_closeable_ = py::hasattr(active_io_, "close");
+    if (can_seek() && io_seekable_) {
+      try {
+        active_io_.attr("seek")(py::int_(0), py::int_(SEEK_CUR));
+      } catch (const py::error_already_set &) {
+        PyErr_Clear();
+      }
+    }
   }
-  if (!py::hasattr(result, "read")) {
-    throw py::type_error("stream factory must return None or an object with read()");
+
+  void release_active_io() {
+    if (active_io_.is_none()) {
+      return;
+    }
+    if (io_closeable_) {
+      try {
+        active_io_.attr("close")();
+      } catch (const py::error_already_set &) {
+        PyErr_Clear();
+      }
+    }
+    active_io_ = py::none();
+    io_seekable_ = false;
+    io_tellable_ = false;
+    io_closeable_ = false;
   }
-  return std::make_shared<PyObjectStream>(result, requested);
-}
+
+  py::object active_io_;
+  bool io_seekable_;
+  bool io_tellable_;
+  bool io_closeable_;
+  PyObject *self_reference_;
+};
 
 void register_python_stream_factory(const py::object &callable) {
   if (callable.is_none()) {
@@ -217,7 +385,18 @@ void register_python_stream_factory(const py::object &callable) {
   RootStreamFactory factory = [func](const PathHierarchy &hierarchy) -> std::shared_ptr<IDataStream> {
     py::gil_scoped_acquire gil;
     py::object result = func(path_hierarchy_to_python(hierarchy));
-    return stream_from_python_result(result, hierarchy);
+    if (result.is_none()) {
+      return nullptr;
+    }
+    if (!py::isinstance<PyUserStream>(result)) {
+      throw py::type_error("stream factory must return None or an archive_r.Stream instance");
+    }
+    auto stream = result.cast<std::shared_ptr<PyUserStream>>();
+    stream->retain_python_owner(result);
+    if (!hierarchies_equal(stream->source_hierarchy(), hierarchy)) {
+      throw py::value_error("Stream subclass must be initialized with the hierarchy provided to the factory");
+    }
+    return stream;
   };
 
   set_root_stream_factory(factory);
@@ -475,7 +654,7 @@ public:
               std::optional<std::vector<std::string>> metadata_keys = std::nullopt, std::optional<bool> descend_archives = std::nullopt)
       : traverser_options_(build_options(passphrases, formats, metadata_keys, descend_archives))
       , archive_options_snapshot_(to_archive_option(traverser_options_))
-      , traverser(normalize_paths(paths), traverser_options_)
+      , traverser(python_normalize_paths(paths), traverser_options_)
       , it(traverser.end()) {
   }
 
@@ -551,96 +730,6 @@ private:
     return options;
   }
 
-  static PathEntry py_to_path_entry(const py::handle &obj) {
-    if (py::isinstance<py::str>(obj)) {
-      return PathEntry::single(obj.cast<std::string>());
-    }
-
-    py::list sequence;
-    try {
-      sequence = py::list(py::reinterpret_borrow<py::object>(obj));
-    } catch (const py::cast_error &) {
-      throw std::invalid_argument("PathEntry must be string or nested sequence");
-    }
-
-    if (sequence.size() == 0) {
-      throw std::invalid_argument("PathEntry sequence cannot be empty");
-    }
-
-    bool all_strings = true;
-    for (py::handle item : sequence) {
-      if (!py::isinstance<py::str>(item)) {
-        all_strings = false;
-        break;
-      }
-    }
-
-    if (all_strings) {
-      std::vector<std::string> parts;
-      parts.reserve(static_cast<size_t>(sequence.size()));
-      for (py::handle item : sequence) {
-        parts.emplace_back(item.cast<std::string>());
-      }
-      return PathEntry::multi_volume(std::move(parts));
-    }
-
-    PathEntry::NodeList nodes;
-    nodes.reserve(static_cast<size_t>(sequence.size()));
-    for (py::handle item : sequence) {
-      nodes.emplace_back(py_to_path_entry(item));
-    }
-    return PathEntry::nested(std::move(nodes));
-  }
-
-  static PathHierarchy py_to_path_hierarchy(const py::handle &obj) {
-    if (py::isinstance<py::str>(obj)) {
-      return make_single_path(obj.cast<std::string>());
-    }
-
-    py::list sequence;
-    try {
-      sequence = py::list(py::reinterpret_borrow<py::object>(obj));
-    } catch (const py::cast_error &) {
-      throw std::invalid_argument("path hierarchy must be string or sequence");
-    }
-
-    if (sequence.size() == 0) {
-      throw std::invalid_argument("path hierarchy cannot be empty");
-    }
-
-    PathHierarchy hierarchy;
-    hierarchy.reserve(static_cast<size_t>(sequence.size()));
-    for (py::handle component : sequence) {
-      hierarchy.emplace_back(py_to_path_entry(component));
-    }
-    return hierarchy;
-  }
-
-  static std::vector<PathHierarchy> normalize_paths(const py::object &paths_obj) {
-    if (py::isinstance<py::str>(paths_obj)) {
-      return { make_single_path(paths_obj.cast<std::string>()) };
-    }
-
-    py::list path_list;
-    try {
-      path_list = py::list(paths_obj);
-    } catch (const py::cast_error &) {
-      throw std::invalid_argument("paths must be a string or a sequence of path hierarchies");
-    }
-
-    if (path_list.size() == 0) {
-      throw std::invalid_argument("paths cannot be empty");
-    }
-
-    std::vector<PathHierarchy> result;
-    result.reserve(static_cast<size_t>(path_list.size()));
-    for (py::handle item : path_list) {
-      result.emplace_back(py_to_path_hierarchy(item));
-    }
-
-    return result;
-  }
-
   TraverserOptions traverser_options_;
   ArchiveOption archive_options_snapshot_;
   Traverser traverser;
@@ -680,13 +769,22 @@ PYBIND11_MODULE(archive_r, m) {
   m.attr("STANDARD_FORMATS") = formats_tuple;
   m.attr("SAFE_FORMATS") = formats_tuple;
 
-      m.def("register_stream_factory", &register_python_stream_factory, py::arg("factory") = py::none(),
-        "Register a callable returning a file-like object for custom root streams. Pass None to reset.");
+    m.def("register_stream_factory", &register_python_stream_factory, py::arg("factory") = py::none(),
+      "Register a callable returning archive_r.Stream instances for custom root streams. Pass None to reset.");
 
-      m.def("on_fault",
+  m.def("on_fault",
         [](const py::object &callback) { register_fault_callback(make_python_fault_callback(callback)); }, py::arg("callback") = py::none(),
         "Register or clear the global EntryFault callback (None clears)");
 
+  py::class_<PyUserStream, std::shared_ptr<PyUserStream>>(m, "Stream")
+      .def(py::init([](py::object hierarchy, py::object supports_seek_obj) {
+             auto path = python_path_hierarchy_from_object(hierarchy);
+             bool supports_seek = supports_seek_obj.is_none() ? true : supports_seek_obj.cast<bool>();
+             return std::make_shared<PyUserStream>(std::move(path), supports_seek);
+           }),
+           py::arg("hierarchy"), py::arg("supports_seek") = py::none(),
+           "Base class for custom multi-volume streams returned from register_stream_factory.");
+
   // Entry class
   py::class_<PyEntry, std::shared_ptr<PyEntry>>(m, "Entry")
       .def_property_readonly("path", &PyEntry::path, "Get full path of the entry")

{archive_r_python-0.1.0 → archive_r_python-0.1.2}/test/test_traverser.py

@@ -24,15 +24,16 @@ import archive_r
 class TestTraverser(unittest.TestCase):
     DEFAULT_FORMATS = tuple(list(archive_r.STANDARD_FORMATS) + ["mtree"])
 
-    class MinimalStream:
-        def __init__(self, payload: bytes):
-            self._buffer = io.BytesIO(payload)
-
-        def read(self, length: int = -1) -> bytes:
-            return self._buffer.read(length)
+    class PayloadStream(archive_r.Stream):
+        def __init__(self, hierarchy, payload: bytes, *, supports_seek: bool | None = None):
+            if supports_seek is None:
+                super().__init__(hierarchy)
+            else:
+                super().__init__(hierarchy, supports_seek=supports_seek)
+            self._payload = payload
 
-        def rewind(self) -> None:
-            self._buffer.seek(0)
+        def open_part_io(self, _part_hierarchy):
+            return io.BytesIO(self._payload)
 
     @classmethod
     def setUpClass(cls):
@@ -44,6 +45,7 @@ class TestTraverser(unittest.TestCase):
         cls.directory_path = str(test_data_dir / 'directory_test')
         cls.broken_archive = str(test_data_dir / 'broken_nested.tar')
         cls.stress_archive = str(test_data_dir / 'stress_test_ultimate.tar.gz')
+        cls.multi_volume_parts = sorted(str(path.resolve()) for path in test_data_dir.glob('test_input.tar.gz.part*'))
         
         if not os.path.exists(cls.simple_archive):
             raise FileNotFoundError(f"Test archive not found: {cls.simple_archive}")
@@ -57,6 +59,8 @@ class TestTraverser(unittest.TestCase):
             raise FileNotFoundError(f"Broken archive not found: {cls.broken_archive}")
         if not os.path.exists(cls.stress_archive):
             raise FileNotFoundError(f"Stress archive not found: {cls.stress_archive}")
+        if not cls.multi_volume_parts:
+            raise FileNotFoundError('Multi-volume parts test_input.tar.gz.part* not found')
 
     def _normalized_options(self, **kwargs):
         options = dict(kwargs)
@@ -334,7 +338,7 @@ class TestTraverser(unittest.TestCase):
         def factory(hierarchy):
             calls["count"] += 1
             if hierarchy[0] == os.path.abspath(self.simple_archive):
-                return io.BytesIO(payload)
+                return self.PayloadStream(hierarchy, payload)
             return None
 
         archive_r.register_stream_factory(factory)
@@ -351,7 +355,7 @@ class TestTraverser(unittest.TestCase):
 
         def factory(hierarchy):
             if hierarchy[0] == os.path.abspath(virtual):
-                return open(self.simple_archive, "rb")
+                return self.PayloadStream(hierarchy, Path(self.simple_archive).read_bytes())
             return None
 
         archive_r.register_stream_factory(factory)
@@ -368,13 +372,46 @@ class TestTraverser(unittest.TestCase):
             if hierarchy[0] != absolute:
                 return None
             calls["count"] += 1
-            return self.MinimalStream(payload)
+            return self.PayloadStream(hierarchy, payload)
 
         archive_r.register_stream_factory(factory)
         actual = self._collect_paths(self.simple_archive)
         self.assertEqual(expected, actual)
         self.assertEqual(1, calls["count"])
 
+    def test_stream_factory_multi_volume_custom_stream(self):
+        class RecordingStream(archive_r.Stream):
+            def __init__(self, hierarchy):
+                super().__init__(hierarchy, supports_seek=True)
+                self.requests = []
+
+            def open_part_io(self, part_hierarchy):
+                head = part_hierarchy[0]
+                self.requests.append(head)
+                return open(head, 'rb')
+
+        parts_hierarchy = [[part for part in self.multi_volume_parts]]
+        archive_r.register_stream_factory(None)
+        expected = self._collect_paths(parts_hierarchy)
+
+        streams = []
+
+        def factory(hierarchy):
+            head = hierarchy[0]
+            self.assertIsInstance(head, list)
+            stream = RecordingStream(hierarchy)
+            streams.append(stream)
+            return stream
+
+        try:
+            archive_r.register_stream_factory(factory)
+            actual = self._collect_paths(parts_hierarchy)
+            self.assertEqual(expected, actual)
+            self.assertTrue(streams)
+            self.assertEqual(self.multi_volume_parts, streams[0].requests)
+        finally:
+            archive_r.register_stream_factory(None)
+
     def test_stream_factory_requires_callable(self):
         """register_stream_factory should reject non-callables"""
         with self.assertRaises(TypeError):
@@ -386,24 +423,27 @@ class TestTraverser(unittest.TestCase):
         payload = Path(self.simple_archive).read_bytes()
         streams = []
 
-        class SeekableOnlyStream:
-            def __init__(self, data: bytes):
-                self._buffer = io.BytesIO(data)
-                self.seek_calls = 0
+        class TrackingBuffer(io.BytesIO):
+            def __init__(self, owner, data: bytes):
+                super().__init__(data)
+                self._owner = owner
 
-            def read(self, length: int = -1) -> bytes:
-                return self._buffer.read(length)
+            def seek(self, offset: int, whence: int = io.SEEK_SET) -> int:
+                self._owner.seek_calls += 1
+                return super().seek(offset, whence)
 
-            def seek(self, offset: int, whence: int = 0) -> int:
-                self.seek_calls += 1
-                return self._buffer.seek(offset, whence)
+        class SeekableOnlyStream(archive_r.Stream):
+            def __init__(self, hierarchy, data: bytes):
+                super().__init__(hierarchy, supports_seek=True)
+                self._data = data
+                self.seek_calls = 0
 
-            def tell(self) -> int:
-                return self._buffer.tell()
+            def open_part_io(self, _hierarchy):
+                return TrackingBuffer(self, self._data)
 
         def factory(hierarchy):
             if hierarchy[0] == os.path.abspath(self.simple_archive):
-                stream = SeekableOnlyStream(payload)
+                stream = SeekableOnlyStream(hierarchy, payload)
                 streams.append(stream)
                 return stream
             return None
@@ -414,6 +454,14 @@ class TestTraverser(unittest.TestCase):
         self.assertTrue(streams)
         self.assertTrue(any(stream.seek_calls >= 1 for stream in streams))
 
+    def test_stream_factory_rejects_plain_io(self):
+        def factory(hierarchy):
+            if hierarchy[0] == head:
+                stream = RecordingStream(hierarchy)
+                streams.append(stream)
+                return stream
+            self._collect_paths(self.simple_archive)
+
     def test_multi_volume_grouping(self):
         """Verify multi-volume archives can be grouped and traversed"""
         part_paths = []

archive_r_python-0.1.0/VERSION

@@ -1 +0,0 @@
-0.1.0