md2mrkdwn 0.4.2__tar.gz

md2mrkdwn-0.4.2/.gitignore

@@ -0,0 +1,77 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+.idea
+media
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+configs/local_settings.py
+
+# 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/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+#Ipython Notebook
+.ipynb_checkpoints
+venv/*
+env/*
+.venv/*
+.env/*
+
+# Idea modules
+*.iml
+
+.ruff_cache
+.pytest_cache
+.mypy_cache
+
+.claude/
+CLAUDE.md

md2mrkdwn-0.4.2/LICENSE

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

md2mrkdwn-0.4.2/PKG-INFO

@@ -0,0 +1,419 @@
+Metadata-Version: 2.4
+Name: md2mrkdwn
+Version: 0.4.2
+Summary: Convert Markdown to Slack mrkdwn format
+Project-URL: Homepage, https://github.com/bigbag/md2mrkdwn
+Project-URL: Repository, https://github.com/bigbag/md2mrkdwn
+Project-URL: Issues, https://github.com/bigbag/md2mrkdwn/issues
+Author-email: Pavel Liashkov <pavel.liashkov@protonamil.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: converter,formatting,markdown,mrkdwn,slack
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# md2mrkdwn
+
+[![CI](https://github.com/bigbag/md2mrkdwn/workflows/CI/badge.svg)](https://github.com/bigbag/md2mrkdwn/actions?query=workflow%3ACI)
+[![pypi](https://img.shields.io/pypi/v/md2mrkdwn.svg)](https://pypi.python.org/pypi/md2mrkdwn)
+[![downloads](https://img.shields.io/pypi/dm/md2mrkdwn.svg)](https://pypistats.org/packages/md2mrkdwn)
+[![versions](https://img.shields.io/pypi/pyversions/md2mrkdwn.svg)](https://github.com/bigbag/md2mrkdwn)
+[![license](https://img.shields.io/github/license/bigbag/md2mrkdwn.svg)](https://github.com/bigbag/md2mrkdwn/blob/master/LICENSE)
+
+Pure Python library for converting Markdown to Slack's mrkdwn format. Zero dependencies, comprehensive formatting support, and proper handling of edge cases.
+
+## Features
+
+- **Zero dependencies** - Pure Python implementation with no external packages required
+- **Comprehensive formatting** - Supports bold, italic, strikethrough, links, images, lists, and more
+- **Configurable** - Customize symbols, formats, and enable/disable specific conversions
+- **Code block handling** - Preserves content inside code blocks without conversion
+- **Table support** - Wraps markdown tables in code blocks for Slack display
+- **Task lists** - Converts checkbox syntax to Unicode symbols (☐/☑)
+- **Edge case handling** - Properly handles nested formatting and special characters
+
+## Quick Start
+
+```python
+from md2mrkdwn import convert
+
+markdown = "**Hello** *World*! Check out [Slack](https://slack.com)"
+mrkdwn = convert(markdown)
+print(mrkdwn)
+# Output: *Hello* _World_! Check out <https://slack.com|Slack>
+```
+
+## Installation
+
+```bash
+# Install with pip
+pip install md2mrkdwn
+
+# Or install with uv
+uv add md2mrkdwn
+
+# Or install with pipx (for CLI tools that use this library)
+pipx install md2mrkdwn
+```
+
+## Usage
+
+### Simple Function
+
+The `convert()` function provides a simple interface for one-off conversions:
+
+```python
+from md2mrkdwn import convert
+
+markdown = """
+# Hello World
+
+This is **bold** and *italic* text.
+
+- Item 1
+- Item 2
+
+Check out [this link](https://example.com)!
+"""
+
+mrkdwn = convert(markdown)
+print(mrkdwn)
+```
+
+Output:
+```
+*Hello World*
+
+This is *bold* and _italic_ text.
+
+• Item 1
+• Item 2
+
+Check out <https://example.com|this link>!
+```
+
+### Class-based Usage
+
+For multiple conversions, use the `MrkdwnConverter` class:
+
+```python
+from md2mrkdwn import MrkdwnConverter
+
+converter = MrkdwnConverter()
+
+# Convert multiple texts
+text1 = converter.convert("**bold** and *italic*")
+text2 = converter.convert("# Header\n\n- List item")
+
+print(text1)  # *bold* and _italic_
+print(text2)  # *Header*\n\n• List item
+```
+
+### Custom Configuration
+
+Use `MrkdwnConfig` to customize conversion behavior:
+
+```python
+from md2mrkdwn import convert, MrkdwnConfig, MrkdwnConverter
+
+# Custom bullet character
+config = MrkdwnConfig(bullet_char="-")
+print(convert("- Item 1\n- Item 2", config=config))
+# Output: - Item 1
+#         - Item 2
+
+# Custom checkbox symbols
+config = MrkdwnConfig(checkbox_checked="✓", checkbox_unchecked="○")
+print(convert("- [x] Done\n- [ ] Todo", config=config))
+# Output: • ✓ Done
+#         • ○ Todo
+
+# Plain headers (no bold)
+config = MrkdwnConfig(header_style="plain")
+print(convert("# Title", config=config))
+# Output: Title
+
+# URL-only links (no link text)
+config = MrkdwnConfig(link_format="url_only")
+print(convert("[Click here](https://example.com)", config=config))
+# Output: <https://example.com>
+
+# Disable specific conversions
+config = MrkdwnConfig(convert_bold=False, convert_italic=False)
+print(convert("**bold** and *italic*", config=config))
+# Output: **bold** and *italic*
+
+# Reusable converter with config
+converter = MrkdwnConverter(MrkdwnConfig(
+    bullet_char="→",
+    horizontal_rule_char="=",
+    horizontal_rule_length=20
+))
+print(converter.convert("- Item\n\n---"))
+# Output: → Item
+#
+#         ====================
+```
+
+### Configuration Options
+
+| Option                     | Type        | Default                | Description                               |
+|----------------------------|-------------|------------------------|-------------------------------------------|
+| `bullet_char`              | str         | `•`                    | Character for unordered list items        |
+| `checkbox_checked`         | str         | `☑`                    | Symbol for checked task items             |
+| `checkbox_unchecked`       | str         | `☐`                    | Symbol for unchecked task items           |
+| `horizontal_rule_char`     | str         | `─`                    | Character for horizontal rules            |
+| `horizontal_rule_length`   | int         | `10`                   | Length of horizontal rules                |
+| `header_style`             | HeaderStyle | `HeaderStyle.BOLD`     | `BOLD`, `PLAIN`, or `PREFIX`              |
+| `link_format`              | LinkFormat  | `LinkFormat.SLACK`     | `SLACK`, `URL_ONLY`, or `TEXT_ONLY`       |
+| `table_mode`               | TableMode   | `TableMode.CODE_BLOCK` | `CODE_BLOCK` or `PRESERVE`              |
+| `table_link_format`        | LinkFormat  | `LinkFormat.URL_ONLY`  | Link format inside tables                 |
+| `strip_table_emoji`        | bool        | `True`                 | Strip emoji shortcodes from tables        |
+| `convert_table_links`      | bool        | `True`                 | Enable/disable link conversion in tables  |
+| `convert_bold`             | bool        | `True`                 | Enable/disable bold conversion            |
+| `convert_italic`           | bool        | `True`                 | Enable/disable italic conversion          |
+| `convert_strikethrough`    | bool        | `True`                 | Enable/disable strikethrough conversion   |
+| `convert_links`            | bool        | `True`                 | Enable/disable link conversion            |
+| `convert_images`           | bool        | `True`                 | Enable/disable image conversion           |
+| `convert_lists`            | bool        | `True`                 | Enable/disable list conversion            |
+| `convert_task_lists`       | bool        | `True`                 | Enable/disable task list conversion       |
+| `convert_headers`          | bool        | `True`                 | Enable/disable header conversion          |
+| `convert_horizontal_rules` | bool        | `True`                 | Enable/disable horizontal rule conversion |
+| `convert_tables`           | bool        | `True`                 | Enable/disable table wrapping             |
+
+### Handling Tables
+
+Markdown tables are automatically wrapped in code blocks since Slack doesn't support native table rendering:
+
+```python
+from md2mrkdwn import convert
+
+markdown = """
+| Name | Age |
+|------|-----|
+| Alice | 30 |
+| Bob | 25 |
+"""
+
+print(convert(markdown))
+```
+
+Output:
+```
+```
+| Name | Age |
+|------|-----|
+| Alice | 30 |
+| Bob | 25 |
+```
+```
+
+#### Links in Tables
+
+Links inside tables are converted to URL-only format by default (different from the global `link_format` setting):
+
+```python
+from md2mrkdwn import convert, MrkdwnConfig, LinkFormat
+
+markdown = """
+| App | Link |
+|-----|------|
+| Example | [Visit](https://example.com) |
+"""
+
+# Default: URL only
+print(convert(markdown))
+# | App | Link |
+# | Example | https://example.com |
+
+# Slack format
+config = MrkdwnConfig(table_link_format=LinkFormat.SLACK)
+print(convert(markdown, config))
+# | Example | <https://example.com|Visit> |
+
+# Text only (link text, no URL)
+config = MrkdwnConfig(table_link_format=LinkFormat.TEXT_ONLY)
+print(convert(markdown, config))
+# | Example | Visit |
+```
+
+## Conversion Reference
+
+| Markdown                   | mrkdwn             | Notes                        |
+|----------------------------|--------------------|------------------------------|
+| `**bold**` or `__bold__`   | `*bold*`           | Slack uses single asterisk   |
+| `*italic*` or `_italic_`   | `_italic_`         | Slack uses underscores       |
+| `***bold+italic***`        | `*_text_*`         | Combined formatting          |
+| `~~strikethrough~~`        | `~text~`           | Single tilde                 |
+| `[text](url)`              | `<url\|text>`      | Slack link format            |
+| `![alt](url)`              | `<url>`            | Images become plain URLs     |
+| `# Header` (all levels)    | `*Header*`         | Bold (Slack has no headers)  |
+| `- item` / `* item`        | `• item`           | Bullet character (U+2022)    |
+| `1. item`                  | `1. item`          | Preserved as-is              |
+| `- [ ] task`               | `• ☐ task`         | Unchecked checkbox (U+2610)  |
+| `- [x] task`               | `• ☑ task`         | Checked checkbox (U+2611)    |
+| `> quote`                  | `> quote`          | Same syntax                  |
+| `` `code` ``               | `` `code` ``       | Same syntax                  |
+| ``` code block ```         | ``` code block ``` | Same syntax                  |
+| `---` / `***`              | `──────────`       | Horizontal rule (U+2500)     |
+| Tables                     | Wrapped in ```     | Slack has no native tables   |
+
+## How It Works
+
+### Conversion Pipeline
+
+md2mrkdwn processes text through a multi-stage pipeline:
+
+1. **Table extraction** - Tables are detected, validated, and replaced with placeholders
+2. **Code block tracking** - Lines inside code blocks are skipped during conversion
+3. **Pattern application** - Regex patterns convert formatting using placeholder protection
+4. **Placeholder restoration** - Tables and temporary markers are replaced with final output
+
+### Pattern Interference Prevention
+
+A key challenge in markdown conversion is preventing patterns from interfering with each other. For example, converting `**bold**` to `*bold*` could then be matched by the italic pattern.
+
+md2mrkdwn solves this using placeholder substitution:
+1. Bold text is temporarily marked with null-byte placeholders
+2. Italic patterns run without matching the placeholders
+3. Placeholders are replaced with final mrkdwn characters
+
+### Table Handling
+
+Tables are detected using these criteria:
+- Lines matching `|...|` pattern
+- Second row contains separator cells (dashes with optional alignment colons)
+- Header and separator have matching column counts
+
+Valid tables are wrapped in triple-backtick code blocks for monospace display in Slack.
+
+Column alignment accounts for Unicode character display width. Emoji like ⭐ render as 2 columns wide in monospace fonts but have a character length of 1. The converter pads columns based on display width to maintain proper alignment.
+
+### Code Block Protection
+
+Content inside code blocks (both fenced and inline) is protected from conversion:
+- Fenced blocks: State machine tracks opening/closing ``` markers
+- Inline code: Segments are extracted before conversion and restored after
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/bigbag/md2mrkdwn.git
+cd md2mrkdwn
+make install
+```
+
+### Commands
+
+```bash
+make install  # Install all dependencies
+make test     # Run tests with coverage
+make lint     # Run linters (ruff + mypy)
+make format   # Format code with ruff
+make clean    # Clean cache and build files
+```
+
+### Running Tests
+
+```bash
+# Run all tests with coverage
+uv run pytest --cov=md2mrkdwn --cov-report=term-missing
+
+# Run specific test class
+uv run pytest tests/test_converter.py::TestBasicFormatting -v
+
+# Run with verbose output
+uv run pytest -v
+```
+
+### Project Structure
+
+```
+md2mrkdwn/
+├── src/
+│   └── md2mrkdwn/
+│       ├── __init__.py      # Package exports
+│       └── converter.py     # MrkdwnConverter, MrkdwnConfig classes
+├── tests/
+│   ├── conftest.py          # Pytest fixtures
+│   ├── test_converter.py    # Converter tests
+│   └── test_config.py       # Configuration tests
+├── pyproject.toml           # Project configuration
+├── Makefile                 # Development commands
+└── README.md
+```
+
+## API Reference
+
+### `convert(markdown: str, config: MrkdwnConfig | None = None) -> str`
+
+Convert Markdown text to Slack mrkdwn format.
+
+**Parameters:**
+- `markdown` - Input text in Markdown format
+- `config` - Optional configuration (uses defaults if not provided)
+
+**Returns:**
+- Text converted to Slack mrkdwn format
+
+### `MrkdwnConverter`
+
+Class for converting Markdown to mrkdwn.
+
+**Constructor:**
+- `MrkdwnConverter(config: MrkdwnConfig | None = None)`
+
+**Methods:**
+- `convert(markdown: str) -> str` - Convert Markdown text to mrkdwn
+
+**Example:**
+```python
+converter = MrkdwnConverter()
+result = converter.convert("**Hello** *World*")
+
+# With custom config
+config = MrkdwnConfig(bullet_char="-")
+converter = MrkdwnConverter(config)
+result = converter.convert("- Item")
+```
+
+### `MrkdwnConfig`
+
+Immutable configuration dataclass for customizing conversion behavior.
+
+**Example:**
+```python
+from md2mrkdwn import MrkdwnConfig, DEFAULT_CONFIG
+
+# Create custom config
+config = MrkdwnConfig(
+    bullet_char="→",
+    header_style="plain",
+    convert_bold=False
+)
+
+# Use the default config singleton
+print(DEFAULT_CONFIG.bullet_char)  # •
+```
+
+
+## See Also
+
+- [Slack mrkdwn specification](https://api.slack.com/reference/surfaces/formatting) - Official Slack formatting documentation
+- [markdown_to_mrkdwn](https://github.com/fla9ua/markdown_to_mrkdwn) - Related project for markdown to mrkdwn conversion
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.