pywimparser 0.1.0__tar.gz

pywimparser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pywimparser contributors
+
+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.

pywimparser-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md LICENSE THIRD_PARTY_NOTICES.md
+include scripts/build_libwim.sh
+recursive-include src/pywimparser py.typed
+recursive-include tests *.py *.wim *.md

pywimparser-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: pywimparser
+Version: 0.1.0
+Summary: Python library for parsing and extracting Microsoft WIM archives via libwim
+Author: pywimparser contributors
+License: MIT
+Project-URL: Homepage, https://github.com/bwhitn/pywimparser
+Project-URL: Repository, https://github.com/bwhitn/pywimparser
+Project-URL: Issues, https://github.com/bwhitn/pywimparser/issues
+Keywords: wim,windows,forensics,parser,archive
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Archiving
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Dynamic: license-file
+
+# pywimparser
+
+`pywimparser` is a Python library for reading Microsoft WIM archives.
+
+It focuses on:
+- parsing as much metadata as possible
+- listing files/directories inside images
+- extracting full images or selected paths
+
+This project is read-only for WIM operations. It does **not** create or modify WIM files.
+
+## Backend Model
+
+`pywimparser` has two runtime paths:
+
+- Native `libwim` backend (`ctypes`, raw C API)
+  - full metadata traversal
+  - robust extraction support
+  - supports XPRESS, LZX, and LZMS through `libwim`
+- Pure Python fallback
+  - parses core WIM structures directly
+  - can list/extract uncompressed resources
+  - cannot fully decompress entropy-coded XPRESS/LZX/LZMS resources
+
+Use `WimParser.parse_backend` to see which backend was used for a parse call.
+
+## Features
+
+- Archive-level metadata
+  - header fields (signature, version, flags, chunk size, GUID, parts, image count)
+  - lookup/offset table entries
+  - XML document (when available)
+- Image metadata
+  - name, description, display name/description
+  - file/dir counts and total bytes (when present)
+  - selected Windows metadata from XML (when present)
+- Filesystem metadata
+  - path, type, timestamps, attributes, size, packed size, stream hash
+- Extraction
+  - `extract_all()` for an image
+  - `extract([...])` for selected paths
+
+## Platform Support
+
+- Packaging:
+  - `pywimparser` is distributed as a pure-Python wheel (`py3-none-any`) plus sdist.
+  - The same wheel is installable on Linux/macOS/Windows for Intel and ARM.
+- CI coverage:
+  - Linux: x64 + arm64
+  - macOS: Intel + Apple Silicon
+  - Windows: x64 + arm64
+- Native `libwim` backend CI:
+  - validated on Linux x64 + arm64
+  - other platforms use the pure-Python fallback unless `libwim` is installed and discoverable
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install pywimparser
+```
+
+For full extraction/compression support, ensure `libwim` is installed and discoverable.
+
+## Build `libwim` Without `ntfs-3g`
+
+The repository includes `scripts/build_libwim.sh` to build shared `libwim` with:
+- `--without-ntfs-3g`
+- `--without-fuse`
+- `--enable-shared`
+- `--disable-static`
+
+This keeps usage in the `libwim` dual-license path that allows LGPL option when `ntfs-3g` is not linked.
+
+```bash
+./scripts/build_libwim.sh
+```
+
+After build, point `pywimparser` to the library:
+
+```bash
+export PYWIMPARSER_WIMLIB_PREFIX="$(pwd)/.vendor/wimlib"
+# or:
+export PYWIMPARSER_LIBWIM="$(pwd)/.vendor/wimlib/lib/libwim.so"
+```
+
+## Quick Start
+
+```python
+from pywimparser import WimParser
+
+parser = WimParser("install.wim")
+metadata = parser.parse()
+
+print(parser.parse_backend)              # "libwim-c" or "python"
+print(parser.native_backend_available)   # True if libwim is usable
+print(metadata.header.compression_format)
+
+entries = parser.list_entries(image_index=1)
+print(entries[0].path)
+
+parser.extract_all("./out", image_index=1)
+parser.extract(["Windows/System32/notepad.exe"], "./out", image_index=1)
+```
+
+## CLI
+
+```bash
+pywimparser info install.wim
+pywimparser list install.wim --image 1
+pywimparser extract install.wim ./out --image 1
+pywimparser extract install.wim ./out --image 1 --path Windows/System32/cmd.exe
+```
+
+## Development
+
+Create and activate a virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install package + dev tooling:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Fixture notes are in `tests/fixtures/README.md`.
+
+## Build Artifacts
+
+Build wheel + sdist:
+
+```bash
+python -m build
+```
+
+## GitHub Actions / PyPI Readiness
+
+The repository includes workflows for:
+- CI (install package, run tests, build artifacts)
+- Publish (build sdist/wheel, publish with trusted publishing)
+
+Before releasing publicly:
+- confirm `project.urls` in `pyproject.toml`
+- choose and document your versioning policy
+- configure your PyPI trusted publisher or token flow
+
+Tracked checklist: see `NEXT_STEPS.md`.
+
+## Public API
+
+Main class:
+- `WimParser(path)`
+
+Methods:
+- `parse(force_reload=False)`
+- `list_entries(image_index=1)`
+- `extract_all(destination, image_index=1)`
+- `extract(paths, destination, image_index=1)`
+
+Properties:
+- `parse_backend`
+- `native_backend_available`
+- `rust_backend_available` (compatibility alias)
+- `extraction_available`
+
+## License
+
+`pywimparser` is licensed under MIT.
+
+`libwim` is third-party software with its own license terms. See `THIRD_PARTY_NOTICES.md`.
+
+This README is technical guidance, not legal advice.

pywimparser-0.1.0/README.md

@@ -0,0 +1,184 @@
+# pywimparser
+
+`pywimparser` is a Python library for reading Microsoft WIM archives.
+
+It focuses on:
+- parsing as much metadata as possible
+- listing files/directories inside images
+- extracting full images or selected paths
+
+This project is read-only for WIM operations. It does **not** create or modify WIM files.
+
+## Backend Model
+
+`pywimparser` has two runtime paths:
+
+- Native `libwim` backend (`ctypes`, raw C API)
+  - full metadata traversal
+  - robust extraction support
+  - supports XPRESS, LZX, and LZMS through `libwim`
+- Pure Python fallback
+  - parses core WIM structures directly
+  - can list/extract uncompressed resources
+  - cannot fully decompress entropy-coded XPRESS/LZX/LZMS resources
+
+Use `WimParser.parse_backend` to see which backend was used for a parse call.
+
+## Features
+
+- Archive-level metadata
+  - header fields (signature, version, flags, chunk size, GUID, parts, image count)
+  - lookup/offset table entries
+  - XML document (when available)
+- Image metadata
+  - name, description, display name/description
+  - file/dir counts and total bytes (when present)
+  - selected Windows metadata from XML (when present)
+- Filesystem metadata
+  - path, type, timestamps, attributes, size, packed size, stream hash
+- Extraction
+  - `extract_all()` for an image
+  - `extract([...])` for selected paths
+
+## Platform Support
+
+- Packaging:
+  - `pywimparser` is distributed as a pure-Python wheel (`py3-none-any`) plus sdist.
+  - The same wheel is installable on Linux/macOS/Windows for Intel and ARM.
+- CI coverage:
+  - Linux: x64 + arm64
+  - macOS: Intel + Apple Silicon
+  - Windows: x64 + arm64
+- Native `libwim` backend CI:
+  - validated on Linux x64 + arm64
+  - other platforms use the pure-Python fallback unless `libwim` is installed and discoverable
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install pywimparser
+```
+
+For full extraction/compression support, ensure `libwim` is installed and discoverable.
+
+## Build `libwim` Without `ntfs-3g`
+
+The repository includes `scripts/build_libwim.sh` to build shared `libwim` with:
+- `--without-ntfs-3g`
+- `--without-fuse`
+- `--enable-shared`
+- `--disable-static`
+
+This keeps usage in the `libwim` dual-license path that allows LGPL option when `ntfs-3g` is not linked.
+
+```bash
+./scripts/build_libwim.sh
+```
+
+After build, point `pywimparser` to the library:
+
+```bash
+export PYWIMPARSER_WIMLIB_PREFIX="$(pwd)/.vendor/wimlib"
+# or:
+export PYWIMPARSER_LIBWIM="$(pwd)/.vendor/wimlib/lib/libwim.so"
+```
+
+## Quick Start
+
+```python
+from pywimparser import WimParser
+
+parser = WimParser("install.wim")
+metadata = parser.parse()
+
+print(parser.parse_backend)              # "libwim-c" or "python"
+print(parser.native_backend_available)   # True if libwim is usable
+print(metadata.header.compression_format)
+
+entries = parser.list_entries(image_index=1)
+print(entries[0].path)
+
+parser.extract_all("./out", image_index=1)
+parser.extract(["Windows/System32/notepad.exe"], "./out", image_index=1)
+```
+
+## CLI
+
+```bash
+pywimparser info install.wim
+pywimparser list install.wim --image 1
+pywimparser extract install.wim ./out --image 1
+pywimparser extract install.wim ./out --image 1 --path Windows/System32/cmd.exe
+```
+
+## Development
+
+Create and activate a virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install package + dev tooling:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Fixture notes are in `tests/fixtures/README.md`.
+
+## Build Artifacts
+
+Build wheel + sdist:
+
+```bash
+python -m build
+```
+
+## GitHub Actions / PyPI Readiness
+
+The repository includes workflows for:
+- CI (install package, run tests, build artifacts)
+- Publish (build sdist/wheel, publish with trusted publishing)
+
+Before releasing publicly:
+- confirm `project.urls` in `pyproject.toml`
+- choose and document your versioning policy
+- configure your PyPI trusted publisher or token flow
+
+Tracked checklist: see `NEXT_STEPS.md`.
+
+## Public API
+
+Main class:
+- `WimParser(path)`
+
+Methods:
+- `parse(force_reload=False)`
+- `list_entries(image_index=1)`
+- `extract_all(destination, image_index=1)`
+- `extract(paths, destination, image_index=1)`
+
+Properties:
+- `parse_backend`
+- `native_backend_available`
+- `rust_backend_available` (compatibility alias)
+- `extraction_available`
+
+## License
+
+`pywimparser` is licensed under MIT.
+
+`libwim` is third-party software with its own license terms. See `THIRD_PARTY_NOTICES.md`.
+
+This README is technical guidance, not legal advice.

pywimparser-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,25 @@
+# Third-Party Notices
+
+`pywimparser` itself is licensed under MIT.
+
+This project can use `libwim` at runtime through `ctypes` (dynamic linking).
+
+## libwim
+
+- Project: https://wimlib.net/
+- Upstream source: https://github.com/ebiggers/wimlib
+
+Upstream licensing summary (from wimlib project documentation):
+- wimlib project as a whole: GPLv3+
+- `libwim` library component: dual license, GPLv3+ **or** LGPLv2.1+ when allowed
+- If built with `libntfs-3g` linkage, GPL requirements apply
+- If built without `ntfs-3g` (for example `./configure --without-ntfs-3g`), LGPL option for `libwim` remains available
+
+`scripts/build_libwim.sh` in this repository intentionally builds with `--without-ntfs-3g`.
+
+## Distribution Notes
+
+- `pywimparser` does not bundle `libwim` by default.
+- If you redistribute binaries that include or depend on `libwim`, you must satisfy `libwim`'s license obligations for your chosen build/distribution model.
+
+This file is a technical summary, not legal advice.

pywimparser-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pywimparser"
+version = "0.1.0"
+description = "Python library for parsing and extracting Microsoft WIM archives via libwim"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "pywimparser contributors" }]
+keywords = ["wim", "windows", "forensics", "parser", "archive"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: System :: Archiving",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "twine>=5.1.1",
+]
+
+[project.scripts]
+pywimparser = "pywimparser.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/bwhitn/pywimparser"
+Repository = "https://github.com/bwhitn/pywimparser"
+Issues = "https://github.com/bwhitn/pywimparser/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pywimparser = ["py.typed"]

pywimparser-0.1.0/scripts/build_libwim.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+VERSION="${WIMLIB_VERSION:-1.14.5}"
+PREFIX="${WIMLIB_PREFIX:-$(pwd)/.vendor/wimlib}"
+WORKDIR="${WIMLIB_WORKDIR:-/tmp/wimlib-build-${VERSION}}"
+TARBALL="/tmp/wimlib-${VERSION}.tar.gz"
+SRC_DIR="${WORKDIR}/wimlib-${VERSION}"
+
+if command -v nproc >/dev/null 2>&1; then
+  BUILD_JOBS="$(nproc)"
+elif command -v sysctl >/dev/null 2>&1; then
+  BUILD_JOBS="$(sysctl -n hw.ncpu)"
+else
+  BUILD_JOBS=1
+fi
+
+echo "Building wimlib ${VERSION} without ntfs-3g"
+echo "Install prefix: ${PREFIX}"
+
+rm -rf "${WORKDIR}"
+mkdir -p "${WORKDIR}"
+
+curl -L "https://wimlib.net/downloads/wimlib-${VERSION}.tar.gz" -o "${TARBALL}"
+tar -xzf "${TARBALL}" -C "${WORKDIR}"
+
+pushd "${SRC_DIR}" >/dev/null
+./configure \
+  --prefix="${PREFIX}" \
+  --without-ntfs-3g \
+  --without-fuse \
+  --enable-shared \
+  --disable-static
+make -j"${BUILD_JOBS}"
+make install
+popd >/dev/null
+
+echo "libwim built at ${PREFIX}"
+echo "Set one of:"
+echo "  export PYWIMPARSER_WIMLIB_PREFIX=${PREFIX}"
+echo "  export PYWIMPARSER_LIBWIM=${PREFIX}/lib/libwim.so"

pywimparser-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pywimparser-0.1.0/src/pywimparser/__init__.py

@@ -0,0 +1,33 @@
+"""pywimparser public API."""
+
+from .exceptions import (
+    ExternalToolError,
+    ExtractionError,
+    InvalidWimError,
+    UnsupportedFeatureError,
+    WimParserError,
+)
+from .models import (
+    WimArchiveMetadata,
+    WimFileEntry,
+    WimHeader,
+    WimImageMetadata,
+    WimLookupEntry,
+    WimResourceHeader,
+)
+from .parser import WimParser
+
+__all__ = [
+    "ExternalToolError",
+    "ExtractionError",
+    "InvalidWimError",
+    "UnsupportedFeatureError",
+    "WimParser",
+    "WimParserError",
+    "WimArchiveMetadata",
+    "WimFileEntry",
+    "WimHeader",
+    "WimImageMetadata",
+    "WimLookupEntry",
+    "WimResourceHeader",
+]

pywimparser-0.1.0/src/pywimparser/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())