Skip to main content

mq-python

PyPI

Python bindings for the mq Markdown processor.

Installation

pip install markdown-query

Usage

Basic Usage

Use the run function to process Markdown with mq queries:

import mq

# Extract all level 1 headings
result = mq.run(".h1", "# Hello World\n\n## Heading2\n\nText")
print(result.values)  # ['# Hello World']

# Extract all level 2 headings
result = mq.run(".h2", "# Main Title\n\n## Section A\n\n## Section B")
print(result.values)  # ['## Section A', '## Section B']

# Get all results as a single string
print(result.text)  # '## Section A\n## Section B'

Filtering and Transforming

Use mq query syntax to filter and transform Markdown:

import mq

markdown = """
# Product

## Features
Great features here.

## Installation
Install instructions.
"""

# Filter headings containing specific text
result = mq.run('.h2 | select(contains("Feature"))', markdown)
print(result.values)  # ['## Features']

# Extract list items
result = mq.run(".[]", "# List\n\n- Item 1\n- Item 2\n- Item 3")
print(result.values)  # ['- Item 1', '- Item 2', '- Item 3']

# Extract code blocks
result = mq.run(".code", "# Code\n\n```python\nprint('Hello')\n```")
print(result.values)  # ["```python\nprint('Hello')\n```"]

Input Formats

mq supports multiple input formats:

import mq

# Markdown (default)
result = mq.run(".h1", "# Heading", mq.Options(input_format=mq.InputFormat.MARKDOWN))

# MDX (Markdown with JSX)
options = mq.Options(input_format=mq.InputFormat.MDX)
result = mq.run("select(is_mdx())", "# MDX\n\n<Component />", options)
print(result.values)  # ['<Component />']

# HTML
options = mq.Options(input_format=mq.InputFormat.HTML)
result = mq.run('select(contains("Hello"))', "<h1>Hello</h1><p>World</p>", options)
print(result.values)  # ['# Hello']

# Plain text
options = mq.Options(input_format=mq.InputFormat.TEXT)
result = mq.run('select(contains("2"))', "Line 1\nLine 2\nLine 3", options)
print(result.values)  # ['Line 2']

Available input formats:

  • InputFormat.MARKDOWN - Standard Markdown (default)
  • InputFormat.MDX - Markdown with JSX
  • InputFormat.HTML - HTML content
  • InputFormat.TEXT - Plain text
  • InputFormat.RAW - Raw string input
  • InputFormat.NULL - Null input

Options

mq.Options accepts keyword arguments, and every option can also be set as an attribute:

import mq

options = mq.Options(input_format=mq.InputFormat.HTML, list_style=mq.ListStyle.PLUS)
options.link_url_style = mq.UrlSurroundStyle.ANGLE

Options that are not set use their defaults (shown below).

Output Formats and Rendering Options

Use MQResult.render() to render the result as Markdown, HTML or plain text. The rendering options (list_style, link_title_style, link_url_style) are applied to the output:

import mq

markdown = "# Title\n\n- Item 1\n- Item 2\n\n[link](https://example.com \"title\")"

options = mq.Options(
    list_style=mq.ListStyle.PLUS,                      # Use '+' for list items
    link_title_style=mq.TitleSurroundStyle.SINGLE,     # Use single quotes for link titles
    link_url_style=mq.UrlSurroundStyle.ANGLE,          # Use angle brackets for URLs
)
result = mq.run(".", markdown, options)

print(result.render())                          # Markdown (default)
print(result.render(mq.OutputFormat.HTML))      # HTML
print(result.render(mq.OutputFormat.TEXT))      # Plain text

# The default format of render() can be set with output_format
options = mq.Options(output_format=mq.OutputFormat.HTML)
print(mq.run(".h1", "# Hello", options).render())  # '<h1>Hello</h1>\n'

Available options:

  • OutputFormat: MARKDOWN (default), HTML, TEXT
  • ListStyle: DASH (default), PLUS, STAR
  • TitleSurroundStyle: DOUBLE (default), SINGLE, PAREN
  • UrlSurroundStyle: NONE (default), ANGLE

HTML to Markdown Conversion

Convert HTML to Markdown:

import mq

html = "<h1>Hello World</h1><p>This is a <strong>test</strong>.</p>"
markdown = mq.html_to_markdown(html)
print(markdown)  # '# Hello World\n\nThis is a **test**.'

# With conversion options
options = mq.ConversionOptions()
options.extract_scripts_as_code_blocks = True  # Convert <script> tags to code blocks
options.generate_front_matter = True           # Generate front matter from metadata
options.use_title_as_h1 = True                 # Use <title> as h1 heading

markdown = mq.html_to_markdown(html, options)

Working with Results

The run function returns an MQResult object:

import mq

result = mq.run(".h", "# H1\n\n## H2\n\n### H3")

# Get the number of results
print(len(result))  # 3

# Access individual results by index
print(result[0].text)  # '# H1'

# Iterate over results
for value in result.values:
    print(value)

# Get all results as a single string
print(result.text)  # '# H1\n## H2\n### H3'

# Check if a value is in the result
print("# H1" in result.values)  # True

Each MQValue has the following properties:

  • text - The string representation of the value
  • values - For arrays, returns the list of values (otherwise a list containing the value itself)
  • markdown_type - The type of Markdown element (e.g., Heading, Code, List)
  • is_array() - Check if the value is an array
  • is_markdown() - Check if the value is a Markdown element

Error Handling

Invalid queries and inputs that cannot be parsed raise a RuntimeError:

import mq

try:
    result = mq.run(".invalid!!!", "# Heading")
except RuntimeError as e:
    print(f"Query error: {e}")

Development

Building from Source

git clone https://github.com/harehare/mq-python
cd mq-python
uv sync --dev
uv run maturin develop

Running Tests

uv run pytest tests/

Support

License

Licensed under the MIT License.

Metadata

Release files for markdown-query 0.9.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for markdown-query 0.9.4
File Interpreter ABI Platform Actions
markdown_query-0.9.4-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for markdown_query-0.9.4-cp39-abi3-win_amd64.whl
markdown_query-0.9.4-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.9 abi3 Linux glibc 2.17+ x86-64 Details for markdown_query-0.9.4-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
markdown_query-0.9.4-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for markdown_query-0.9.4-cp39-abi3-macosx_11_0_arm64.whl

Total release size: 11.9 MB

Release files / markdown_query-0.9.4-cp39-abi3-win_amd64.whl

Download URL markdown_query-0.9.4-cp39-abi3-win_amd64.whl
Size 3.8 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
4dba8b77ec1ecd0a05b7dfcdd580c390e61f514045e57087c23ecd090fd52460
BLAKE2b-256 checksum
How to use checksums
0bf891dc3188e8c8ff4fb2719aadb92d282eb76b1256abf36e4f8ae6449ed83b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / markdown_query-0.9.4-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL markdown_query-0.9.4-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 4.3 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
321906b2f9a866a82b81052c4148b8aeda13579fce2f974253cab08a2efd5b90
BLAKE2b-256 checksum
How to use checksums
edb6b3ceacee4a07c25af53dfccbe186d5e9a83ca6a7e56c2e52e010c48177a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / markdown_query-0.9.4-cp39-abi3-macosx_11_0_arm64.whl

Download URL markdown_query-0.9.4-cp39-abi3-macosx_11_0_arm64.whl
Size 3.8 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
c755250fd478b6d085ca6990ba8341ec3c98d87b2474dde2ba5322859e158bb4
BLAKE2b-256 checksum
How to use checksums
92c6b8b1fb6ed9ce6f0621bf88cb62f1110a7b06dab77d21ed63d7f7073219f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Security for markdown-query 0.9.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 3 files in this release have been uploaded with provenance metadata.

Select from 3 files

Attestation for markdown_query-0.9.4-cp39-abi3-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.9.4 This release

3 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page