oaknut-hfe 13.6.0__tar.gz

oaknut_hfe-13.6.0/LICENSE

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

oaknut_hfe-13.6.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: oaknut-hfe
+Version: 13.6.0
+Summary: Python library for reading HFE (HxC Floppy Emulator) flux-level disc images
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-hfe
+Project-URL: Documentation, https://rob-smallshire.github.io/oaknut/disc/api/reference/hfe.html
+Project-URL: Repository, https://github.com/rob-smallshire/oaknut
+Project-URL: Issues, https://github.com/rob-smallshire/oaknut/issues
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: oaknut-exception>=10.0
+Requires-Dist: oaknut-extension>=10.0
+Requires-Dist: oaknut-filesystem>=13.5
+Provides-Extra: cli
+Requires-Dist: oaknut-cli>=10.0; extra == "cli"
+Requires-Dist: oaknut-file>=10.0; extra == "cli"
+Dynamic: license-file
+
+# oaknut-hfe
+
+[![PyPI version](https://img.shields.io/pypi/v/oaknut-hfe)](https://pypi.org/project/oaknut-hfe/)
+[![CI](https://github.com/rob-smallshire/oaknut/actions/workflows/ci.yml/badge.svg)](https://github.com/rob-smallshire/oaknut/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/oaknut-hfe)](https://pypi.org/project/oaknut-hfe/)
+[![License: MIT](https://img.shields.io/pypi/l/oaknut-hfe)](https://github.com/rob-smallshire/oaknut/blob/master/packages/oaknut-hfe/LICENSE)
+
+HFE (HxC Floppy Emulator) disc-image support for the
+[oaknut](https://github.com/rob-smallshire/oaknut) family of packages.
+
+An HFE file records each track of a floppy disc as the raw bitstream the
+drive head delivers. It is the native format of the HxC and Gotek floppy
+emulators and a common output of preservation capture hardware such as
+the Greaseweazle. Because it sits below the sector level, an HFE image
+keeps everything an original disc carries, including the non-standard
+sector IDs, deliberate CRC errors, deleted-data marks and extra tracks
+that copy protection relies on.
+
+This package reads HFE v1 and v3 images, decodes their FM and MFM tracks
+into sectors, and flattens a decoded disc into the logical sector image
+that the oaknut filesystems read.
+
+## Usage
+
+Every `disc` command that reads an image opens an HFE file as the sector
+image decoded from it:
+
+```sh
+disc ls 'Dunjunz_D1S1.hfe:$'
+disc export Dunjunz_D1S1.hfe dunjunz/
+```
+
+The `disc hfe` commands look below the sector level:
+
+```sh
+disc hfe info Dunjunz_D1S1.hfe                 # header and decoded layout
+disc hfe sectors --anomalies Dunjunz_D1S1.hfe  # what protection put there
+disc hfe flatten Dunjunz_D1S1.hfe Dunjunz_D1S1.ssd
+```
+
+From Python:
+
+```python
+from oaknut.hfe import HFEImage, analyse, decode_image, flatten
+
+disc = decode_image(HFEImage.from_filepath("Dunjunz_D1S1.hfe"))
+flat = flatten(disc)  # flat.data is the .ssd image
+for finding in analyse(disc, flat.layout):
+    if finding.anomalous:
+        print(finding.track, finding.side, finding.remarks)
+```
+
+## Status
+
+Pre-alpha, read-only.
+
+## Installation
+
+```sh
+uv add oaknut-hfe
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

oaknut_hfe-13.6.0/README.md

@@ -0,0 +1,65 @@
+# oaknut-hfe
+
+[![PyPI version](https://img.shields.io/pypi/v/oaknut-hfe)](https://pypi.org/project/oaknut-hfe/)
+[![CI](https://github.com/rob-smallshire/oaknut/actions/workflows/ci.yml/badge.svg)](https://github.com/rob-smallshire/oaknut/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/oaknut-hfe)](https://pypi.org/project/oaknut-hfe/)
+[![License: MIT](https://img.shields.io/pypi/l/oaknut-hfe)](https://github.com/rob-smallshire/oaknut/blob/master/packages/oaknut-hfe/LICENSE)
+
+HFE (HxC Floppy Emulator) disc-image support for the
+[oaknut](https://github.com/rob-smallshire/oaknut) family of packages.
+
+An HFE file records each track of a floppy disc as the raw bitstream the
+drive head delivers. It is the native format of the HxC and Gotek floppy
+emulators and a common output of preservation capture hardware such as
+the Greaseweazle. Because it sits below the sector level, an HFE image
+keeps everything an original disc carries, including the non-standard
+sector IDs, deliberate CRC errors, deleted-data marks and extra tracks
+that copy protection relies on.
+
+This package reads HFE v1 and v3 images, decodes their FM and MFM tracks
+into sectors, and flattens a decoded disc into the logical sector image
+that the oaknut filesystems read.
+
+## Usage
+
+Every `disc` command that reads an image opens an HFE file as the sector
+image decoded from it:
+
+```sh
+disc ls 'Dunjunz_D1S1.hfe:$'
+disc export Dunjunz_D1S1.hfe dunjunz/
+```
+
+The `disc hfe` commands look below the sector level:
+
+```sh
+disc hfe info Dunjunz_D1S1.hfe                 # header and decoded layout
+disc hfe sectors --anomalies Dunjunz_D1S1.hfe  # what protection put there
+disc hfe flatten Dunjunz_D1S1.hfe Dunjunz_D1S1.ssd
+```
+
+From Python:
+
+```python
+from oaknut.hfe import HFEImage, analyse, decode_image, flatten
+
+disc = decode_image(HFEImage.from_filepath("Dunjunz_D1S1.hfe"))
+flat = flatten(disc)  # flat.data is the .ssd image
+for finding in analyse(disc, flat.layout):
+    if finding.anomalous:
+        print(finding.track, finding.side, finding.remarks)
+```
+
+## Status
+
+Pre-alpha, read-only.
+
+## Installation
+
+```sh
+uv add oaknut-hfe
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

oaknut_hfe-13.6.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oaknut-hfe"
+dynamic = ["version"]
+authors = [{ name = "Robert Smallshire", email = "robert@smallshire.org.uk" }]
+description = "Python library for reading HFE (HxC Floppy Emulator) flux-level disc images"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "oaknut-exception>=10.0",
+    "oaknut-extension>=10.0",
+    "oaknut-filesystem>=13.5",
+]
+
+# The `cli` extra pulls the shared CLI toolkit so this package can
+# contribute `disc hfe` subcommands. The library core never imports it.
+[project.optional-dependencies]
+cli = ["oaknut-cli>=10.0", "oaknut-file>=10.0"]
+
+[project.urls]
+Homepage = "https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-hfe"
+Documentation = "https://rob-smallshire.github.io/oaknut/disc/api/reference/hfe.html"
+Repository = "https://github.com/rob-smallshire/oaknut"
+Issues = "https://github.com/rob-smallshire/oaknut/issues"
+
+# The image decoder contributed to the oaknut.decoder axis: any `disc`
+# command reading an image opens an HFE file as its flattened sectors.
+[project.entry-points."oaknut.decoder"]
+hfe = "oaknut.hfe.decoder:HFEDecoder"
+
+# Subcommands contributed to the `disc` CLI on the oaknut.command axis:
+# `disc hfe <subcommand>`. Loaded only with the [cli] extra.
+[project.entry-points."oaknut.command"]
+hfe = "oaknut.hfe.cli:hfe"
+
+[tool.setuptools.dynamic]
+version = { attr = "oaknut.hfe.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

oaknut_hfe-13.6.0/setup.cfg

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

oaknut_hfe-13.6.0/src/oaknut/hfe/__init__.py

@@ -0,0 +1,89 @@
+"""HFE (HxC Floppy Emulator) flux-level disc images.
+
+An HFE file records each track of a floppy disc as the raw bitstream a
+drive's read head would deliver, sampled on a fixed cell clock. It is the
+native format of the HxC and Gotek floppy emulators and a common output
+of preservation capture hardware such as the Greaseweazle. Because it sits
+below the sector level, an HFE image keeps everything an original disc
+carries — including the non-standard sector IDs, deliberate CRC errors,
+deleted-data marks and extra tracks that copy protection relies on.
+
+This package reads HFE v1 (``HXCPICFE``) and v3 (``HXCHFEV3``) images,
+decodes their FM and MFM tracks into sectors, and flattens a decoded disc
+into the logical sector image that the oaknut filesystems read.
+"""
+
+from __future__ import annotations
+
+__version__ = "13.6.0"
+
+from oaknut.hfe.build import (
+    TRACK_SAMPLES_300RPM_250KBPS,
+    FormattedSector,
+    build_track,
+    samples_per_half_cell,
+    track_samples,
+)
+from oaknut.hfe.container import (
+    HFE_V1_SIGNATURE,
+    HFE_V3_SIGNATURE,
+    HFEHeader,
+    HFEImage,
+    TrackEncoding,
+    TrackSamples,
+    write_hfe,
+)
+from oaknut.hfe.decode import (
+    DataMark,
+    DecodedDisc,
+    DecodedSector,
+    DecodedTrack,
+    Encoding,
+    SectorID,
+    decode_image,
+    decode_track,
+)
+from oaknut.hfe.decoder import HFEDecoder
+from oaknut.hfe.exceptions import HFEError, HFEFormatError
+from oaknut.hfe.flat import FlatImage, SectorLayout, flatten, flatten_hfe
+from oaknut.hfe.report import SectorFinding, TrackFinding, analyse
+
+__all__ = [
+    # The container
+    "HFEImage",
+    "HFEHeader",
+    "TrackSamples",
+    "TrackEncoding",
+    "HFE_V1_SIGNATURE",
+    "HFE_V3_SIGNATURE",
+    "write_hfe",
+    # Decoding
+    "Encoding",
+    "DataMark",
+    "SectorID",
+    "DecodedSector",
+    "DecodedTrack",
+    "DecodedDisc",
+    "decode_track",
+    "decode_image",
+    # Flattening
+    "SectorLayout",
+    "FlatImage",
+    "flatten",
+    "flatten_hfe",
+    # The sector report
+    "SectorFinding",
+    "TrackFinding",
+    "analyse",
+    # Building tracks
+    "FormattedSector",
+    "build_track",
+    "track_samples",
+    "samples_per_half_cell",
+    "TRACK_SAMPLES_300RPM_250KBPS",
+    # The oaknut.decoder plug-in
+    "HFEDecoder",
+    # Exceptions
+    "HFEError",
+    "HFEFormatError",
+]

oaknut_hfe-13.6.0/src/oaknut/hfe/build.py

@@ -0,0 +1,194 @@
+"""Build FM and MFM tracks from sector descriptions.
+
+The inverse of :mod:`oaknut.hfe.decode`: lay sectors out as an Acorn
+controller would format them, then convert the half-cells to HFE samples
+for :func:`oaknut.hfe.container.write_hfe`. Each :class:`FormattedSector`
+can carry the defects copy protection uses — any ID, a bad ID or data
+CRC, a deleted-data mark, a missing data field — so decoder behaviour can
+be tested without real captures of every trick.
+
+Ported from Beebium's ``TrackBuilder``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from oaknut.hfe.decode import Encoding, SectorID
+from oaknut.hfe.ibm import (
+    DATA_MARK,
+    DELETED_DATA_MARK,
+    FM_DATA_MARK,
+    FM_DELETED_DATA_MARK,
+    FM_ID_MARK,
+    ID_MARK,
+    MFM_SYNC,
+    MFM_SYNC_CRC,
+    crc16,
+    fm_encode,
+    mfm_encode,
+)
+
+__all__ = [
+    "FormattedSector",
+    "build_track",
+    "track_samples",
+    "samples_per_half_cell",
+    "TRACK_SAMPLES_300RPM_250KBPS",
+]
+
+#: Samples in one revolution at 300 rpm on a 250 kbit/s HFE clock.
+TRACK_SAMPLES_300RPM_250KBPS = 100_000
+
+
+@dataclass(frozen=True)
+class FormattedSector:
+    """One sector as formatted onto a track."""
+
+    id: SectorID
+    #: The data field; padded with zeros, or truncated, to the ID's size.
+    data: bytes = b""
+    deleted: bool = False
+    #: Write no data field at all after the ID.
+    omit_data: bool = False
+    #: Corrupt the stored ID CRC.
+    bad_id_crc: bool = False
+    #: Corrupt the stored data CRC.
+    bad_data_crc: bool = False
+
+
+@dataclass(frozen=True)
+class _Layout:
+    gap1: int
+    sync: int
+    gap2: int
+    gap3: int
+    gap_byte: int
+
+
+_FM_LAYOUT = _Layout(gap1=16, sync=6, gap2=11, gap3=21, gap_byte=0xFF)
+_MFM_LAYOUT = _Layout(gap1=50, sync=12, gap2=22, gap3=24, gap_byte=0x4E)
+
+
+def build_track(
+    sectors: Iterable[FormattedSector],
+    encoding: Encoding,
+    *,
+    half_cells: int | None = None,
+) -> str:
+    """The half-cells of a track holding *sectors* in the order given.
+
+    The track is padded with gap bytes to *half_cells* when given (one
+    revolution at 300 rpm is 50,000 FM or 100,000 MFM half-cells).
+
+    Raises:
+        ValueError: The sectors do not fit in *half_cells*.
+    """
+    if encoding is Encoding.FM:
+        cells = _fm_track(sectors)
+        filler = fm_encode(bytes([_FM_LAYOUT.gap_byte]))
+    else:
+        cells = _mfm_track(sectors)
+        filler = mfm_encode(bytes([_MFM_LAYOUT.gap_byte]))
+    if half_cells is not None:
+        if len(cells) > half_cells:
+            raise ValueError(f"track needs {len(cells)} half-cells; only {half_cells} fit")
+        cells += (filler * (half_cells // len(filler) + 1))[: half_cells - len(cells)]
+    return cells
+
+
+def _field(sector: FormattedSector, encoding: Encoding) -> tuple[bytes, bytes]:
+    identifier = sector.id
+    id_bytes = bytes(
+        [identifier.cylinder, identifier.head, identifier.record, identifier.size_code]
+    )
+    data = sector.data[: identifier.size(encoding)].ljust(identifier.size(encoding), b"\x00")
+    return id_bytes, data
+
+
+def _crc_bytes(crc: int, corrupt: bool) -> bytes:
+    return (crc ^ (0x5A5A if corrupt else 0)).to_bytes(2, "big")
+
+
+def _fm_track(sectors: Iterable[FormattedSector]) -> str:
+    layout = _FM_LAYOUT
+    gap = bytes([layout.gap_byte])
+    parts = [fm_encode(gap * layout.gap1)]
+    for sector in sectors:
+        id_bytes, data = _field(sector, Encoding.FM)
+        parts.append(fm_encode(b"\x00" * layout.sync))
+        parts.append(FM_ID_MARK)
+        id_crc = crc16(bytes([ID_MARK]) + id_bytes)
+        parts.append(fm_encode(id_bytes + _crc_bytes(id_crc, sector.bad_id_crc)))
+        parts.append(fm_encode(gap * layout.gap2))
+        if not sector.omit_data:
+            mark = DELETED_DATA_MARK if sector.deleted else DATA_MARK
+            parts.append(fm_encode(b"\x00" * layout.sync))
+            parts.append(FM_DELETED_DATA_MARK if sector.deleted else FM_DATA_MARK)
+            data_crc = crc16(bytes([mark]) + data)
+            parts.append(fm_encode(data + _crc_bytes(data_crc, sector.bad_data_crc)))
+        parts.append(fm_encode(gap * layout.gap3))
+    return "".join(parts)
+
+
+class _MFMWriter:
+    def __init__(self):
+        self._parts: list[str] = []
+        self._last_bit = 0
+
+    def bytes(self, data: bytes) -> None:
+        if data:
+            self._parts.append(mfm_encode(data, self._last_bit))
+            self._last_bit = data[-1] & 1
+
+    def sync(self) -> None:
+        self._parts.append(MFM_SYNC * 3)
+        self._last_bit = 1  # 0xA1 ends in a 1
+
+    def cells(self) -> str:
+        return "".join(self._parts)
+
+
+def _mfm_track(sectors: Iterable[FormattedSector]) -> str:
+    layout = _MFM_LAYOUT
+    gap = bytes([layout.gap_byte])
+    writer = _MFMWriter()
+    writer.bytes(gap * layout.gap1)
+    for sector in sectors:
+        id_bytes, data = _field(sector, Encoding.MFM)
+        writer.bytes(b"\x00" * layout.sync)
+        writer.sync()
+        id_crc = crc16(bytes([ID_MARK]) + id_bytes, MFM_SYNC_CRC)
+        writer.bytes(bytes([ID_MARK]) + id_bytes + _crc_bytes(id_crc, sector.bad_id_crc))
+        writer.bytes(gap * layout.gap2)
+        if not sector.omit_data:
+            mark = DELETED_DATA_MARK if sector.deleted else DATA_MARK
+            writer.bytes(b"\x00" * layout.sync)
+            writer.sync()
+            data_crc = crc16(bytes([mark]) + data, MFM_SYNC_CRC)
+            writer.bytes(bytes([mark]) + data + _crc_bytes(data_crc, sector.bad_data_crc))
+        writer.bytes(gap * layout.gap3)
+    return writer.cells()
+
+
+def samples_per_half_cell(encoding: Encoding, bitrate_kbps: int = 250) -> int:
+    """HFE samples per half-cell: an FM half-cell is 4 µs, an MFM one 2 µs.
+
+    Raises:
+        ValueError: The bit rate does not give a whole number of samples.
+    """
+    nominal = 125 if encoding is Encoding.FM else 250
+    count, remainder = divmod(bitrate_kbps, nominal)
+    if remainder or count == 0:
+        raise ValueError(f"{encoding.value} cannot be sampled at {bitrate_kbps} kbit/s")
+    return count
+
+
+def track_samples(half_cells: str, encoding: Encoding, bitrate_kbps: int = 250) -> str:
+    """HFE samples for *half_cells*, each transition at the end of its cell."""
+    count = samples_per_half_cell(encoding, bitrate_kbps)
+    if count == 1:
+        return half_cells
+    pad = "0" * (count - 1)
+    return "".join(pad + cell for cell in half_cells)