markmaton 0.1.4__py3-none-win_amd64.whl

markmaton/__init__.py

@@ -0,0 +1,15 @@
+"""markmaton package."""
+
+from .engine import convert_html, discover_engine
+from .models import ConvertOptions, ConvertRequest, ConvertResponse
+
+__all__ = [
+    "__version__",
+    "ConvertOptions",
+    "ConvertRequest",
+    "ConvertResponse",
+    "convert_html",
+    "discover_engine",
+]
+
+__version__ = "0.1.0"

markmaton/cli.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .engine import convert_html
+from .models import ConvertOptions, ConvertRequest
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="markmaton")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    convert_parser = subparsers.add_parser("convert", help="Convert HTML into Markdown")
+    convert_parser.add_argument("--html-file", type=Path, help="Path to an HTML file")
+    convert_parser.add_argument("--url", help="Source URL used as parsing context")
+    convert_parser.add_argument("--final-url", help="Final URL after redirects")
+    convert_parser.add_argument("--content-type", help="Optional content type hint")
+    convert_parser.add_argument(
+        "--output-format",
+        choices=("json", "markdown"),
+        default="json",
+        help="Choose between full JSON output or markdown only",
+    )
+    convert_parser.add_argument(
+        "--full-content",
+        action="store_true",
+        help="Disable main-content-only cleaning",
+    )
+    convert_parser.add_argument(
+        "--include-selector",
+        action="append",
+        default=[],
+        help="CSS selector to force-include before conversion",
+    )
+    convert_parser.add_argument(
+        "--exclude-selector",
+        action="append",
+        default=[],
+        help="CSS selector to remove before conversion",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command != "convert":
+        parser.error("unknown command")
+
+    html = _read_html(args.html_file)
+    request = ConvertRequest(
+        html=html,
+        url=args.url,
+        final_url=args.final_url,
+        content_type=args.content_type,
+        options=ConvertOptions(
+            only_main_content=not args.full_content,
+            include_selectors=list(args.include_selector),
+            exclude_selectors=list(args.exclude_selector),
+        ),
+    )
+    response = convert_html(request)
+
+    if args.output_format == "markdown":
+        sys.stdout.write(response.markdown)
+        if response.markdown and not response.markdown.endswith("\n"):
+            sys.stdout.write("\n")
+        return 0
+
+    sys.stdout.write(
+        json.dumps(
+            {
+                "markdown": response.markdown,
+                "html_clean": response.html_clean,
+                "metadata": response.metadata.__dict__,
+                "links": response.links,
+                "images": response.images,
+                "quality": response.quality.__dict__,
+            },
+            ensure_ascii=False,
+        )
+    )
+    sys.stdout.write("\n")
+    return 0
+
+
+def _read_html(path: Path | None) -> str:
+    if path is None:
+        return sys.stdin.read()
+    return path.read_text(encoding="utf-8")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

markmaton/engine.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from .models import ConvertRequest, ConvertResponse
+
+
+class EngineNotFoundError(RuntimeError):
+    pass
+
+
+def convert_html(request: ConvertRequest, binary_path: Optional[str] = None) -> ConvertResponse:
+    engine = discover_engine(binary_path)
+    completed = subprocess.run(
+        [str(engine)],
+        input=json.dumps(request.to_payload()),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if completed.returncode != 0:
+        message = completed.stderr.strip() or completed.stdout.strip() or "markmaton engine failed"
+        raise RuntimeError(message)
+
+    payload = json.loads(completed.stdout)
+    return ConvertResponse.from_dict(payload)
+
+
+def discover_engine(explicit_path: Optional[str] = None) -> Path:
+    candidates = []
+    if explicit_path:
+        candidates.append(Path(explicit_path))
+
+    if env_path := os.environ.get("MARKMATON_ENGINE"):
+        candidates.append(Path(env_path))
+
+    package_bin = Path(__file__).resolve().parent / "bin" / _binary_name()
+    candidates.append(package_bin)
+
+    repo_bin = Path(__file__).resolve().parent.parent / "bin" / _binary_name()
+    candidates.append(repo_bin)
+
+    if which := shutil.which(_binary_name()):
+        candidates.append(Path(which))
+
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+
+    raise EngineNotFoundError(
+        "Could not find markmaton-engine. Set MARKMATON_ENGINE or place the binary in markmaton/bin or ./bin."
+    )
+
+
+def _binary_name() -> str:
+    return "markmaton-engine.exe" if platform.system().lower().startswith("win") else "markmaton-engine"

markmaton/models.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional
+
+
+@dataclass
+class ConvertOptions:
+    only_main_content: bool = True
+    include_selectors: List[str] = field(default_factory=list)
+    exclude_selectors: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "only_main_content": self.only_main_content,
+            "include_selectors": list(self.include_selectors),
+            "exclude_selectors": list(self.exclude_selectors),
+        }
+
+
+@dataclass
+class ConvertRequest:
+    html: str
+    url: Optional[str] = None
+    final_url: Optional[str] = None
+    content_type: Optional[str] = None
+    options: ConvertOptions = field(default_factory=ConvertOptions)
+
+    def to_payload(self) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {
+            "html": self.html,
+            "options": self.options.to_dict(),
+        }
+        if self.url:
+            payload["url"] = self.url
+        if self.final_url:
+            payload["final_url"] = self.final_url
+        if self.content_type:
+            payload["content_type"] = self.content_type
+        return payload
+
+
+@dataclass
+class Metadata:
+    title: str = ""
+    description: str = ""
+    canonical_url: str = ""
+    language: str = ""
+    author: str = ""
+    og_title: str = ""
+    og_description: str = ""
+    extras: Dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> "Metadata":
+        return cls(
+            title=str(value.get("title", "") or ""),
+            description=str(value.get("description", "") or ""),
+            canonical_url=str(value.get("canonical_url", "") or ""),
+            language=str(value.get("language", "") or ""),
+            author=str(value.get("author", "") or ""),
+            og_title=str(value.get("og_title", "") or ""),
+            og_description=str(value.get("og_description", "") or ""),
+            extras=dict(value.get("extras", {}) or {}),
+        )
+
+
+@dataclass
+class Quality:
+    text_length: int = 0
+    paragraph_count: int = 0
+    link_count: int = 0
+    image_count: int = 0
+    title_present: bool = False
+    link_density: float = 0.0
+    quality_score: float = 0.0
+    used_main_content: bool = True
+    fallback_used: bool = False
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> "Quality":
+        return cls(
+            text_length=int(value.get("text_length", 0) or 0),
+            paragraph_count=int(value.get("paragraph_count", 0) or 0),
+            link_count=int(value.get("link_count", 0) or 0),
+            image_count=int(value.get("image_count", 0) or 0),
+            title_present=bool(value.get("title_present", False)),
+            link_density=float(value.get("link_density", 0.0) or 0.0),
+            quality_score=float(value.get("quality_score", 0.0) or 0.0),
+            used_main_content=bool(value.get("used_main_content", True)),
+            fallback_used=bool(value.get("fallback_used", False)),
+        )
+
+
+@dataclass
+class ConvertResponse:
+    markdown: str
+    html_clean: str
+    metadata: Metadata
+    links: List[str]
+    images: List[str]
+    quality: Quality
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> "ConvertResponse":
+        return cls(
+            markdown=str(value.get("markdown", "") or ""),
+            html_clean=str(value.get("html_clean", "") or ""),
+            metadata=Metadata.from_dict(value.get("metadata", {}) or {}),
+            links=list(value.get("links", []) or []),
+            images=list(value.get("images", []) or []),
+            quality=Quality.from_dict(value.get("quality", {}) or {}),
+        )

markmaton-0.1.4.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: markmaton
+Version: 0.1.4
+Summary: Lightweight HTML-to-Markdown tooling for agent workflows.
+Project-URL: Homepage, https://github.com/appautomaton/markmaton
+Project-URL: Repository, https://github.com/appautomaton/markmaton
+Project-URL: Issues, https://github.com/appautomaton/markmaton/issues
+Author: appautomaton
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# markmaton
+
+Lightweight HTML-to-Markdown tooling for agent workflows.
+
+## Status
+
+This repository is intentionally starting small.
+
+The current goal is to build a clean, fast parser core that can:
+
+- take normalized page HTML from tools like Playwright, `fetch`, or no-driver
+- clean the page structure
+- return robust Markdown and page metadata
+
+## Direction
+
+- parser core: Go
+- distribution: Python packaging / PyPI
+- first focus: library and CLI for local agent use
+- release track: GitHub Actions + Trusted Publishing
+
+## Current shape
+
+- Go engine: `cmd/markmaton-engine`
+- Python wrapper: `markmaton/`
+- Architecture docs: `docs/`
+- Plans and issue CSVs: `plan/` and `issues/`
+
+## Testing policy
+
+- automated tests should be unit-test-first
+- parser module tests should use local fixtures and golden files
+- Python wrapper tests should mock the engine boundary
+- real engine checks stay manual unless there is a strong reason to automate them
+
+## Testing layout
+
+- Go package unit tests live beside each package under `internal/*`.
+- Shared Go fixture/golden helpers live in `internal/testutil/`.
+- Stable parser fixtures live under `testdata/fixtures/core/`.
+- Real-world regression fixtures live under `testdata/fixtures/regression/`.
+- Golden markdown outputs for stable core fixtures live under `testdata/golden/core/`.
+- Python wrapper tests live under `tests/unit/`.
+
+## Local smoke
+
+See:
+
+- `docs/local-smoke.md`
+- `docs/packaging-layout.md`
+- `docs/pypi-release.md`

markmaton-0.1.4.dist-info/RECORD

@@ -0,0 +1,10 @@
+markmaton/__init__.py,sha256=NrKC0RUaN1d6RZQG5IabKjY0BPKP7uvEuOmHOoiOeMs,326
+markmaton/cli.py,sha256=QNki9al0uM3GHg1vQTOQsqssV30ev_NFZcEqBwX0NIU,3080
+markmaton/engine.py,sha256=wOJFku1WW4Xro983gHzVJJq3GZuzLBvK_6b4tFp4iYc,1847
+markmaton/models.py,sha256=tfHX69BLEkREY7as9x37abD0sD1nmHJ2afHEEfWDUJQ,3852
+markmaton/bin/markmaton-engine.exe,sha256=FdDsko-7ZLRwbJUa7iHQUZ_EvQqbNV8HjcG0t93nWgI,7063040
+markmaton-0.1.4.dist-info/METADATA,sha256=8L9bAUF83_7JUVZmie6yUXnHVbuR7yr4DygSS_2_YlU,2272
+markmaton-0.1.4.dist-info/WHEEL,sha256=OKr2XcpSNWrtUe-CU6RMYrBnsfqGnZ3jZM4vKnozTRA,94
+markmaton-0.1.4.dist-info/entry_points.txt,sha256=9dr-Ibs3HAimb7LLYZqp8srYc3ZUhVNSSmmKH2oYDtg,49
+markmaton-0.1.4.dist-info/licenses/LICENSE,sha256=jT17UDsaOIhnm4G8-3nl-R0q0ynrVfIFkjio0-U8pAw,1090
+markmaton-0.1.4.dist-info/RECORD,,

markmaton-0.1.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64

markmaton-0.1.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+markmaton = markmaton.cli:main

markmaton-0.1.4.dist-info/licenses/LICENSE

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