pywimparser 0.1.0
Python library for parsing and extracting Microsoft WIM archives via libwim
License: MIT
Requires Python: >=3.10
Keywords: wim, windows, forensics, parser, archive

# 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.