v0.4.0: add pluggable archive extraction (v15)

Add expand_archive() and expand_archive_streaming() for extracting
ZIP/TAR archives directly into MFS with auto-detection and conflict handling.

- add _archive.py with ArchiveAdapter base class, ZipAdapter, and TarAdapter
- expand_archive() provides atomic extraction via import_tree()
- expand_archive_streaming() provides low-memory streaming extraction
- add _sanitize_archive_path() for Zip Slip prevention
- add on_conflict parameter for duplicate and collision handling
- re-export ArchiveAdapter, expand_archive, expand_archive_streaming from __init__
- add 67 tests across 5 new test files (total: 436)
- update README, README_ja, TESTING, TESTING_ja, CHANGELOG, and examples
- add archive-related Non-Goals to README compatibility section

Author: nightmarewalker

CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-03-21
+
+### Added
+- `ArchiveAdapter`: pluggable base class for archive format support
+- `expand_archive()`: atomic archive expansion via `import_tree()`,
+  with auto-detection and optional `adapters` / `adapter` parameters
+- `expand_archive_streaming()`: streaming archive expansion via `open()`/`write()`,
+  with O(single-file) peak memory and `on_conflict="skip"` for incremental extraction
+- Built-in `ZipAdapter` and `TarAdapter` (standard library only)
+- Archive path sanitization: absolute paths, `../` traversal sequences,
+  and backslash paths are silently stripped before extraction (Zip Slip protection)
+- `on_conflict` parameter controls archive-internal duplicates and MFS existing
+  file collisions; existing directory collisions always raise `IsADirectoryError`
+- 67 new tests across 5 files for archive expansion feature (total: 436)
+
+### Changed
+- `dmemfs.__version__` and project version bumped to `0.4.0`
+
 ## [0.3.0] - 2026-03-09
 
 ### Added

README.md

@@ -17,7 +17,7 @@ Languages: [English](https://github.com/nightmarewalker/D-MemFS/blob/main/README
 
 | Metric | Details |
 |---|---|
-| 🧪 **Robustness** | 369 tests with 97% code coverage |
+| 🧪 **Robustness** | 436 tests with 97% code coverage |
 | 🔒 **Verified Safety** | 98, 100×4 — top scores across all security categories (Socket.dev) |
 | 🌟 **Community** | [Discussed on `r/Python`](https://www.reddit.com/r/Python/comments/1rrqr8z/i_built_an_inmemory_virtual_filesystem_for_python/) with highly positive reception |
 ---
@@ -34,16 +34,16 @@ Languages: [English](https://github.com/nightmarewalker/D-MemFS/blob/main/README
 - Async wrapper (`AsyncMemoryFileSystem`) powered by `asyncio.to_thread`
 - Zero runtime dependencies (standard library only)
 - **No admin/root privileges required** — works on locked-down CI runners, containers, and shared machines where OS-level RAM disks are not an option
-- **369 tests, 97% coverage** across 3 OS (Linux / Windows / macOS) × 3 Python versions (3.11–3.13, including free-threaded 3.13t)
+- **436 tests, 97% coverage** across 3 OS (Linux / Windows / macOS) × 3 Python versions (3.11–3.13, including free-threaded 3.13t)
 
 This is useful when `io.BytesIO` is too primitive (single buffer), and OS-level RAM disks/tmpfs are impractical (permissions, container policy, Windows driver friction). Ideal for **CI pipeline acceleration** — eliminate disk I/O from test suites and data processing without any infrastructure changes.
 
 **Note on Architectural Boundary:** This is strictly an in-process tool. External subprocesses (CLI tools) cannot access these files via standard OS paths. If your pipeline relies heavily on passing files to external binaries, an OS-level RAM disk (`tmpfs`) is the correct tool. D-MemFS shines when accelerating Python-native test suites or internal data pipelines.
 
 ---
 
-### Archive Extraction In-Memory
-Extract large ZIP or TAR archives entirely in-memory to process their contents on the fly. Prevent disk wear (TBW) and eliminate the risk of leaving garbage files behind.
+### Archive Extraction
+Extract ZIP/TAR archives directly into D-MemFS using the built-in `expand_archive()` (atomic, all-or-nothing) or `expand_archive_streaming()` (low-memory, incremental). Custom archive formats are supported via the pluggable `ArchiveAdapter` interface. A low-level manual extraction example using `open()`/`write()` is also included as a reference for advanced use cases.
 * 📝 **Tutorial:** [`examples/archive_extraction.md`](examples/archive_extraction.md)
 
 ### CI/CD Pipelines & Test Debugging
@@ -110,6 +110,12 @@ except MFSQuotaExceededError as e:
 - `stat`, `stats`, `get_size`
 - `export_as_bytesio`, `export_tree`, `iter_export_tree`, `import_tree`
 
+### Archive Extraction Functions
+
+- `expand_archive(mfs, source, dest, *, on_conflict, adapter, adapters)` — atomic extraction via `import_tree()`
+- `expand_archive_streaming(mfs, source, dest, *, on_conflict, adapter, adapters)` — streaming extraction, returns write count
+- `ArchiveAdapter` — base class for pluggable archive format support (built-in: `ZipAdapter`, `TarAdapter`)
+
 **Constructor parameters:**
 - `max_quota` (default `256 MiB`): byte quota for file data
 - `max_nodes` (default `None`): optional cap on total node count (files + directories). Raises `MFSNodeLimitExceededError` when exceeded.
@@ -322,6 +328,9 @@ uvx --with-requirements requirements.txt pdoc dmemfs -o docs/api
 - No symlink/hardlink support — intentionally omitted to eliminate path traversal loops and structural complexity (same rationale as `pathlib.PurePath`).
 - No direct `pathlib.Path` / `os.PathLike` API — MFS paths are virtual and must not be confused with host filesystem paths. Accepting `os.PathLike` would allow third-party libraries or a plain `open()` call to silently treat an MFS virtual path as a real OS path, potentially issuing unintended syscalls against the host filesystem. All paths must be plain `str` with POSIX-style absolute notation (e.g. `"/data/file.txt"`).
 - No kernel filesystem integration (intentionally in-process only)
+- No exhaustive archive format support — core handles zip and tar (standard library) only. For other formats (7z, RAR, etc.), you can write your own adapter. See [`examples/archive_extraction.md`](examples/archive_extraction.md) for details.
+- No password-protected / encrypted archive support
+- Archive extraction functions are sync-only. Use `asyncio.to_thread()` in async code.
 
 Auto-promotion behavior:
 

README_ja.md

@@ -17,7 +17,7 @@
 
 | 指標 | 実績 |
 |---|---|
-| 🧪 **堅牢性** | 369テスト、カバレッジ97% |
+| 🧪 **堅牢性** | 436テスト、カバレッジ97% |
 | 🔒 **安全性の検証** | 98, 100×4 — 全セキュリティカテゴリでトップスコア（Socket.dev） |
 | 🌟 **コミュニティ** | [`r/Python` にて議論され、高い評価を獲得](https://www.reddit.com/r/Python/comments/1rrqr8z/i_built_an_inmemory_virtual_filesystem_for_python/) |
 ---
@@ -34,16 +34,16 @@
 - `asyncio.to_thread` ベースの Async ラッパー（`AsyncMemoryFileSystem`）
 - ランタイム依存ゼロ（標準ライブラリのみ）
 - **管理者権限不要** — OS レベルの RAM ディスクが使えない CI ランナー、コンテナ、共有マシンでもそのまま動作
-- **369テスト、カバレッジ97%** — 3 OS（Linux / Windows / macOS）× 3 Python バージョン（3.11〜3.13、フリースレッド 3.13t 含む）で検証済み
+- **436テスト、カバレッジ97%** — 3 OS（Linux / Windows / macOS）× 3 Python バージョン（3.11〜3.13、フリースレッド 3.13t 含む）で検証済み
 
 `io.BytesIO` が単一バッファで不足する場合や、OSレベルのRAMディスク/tmpfsが使いにくい環境（権限制約、コンテナポリシー、Windowsの運用負荷）で有効です。**CI パイプラインの高速化**にも最適——インフラ変更なしにテストやデータ処理からディスク I/O を排除できます。
 
 **アーキテクチャの境界に関する注意:** 本ライブラリは完全にプロセス内のツールです。外部のサブプロセス（CLIツールなど）は、標準的なOSのパスを経由してこれらのファイルにアクセスすることはできません。外部バイナリへのファイル受け渡しを多用するパイプラインの場合は、OSレベルのRAMディスク（`tmpfs`）が適しています。D-MemFSは、Pythonネイティブなテストスイートや内部データパイプラインの高速化において真価を発揮します。
 
 ---
 
-### アーカイブのインメモリ解凍
-巨大なZIPやTARアーカイブをすべてメモリ上で解凍し、オンザフライで内容を処理します。ディスクの摩耗（TBW）を防ぎ、ゴミファイルが残るリスクを排除します。
+### アーカイブ展開
+組み込みの `expand_archive()`（アトミック・All-or-Nothing）または `expand_archive_streaming()`（低メモリ・差分展開対応）で ZIP/TAR アーカイブを直接 D-MemFS 上に展開します。プラガブルな `ArchiveAdapter` インターフェースにより、カスタムアーカイブ形式への対応も可能です。低レベルの `open()`/`write()` による手動展開例も、高度なユースケースの参考として同梱しています。
 * 📝 **チュートリアル:** [`examples/archive_extraction.md`](examples/archive_extraction.md)
 
 ### CI/CDパイプラインとテストのデバッグ
@@ -110,6 +110,12 @@ except MFSQuotaExceededError as e:
 - `stat`, `stats`, `get_size`
 - `export_as_bytesio`, `export_tree`, `iter_export_tree`, `import_tree`
 
+### アーカイブ展開関数
+
+- `expand_archive(mfs, source, dest, *, on_conflict, adapter, adapters)` — `import_tree()` 経由のアトミック展開
+- `expand_archive_streaming(mfs, source, dest, *, on_conflict, adapter, adapters)` — ストリーミング展開、書き込み回数を返却
+- `ArchiveAdapter` — プラガブルなアーカイブ形式サポート用基底クラス（組み込み: `ZipAdapter`, `TarAdapter`）
+
 **コンストラクタパラメータ:**
 - `max_quota`（デフォルト `256 MiB`）: ファイルデータのバイトクォータ
 - `max_nodes`（デフォルト `None`）: ノード数の上限（ファイル＋ディレクトリ）。超過時は `MFSNodeLimitExceededError`
@@ -320,6 +326,9 @@ uvx --with-requirements requirements.txt pdoc dmemfs -o docs/api
 - シンボリックリンク/ハードリンク非対応 — パストラバーサルループや構造の複雑化を排除するため意図的に省略（`pathlib.PurePath` と同じ設計方針）。
 - `pathlib.Path` / `os.PathLike` 直接対応なし — MFS のパスは仮想パスであり、ホストファイルシステムのパスと混同されてはならない。`os.PathLike` を受け入れると、サードパーティライブラリや素の `open()` 呼び出しが MFS の仮想パスを実 OS のパスと誤認し、ホストファイルシステムに対して意図しないシステムコールを発行するリスクがある。すべてのパスは POSIX 絶対表記の `str`（例: `"/data/file.txt"`）で指定すること。
 - カーネルFS統合なし（意図的にプロセス内完結）
+- アーカイブ形式の網羅的サポートなし — コアが対応するのは zip と tar（標準ライブラリ）のみ。7z・RAR 等には、独自のアダプタを作成することで対応可能。詳細は [`examples/archive_extraction.md`](examples/archive_extraction.md) を参照。
+- パスワード付き／暗号化アーカイブ非対応
+- アーカイブ展開関数は sync 専用。async 環境では `asyncio.to_thread()` を使用すること。
 
 自動昇格の挙動:
 

TESTING.md

@@ -166,7 +166,7 @@ uvx --with-requirements requirements.txt pdoc dmemfs -o docs/api
 
 ## Test File Mapping Table
 
-File breakdown of all tests (369 items):
+File breakdown of all tests (436 items):
 
 | File Path | Test Count | Covered Area |
 |---|---:|---|
@@ -183,6 +183,8 @@ File breakdown of all tests (369 items):
 | `tests/unit/test_package_metadata.py` | 1 | Package metadata consistency |
 | `tests/unit/test_memory_info.py` | 8 | v14: `get_available_memory_bytes()` OS dependent memory detection |
 | `tests/unit/test_memory_guard.py` | 8 | v14: `NullGuard`/`InitGuard`/`PerWriteGuard` strategy patterns |
+| `tests/unit/test_archive_sanitize.py` | 12 | v15: `_sanitize_archive_path()` Zip Slip prevention |
+| `tests/unit/test_archive_adapter.py` | 13 | v15: `ArchiveAdapter` base class, `can_handle()`, `_detect()` |
 | `tests/integration/test_open_modes.py` | 21 | `open()` modes behavior (rb/wb/ab/r+b/xb) |
 | `tests/integration/test_mkdir_listdir.py` | 32 | `mkdir`, `listdir`, `exists`, `is_dir`, `glob`, `walk` |
 | `tests/integration/test_rename_move.py` | 34 | `rename`, `move`, `copy`, `copy_tree` |
@@ -192,13 +194,16 @@ File breakdown of all tests (369 items):
 | `tests/integration/test_concurrency.py` | 7 | Multi-threaded concurrent access |
 | `tests/integration/test_async.py` | 22 | `AsyncMemoryFileSystem` asynchronous API |
 | `tests/integration/test_memory_guard_integration.py` | 12 | v14: MemoryGuard integration tests, MemoryError messages |
+| `tests/integration/test_archive_expand.py` | 19 | v15: `expand_archive()` atomic extraction integration tests |
+| `tests/integration/test_archive_streaming.py` | 20 | v15: `expand_archive_streaming()` streaming extraction integration tests |
 | `tests/scenarios/test_usecase_etl_staging.py` | 4 | ETL staging, incremental updates, concurrent writing |
 | `tests/scenarios/test_usecase_archive_like.py` | 5 | Archive operations, import_tree/export_tree roundtrip |
 | `tests/scenarios/test_usecase_sqlite_snapshot.py` | 3 | SQLite serialize/deserialize, quota limits |
 | `tests/scenarios/test_usecase_restricted_env.py` | 3 | Use cases in quota-restricted environments |
+| `tests/scenarios/test_usecase_archive_expand.py` | 3 | v15: UC-1 archive expand → transform → repack scenarios |
 | `tests/stress/test_threaded_stress.py` | 6 | Multi-threaded stress tests |
 | `tests/property/test_hypothesis.py` | 5 | Hypothesis property-based tests |
-| **Total** | **369** | |
+| **Total** | **436** | |
 
 
 See `.github/workflows/test.yml` for GitHub Actions settings.

TESTING_ja.md

@@ -61,7 +61,9 @@ tests/
 │   ├── test_text_handle.py
 │   ├── test_package_metadata.py
 │   ├── test_memory_info.py         # v14: OS 依存メモリ検出
-│   └── test_memory_guard.py        # v14: MemoryGuard 戦略
+│   ├── test_memory_guard.py        # v14: MemoryGuard 戦略
+│   ├── test_archive_sanitize.py    # v15: _sanitize_archive_path() Zip Slip 防止
+│   └── test_archive_adapter.py     # v15: ArchiveAdapter 基底クラス・_detect()
 ├── integration/        # MemoryFileSystem 公開 API の結合テスト
 │   ├── test_open_modes.py
 │   ├── test_mkdir_listdir.py
@@ -71,12 +73,15 @@ tests/
 │   ├── test_stats.py
 │   ├── test_concurrency.py
 │   ├── test_async.py             # v11: AsyncMemoryFileSystem
-│   └── test_memory_guard_integration.py  # v14: MemoryGuard 統合テスト
+│   ├── test_memory_guard_integration.py  # v14: MemoryGuard 統合テスト
+│   ├── test_archive_expand.py    # v15: expand_archive() 結合テスト
+│   └── test_archive_streaming.py # v15: expand_archive_streaming() 結合テスト
 ├── scenarios/          # 代表ユースケースのシナリオテスト
 │   ├── test_usecase_sqlite_snapshot.py
 │   ├── test_usecase_etl_staging.py
 │   ├── test_usecase_archive_like.py
-│   └── test_usecase_restricted_env.py
+│   ├── test_usecase_restricted_env.py
+│   └── test_usecase_archive_expand.py  # v15: UC-1 アーカイブ展開シナリオ
 ├── stress/             # 負荷・ストレステスト
 │   └── test_threaded_stress.py
 ├── property/           # Hypothesis プロパティベーステスト
@@ -167,7 +172,7 @@ uvx --with-requirements requirements.txt pdoc dmemfs -o docs/api
 
 ## テストファイル対応表
 
-全テスト（369件）のファイル別内訳:
+全テスト（436件）のファイル別内訳:
 
 | ファイルパス | テスト数 | カバー領域 |
 |---|---:|---|
@@ -184,6 +189,8 @@ uvx --with-requirements requirements.txt pdoc dmemfs -o docs/api
 | `tests/unit/test_package_metadata.py` | 1 | パッケージメタデータの整合性 |
 | `tests/unit/test_memory_info.py` | 8 | v14: `get_available_memory_bytes()` OS 依存メモリ検出 |
 | `tests/unit/test_memory_guard.py` | 8 | v14: `NullGuard`/`InitGuard`/`PerWriteGuard` 戦略パターン |
+| `tests/unit/test_archive_sanitize.py` | 12 | v15: `_sanitize_archive_path()` Zip Slip 防止 |
+| `tests/unit/test_archive_adapter.py` | 13 | v15: `ArchiveAdapter` 基底クラス・`can_handle()`・`_detect()` |
 | `tests/integration/test_open_modes.py` | 21 | `open()` モード（rb/wb/ab/r+b/xb）の動作 |
 | `tests/integration/test_mkdir_listdir.py` | 32 | `mkdir`・`listdir`・`exists`・`is_dir`・`glob`・`walk` |
 | `tests/integration/test_rename_move.py` | 34 | `rename`・`move`・`copy`・`copy_tree` |
@@ -193,13 +200,16 @@ uvx --with-requirements requirements.txt pdoc dmemfs -o docs/api
 | `tests/integration/test_concurrency.py` | 7 | マルチスレッド並行アクセス |
 | `tests/integration/test_async.py` | 22 | `AsyncMemoryFileSystem` 非同期 API |
 | `tests/integration/test_memory_guard_integration.py` | 12 | v14: MemoryGuard 統合テスト・MemoryError メッセージ |
+| `tests/integration/test_archive_expand.py` | 19 | v15: `expand_archive()` アトミック展開 結合テスト |
+| `tests/integration/test_archive_streaming.py` | 20 | v15: `expand_archive_streaming()` ストリーミング展開 結合テスト |
 | `tests/scenarios/test_usecase_etl_staging.py` | 4 | ETL ステージング・増分更新・並行書き込み |
 | `tests/scenarios/test_usecase_archive_like.py` | 5 | アーカイブ操作・import_tree/export_tree ラウンドトリップ |
 | `tests/scenarios/test_usecase_sqlite_snapshot.py` | 3 | SQLite serialize/deserialize・クォータ制限 |
 | `tests/scenarios/test_usecase_restricted_env.py` | 3 | クォータ制限環境でのユースケース |
+| `tests/scenarios/test_usecase_archive_expand.py` | 3 | v15: UC-1 アーカイブ展開→加工→再パック シナリオ |
 | `tests/stress/test_threaded_stress.py` | 6 | マルチスレッド負荷テスト |
 | `tests/property/test_hypothesis.py` | 5 | Hypothesis プロパティベーステスト |
-| **合計** | **369** | |
+| **合計** | **436** | |
 
 
 GitHub Actions の設定は `.github/workflows/test.yml` を参照。  

dmemfs/__init__.py

@@ -1,5 +1,6 @@
 from typing import TYPE_CHECKING
 
+from ._archive import ArchiveAdapter, expand_archive, expand_archive_streaming
 from ._exceptions import MFSNodeLimitExceededError, MFSQuotaExceededError
 from ._fs import MemoryFileSystem
 from ._handle import MemoryFileHandle
@@ -30,5 +31,9 @@ def __getattr__(name: str):  # type: ignore[no-untyped-def]
     "MFSTextHandle",
     "AsyncMemoryFileSystem",
     "AsyncMemoryFileHandle",
+    # v15: archive expansion
+    "ArchiveAdapter",
+    "expand_archive",
+    "expand_archive_streaming",
 ]
-__version__ = "0.3.0"
+__version__ = "0.4.0"