---
id: braq
version: "0.0.12"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# braq — Structured text format with sections

License: permissive · Maintenance: dormant · Downloads: 125.5K/mo

## What it is and what it does

Braq is a lightweight text format and parser designed around the idea that structured data can be organized into human-readable sections, each with a header in square brackets and a body of plain text. The library provides functions to parse Braq documents into dictionaries (mapping headers to bodies) and to render Section objects back into formatted text. It supports embedding dictionary data structures via the Paradict format within sections, making it suitable for config files, code documentation, and AI prompt construction.

The format is deliberately simple: a document consists of an optional unnamed section at the top, followed by named sections. Multiple sections with the same header are concatenated. The library has no external runtime dependencies, making it quick to install and integrate. It targets developers who want a middle ground between plain text and rigid structured formats like JSON or YAML, particularly for use cases where readability and human editability matter as much as machine parsing.

Use it for:

- Parse configuration files that mix human-readable help text with embedded dictionary data structures.
- Extract and organize docstrings from Python functions using custom section-based documentation formats.
- Construct structured AI prompts that interleave instructions, user input, and conversation history in readable sections.
- Build custom document formats for domain-specific applications by extending Braq's section abstraction.
- Store and retrieve multi-section documents where sections may repeat and their bodies concatenate automatically.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Braq is a Python library for parsing and rendering section-based human-readable documents where content is organized under square-bracket headers with plain-text bodies.

Yes, if you need a lightweight, dependency-free way to parse or generate section-based text documents. The format is simple and the library is stable. However, the project is dormant with minimal community activity, so consider it for self-contained use cases rather than as a foundation for a larger ecosystem. Not suitable if you require active maintenance or frequent updates.

## Install

pip install braq
uv add braq
poetry add braq

## Installing braq

Before you install: Installation is straightforward with no runtime dependencies. The project is dormant (last commit 2024-12-10, no activity for 612 days) but remains available and functional for its stated purpose.

License in practice: MIT license is permissive, allowing use in commercial and private projects with minimal restrictions.

Quickstart:

pip install braq

import braq

text = """[section 1]
this is section 1"""
d = braq.parse(text)
print(d["section 1"])

Requires Python 3.5 or later.

Verify before relying:

- Whether the library handles edge cases in nested or deeply indented structures reliably.
- Performance characteristics with very large documents or many sections.
- Community adoption and real-world usage patterns beyond the documented examples.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 125.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

section-based document format parser, human-readable structured text, config file format library, document parsing with sections, text format with headers and bodies, lightweight data format, docstring and prompt formatting, text-format, config-parsing, documentation

[View on SkillFed](https://skillfed.io/packages/braq) · [View on PyPI](https://pypi.org/project/braq/)