mifpy 1.0.0__py3-none-any.whl

mifpy/__init__.py

@@ -0,0 +1,13 @@
+from .core import MIFPackage
+from .exceptions import MIFValidationError
+from .srt import parse_srt, format_srt
+from .utils import ms_to_timestamp, timestamp_to_ms
+
+__all__ = [
+    "MIFPackage",
+    "MIFValidationError",
+    "parse_srt",
+    "format_srt",
+    "ms_to_timestamp",
+    "timestamp_to_ms",
+]

mifpy/cli.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import argparse
+import json
+import zipfile
+from pathlib import Path
+
+from .core import MIFPackage
+
+
+def inspect_command(path: Path) -> int:
+    package = MIFPackage.load(path)
+    print(f"MIF package: {path}")
+    print("Metadata:")
+    for key, value in package.get_metadata().items():
+        print(f"  {key}: {value}")
+    print(f"Subtitles length: {len(package.get_subtitles())} characters")
+    print(f"Appearances: {len(package.get_appearances().get('appearances', []))}")
+    print(f"Content files: {len(package.list_content_files())}")
+    return 0
+
+
+def extract_command(source: Path, destination: Path) -> int:
+    destination.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(source, "r") as archive:
+        archive.extractall(destination)
+    print(f"Extracted {source} to {destination}")
+    return 0
+
+
+def create_command(path: Path) -> int:
+    meta = {"title": "Example Movie", "year": 2025, "runtime_ms": 90_000}
+    subtitles = "1\n00:00:00,000 --> 00:00:03,000\nHello from MIF!\n"
+    appearances = {
+        "actors": {
+            "example_actor": {
+                "name": "Example Actor",
+                "image": "content/example.png",
+            }
+        },
+        "appearances": [
+            {"actor": "example_actor", "start_ms": 0, "end_ms": 3000}
+        ],
+    }
+    package = MIFPackage.create(meta=meta, subtitles=subtitles, appearances=appearances)
+    package.add_content_file("example.png", b"")
+    package.save(path)
+    print(f"Created example MIF file at {path}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="mifpy", description="Movie Information Format toolkit")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    inspect_parser = subparsers.add_parser("inspect", help="Display MIF metadata and structure")
+    inspect_parser.add_argument("source", type=Path, help="Path to the .mif file")
+
+    extract_parser = subparsers.add_parser("extract", help="Extract the contents of a MIF archive")
+    extract_parser.add_argument("source", type=Path, help="Path to the .mif file")
+    extract_parser.add_argument("destination", type=Path, help="Output folder")
+
+    create_parser = subparsers.add_parser("create", help="Create a template MIF file")
+    create_parser.add_argument("target", type=Path, help="Path to create the .mif file")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "inspect":
+        return inspect_command(args.source)
+    if args.command == "extract":
+        return extract_command(args.source, args.destination)
+    if args.command == "create":
+        return create_command(args.target)
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mifpy/core.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import json
+import zipfile
+from pathlib import Path
+from typing import Any
+
+from .exceptions import MIFValidationError
+from .parser import parse_appearances, parse_manifest, parse_meta
+from .srt import parse_srt
+from .writer import build_manifest_text, build_meta_text, build_appearances_text
+
+
+class MIFPackage:
+    MANIFEST_NAME = "manifest.ini"
+    META_NAME = "meta.ini"
+    SUBTITLES_NAME = "subtitles.srt"
+    APPEARANCES_NAME = "appearances.json"
+    DEFAULT_CONTENT_DIR = "content/"
+
+    def __init__(
+        self,
+        meta: dict[str, Any],
+        subtitles: str,
+        appearances: dict[str, Any],
+        content_files: dict[str, bytes] | None = None,
+        content_dir: str | None = None,
+    ):
+        self._meta = meta
+        self._subtitles = subtitles
+        self._appearances = appearances
+        self._content_files = content_files or {}
+        self._content_dir = content_dir or self.DEFAULT_CONTENT_DIR
+        self._validate()
+
+    @classmethod
+    def create(
+        cls,
+        meta: dict[str, Any],
+        subtitles: str,
+        appearances: dict[str, Any],
+    ) -> "MIFPackage":
+        return cls(meta=meta, subtitles=subtitles, appearances=appearances, content_files={})
+
+    @classmethod
+    def load(cls, path: str | Path) -> "MIFPackage":
+        path_obj = Path(path)
+        if not path_obj.exists():
+            raise FileNotFoundError(f"MIF file not found: {path}")
+
+        with zipfile.ZipFile(path_obj, "r") as archive:
+            namelist = archive.namelist()
+            if cls.MANIFEST_NAME not in namelist:
+                raise MIFValidationError("manifest.ini is required in a MIF archive")
+
+            manifest_text = archive.read(cls.MANIFEST_NAME).decode("utf-8")
+            manifest = parse_manifest(manifest_text)
+            files = manifest["files"]
+            content_dir = files["content_dir"]
+
+            def read_required(file_key: str, name: str) -> str:
+                if name not in namelist:
+                    raise MIFValidationError(f"{file_key} declared in manifest.ini is missing from the archive: {name}")
+                return archive.read(name).decode("utf-8")
+
+            meta_text = read_required("meta", files["meta"])
+            subtitles_text = read_required("subtitles", files["subtitles"])
+            appearances_text = read_required("appearances", files["appearances"])
+
+            metadata = parse_meta(meta_text)
+            appearances = parse_appearances(appearances_text, content_files=[name for name in namelist])
+
+            content_files: dict[str, bytes] = {}
+            for member in namelist:
+                if not member.endswith("/") and member.startswith(content_dir):
+                    relative = member[len(content_dir) :]
+                    if relative:
+                        content_files[relative] = archive.read(member)
+
+            for actor_id, actor in appearances["actors"].items():
+                image_path = actor.get("image")
+                if image_path:
+                    normalized = image_path.replace("\\", "/").lstrip("/")
+                    if normalized not in namelist:
+                        raise MIFValidationError(
+                            f"actor '{actor_id}' references missing content file '{image_path}'"
+                        )
+
+            return cls(
+                meta=metadata,
+                subtitles=subtitles_text,
+                appearances=appearances,
+                content_files=content_files,
+                content_dir=content_dir,
+            )
+
+    def save(self, path: str | Path) -> None:
+        self._validate_image_references()
+        path_obj = Path(path)
+        path_obj.parent.mkdir(parents=True, exist_ok=True)
+
+        with zipfile.ZipFile(path_obj, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+            archive.writestr(self.MANIFEST_NAME, build_manifest_text(self._content_dir))
+            archive.writestr(self.META_NAME, build_meta_text(self._meta))
+            archive.writestr(self.SUBTITLES_NAME, self._subtitles)
+            archive.writestr(self.APPEARANCES_NAME, build_appearances_text(self._appearances))
+
+            for relative_path, content in self._content_files.items():
+                normalized = relative_path.replace("\\", "/").lstrip("/")
+                if ".." in normalized.split("/"):
+                    raise ValueError("Content file paths must not traverse parent directories")
+                archive_path = f"{self._content_dir}{normalized}"
+                archive.writestr(archive_path, content)
+
+    def _validate_image_references(self) -> None:
+        content_paths = {f"{self._content_dir}{name}" for name in self._content_files}
+        for actor_id, actor in self._appearances.get("actors", {}).items():
+            image_path = actor.get("image")
+            if image_path:
+                normalized = image_path.replace("\\", "/").lstrip("/")
+                if normalized not in content_paths:
+                    raise MIFValidationError(
+                        f"actor '{actor_id}' references missing content file '{image_path}'"
+                    )
+
+    def get_metadata(self) -> dict[str, Any]:
+        return dict(self._meta)
+
+    def get_subtitles(self) -> str:
+        return self._subtitles
+
+    def get_appearances(self) -> dict[str, Any]:
+        return {
+            "actors": dict(self._appearances["actors"]),
+            "appearances": [dict(item) for item in self._appearances["appearances"]],
+        }
+
+    def list_content_files(self) -> list[str]:
+        return sorted(self._content_files.keys())
+
+    def add_content_file(self, path: str, data: bytes) -> None:
+        if not isinstance(path, str) or not path.strip():
+            raise ValueError("Content file path must be a non-empty string")
+        if not isinstance(data, (bytes, bytearray)):
+            raise ValueError("Content file data must be bytes")
+
+        normalized = path.replace("\\", "/").lstrip("/")
+        if ".." in normalized.split("/"):
+            raise ValueError("Content file paths must not traverse parent directories")
+        self._content_files[normalized] = bytes(data)
+
+    def _validate(self) -> None:
+        if not isinstance(self._meta, dict):
+            raise MIFValidationError("meta must be a dictionary")
+        if not isinstance(self._subtitles, str):
+            raise MIFValidationError("subtitles must be a string")
+        if not isinstance(self._appearances, dict):
+            raise MIFValidationError("appearances must be a dictionary")
+
+        _ = parse_meta(build_meta_text(self._meta))
+        _ = parse_appearances(build_appearances_text(self._appearances), content_files=None)
+

mifpy/exceptions.py

@@ -0,0 +1,9 @@
+class MIFValidationError(Exception):
+    """Raised when a MIF package contains invalid metadata or structure."""
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.message = message
+
+    def __str__(self) -> str:
+        return f"MIFValidationError: {self.message}"

mifpy/parser.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import configparser
+import json
+from typing import Any
+
+from .exceptions import MIFValidationError
+from .utils import timestamp_to_ms
+
+
+def _normalize_path(path: str) -> str:
+    return path.replace("\\", "/").lstrip("/")
+
+
+def parse_manifest(text: str) -> dict[str, Any]:
+    parser = configparser.ConfigParser()
+    parser.read_string(text)
+
+    if "mif" not in parser:
+        raise MIFValidationError("manifest.ini is missing the [mif] section")
+    if "files" not in parser:
+        raise MIFValidationError("manifest.ini is missing the [files] section")
+
+    try:
+        version = parser.getint("mif", "version")
+    except (configparser.NoOptionError, ValueError):
+        raise MIFValidationError("manifest.ini must declare an integer version")
+
+    files = {}
+    for key in ["meta", "subtitles", "appearances"]:
+        if not parser.has_option("files", key):
+            raise MIFValidationError(f"manifest.ini is missing the required file entry '{key}'")
+        files[key] = _normalize_path(parser.get("files", key))
+
+    content_dir = parser.get("files", "content_dir", fallback="content/")
+    content_dir = _normalize_path(content_dir)
+    if content_dir and not content_dir.endswith("/"):
+        content_dir += "/"
+
+    return {"version": version, "files": {**files, "content_dir": content_dir}}
+
+
+def parse_meta(text: str) -> dict[str, Any]:
+    parser = configparser.ConfigParser()
+    parser.read_string(text)
+
+    if "movie" not in parser:
+        raise MIFValidationError("meta.ini is missing the [movie] section")
+
+    movie = parser["movie"]
+    title = movie.get("title", fallback="").strip()
+    year = movie.get("year", fallback="").strip()
+    runtime_ms = movie.get("runtime_ms", fallback="").strip()
+
+    if not title:
+        raise MIFValidationError("meta.ini must include a non-empty title")
+    if not year.isdigit():
+        raise MIFValidationError("meta.ini year must be numeric")
+    if not runtime_ms.isdigit():
+        raise MIFValidationError("meta.ini runtime_ms must be numeric")
+
+    return {
+        "title": title,
+        "year": int(year),
+        "runtime_ms": int(runtime_ms),
+    }
+
+
+def parse_appearances(text: str, content_files: list[str] | None = None) -> dict[str, Any]:
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise MIFValidationError(f"appearances.json is not valid JSON: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise MIFValidationError("appearances.json must contain a JSON object")
+    if "actors" not in data or "appearances" not in data:
+        raise MIFValidationError("appearances.json must include 'actors' and 'appearances' keys")
+
+    actors = data["actors"]
+    appearances = data["appearances"]
+
+    if not isinstance(actors, dict):
+        raise MIFValidationError("appearances.json actors section must be an object")
+    if not isinstance(appearances, list):
+        raise MIFValidationError("appearances.json appearances section must be an array")
+
+    for actor_id, actor in actors.items():
+        if not isinstance(actor_id, str) or not actor_id.strip():
+            raise MIFValidationError("actor IDs must be non-empty strings")
+        if not isinstance(actor, dict):
+            raise MIFValidationError(f"actor '{actor_id}' must be an object")
+        if "name" not in actor or not isinstance(actor["name"], str) or not actor["name"].strip():
+            raise MIFValidationError(f"actor '{actor_id}' must include a non-empty name")
+        if "image" in actor:
+            image = actor["image"]
+            if not isinstance(image, str) or not image.strip():
+                raise MIFValidationError(f"actor '{actor_id}' image path must be a non-empty string")
+            if content_files is not None:
+                normalized = _normalize_path(image)
+                if normalized not in content_files:
+                    raise MIFValidationError(f"actor '{actor_id}' references missing content file '{image}'")
+
+    for index, appearance in enumerate(appearances):
+        if not isinstance(appearance, dict):
+            raise MIFValidationError("each appearance entry must be an object")
+        actor = appearance.get("actor")
+        if not isinstance(actor, str) or actor not in actors:
+            raise MIFValidationError(f"appearance entry at index {index} references unknown actor '{actor}'")
+
+        for field in ["start_ms", "end_ms"]:
+            value = appearance.get(field)
+            if not isinstance(value, int) or value < 0:
+                raise MIFValidationError(f"appearance entry at index {index} must include a non-negative integer '{field}'")
+
+        if appearance["end_ms"] < appearance["start_ms"]:
+            raise MIFValidationError(f"appearance entry at index {index} has end_ms before start_ms")
+
+    return {"actors": actors, "appearances": appearances}

mifpy/srt.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import List
+
+from .utils import timestamp_to_ms
+from .exceptions import MIFValidationError
+
+
+def parse_srt(text: str) -> List[dict]:
+    if not isinstance(text, str):
+        raise ValueError("SRT input must be a string")
+
+    lines = text.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    entries: List[dict] = []
+    current: dict | None = None
+    state = "index"
+
+    for raw_line in lines + [""]:
+        line = raw_line.strip()
+
+        if state == "index":
+            if not line:
+                continue
+            current = {"index": line, "start": "", "end": "", "text": []}
+            state = "timestamp"
+            continue
+
+        if state == "timestamp" and current is not None:
+            if "-->" not in line:
+                raise MIFValidationError(f"Malformed SRT timestamp line: {line!r}")
+            start, end = [part.strip() for part in line.split("-->", 1)]
+            current["start"] = start
+            current["end"] = end
+            state = "text"
+            continue
+
+        if state == "text" and current is not None:
+            if not line:
+                if current["text"]:
+                    current["text"] = "\n".join(current["text"])
+                    entries.append(current)
+                    current = None
+                    state = "index"
+                continue
+            current["text"].append(raw_line)
+            continue
+
+    if current is not None and current["text"]:
+        current["text"] = "\n".join(current["text"])
+        entries.append(current)
+
+    return entries
+
+
+def format_srt(entries: List[dict]) -> str:
+    output_lines: List[str] = []
+
+    for entry in entries:
+        index = entry.get("index", "")
+        start = entry.get("start", "")
+        end = entry.get("end", "")
+        text = entry.get("text", "")
+
+        if not index or not start or not end or text is None:
+            raise ValueError("Each subtitle entry must include index, start, end, and text")
+
+        output_lines.append(str(index))
+        output_lines.append(f"{start} --> {end}")
+        if isinstance(text, str):
+            output_lines.extend(text.split("\n"))
+        else:
+            output_lines.extend(map(str, text))
+        output_lines.append("")
+
+    return "\n".join(output_lines).strip() + "\n"

mifpy/utils.py

@@ -0,0 +1,25 @@
+import re
+
+SRT_TIMESTAMP_PATTERN = re.compile(r"^(\d{2}):(\d{2}):(\d{2}),(\d{3})$")
+
+
+def ms_to_timestamp(ms: int) -> str:
+    if not isinstance(ms, int) or ms < 0:
+        raise ValueError("Milliseconds must be a non-negative integer")
+
+    hours, rest = divmod(ms, 3_600_000)
+    minutes, rest = divmod(rest, 60_000)
+    seconds, milliseconds = divmod(rest, 1_000)
+    return f"{hours:02}:{minutes:02}:{seconds:02},{milliseconds:03}"
+
+
+def timestamp_to_ms(timestamp: str) -> int:
+    if not isinstance(timestamp, str):
+        raise ValueError("Timestamp must be a string")
+
+    match = SRT_TIMESTAMP_PATTERN.match(timestamp.strip())
+    if not match:
+        raise ValueError(f"Invalid SRT timestamp format: {timestamp!r}")
+
+    hours, minutes, seconds, milliseconds = map(int, match.groups())
+    return ((hours * 60 + minutes) * 60 + seconds) * 1_000 + milliseconds

mifpy/writer.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import configparser
+import json
+from typing import Any
+
+
+def build_manifest_text(content_dir: str) -> str:
+    if content_dir and not content_dir.endswith("/"):
+        content_dir = f"{content_dir}/"
+
+    parser = configparser.ConfigParser()
+    parser["mif"] = {"version": "1"}
+    parser["files"] = {
+        "meta": "meta.ini",
+        "subtitles": "subtitles.srt",
+        "appearances": "appearances.json",
+        "content_dir": content_dir or "content/",
+    }
+
+    from io import StringIO
+
+    buffer = StringIO()
+    parser.write(buffer)
+    return buffer.getvalue()
+
+
+def build_meta_text(meta: dict[str, Any]) -> str:
+    parser = configparser.ConfigParser()
+    parser["movie"] = {
+        "title": str(meta.get("title", "")),
+        "year": str(int(meta.get("year", 0))),
+        "runtime_ms": str(int(meta.get("runtime_ms", 0))),
+    }
+
+    from io import StringIO
+
+    buffer = StringIO()
+    parser.write(buffer)
+    return buffer.getvalue()
+
+
+def build_appearances_text(appearances: dict[str, Any]) -> str:
+    return json.dumps(appearances, indent=2, ensure_ascii=False) + "\n"

mifpy-1.0.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: mifpy
+Version: 1.0.0
+Summary: A Python library for reading and writing Movie Information Format (.mif) containers.
+License: MIT
+Author: OmgRod
+Author-email: rod@omgrod.me
+Requires-Python: >=3.10
+Classifier: License :: OSI Approved :: MIT License
+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
+Description-Content-Type: text/markdown
+
+# MIFpy
+
+`mifpy` is a lightweight Python library for the Movie Information Format (`.mif`), a ZIP-based container format for movie metadata, subtitles, actor appearance timelines, and associated assets.
+
+## Features
+
+- Load and save `.mif` archives using Python `zipfile`
+- Validate required package files and formats
+- Parse `manifest.ini`, `meta.ini`, `appearances.json`, and `subtitles.srt`
+- Add content assets under `content/`
+- CLI support: `inspect`, `extract`, and `create`
+
+## Package structure
+
+A valid `.mif` archive contains:
+
+- `manifest.ini`
+- `meta.ini`
+- `subtitles.srt`
+- `appearances.json`
+- `content/` (optional)
+
+## Installation
+
+Install with Poetry:
+
+```bash
+poetry install
+```
+
+## Usage
+
+```python
+from mifpy import MIFPackage
+
+pkg = MIFPackage.create(
+    meta={"title": "The Matrix", "year": 1999, "runtime_ms": 8160000},
+    subtitles="1\n00:00:00,000 --> 00:00:02,000\nWake up, Neo.\n",
+    appearances={
+        "actors": {
+            "keanu_reeves": {
+                "name": "Keanu Reeves",
+                "image": "content/keanu.png",
+            }
+        },
+        "appearances": [
+            {"actor": "keanu_reeves", "start_ms": 1000, "end_ms": 10000}
+        ],
+    },
+)
+
+pkg.add_content_file("keanu.png", b"<raw-image-bytes>")
+pkg.save("movie.mif")
+```
+
+## CLI
+
+```bash
+mifpy inspect movie.mif
+mifpy extract movie.mif ./out
+mifpy create sample.mif
+```
+
+## Testing
+
+Run tests with:
+
+```bash
+poetry run pytest
+```
+

mifpy-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+mifpy/__init__.py,sha256=AcWg1EKYe73gpnZWpae1_S8fvd6ealUmMW557-vBPMA,316
+mifpy/cli.py,sha256=7-qQ0r47_FMxiG7WvfPhtYWtgcTdc_4EdY3SsGoRkwU,2869
+mifpy/core.py,sha256=44gHr2E_ScoKYm7a2JKed-IPvVUMxJBLV0-Ha2vJru8,6869
+mifpy/exceptions.py,sha256=JzZuJ9a8ma66TdUq-g0PS7P2hrPlQvmjK8yMoGKnrFM,310
+mifpy/parser.py,sha256=dMplVRM0No7J4RDDZOV2EzHkbmgaudAVbh74_wG_x24,5007
+mifpy/srt.py,sha256=k03Aw0hmWtYAt2qySsttfYad9XNtBQGexKvMTHMJzA8,2410
+mifpy/utils.py,sha256=Q3Ygpg7DNMNQXfvQ2jG3Gf9_kp7gmK2GHLFYlJUWO5U,896
+mifpy/writer.py,sha256=Uog9m2L1nx_vQQ-J4pHihY_mzye9Qyr1NZiEPXZ9d-U,1177
+mifpy-1.0.0.dist-info/entry_points.txt,sha256=c4sCrX46OMrppJreNbgq3wvKCYicpBd1MIWm22qiZvQ,40
+mifpy-1.0.0.dist-info/METADATA,sha256=dHNUA0soon3sEMo9848yTISq8OqRUXIm-HeVJYQwHeU,2071
+mifpy-1.0.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+mifpy-1.0.0.dist-info/RECORD,,

mifpy-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

mifpy-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mifpy=mifpy.cli:main
+