md2star 2.0.0__py3-none-any.whl

md2star/__init__.py

@@ -0,0 +1,42 @@
+"""md2star — Markdown → DOCX/PPTX/PDF bridge built on Pandoc.
+
+Module summary
+--------------
+Public package surface for md2star. Re-exports the preprocessor entry
+points so consumers can import them either from the top-level package
+or from the ``md2star.preprocessing`` submodule.
+
+Usage
+-----
+>>> from md2star import preprocess_markdown
+>>> out = preprocess_markdown("# Hello\\n", base_dir=".")
+>>> print(out.splitlines()[0])  # '# Hello'
+# Hello
+
+Author
+------
+[Warith HARCHAOUI](https://linkedin.com/in/warith-harchaoui)
+"""
+
+from __future__ import annotations
+
+__version__: str = "2.0.0"
+
+from .preprocessing import (
+    DEFAULT_ALT_TEXT_MODEL,
+    DEFAULT_LINT_MODEL,
+    fill_empty_alt_text,
+    is_ollama_installed,
+    preprocess_markdown,
+    render_mermaid_local,
+)
+
+__all__ = [
+    "__version__",
+    "preprocess_markdown",
+    "render_mermaid_local",
+    "fill_empty_alt_text",
+    "is_ollama_installed",
+    "DEFAULT_LINT_MODEL",
+    "DEFAULT_ALT_TEXT_MODEL",
+]

md2star/__main__.py

@@ -0,0 +1,31 @@
+"""Allow ``python -m md2star`` as an alternative to the ``md2star`` console script.
+
+Module summary
+--------------
+Thin shim that forwards ``python -m md2star`` invocations to
+:func:`md2star.cli.main`. Python convention: every importable
+package that exposes a CLI should be runnable via ``-m``, so users
+who bypass the installed entry point (debugging, sandboxed Pythons,
+`pipx run --spec md2star md2star` style invocations) still get the
+same behaviour.
+
+Usage
+-----
+>>> # From the shell:
+>>> #   python -m md2star --help
+>>> #   python -m md2star docx report.md
+>>> # is equivalent to the installed `md2star` entry point.
+
+Author
+------
+[Warith HARCHAOUI](https://linkedin.com/in/warith-harchaoui/)
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

md2star/cache.py

@@ -0,0 +1,93 @@
+"""Per-user cache directory for md2star image/mermaid artifacts.
+
+Module summary
+--------------
+Historically, downscaled images, downloaded remote images, and rendered
+mermaid PNGs all landed next to the user's source Markdown, cluttering
+working directories with hidden dotfiles (``.remote_*``, ``*_max1600.*``,
+``*_cell.*``, ``.mermaid_*``). This module centralises every artifact under
+``$XDG_CACHE_HOME/md2star/`` (with platform fallbacks) so the user's source
+trees stay clean and the cache can be wiped with a single
+``md2star clear-cache``.
+
+Cache layout::
+
+    $XDG_CACHE_HOME/md2star/
+    ├── remote/           # downloaded http(s):// images, keyed by URL MD5
+    ├── resized/          # downscaled rasters, keyed by source-path + size MD5
+    ├── cell/             # cell-fitted images, keyed by source-path MD5
+    └── mermaid/          # rendered mermaid PNGs + resolved config JSON
+
+The hash-keyed filenames make collisions across users impossible — two
+different source files with the same basename do not stomp each other.
+
+Usage
+-----
+>>> from md2star.cache import cache_dir, clear_cache
+>>> p = cache_dir("remote")
+>>> print(p.name)  # 'remote'
+remote
+>>> freed = clear_cache()
+>>> print(freed >= 0)  # True
+True
+
+Author
+------
+[Warith HARCHAOUI](https://linkedin.com/in/warith-harchaoui/)
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+_APP_NAME = "md2star"
+
+
+def _platform_cache_root() -> Path:
+    """Return the per-user cache root using each platform's convention.
+
+    * Linux/BSD: ``$XDG_CACHE_HOME`` (default ``~/.cache``).
+    * macOS: ``~/Library/Caches`` (Apple's documented per-user cache dir).
+    * Windows: ``%LOCALAPPDATA%`` (default ``~\\AppData\\Local``).
+    """
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    if xdg:
+        return Path(xdg)
+
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Caches"
+    if sys.platform == "win32":
+        local = os.environ.get("LOCALAPPDATA")
+        if local:
+            return Path(local)
+        return Path.home() / "AppData" / "Local"
+    return Path.home() / ".cache"
+
+
+def cache_dir(subdir: str | None = None) -> Path:
+    """Return the md2star cache dir (or a subdirectory of it), creating it.
+
+    Honors ``MD2STAR_CACHE_DIR`` for testing / opt-out (e.g. a tempdir in CI).
+    """
+    override = os.environ.get("MD2STAR_CACHE_DIR")
+    root = Path(override) if override else (_platform_cache_root() / _APP_NAME)
+    target = root / subdir if subdir else root
+    target.mkdir(parents=True, exist_ok=True)
+    return target
+
+
+def clear_cache() -> int:
+    """Remove the entire md2star cache directory. Returns bytes freed (approx)."""
+    root = cache_dir()
+    total = 0
+    for dirpath, _dirnames, filenames in os.walk(root):
+        for name in filenames:
+            try:
+                total += os.path.getsize(os.path.join(dirpath, name))
+            except OSError:
+                pass
+    shutil.rmtree(root, ignore_errors=True)
+    return total