markrender 1.1.0__tar.gz → 1.2.0__tar.gz

markrender-1.2.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to MarkRender are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project uses [Semantic Versioning](https://semver.org/). Releases are
+cut from conventional commits, and new entries are added by the publish
+workflow when a release goes out.
+
+## [1.1.1] - 2026-10-30
+
+### Fixed
+
+- Dim mode now renders the whole response in one uniform muted gray, including paragraphs, lists, tables, quotes, and code blocks.
+
+### Documentation
+
+- Clarified the CLI and Python usage examples.
+
+## [1.1.0] - 2026-10-30
+
+### Added
+
+- Dim mode for streaming responses, enabled per render call.
+- Theme previews in the README and a `preview-themes` command.
+- `--width`, `--force-color`, and `--version` CLI flags.
+- TOML config file support with warnings for unknown keys.
+- Dynamic code block line-number widths.
+- Better handling of split stream chunks and buffer boundaries.
+
+### Changed
+
+- Rewrote the README around CLI and Python usage instead of feature marketing.
+- Dim mode moved from the constructor to a `render()` argument.
+- Themes are now deep-copied so rendering cannot mutate shared theme state.
+- Improved the parser regexes for bold + italic, inline code, links, and blockquotes.
+
+### Fixed
+
+- Blockquotes falling through to other block handlers.
+- Dictionary themes loaded from TOML files failing to render.
+- Table overflow when content is wider than the terminal.
+- Encoding fallback when the output stream is not UTF-8.
+- Config files now warn about unknown keys instead of failing silently.
+
+Releases before 1.1.0 were published before this changelog existed.

{markrender-1.1.0/markrender.egg-info → markrender-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markrender
-Version: 1.1.0
+Version: 1.2.0
 Summary: Professional terminal markdown renderer for streaming LLM responses
 Author: Praneeth Gandodi
 License: MIT
@@ -34,14 +34,14 @@ Dynamic: license-file
 
 **Professional Terminal Markdown Renderer for Streaming LLM Responses**
 
-MarkRender is a Python library that renders markdown in terminals, designed for streaming LLM responses. It provides syntax highlighting, multiple color themes, and supports markdown features without flickering.
+MarkRender renders markdown in the terminal. It is built for streaming output, so you can hand it a complete string or feed it chunks from an LLM as they arrive. Syntax highlighting, themes, tables, and the rest work the same either way, without reprinting content that is already on screen.
 
 ## Features
 
 - **Streaming Support** - Designed for chunk-by-chunk LLM response rendering
 - **7 Themes** - github-dark, monokai, dracula, nord, one-dark, solarized-dark, solarized-light
 - **Syntax Highlighting** - Powered by Pygments with 500+ languages
-- **Dim Mode** - Render content in dimmed/reduced colors for "thinking" sections
+- **Dim Mode** - Render "thinking" content in a single muted gray
 - **Theme Preview** - Preview all themes with sample content via CLI
 - **Line Numbers** - Optional line numbers in code blocks
 - **Tables** - Table rendering with borders and overflow truncation
@@ -55,183 +55,269 @@ MarkRender is a Python library that renders markdown in terminals, designed for
 
 ## Installation
 
+MarkRender is on PyPI:
+
+```bash
+pip install markrender
+```
+
+That installs the library and the `markrender` command. Check that it worked:
+
+```bash
+markrender --version
+```
+
+Upgrade an existing install with:
+
 ```bash
-pip install git+https://github.com/Praneeth-Gandodi/markrender.git
+pip install --upgrade markrender
 ```
 
-Or install from source:
+If you want to work on MarkRender itself, clone the repo and install it in editable mode instead:
 
 ```bash
 git clone https://github.com/Praneeth-Gandodi/markrender.git
 cd markrender
-pip install -e .
+pip install -e ".[dev]"
+```
+
+## Command Line
+
+Render a file:
+
+```bash
+markrender README.md
+```
+
+Read markdown from stdin:
+
+```bash
+cat notes.md | markrender
+```
+
+On PowerShell:
+
+```powershell
+Get-Content notes.md -Raw | markrender
+```
+
+Pick a theme:
+
+```bash
+markrender --theme dracula notes.md
+```
+
+Adjust code blocks:
+
+```bash
+markrender --no-line-numbers notes.md
+markrender --code-background notes.md
+markrender --no-stream-code notes.md
+```
+
+Set a fixed width when the terminal reports the wrong size, or when the output goes somewhere else:
+
+```bash
+markrender --width 80 notes.md
+```
+
+Force color when piping into another program, a log file, or CI:
+
+```bash
+markrender --force-color notes.md | less -R
+```
+
+List the theme names:
+
+```bash
+markrender --list-themes
 ```
 
-## Quick Start
+Preview every theme with sample content:
+
+```bash
+markrender --preview-themes
+```
+
+Running `markrender` with no file and nothing piped in prints an error and exits.
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--theme NAME` | Color theme (default: `github-dark`) |
+| `--no-line-numbers` | Hide line numbers in code blocks |
+| `--code-background` | Show a background behind code blocks |
+| `--width N` | Wrap at a fixed width instead of the terminal width |
+| `--no-stream-code` | Render code blocks in one pass instead of line by line |
+| `--force-color` | Emit colors even when the output is not a terminal |
+| `--list-themes` | Print available themes and exit |
+| `--preview-themes` | Render sample markdown in every theme and exit |
+| `-v`, `--version` | Print the version and exit |
+
+CLI flags override values from a config file. See [Configuration](#configuration).
+
+## Python API
+
+### Render a string
 
 ````python
 from markrender import MarkdownRenderer
 
-# Create renderer with default theme
 renderer = MarkdownRenderer()
 
-# Render markdown content
-markdown_text = """
-# Hello World
+markdown = """
+# Hello
 
-This is **bold** and this is *italic*.
+Some **bold** text, some *italic* text, and `inline code`.
 
 ```python
 def hello():
     print("Hello from MarkRender!")
 ```
 
-## Features
-- Item 1
-- Item 2
-- [x] Completed task
-- [ ] Pending task
+- A list item
+- [x] A finished task
+- [ ] A pending task
 """
 
-renderer.render(markdown_text)
+renderer.render(markdown)
 renderer.finalize()
 ````
 
-### Streaming LLM Responses
+`render()` writes output as it parses, and `finalize()` flushes whatever is still buffered. For a string you already have, call them one after the other.
 
-Perfect for rendering streaming responses from LLM APIs:
+### Streaming LLM responses
 
 ```python
 from markrender import MarkdownRenderer
 from openai import OpenAI
 
 client = OpenAI()
-renderer = MarkdownRenderer(theme='github-dark')
+renderer = MarkdownRenderer(theme="github-dark")
 
 stream = client.chat.completions.create(
-    model="gpt-4",
+    model="gpt-4o",
     messages=[{"role": "user", "content": "Explain quantum computing"}],
-    stream=True
+    stream=True,
 )
 
 for chunk in stream:
-    content = chunk.choices[0].delta.content
-    if content:
-        renderer.render(content)
+    text = chunk.choices[0].delta.content
+    if text:
+        renderer.render(text)
 
 renderer.finalize()
 ```
 
-### Dim Mode
-
-Use dim mode for "thinking" sections or less prominent content:
-
-```python
-from markrender import MarkdownRenderer
+The renderer keeps partial lines and open blocks in an internal buffer, so chunks can split anywhere: mid-word, mid-table, or in the middle of a code fence. Feed every chunk and call `finalize()` once when the stream ends.
 
-renderer = MarkdownRenderer()
+### Dim mode
 
-# Normal rendering
-renderer.render("This is **normal** content")
+`render()` takes a `dim_mode` argument, which draws that chunk as plain muted gray. Formatting colors, bold, and syntax highlighting are dropped so the whole block reads like thinking text instead of competing with the answer:
 
-# Dim/reduced color rendering
-renderer.render("This content is dimmed and less prominent", dim_mode=True)
+```python
+renderer.render("Let me think about this...", dim_mode=True)
+renderer.render("Here is the answer.", dim_mode=False)
 ```
 
-### Theme Preview
-
-Preview all available themes from the CLI:
-
-```bash
-markrender --preview-themes
-```
+Dim mode applies per call, so you can turn it on and off while streaming.
 
-## Themes
+### Custom output
 
-MarkRender includes 7 professional color themes:
+By default output goes to stdout. Pass any text stream with `output`:
 
 ```python
-themes = [
-    'github-dark',      # GitHub's dark theme (default)
-    'monokai',          # Popular Monokai theme
-    'dracula',          # Dracula theme
-    'nord',             # Nord color palette
-    'one-dark',         # Atom One Dark
-    'solarized-dark',   # Solarized Dark
-    'solarized-light'   # Solarized Light
-]
+from markrender import MarkdownRenderer
 
-renderer = MarkdownRenderer(theme='dracula')
+with open("rendered.txt", "w", encoding="utf-8") as log:
+    renderer = MarkdownRenderer(output=log, force_color=True)
+    renderer.render("# Saved to a file\n")
+    renderer.finalize()
 ```
 
-List available themes:
+Color detection still looks at stdout, so set `force_color=True` if you want ANSI colors in the file.
 
-```bash
-markrender --list-themes
-```
+### Constructor options
 
-## Configuration
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `theme` | `"github-dark"` | Theme name |
+| `code_background` | `False` | Draw a background behind code blocks |
+| `line_numbers` | `True` | Show line numbers in code blocks |
+| `inline_code_color` | theme default | ANSI color code for inline code |
+| `width` | auto-detect | Wrap width in characters |
+| `force_color` | `False` | Emit color even when the output is not a TTY |
+| `stream_code` | `True` | Render code lines as they arrive |
+| `output` | `sys.stdout` | Stream to write to |
+| `use_config` | `True` | Load a config file if one is found |
+| `config` | `None` | Pass a `RendererConfig` directly |
 
-### Python API
+Custom inline code color uses the `rgb` helper:
 
 ```python
 from markrender import MarkdownRenderer
 from markrender.colors import rgb
 
 renderer = MarkdownRenderer(
-    theme='monokai',                       # Color theme
-    code_background=False,                 # Show background in code blocks
-    line_numbers=True,                     # Show line numbers in code
-    inline_code_color=rgb(255, 100, 200),  # Custom inline code color
-    width=100,                             # Terminal width (auto-detect by default)
-    force_color=False,                     # Force color output
-    stream_code=True                       # Stream code lines as they arrive
+    theme="monokai",
+    inline_code_color=rgb(255, 100, 200),
+    width=100,
 )
 ```
 
-### Parameters
-
-- **theme** (str): Color theme name (default: `'github-dark'`)
-- **code_background** (bool): Show background in code blocks (default: `False`)
-- **line_numbers** (bool): Show line numbers in code blocks (default: `True`)
-- **inline_code_color** (str): Custom ANSI color code for inline code (default: theme default)
-- **width** (int): Terminal width in characters (default: auto-detect)
-- **force_color** (bool): Force color output even if terminal does not support it (default: `False`)
-- **stream_code** (bool): Render code lines as they arrive instead of buffering (default: `True`)
-- **output** (file): Output stream (default: `sys.stdout`)
-
-### CLI Usage
+## Configuration
 
-```bash
-markrender README.md
-markrender --theme dracula file.md
-cat file.md | markrender
-markrender --preview-themes
-markrender --list-themes
-markrender --no-line-numbers --code-background file.md
-markrender --width 80 --force-color file.md
-```
+MarkRender reads a TOML config file if one exists. It checks these locations in order and uses the first match:
 
-### Config File
+1. `.markrender.toml` in the current directory
+2. `~/.markrender/config.toml`
+3. `~/.config/markrender/config.toml`
 
-MarkRender supports TOML configuration files. Place a `.markrender.toml` in your current directory or `~/.markrender/config.toml`:
+Example `.markrender.toml`:
 
 ```toml
 [theme]
-name = "github-dark"
+name = "dracula"
 
 [rendering]
-code_background = false
-line_numbers = true
+code_background = true
+line_numbers = false
 
 [output]
-# width = 80
+width = 100
 force_color = false
 
 [features]
-stream_code = true
+stream_code = false
 ```
 
+Values are applied in this order, from highest to lowest priority:
+
+1. Arguments passed to `MarkdownRenderer(...)`
+2. The config file
+3. Built-in defaults
+
+Only non-`None` arguments override the config, so `MarkdownRenderer()` picks up your file settings. Pass `use_config=False` to ignore config files entirely.
+
+## Themes
+
+| Theme | Notes |
+|-------|-------|
+| `github-dark` | GitHub's dark theme (default) |
+| `monokai` | Classic Monokai palette |
+| `dracula` | Dracula palette |
+| `nord` | Nord palette |
+| `one-dark` | Atom One Dark |
+| `solarized-dark` | Solarized Dark |
+| `solarized-light` | Solarized Light |
+
+```python
+renderer = MarkdownRenderer(theme="dracula")
+```
+
+See the names from the CLI with `markrender --list-themes`, or render a sample in each theme with `markrender --preview-themes`.
+
 ## Supported Markdown Features
 
 ### Headings
@@ -336,6 +422,11 @@ Hello :wave: Let's :rocket: go!
 - **Note-Taking Apps** - Terminal-based markdown note viewers
 - **Log Viewers** - Render structured logs with markdown
 
+## Changelog
+
+Release notes come from conventional commit messages, so the history stays in
+one place. See [CHANGELOG.md](CHANGELOG.md) for what changed in each version.
+
 ## Development
 
 ### Setup Development Environment
@@ -372,12 +463,19 @@ no version number to edit by hand.
 2. Choose `auto` (recommended) or an explicit `patch`, `minor`, or `major` bump.
 3. The workflow runs the tests, creates the next `vX.Y.Z` tag, builds the
    sdist and wheel, publishes to PyPI, and creates a GitHub release.
+4. Release notes are generated from the commits since the last tag, and the
+   same entry is added to [CHANGELOG.md](CHANGELOG.md) on `main`.
 
 With `auto`, commit messages since the last tag decide the bump:
 
 - `feat!:` or a `BREAKING CHANGE:` footer → major
 - `feat:` → minor
-- everything else → patch
+- `fix:`, `perf:`, `refactor:`, or `revert:` → patch
+- `docs:`, `test:`, `chore:`, `ci:`, `build:`, and `style:` don't trigger a
+  release on their own
+
+Write commit subjects in the `type(scope): summary` form so the changelog and
+version bump stay accurate.
 
 Publishing uses PyPI Trusted Publishing (OIDC), so no API token is stored in
 the repository. Configure it once: