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.10.1

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.10.1
File Interpreter ABI Platform Actions
markdown_query-0.10.1-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for markdown_query-0.10.1-cp39-abi3-win_amd64.whl
markdown_query-0.10.1-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.10.1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
markdown_query-0.10.1-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for markdown_query-0.10.1-cp39-abi3-macosx_11_0_arm64.whl

Total release size: 12.1 MB

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

Download URL markdown_query-0.10.1-cp39-abi3-win_amd64.whl
Size 3.9 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
0d80edbbd38899f2376541052927f5750f6a85bcb24306b4ef4a584d8e374700
BLAKE2b-256 checksum
How to use checksums
d97bd0586fe1606be79dc9ae25ac363fc716163b62f713e618ef0248ac35ac8a
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 Nov 7, 2026.

Transparency log

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

Download URL markdown_query-0.10.1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 4.4 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
37529a6387c9e45a49ec8827a08c1b8baaa0982cacee476e7f7c4f61cc29d8a8
BLAKE2b-256 checksum
How to use checksums
6ef6e3403098efbb5615d7a01cfb29e803ac3df5f295aebcad4ba1ce55c6bbb2
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 Nov 7, 2026.

Transparency log

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

Download URL markdown_query-0.10.1-cp39-abi3-macosx_11_0_arm64.whl
Size 3.9 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
4189911881dffdea286a4d72aed19f1944622693098557b759686bea806cbe24
BLAKE2b-256 checksum
How to use checksums
5e64e80af11030e94d9a92857bc65f13c4a3276a4f93311ff5a7bc0ddd17f74c
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 Nov 7, 2026.

Transparency log

Security for markdown-query 0.10.1

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.10.1-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 Nov 7, 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.10.1 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