rawblock-io 0.1.0__py3-none-any.whl

rawblock_io/__init__.py

@@ -0,0 +1,41 @@
+"""Raw block device I/O with automatic strategy fallback.
+
+Provides a pluggable I/O strategy chain for reading/writing raw block
+devices and disk image files, along with cross-platform device and
+mount-point resolution.
+
+Layers (one file per layer):
+  ``_resolve``     — Block device / mount point resolution
+  ``_strategies``  — Pluggable I/O strategy base class & helpers
+  ``_direct_io``   — ``DirectIOStrategy``
+  ``_backing_file`` — ``BackingFileStrategy``
+  ``_dd``          — ``DDStrategy``
+  ``_io``          — ``RawBlockIO`` (strategy chain)
+"""
+
+from rawblock_io._strategies import (
+    IOStrategy,
+    DirectIOStrategy,
+    BackingFileStrategy,
+    DDStrategy,
+    BLOCK_SIZE,
+    _block_align,
+    _try_pread,
+    _try_pwrite,
+)
+from rawblock_io._io import RawBlockIO
+from rawblock_io._resolve import resolve_device, resolve_mount_point
+
+__all__ = [
+    'IOStrategy',
+    'DirectIOStrategy',
+    'BackingFileStrategy',
+    'DDStrategy',
+    'BLOCK_SIZE',
+    '_block_align',
+    '_try_pread',
+    '_try_pwrite',
+    'RawBlockIO',
+    'resolve_device',
+    'resolve_mount_point',
+]

rawblock_io/_backing_file.py

@@ -0,0 +1,84 @@
+"""Backing-file strategy — reads/writes via the loop-device backing file."""
+
+import os
+import platform
+import plistlib
+import subprocess
+
+from rawblock_io._strategies import IOStrategy, _try_pread, _try_pwrite
+
+
+class BackingFileStrategy(IOStrategy):
+    """Resolve the loop-device backing file and operate on that.
+
+    When the *device* is a loop device (e.g. ``/dev/loop0``) this
+    reads/writes the underlying backing file directly, bypassing
+    the kernel block layer entirely.
+
+    On macOS resolves via ``hdiutil info -plist`` instead.
+    """
+
+    def __init__(self):
+        self._backing_cache: dict[str, str | None] = {}
+        self._is_darwin = platform.system() == 'Darwin'
+
+    def _resolve(self, device: str) -> str | None:
+        if device not in self._backing_cache:
+            if self._is_darwin:
+                self._backing_cache[device] = self._resolve_darwin(device)
+            else:
+                self._backing_cache[device] = self._resolve_linux(device)
+        return self._backing_cache[device]
+
+    def _resolve_linux(self, device: str) -> str | None:
+        dev_name = device.lstrip('/dev/')
+        for cmd in (
+            ['cat', f'/sys/block/{dev_name}/loop/backing_file'],
+            ['sudo', 'cat', f'/sys/block/{dev_name}/loop/backing_file'],
+            ['losetup', '-n', '-O', 'BACK-FILE', device],
+            ['sudo', 'losetup', '-n', '-O', 'BACK-FILE', device],
+        ):
+            try:
+                r = subprocess.run(
+                    cmd, capture_output=True, text=True, timeout=5)
+                if r.returncode == 0:
+                    return r.stdout.strip() or None
+            except Exception:
+                pass
+        return None
+
+    def _resolve_darwin(self, device: str) -> str | None:
+        try:
+            r = subprocess.run(
+                ['hdiutil', 'info', '-plist'],
+                capture_output=True, text=True, timeout=10)
+            if r.returncode != 0:
+                return None
+            plist = plistlib.loads(r.stdout.encode())
+            for img in plist.get('images', []):
+                if not isinstance(img, dict):
+                    continue
+                for ent in img.get('system-entities', []):
+                    if isinstance(ent, dict) and ent.get('dev-entry') == device:
+                        return img.get('image-path')
+        except Exception:
+            pass
+        return None
+
+    def read(self, device: str, offset: int, size: int) -> bytes | None:
+        backing = self._resolve(device)
+        if backing and os.access(backing, os.R_OK):
+            return _try_pread(backing, offset, size)
+        return None
+
+    def write(self, device: str, offset: int, data: bytes) -> bool:
+        backing = self._resolve(device)
+        if backing and os.access(backing, os.W_OK):
+            return _try_pwrite(backing, offset, data)
+        return False
+
+    def clear_cache(self, device: str | None = None):
+        if device is None:
+            self._backing_cache.clear()
+        else:
+            self._backing_cache.pop(device, None)

rawblock_io/_dd.py

@@ -0,0 +1,59 @@
+"""DD strategy — falls back to ``sudo dd`` for raw block device I/O."""
+
+import subprocess
+import tempfile
+
+from rawblock_io._strategies import IOStrategy, BLOCK_SIZE, _block_align
+
+
+class DDStrategy(IOStrategy):
+    """Fall back to ``sudo dd`` for read/write on physical block devices.
+
+    Used when the process lacks direct access to the device and must
+    elevate privileges via ``sudo``.
+
+    I/O is always done in multiples of ``BLOCK_SIZE`` (512 bytes) to
+    support platforms where the device requires sector-aligned access
+    (e.g. macOS ``/dev/rdisk*`` raw devices).
+    """
+
+    def read(self, device: str, offset: int, size: int) -> bytes | None:
+        try:
+            aligned_off, total, skip = _block_align(offset, size)
+            cmd = ['sudo', 'dd', f'if={device}', f'bs={BLOCK_SIZE}',
+                   f'skip={aligned_off // BLOCK_SIZE}',
+                   f'count={total // BLOCK_SIZE}']
+            r = subprocess.run(cmd, stdout=subprocess.PIPE,
+                               stderr=subprocess.DEVNULL)
+            if r.returncode != 0:
+                return None
+            return r.stdout[skip:skip + size]
+        except FileNotFoundError:
+            return None
+
+    def write(self, device: str, offset: int, data: bytes) -> bool:
+        try:
+            aligned_off, total, skip = _block_align(offset, len(data))
+            if skip == 0 and total == len(data):
+                return self._write_blocks(device, aligned_off, data)
+            buf = self.read(device, aligned_off, total)
+            if buf is None or len(buf) < total:
+                return False
+            buf = bytearray(buf)
+            buf[skip:skip + len(data)] = data
+            return self._write_blocks(device, aligned_off, bytes(buf))
+        except FileNotFoundError:
+            return False
+
+    def _write_blocks(self, device: str, offset: int, data: bytes) -> bool:
+        with tempfile.NamedTemporaryFile() as tf:
+            tf.write(data)
+            tf.flush()
+            cmd = ['sudo', 'dd', f'if={tf.name}', f'of={device}',
+                   f'bs={BLOCK_SIZE}',
+                   f'seek={offset // BLOCK_SIZE}',
+                   f'count={len(data) // BLOCK_SIZE}',
+                   'conv=fsync']
+            subprocess.run(cmd, check=True, stdout=subprocess.PIPE,
+                           stderr=subprocess.DEVNULL)
+        return True

rawblock_io/_direct_io.py

@@ -0,0 +1,17 @@
+"""Direct I/O strategy — reads/writes via ``os.pread``/``os.pwrite``."""
+
+from rawblock_io._strategies import IOStrategy, _try_pread, _try_pwrite
+
+
+class DirectIOStrategy(IOStrategy):
+    """Read/write directly on *device* via ``os.pread``/``os.pwrite``.
+
+    Works for regular files (e.g. disk images) and any block device
+    the process has permission to access.
+    """
+
+    def read(self, device: str, offset: int, size: int) -> bytes | None:
+        return _try_pread(device, offset, size)
+
+    def write(self, device: str, offset: int, data: bytes) -> bool:
+        return _try_pwrite(device, offset, data)

rawblock_io/_io.py

@@ -0,0 +1,43 @@
+"""Raw block I/O — delegates to a chain of pluggable strategies."""
+
+from rawblock_io._strategies import (
+    IOStrategy,
+    DirectIOStrategy,
+    BackingFileStrategy,
+    DDStrategy,
+)
+
+
+def _default_strategies() -> list[IOStrategy]:
+    return [DirectIOStrategy(), BackingFileStrategy(), DDStrategy()]
+
+
+class RawBlockIO:
+    """Raw block I/O — delegates to a chain of pluggable strategies.
+
+    Parameters
+    ----------
+    strategies
+        Ordered list of ``IOStrategy`` instances. Defaults to
+        ``[DirectIOStrategy(), BackingFileStrategy(), DDStrategy()]``
+        on Linux; ``[DirectIOStrategy(), DDStrategy()]`` on macOS.
+    """
+
+    def __init__(self, strategies: list[IOStrategy] | None = None):
+        self._strategies = strategies or _default_strategies()
+
+    def clear_cache(self, device: str | None = None):
+        for s in self._strategies:
+            s.clear_cache(device)
+
+    def read(self, device: str, offset: int, size: int) -> bytes:
+        for s in self._strategies:
+            result = s.read(device, offset, size)
+            if result is not None:
+                return result
+        return b''
+
+    def write(self, device: str, offset: int, data: bytes):
+        for s in self._strategies:
+            if s.write(device, offset, data):
+                return

rawblock_io/_resolve.py

@@ -0,0 +1,57 @@
+"""Platform-specific helpers to resolve a block device and mount point from a
+file path.
+
+Dispatches to an OS-specific submodule (``_resolve_linux`` or
+``_resolve_darwin``) at module-load time and re-exports the public API.
+"""
+
+import importlib
+import platform
+import subprocess
+
+
+SYSTEM = platform.system()
+
+
+def _df_output(path: str) -> tuple[str, str, str] | None:
+    """Return ``(device, mount_point, fstype)`` for *path* via ``df``."""
+    try:
+        if SYSTEM == 'Darwin':
+            r = subprocess.run(
+                ['df', str(path)],
+                capture_output=True, text=True, timeout=5)
+            if r.returncode != 0:
+                return None
+            lines = r.stdout.strip().splitlines()
+            if len(lines) < 2:
+                return None
+            parts = lines[1].split()
+            if len(parts) < 3:
+                return None
+            device = parts[0]
+            mount_point = parts[-1]
+            stat_r = subprocess.run(
+                ['stat', '-f', '%T', str(path)],
+                capture_output=True, text=True, timeout=5)
+            fstype = stat_r.stdout.strip() if stat_r.returncode == 0 else ''
+            return device, mount_point, fstype
+        else:
+            r = subprocess.run(
+                ['df', '--output=fstype,target,source', str(path)],
+                capture_output=True, text=True, timeout=5)
+            if r.returncode != 0:
+                return None
+            lines = r.stdout.strip().splitlines()
+            if len(lines) < 2:
+                return None
+            cols = lines[1].split(None, 2)
+            if len(cols) < 3:
+                return None
+            return cols[2], cols[1], cols[0]
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
+        return None
+
+
+_mod = importlib.import_module(f'._resolve_{SYSTEM.lower()}', __package__)
+resolve_device = _mod.resolve_device
+resolve_mount_point = _mod.resolve_mount_point

rawblock_io/_resolve_darwin.py

@@ -0,0 +1,42 @@
+"""macOS-specific device/mount resolution."""
+
+import os
+import plistlib
+import subprocess
+
+from rawblock_io._resolve import _df_output
+
+
+def resolve_device(path: str) -> str | None:
+    info = _df_output(path)
+    if info:
+        dev = info[0]
+        backing = _resolve_backing_file_darwin(dev)
+        if backing and os.path.isfile(backing):
+            return backing
+        return dev
+    return None
+
+
+def _resolve_backing_file_darwin(dev_entry: str) -> str | None:
+    try:
+        r = subprocess.run(
+            ['hdiutil', 'info', '-plist'],
+            capture_output=True, text=True, timeout=10)
+        if r.returncode != 0:
+            return None
+        plist = plistlib.loads(r.stdout.encode())
+        for img in plist.get('images', []):
+            if not isinstance(img, dict):
+                continue
+            for ent in img.get('system-entities', []):
+                if isinstance(ent, dict) and ent.get('dev-entry') == dev_entry:
+                    return img.get('image-path')
+    except Exception:
+        pass
+    return None
+
+
+def resolve_mount_point(path: str) -> str | None:
+    info = _df_output(path)
+    return info[1] if info else None

rawblock_io/_resolve_linux.py

@@ -0,0 +1,30 @@
+"""Linux-specific device/mount resolution."""
+
+import os
+import subprocess
+
+
+def resolve_device(path: str) -> str | None:
+    st = os.stat(path)
+    major = os.major(st.st_dev)
+    minor = os.minor(st.st_dev)
+    with open('/proc/partitions') as f:
+        for line in f:
+            parts = line.split()
+            if len(parts) == 4 and parts[0].isdigit():
+                if int(parts[0]) == major and int(parts[1]) == minor:
+                    return f'/dev/{parts[3]}'
+    try:
+        link = os.readlink(f'/sys/dev/block/{major}:{minor}')
+        return os.path.join('/dev', os.path.basename(link))
+    except OSError:
+        return None
+
+
+def resolve_mount_point(path: str) -> str | None:
+    r = subprocess.run(
+        ['findmnt', '-n', '-o', 'TARGET', '--target', str(path)],
+        capture_output=True, text=True, timeout=5)
+    if r.returncode == 0 and r.stdout.strip():
+        return r.stdout.strip()
+    return None

rawblock_io/_strategies.py

@@ -0,0 +1,80 @@
+"""Pluggable I/O strategy classes for raw block I/O.
+
+Each strategy implements a different mechanism for reading/writing raw
+blocks on a device path. Strategies are tried in order until one succeeds.
+
+The base class and shared helpers live here; each concrete strategy is
+defined in its own submodule and re-exported below.
+"""
+
+import os
+from abc import ABC, abstractmethod
+
+
+class IOStrategy(ABC):
+    """Pluggable read/write strategy for raw block I/O."""
+
+    @abstractmethod
+    def read(self, device: str, offset: int, size: int) -> bytes | None:
+        """Read *size* bytes from *device* at *offset*.
+
+        Return bytes on success, or ``None`` to fall through to the
+        next strategy in the chain.
+        """
+
+    @abstractmethod
+    def write(self, device: str, offset: int, data: bytes) -> bool | None:
+        """Write *data* to *device* at *offset*.
+
+        Return ``True`` when handled, or ``None``/``False`` to fall
+        through to the next strategy.
+        """
+
+    def clear_cache(self, device: str | None = None):
+        """Drop cached state for *device* (or all if ``None``)."""
+
+
+def _try_pread(path: str, offset: int, size: int) -> bytes | None:
+    try:
+        fd = os.open(path, os.O_RDONLY)
+        try:
+            return os.pread(fd, size, offset)
+        finally:
+            os.close(fd)
+    except OSError:
+        return None
+
+
+def _try_pwrite(path: str, offset: int, data: bytes) -> bool:
+    try:
+        fd = os.open(path, os.O_WRONLY)
+        try:
+            n = os.pwrite(fd, data, offset)
+            assert n == len(data)
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        return True
+    except OSError:
+        return False
+
+
+BLOCK_SIZE = 512
+
+
+def _block_align(offset: int, size: int) -> tuple[int, int, int]:
+    """Return ``(aligned_offset, total_bytes, prefix_skip)``.
+
+    Rounds *offset* down and *size* up so the resulting region is aligned
+    to ``BLOCK_SIZE``.  *prefix_skip* is the number of bytes before the
+    caller's data in the first block.
+    """
+    aligned = (offset // BLOCK_SIZE) * BLOCK_SIZE
+    end = offset + size
+    aligned_end = ((end + BLOCK_SIZE - 1) // BLOCK_SIZE) * BLOCK_SIZE
+    return aligned, aligned_end - aligned, offset - aligned
+
+
+from rawblock_io._direct_io import DirectIOStrategy  # noqa: E402
+from rawblock_io._backing_file import BackingFileStrategy  # noqa: E402
+from rawblock_io._dd import DDStrategy  # noqa: E402

rawblock_io-0.1.0.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: rawblock-io
+Version: 0.1.0
+Summary: Raw block device I/O with automatic strategy fallback and cross-platform device/mount resolution
+Author-email: Michael Banucu <michael.banucu@googlemail.com>
+License: GPL-3.0-only
+Project-URL: Homepage, https://github.com/MBanucu/rawblock-io
+Project-URL: Repository, https://github.com/MBanucu/rawblock-io
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+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: Topic :: System :: Filesystems
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# rawblock-io
+
+Raw block device I/O with automatic strategy fallback and cross-platform
+device/mount point resolution.
+
+## Features
+
+- **Pluggable I/O strategies** — tries direct access first, falls back
+  through loop-device backing file to `sudo dd`
+- **`DirectIOStrategy`** — `os.pread`/`os.pwrite` on regular files and
+  accessible block devices
+- **`BackingFileStrategy`** — resolves loop-device backing files (`/sys/block`,
+  `losetup`, or `hdiutil` on macOS)
+- **`DDStrategy`** — `sudo dd` fallback for physical block devices
+- **`resolve_device`** — find the underlying block device for any file path
+  (Linux `/proc/partitions` + `/sys/dev/block`, macOS `hdiutil`)
+- **`resolve_mount_point`** — find the mount point for any file path
+  (Linux `findmnt`, macOS `df`)
+
+## Quick start
+
+```python
+from rawblock_io import RawBlockIO, resolve_device
+
+io = RawBlockIO()
+device = resolve_device('/some/file')
+data = io.read(device, 0, 512)  # read first sector
+```
+
+## License
+
+GPL-3.0-only

rawblock_io-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+rawblock_io/__init__.py,sha256=r_LfYlw9YZ2GHCFDe_BWpjUVt3_ZGAxqfxNuTTi3rg8,1106
+rawblock_io/_backing_file.py,sha256=PnNvlAHeRycXauUeprNTlFjEbFid6o_efcwg3F_FWeM,3076
+rawblock_io/_dd.py,sha256=eCRqhQb_E_Hv1Nh_-3rMAEaYML7FHJyTW9zPFGQaUTs,2379
+rawblock_io/_direct_io.py,sha256=tKTcqJL_HhqgK8pRbgHMldmqnNT_yf-FksmVLoOw0_8,616
+rawblock_io/_io.py,sha256=Lyrrt25iwM2POZghyEK155H3qdgFArwmbLow8E3xT2I,1309
+rawblock_io/_resolve.py,sha256=eYkz7eNnvmyp2kqNsRnmit26uF1j32e8mO1jhYkLly4,1950
+rawblock_io/_resolve_darwin.py,sha256=001wlHUtp5zpaC3vKuAzMY9vcEjO6S1WDuYW4Q1LDOo,1177
+rawblock_io/_resolve_linux.py,sha256=MTkjYHsRYL9SabyP1Ke5RlXARdzajaHnz5Q9B_u7Um8,935
+rawblock_io/_strategies.py,sha256=cMZ2WirkF7spLGF3aJrqzxJ6sjuZ2C-xdF4iCoBQyq8,2442
+rawblock_io-0.1.0.dist-info/METADATA,sha256=uUNfxI0Y3KA8dReD5lPgoKC97ji6F5AjsVaH00n4hng,2022
+rawblock_io-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rawblock_io-0.1.0.dist-info/top_level.txt,sha256=KhrVE6ZaJnwEW2wS1JoMZV751u2DzR1QV26qM7QU_e8,12
+rawblock_io-0.1.0.dist-info/RECORD,,

rawblock_io-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rawblock_io-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rawblock_io