amethyst-cli 0.1.0__tar.gz

amethyst_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,132 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # WeasyPrint loads Pango through cffi at render time, so the PDF half of
+      # the suite needs it present. Without it those tests skip rather than
+      # fail, which would make a green run mean less than it looks like.
+      - name: Install Pango
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      # Before syncing, because `uv sync` would bring the lockfile up to date
+      # itself and there would be nothing left to catch.
+      - name: Check the lockfile is current
+        run: uv lock --check
+
+      # --frozen so a CI run installs what the lockfile says and never quietly
+      # resolves something newer.
+      - name: Install the project
+        run: uv sync --frozen --python ${{ matrix.python-version }}
+
+      - name: Test
+        run: uv run pytest -q
+
+      # The suite proves a PDF is well-formed, not that it renders at all from
+      # an installed console script — which is a different code path, and the
+      # one users take. Both formats, end to end, on every version.
+      - name: Convert the kitchen sink
+        run: |
+          uv run amethyst convert tests/fixtures/kitchen-sink.md \
+            -o kitchen-sink.pdf --toc --title-page --no-remote
+          uv run amethyst convert tests/fixtures/kitchen-sink.md \
+            -o kitchen-sink.docx --toc --title-page --no-remote
+          test -s kitchen-sink.pdf
+          test -s kitchen-sink.docx
+
+  lint:
+    name: Lint and types
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      # No Pango here on purpose: `amethyst --help`, the linters and the type
+      # checker must all work on a machine that has never heard of it, because
+      # the DOCX half of the tool does.
+      - name: Install the project
+        run: uv sync --frozen --python 3.13
+
+      - name: ruff check
+        run: uv run ruff check src/ tests/
+
+      - name: ruff format
+        run: uv run ruff format --check src/ tests/
+
+      - name: mypy
+        run: uv run mypy src/amethyst
+
+      - name: The CLI loads without Pango
+        run: uv run amethyst --help
+
+  build:
+    name: Build the wheel
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      # The theme TOML and the stylesheet are package data. A wheel that left
+      # them out installs cleanly and fails on the first conversion, which is
+      # exactly the bug the src/ layout exists to catch.
+      - name: The wheel carries its data files
+        run: |
+          python3 -m zipfile -l dist/*.whl | tee contents.txt
+          grep -q 'amethyst/theme/builtin/default.toml' contents.txt
+          grep -q 'amethyst/theme/builtin/css/base.css' contents.txt
+
+      # From the wheel rather than the checkout, so nothing resolves against
+      # the source tree. DOCX because it needs no system library: this job
+      # deliberately has no Pango, and the conversion still has to work.
+      - name: The installed wheel converts
+        run: |
+          uv venv --python 3.13 /tmp/clean
+          VIRTUAL_ENV=/tmp/clean uv pip install dist/*.whl
+          cd /tmp
+          /tmp/clean/bin/amethyst convert \
+            "$GITHUB_WORKSPACE/tests/fixtures/kitchen-sink.md" \
+            -o /tmp/wheel.docx --toc --title-page --no-remote
+          test -s /tmp/wheel.docx
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

amethyst_cli-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+build/
+dist/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# macOS
+.DS_Store
+
+# Runtime
+*.log
+
+# Generated output
+# Amethyst emits these; add `!tests/fixtures/**` if binary fixtures are ever needed
+*.pdf
+*.docx

amethyst_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,63 @@
+# CLAUDE.md
+
+Amethyst is a Python CLI that turns a Markdown file into a well-typeset PDF or
+Word (DOCX) document — one file in, one styled document out:
+
+```sh
+amethyst convert notes.md -o notes.pdf
+amethyst convert notes.md -f docx
+```
+
+The point is output that looks deliberately typeset rather than printed from a
+browser: good defaults with no flags required, and a shared theme so the same
+source reads as the same document in both formats.
+
+## Commands
+
+The venv is Python 3.13 with all dependencies installed:
+
+```sh
+.venv/bin/python
+.venv/bin/amethyst          # the CLI itself, or: .venv/bin/python -m amethyst
+```
+
+`amethyst` is only on `PATH` in a shell with the venv activated, which a tool
+call does not have. A bare `amethyst ...` there fails as "command not found",
+which looks like a broken install and is not one.
+
+No `DYLD_FALLBACK_LIBRARY_PATH` export is needed any more: the PDF renderer
+puts Homebrew's lib directory on the loader path itself, just before it imports
+WeasyPrint. Only import `weasyprint` directly — outside Amethyst's own code —
+and you will still need it:
+
+```sh
+export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib
+```
+
+All four of these should be clean before a commit:
+
+```sh
+.venv/bin/python -m pytest -q
+.venv/bin/ruff check src/ tests/
+.venv/bin/ruff format src/ tests/
+.venv/bin/mypy src/amethyst
+```
+
+`uv.lock` is tracked, so run `uv lock` after touching `[project.dependencies]`.
+`uv lock --check` tells you whether it has drifted.
+
+## Looking at the output
+
+The suite proves a PDF is well-formed, not that it looks right — the two
+rendering defects found while building the PDF path were both invisible to it.
+So look at the pages. There is no `pdftoppm` or `pypdfium2` here, and `sips`
+converts only the first page of a PDF, so split it first:
+
+```sh
+.venv/bin/python -c "
+from pypdf import PdfReader, PdfWriter
+for i, page in enumerate(PdfReader('out.pdf').pages):
+    w = PdfWriter(); w.add_page(page); w.write(f'page{i}.pdf')
+"
+for f in page*.pdf; do sips -s format png "$f" --out "${f%.pdf}.png"; done
+```

amethyst_cli-0.1.0/LICENSE

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

amethyst_cli-0.1.0/PKG-INFO

@@ -0,0 +1,293 @@
+Metadata-Version: 2.5
+Name: amethyst-cli
+Version: 0.1.0
+Summary: Turn a Markdown file into a well-typeset PDF or Word document.
+Project-URL: Homepage, https://github.com/nestix6/Amethyst
+Project-URL: Repository, https://github.com/nestix6/Amethyst
+Project-URL: Issues, https://github.com/nestix6/Amethyst/issues
+Author: Patrik Repkovsky
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,docx,markdown,pdf,typesetting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+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: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Requires-Dist: linkify-it-py>=2.2
+Requires-Dist: markdown-it-py>=4.0
+Requires-Dist: mdit-py-plugins>=0.6
+Requires-Dist: pygments>=2.17
+Requires-Dist: python-docx>=1.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Requires-Dist: weasyprint>=69
+Description-Content-Type: text/markdown
+
+# Amethyst
+
+[![CI](https://github.com/nestix6/Amethyst/actions/workflows/ci.yml/badge.svg)](https://github.com/nestix6/Amethyst/actions/workflows/ci.yml)
+
+Turn a Markdown file into a well-typeset PDF or Word document.
+
+```sh
+amethyst convert notes.md -o notes.pdf
+amethyst convert notes.md -f docx
+```
+
+One file in, one styled document out. No flags required, no stylesheet to
+write, no reference `.docx` to maintain. The point is output that looks
+deliberately typeset rather than printed from a browser — and a shared theme,
+so the same source reads as the same document in both formats.
+
+This page is the quick tour. **[Full documentation](docs/documentation.md)**
+covers every option, the theme format, the configuration layers and the
+architecture.
+
+---
+
+## Install
+
+Amethyst is a Python 3.10+ package. Install it as a tool:
+
+```sh
+uv tool install amethyst-cli
+```
+
+or into an environment of your own with `pip install amethyst-cli`. The
+package is `amethyst-cli`; the command it installs is `amethyst`.
+
+**The PDF path needs Pango**, which is a system library rather than a Python
+one. That is the only thing Amethyst cannot install for you:
+
+```sh
+# macOS
+brew install pango
+
+# Debian / Ubuntu
+sudo apt install libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0
+```
+
+DOCX output needs none of it. If Pango is missing, `amethyst convert -f docx`
+still works and `-f pdf` exits 3 with a line saying what to install, rather
+than a `cffi` traceback.
+
+---
+
+## Use
+
+```sh
+amethyst convert report.md -f pdf                    # writes report.pdf
+amethyst convert report.md -f docx                   # writes report.docx
+amethyst convert report.md -o ~/Desktop/review.pdf   # the extension picks the format
+amethyst convert report.md -f pdf --toc --title-page # contents and a cover
+amethyst convert - -f pdf -o - < report.md           # stdin to stdout
+```
+
+The format has to be stated, by `-f` or by an output path that ends in `.pdf`
+or `.docx` — or once, in a config file. Given `-f` and no `-o`, the output is
+the input path with the extension swapped. With `-o -` the document goes to
+stdout and every message steps aside to stderr, so the bytes stay clean in a
+pipeline.
+
+### Options
+
+| Flag | Effect |
+| --- | --- |
+| `-o, --output PATH` | Output file; the extension infers the format. `-` is stdout. |
+| `-f, --format pdf\|docx` | Explicit format. Required when `-o` is omitted or is stdout. |
+| `-t, --theme NAME\|PATH` | A builtin theme name, or a path to a theme `.toml`. |
+| `--css PATH` | Extra stylesheet, appended last. PDF only. |
+| `--toc` | Open the document with a table of contents. |
+| `--toc-depth N` | Heading levels the contents lists. Default 3. |
+| `--title-page` | Open with a title page built from the frontmatter. |
+| `--title TEXT`, `--author TEXT` | Override what the frontmatter declared. |
+| `--page-size TEXT` | `A4`, `Letter`, or a CSS size. Defaults to the theme's. |
+| `--margin TEXT` | CSS-style: `2cm`, or `2cm 2.5cm`. Defaults to the theme's. |
+| `--no-page-numbers` | Suppress the footer numbering. |
+| `--no-remote` | Never download an image; leave a gap where a remote one was. |
+| `--highlight-style NAME` | Any Pygments style, or `none` to leave code uncoloured. |
+| `--pdf-engine NAME` | `weasyprint`. The flag exists to keep the seam visible. |
+| `-q, --quiet` / `--verbose` | Errors only / detail, and tracebacks on failure. |
+
+Two more commands:
+
+```sh
+amethyst themes list        # the builtin themes, with a line about each
+amethyst themes show NAME   # a theme's TOML, ready to copy and edit
+amethyst init               # write a starter amethyst.toml here
+```
+
+`amethyst --version` prints the version. Exit codes are distinct so the tool
+composes in scripts: **0** ok, **1** conversion failure, **2** bad usage,
+**3** a missing system dependency.
+
+---
+
+## What converts
+
+Everything below works in **both** formats unless the note says otherwise.
+
+Headings, bold, italic, strikethrough, inline code, hard breaks, nested and
+ordered lists, task lists, blockquotes, GFM tables, horizontal rules, links,
+local images, remote images, fenced code with syntax highlighting, footnotes,
+a table of contents, page numbers, a running head, a title page, and document
+metadata. PDFs also get nested outline bookmarks, straight from the headings.
+
+Three things are deliberately approximate:
+
+- **Footnotes in Word** are an endnote-style list at the end of the document,
+  not real Word footnotes.
+- **Task lists in Word** are printed ☐ / ☑ glyphs, not clickable checkboxes.
+- **Raw HTML** passes through to PDF and is skipped in DOCX, with one warning
+  naming the line it was on.
+
+LaTeX math and Mermaid diagrams are out of scope.
+
+---
+
+## Frontmatter
+
+YAML frontmatter sets the document's metadata. It reaches the title page, the
+running head, the PDF's info dictionary and Word's core properties.
+
+```markdown
+---
+title: Quarterly Review
+subtitle: What the numbers did
+author: Ada Lovelace
+date: 2026-03-31
+keywords: [finance, review]
+---
+```
+
+`title` falls back to the first `h1` if it is not declared. A `date` that is
+not a real date — "Spring 2026" — still prints on the cover, but does not
+reach the file's timestamp metadata.
+
+Frontmatter may also set any option from the table above except `format`,
+which has to be settled before the document is opened:
+
+```markdown
+---
+title: Quarterly Review
+theme: academic
+toc: true
+---
+```
+
+---
+
+## Configuration
+
+Settings resolve in this order, later winning:
+
+```
+builtin defaults → ~/.config/amethyst/config.toml → ./amethyst.toml
+                 → the document's frontmatter → command-line flags
+```
+
+`amethyst init` writes a starter `./amethyst.toml` with every setting listed,
+defaulted and commented out. `./` means the working directory, not the
+document's — `init` writes there and `convert` reads there, so the two agree.
+
+A flag you did not type does not overrule the config file, only one you did.
+And a path named inside a config file resolves against that file, so a
+stylesheet named in `~/.config/amethyst/config.toml` means the one beside it.
+
+---
+
+## Themes
+
+A theme is one TOML file declaring fonts, a type scale, colours, spacing and
+page geometry. It compiles two ways — to CSS custom properties for the PDF,
+and to Word style definitions for the DOCX — which is what keeps the two
+outputs looking like the same document.
+
+Three ship: `default` (a serif face and a violet accent), `academic` (a quiet
+book serif, a narrow measure, generous margins) and `github` (system sans,
+blue links, quiet rules).
+
+To write your own, start from a builtin and change what you want:
+
+```sh
+amethyst themes show default > house.toml
+amethyst convert report.md -t house.toml
+```
+
+Anything a theme leaves out is taken from `default`, so a theme can be one
+section — or one line:
+
+```toml
+description = "House style."
+
+[fonts]
+body = ["Charter", "Georgia", "serif"]
+
+[colors]
+accent = "#0b6e4f"
+
+[type]
+size = 10.5
+
+[page]
+size = "Letter"
+margin = "1in 1.25in"
+```
+
+Sizes are numbers, not CSS lengths: `size = 11` is points, and everything else
+(`headings`, `spacing`, `code`, `title`) is a multiple of it — so changing
+`size` alone rescales the whole document. Colours are hex, because a Word
+style cannot take any other notation.
+
+---
+
+## Remote images
+
+An image with an `http(s)` URL is downloaded once, before either renderer
+starts, and cached under `~/.cache/amethyst/images` — `XDG_CACHE_HOME` is
+honoured. A second conversion of the same document makes no request.
+`--no-remote` turns it off, and a fetch that fails warns and leaves a gap
+rather than stopping the conversion.
+
+Amethyst opens a socket in exactly one place, and only for this.
+
+---
+
+## Development
+
+```sh
+uv sync
+uv run amethyst convert tests/fixtures/kitchen-sink.md -o out.pdf
+```
+
+Four checks, all of which should be clean:
+
+```sh
+uv run pytest -q
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
+uv run mypy src/amethyst
+```
+
+`tests/fixtures/kitchen-sink.md` exercises every feature in the table above
+and is converted to both formats by the suite. The suite is offline by
+construction — a test that reaches the network fails rather than waiting on a
+socket — and PDF tests skip with a clear message when Pango is absent.
+
+The one thing tests cannot check is whether a page *looks* right: extracted
+text and page counts cannot see layout. Both rendering defects found while
+building the PDF path passed every assertion. So look at the output after
+changing any CSS.
+
+---
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).