py-self-md5 0.1.0__tar.gz

py_self_md5-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+input.py
+input.self_md5.py
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

py_self_md5-0.1.0/LICENSE

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

py_self_md5-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: py-self-md5
+Version: 0.1.0
+Summary: Wrap Python scripts so they print their own MD5 without reading their source at runtime.
+Author: GGN_2015
+License-Expression: MIT
+License-File: LICENSE
+Keywords: md5,python,quine,self-hash
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# py-self-md5
+
+`py-self-md5` wraps a Python script so the generated script prints
+`MD5: <DIGEST>` before running the original program.
+
+The generated script does **not** read its own source file at runtime.  Instead,
+the inserted prefix stores a quine-style byte template and computes the digest
+from the reconstructed bytes in memory.
+
+This project is inspired by
+[`zhuzilin/pdf-with-its-own-md5`](https://github.com/zhuzilin/pdf-with-its-own-md5),
+where selectable MD5-collision carriers are used to display the final digest in
+a PDF.  This tool targets executable Python programs and does not require
+HashClash or precomputed collision blocks.
+
+## Install
+
+Requires Python 3.11 or newer.
+
+```bash
+python -m pip install py-self-md5
+```
+
+After installation, run the built-in check:
+
+```bash
+py-self-md5 --self-test
+```
+
+You can also run it from the project root without installing:
+
+```bash
+python -m py_self_md5 --self-test
+```
+
+## Usage
+
+Create `input.self_md5.py`:
+
+```bash
+py-self-md5 input.py
+```
+
+Run the generated script:
+
+```bash
+python input.self_md5.py
+```
+
+The first output line is `MD5: <DIGEST>`, where `<DIGEST>` is the uppercase MD5
+digest of `input.self_md5.py`; then the original program continues.
+
+Write to a specific path:
+
+```bash
+py-self-md5 input.py -o output.py
+```
+
+Rewrite the input file in place:
+
+```bash
+py-self-md5 input.py --in-place
+```
+
+Replace an existing `py-self-md5` prefix in place:
+
+```bash
+py-self-md5 input.py --in-place --force
+```
+
+Overwrite an existing output file:
+
+```bash
+py-self-md5 input.py -o output.py --force
+```
+
+Generate and verify in one step:
+
+```bash
+py-self-md5 input.py --check
+```
+
+## What the wrapper preserves
+
+- The tool preserves shebang lines, encoding cookies, module docstrings, and
+  `from __future__ import ...` placement.
+- By default, the input file is not modified.
+- Existing `py-self-md5` prefixes are detected. Use `--force` to replace one.
+
+## Limitations
+
+- This is an executable self-hash wrapper, not a general MD5 collision
+  generator.
+- The generated prefix can be large because it embeds enough bytes to
+  reconstruct the generated script in memory.
+- `--check` executes the generated script, so only use it with programs you are
+  willing to run.

py_self_md5-0.1.0/README.md

@@ -0,0 +1,97 @@
+# py-self-md5
+
+`py-self-md5` wraps a Python script so the generated script prints
+`MD5: <DIGEST>` before running the original program.
+
+The generated script does **not** read its own source file at runtime.  Instead,
+the inserted prefix stores a quine-style byte template and computes the digest
+from the reconstructed bytes in memory.
+
+This project is inspired by
+[`zhuzilin/pdf-with-its-own-md5`](https://github.com/zhuzilin/pdf-with-its-own-md5),
+where selectable MD5-collision carriers are used to display the final digest in
+a PDF.  This tool targets executable Python programs and does not require
+HashClash or precomputed collision blocks.
+
+## Install
+
+Requires Python 3.11 or newer.
+
+```bash
+python -m pip install py-self-md5
+```
+
+After installation, run the built-in check:
+
+```bash
+py-self-md5 --self-test
+```
+
+You can also run it from the project root without installing:
+
+```bash
+python -m py_self_md5 --self-test
+```
+
+## Usage
+
+Create `input.self_md5.py`:
+
+```bash
+py-self-md5 input.py
+```
+
+Run the generated script:
+
+```bash
+python input.self_md5.py
+```
+
+The first output line is `MD5: <DIGEST>`, where `<DIGEST>` is the uppercase MD5
+digest of `input.self_md5.py`; then the original program continues.
+
+Write to a specific path:
+
+```bash
+py-self-md5 input.py -o output.py
+```
+
+Rewrite the input file in place:
+
+```bash
+py-self-md5 input.py --in-place
+```
+
+Replace an existing `py-self-md5` prefix in place:
+
+```bash
+py-self-md5 input.py --in-place --force
+```
+
+Overwrite an existing output file:
+
+```bash
+py-self-md5 input.py -o output.py --force
+```
+
+Generate and verify in one step:
+
+```bash
+py-self-md5 input.py --check
+```
+
+## What the wrapper preserves
+
+- The tool preserves shebang lines, encoding cookies, module docstrings, and
+  `from __future__ import ...` placement.
+- By default, the input file is not modified.
+- Existing `py-self-md5` prefixes are detected. Use `--force` to replace one.
+
+## Limitations
+
+- This is an executable self-hash wrapper, not a general MD5 collision
+  generator.
+- The generated prefix can be large because it embeds enough bytes to
+  reconstruct the generated script in memory.
+- `--check` executes the generated script, so only use it with programs you are
+  willing to run.

py_self_md5-0.1.0/py_self_md5/__init__.py

@@ -0,0 +1,5 @@
+"""Tools for wrapping Python scripts that print their own MD5."""
+
+from .cli import WrapResult, build_wrapped_source, file_md5, wrap_file
+
+__all__ = ["WrapResult", "build_wrapped_source", "file_md5", "wrap_file"]

py_self_md5-0.1.0/py_self_md5/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

py_self_md5-0.1.0/py_self_md5/cli.py

@@ -0,0 +1,390 @@
+#!/usr/bin/env python3
+"""
+Create a Python script that prints its own file MD5 before running user code,
+without reading its own source file at runtime.
+
+The referenced PDF construction uses MD5 collision choices to make static
+content display the digest of the final file.  For executable Python, this
+tool uses a quine-style carrier: the prepended shim stores a byte template for
+the generated script and hashes the reconstructed bytes instead of opening
+__file__.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import hashlib
+import io
+import re
+import subprocess
+import sys
+import tempfile
+import textwrap
+import tokenize
+from dataclasses import dataclass
+from pathlib import Path
+
+
+BEGIN_MARKER = "# <py-self-md5:begin>"
+END_MARKER = "# <py-self-md5:end>"
+CODING_RE = re.compile(br"^[ \t\f]*#.*?coding[:=][ \t]*([-\w.]+)")
+UTF8_BOM = b"\xef\xbb\xbf"
+
+
+@dataclass(frozen=True)
+class WrapResult:
+    input_path: Path
+    output_path: Path
+    md5: str
+    insertion_line: int
+    already_wrapped: bool = False
+
+
+def file_md5(path: Path) -> str:
+    digest = hashlib.md5()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest().upper()
+
+
+def detect_newline(data: bytes) -> bytes:
+    first_lf = data.find(b"\n")
+    if first_lf > 0 and data[first_lf - 1:first_lf] == b"\r":
+        return b"\r\n"
+    return b"\n"
+
+
+def strip_eol(line: bytes) -> bytes:
+    return line.rstrip(b"\r\n")
+
+
+def find_existing_shim_span(data: bytes) -> tuple[int, int] | None:
+    begin_marker = BEGIN_MARKER.encode("ascii")
+    end_marker = END_MARKER.encode("ascii")
+    begin: int | None = None
+    offset = 0
+
+    for line in data.splitlines(keepends=True):
+        if begin is None:
+            if strip_eol(line) == begin_marker:
+                begin = offset
+        elif strip_eol(line) == end_marker:
+            end = offset + len(line)
+            while end < len(data) and data[end:end + 1] in (b"\r", b"\n"):
+                end += 1
+            return begin, end
+        offset += len(line)
+
+    return None
+
+
+def has_coding_cookie(line: bytes) -> bool:
+    return bool(CODING_RE.match(line))
+
+
+def protected_header_line_count(lines: list[bytes]) -> int:
+    """Return lines that must remain before executable code."""
+    count = 0
+    first = lines[0][len(UTF8_BOM):] if lines and lines[0].startswith(UTF8_BOM) else (lines[0] if lines else b"")
+    if lines and first.startswith(b"#!"):
+        count = 1
+    if len(lines) > count and has_coding_cookie(lines[count]):
+        count += 1
+    elif count == 0 and len(lines) > 1 and has_coding_cookie(lines[1]):
+        count = 2
+    return count
+
+
+def byte_offset_for_line(lines: list[bytes], line_no: int) -> int:
+    """Return byte offset for the beginning of a 1-based line number."""
+    if line_no <= 1:
+        if lines and lines[0].startswith(UTF8_BOM):
+            return len(UTF8_BOM)
+        return 0
+    if line_no > len(lines):
+        return sum(len(line) for line in lines)
+    return sum(len(line) for line in lines[: line_no - 1])
+
+
+def decode_python_source(data: bytes) -> str:
+    encoding, _ = tokenize.detect_encoding(io.BytesIO(data).readline)
+    return data.decode(encoding)
+
+
+def first_insert_line_from_ast(source: str, minimum_line: int) -> int:
+    """Find the earliest legal line for executable shim code."""
+    try:
+        module = ast.parse(source)
+    except SyntaxError as exc:
+        raise ValueError(f"input is not valid Python: {exc}") from exc
+
+    insert_line = minimum_line
+    body = module.body
+    index = 0
+
+    if body and isinstance(body[0], ast.Expr):
+        value = body[0].value
+        if isinstance(value, ast.Constant) and isinstance(value.value, str):
+            insert_line = max(insert_line, (body[0].end_lineno or body[0].lineno) + 1)
+            index = 1
+
+    while index < len(body):
+        node = body[index]
+        if (
+            isinstance(node, ast.ImportFrom)
+            and node.module == "__future__"
+            and node.level == 0
+        ):
+            insert_line = max(insert_line, (node.end_lineno or node.lineno) + 1)
+            index += 1
+            continue
+        break
+
+    return insert_line
+
+
+def make_quine_template(
+    head: bytes,
+    *,
+    function_name: str,
+    template_marker: bytes,
+    tail_marker: bytes,
+    newline: bytes,
+) -> bytes:
+    lines = [
+        BEGIN_MARKER,
+        f"def {function_name}():",
+        "    import hashlib as __py_self_md5_hashlib",
+        "    import sys as __py_self_md5_sys",
+        f"    __py_self_md5_template = {template_marker.decode('ascii')}",
+        f"    __py_self_md5_tail = {tail_marker.decode('ascii')}",
+        "    __py_self_md5_source = (",
+        "        __py_self_md5_template",
+        f"        .replace({tail_marker!r}, repr(__py_self_md5_tail).encode('ascii'), 1)",
+        f"        .replace({template_marker!r}, repr(__py_self_md5_template).encode('ascii'), 1)",
+        "        + __py_self_md5_tail",
+        "    )",
+        "    __py_self_md5_sys.stdout.write(",
+        "        'MD5: ' + __py_self_md5_hashlib.md5(__py_self_md5_source).hexdigest().upper() + '\\n'",
+        "    )",
+        f"{function_name}()",
+        f"del {function_name}",
+        END_MARKER,
+        "",
+    ]
+    return head + newline.join(line.encode("ascii") for line in lines)
+
+
+def choose_markers(data: bytes, seed: str) -> tuple[bytes, bytes]:
+    for counter in range(1000):
+        suffix = f"{seed}_{counter}".encode("ascii")
+        template_marker = b"__PY_SELF_MD5_TEMPLATE_" + suffix + b"__"
+        tail_marker = b"__PY_SELF_MD5_TAIL_" + suffix + b"__"
+        if template_marker not in data and tail_marker not in data:
+            return template_marker, tail_marker
+    raise RuntimeError("could not find marker names absent from input")
+
+
+def render_quine(template: bytes, tail: bytes, template_marker: bytes, tail_marker: bytes) -> bytes:
+    return (
+        template
+        .replace(tail_marker, repr(tail).encode("ascii"), 1)
+        .replace(template_marker, repr(template).encode("ascii"), 1)
+        + tail
+    )
+
+
+def build_wrapped_source(data: bytes, *, force: bool = False) -> tuple[bytes, int, bool]:
+    existing_span = find_existing_shim_span(data)
+    if existing_span is not None:
+        if not force:
+            return data, 1, True
+        data = remove_existing_shim(data)
+
+    lines = data.splitlines(keepends=True)
+    minimum_line = protected_header_line_count(lines) + 1
+    source = decode_python_source(data)
+    insertion_line = first_insert_line_from_ast(source, minimum_line)
+    offset = byte_offset_for_line(lines, insertion_line)
+
+    seed = hashlib.sha1(data).hexdigest()[:16]
+    function_name = f"__py_self_md5_{seed}"
+    newline = detect_newline(data)
+
+    head = data[:offset]
+    tail = data[offset:]
+    if head and not head.endswith((b"\n", b"\r")):
+        head += newline
+
+    template_marker, tail_marker = choose_markers(data, seed)
+    template = make_quine_template(
+        head,
+        function_name=function_name,
+        template_marker=template_marker,
+        tail_marker=tail_marker,
+        newline=newline,
+    )
+    wrapped = render_quine(template, tail, template_marker, tail_marker)
+
+    return wrapped, insertion_line, False
+
+
+def remove_existing_shim(data: bytes) -> bytes:
+    span = find_existing_shim_span(data)
+    if span is None:
+        return data
+    begin, end = span
+    return data[:begin] + data[end:]
+
+
+def default_output_path(input_path: Path) -> Path:
+    return input_path.with_name(f"{input_path.stem}.self_md5{input_path.suffix or '.py'}")
+
+
+def wrap_file(input_path: Path, output_path: Path, *, force: bool = False) -> WrapResult:
+    data = input_path.read_bytes()
+    wrapped, insertion_line, already_wrapped = build_wrapped_source(data, force=force)
+    if already_wrapped and input_path.resolve() != output_path.resolve():
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_bytes(wrapped)
+    elif not already_wrapped:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_bytes(wrapped)
+    return WrapResult(
+        input_path=input_path,
+        output_path=output_path,
+        md5=file_md5(output_path),
+        insertion_line=insertion_line,
+        already_wrapped=already_wrapped,
+    )
+
+
+def run_output_check(path: Path, timeout: float) -> tuple[bool, str, str]:
+    expected = file_md5(path)
+    proc = subprocess.run(
+        [sys.executable, str(path)],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        timeout=timeout,
+        check=False,
+    )
+    first_line = proc.stdout.splitlines()[0] if proc.stdout.splitlines() else ""
+    expected_line = f"MD5: {expected}"
+    ok = first_line == expected_line
+    detail = f"expected first line {expected_line}, got {first_line or '<no stdout>'}"
+    if proc.returncode != 0:
+        detail += f"; process exited with {proc.returncode}"
+    return ok, detail, proc.stderr
+
+
+def self_test() -> None:
+    sample = textwrap.dedent(
+        '''\
+        #!/usr/bin/env python3
+        # coding: utf-8
+        """sample module docstring"""
+        from __future__ import annotations
+
+        print("payload ran")
+        '''
+    ).encode("utf-8")
+    with tempfile.TemporaryDirectory() as tmp_dir_name:
+        tmp_dir = Path(tmp_dir_name)
+        source = tmp_dir / "sample.py"
+        output = tmp_dir / "sample.self_md5.py"
+        source.write_bytes(sample)
+        result = wrap_file(source, output, force=False)
+        generated = output.read_bytes()
+        span = find_existing_shim_span(generated)
+        if span is None:
+            raise SystemExit("self-test failed: generated shim markers are missing")
+        shim = generated[span[0]:span[1]]
+        if b"open(" in shim or b"__file__" in shim:
+            raise SystemExit("self-test failed: generated shim reads or references its source file")
+        ok, detail, stderr = run_output_check(result.output_path, timeout=10)
+        if not ok:
+            raise SystemExit(f"self-test failed: {detail}\n{stderr}")
+        print(f"self-test ok: {result.output_path.name} prints MD5: {result.md5}")
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Prepend a startup shim so a .py file prints its own MD5 before user code runs."
+    )
+    parser.add_argument("input", nargs="?", type=Path, help="input Python file")
+    parser.add_argument("-o", "--output", type=Path, help="output path")
+    parser.add_argument(
+        "--in-place",
+        action="store_true",
+        help="rewrite the input file instead of creating *.self_md5.py",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="overwrite output and replace an existing py-self-md5 shim if present",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="execute the generated file and verify that its first stdout line is MD5: <digest>",
+    )
+    parser.add_argument(
+        "--check-timeout",
+        type=float,
+        default=10.0,
+        help="timeout in seconds for --check",
+    )
+    parser.add_argument(
+        "--self-test",
+        action="store_true",
+        help="run an internal safe sample test",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(sys.argv[1:] if argv is None else argv)
+
+    if args.self_test:
+        self_test()
+        return 0
+
+    if args.input is None:
+        raise SystemExit("error: input file is required unless --self-test is used")
+
+    input_path = args.input.resolve()
+    if not input_path.exists():
+        raise SystemExit(f"error: input file does not exist: {input_path}")
+    if not input_path.is_file():
+        raise SystemExit(f"error: input path is not a file: {input_path}")
+
+    if args.in_place and args.output:
+        raise SystemExit("error: --in-place and --output cannot be used together")
+
+    output_path = input_path if args.in_place else (args.output or default_output_path(input_path)).resolve()
+    if output_path.exists() and output_path.resolve() != input_path and not args.force:
+        raise SystemExit(f"error: output exists, use --force to overwrite: {output_path}")
+
+    result = wrap_file(input_path, output_path, force=args.force)
+    if result.already_wrapped:
+        print(f"already wrapped: {result.output_path}")
+    else:
+        print(f"wrote: {result.output_path}")
+        print(f"inserted shim at line: {result.insertion_line}")
+    print(f"file MD5: {result.md5}")
+
+    if args.check:
+        ok, detail, stderr = run_output_check(result.output_path, timeout=args.check_timeout)
+        print(f"check: {'ok' if ok else 'failed'} ({detail})")
+        if stderr:
+            print(stderr, file=sys.stderr, end="")
+        return 0 if ok else 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

py_self_md5-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "py-self-md5"
+version = "0.1.0"
+description = "Wrap Python scripts so they print their own MD5 without reading their source at runtime."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+  { name = "GGN_2015" }
+]
+keywords = ["md5", "quine", "python", "self-hash"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.scripts]
+py-self-md5 = "py_self_md5.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["py_self_md5"]