Braq is one of two spin-offs of Jesth (https://news.ycombinator.com/item?id=35991018) which is an unorthodox data format for which I struggled to design a library with a very simple programming interface.
Jesth was supposed to divide a text document into sections, each consisting of a header and a body. A subformat was available to formally represent structured data in a section. This subformat was optional, allowing for an eclectic set of sections within the same document.
I extracted and improved the subformat in a new spin-off project named Paradict (https://news.ycombinator.com/item?id=38684724).
Braq is the other spin-off project that focuses on Jesth's main idea: just section a document and let the programmer decide what to do with each section. So a section can be a JSON string, a prompt for a chatbot, ASCII art, a note, etc.
On top of the Braq data format, we could build something else, such as a docstring format which will be consumed by a documentation generator.
This is an example of a Python function with its docstring written in a format designed on top of Braq:
def sum(a, b):
"""
This function returns the sum of two integers
[params]
- a: integer
- b: integer
[return]
Sum of a and b
[errors]
- OverflowError: raised when either a or b is too big
- IntegerError: raised when a and b aren't integers
"""
pass
Note that the above docstring format exists and the documentation generator that consumes it is not public. This docstring format is visible in the source code of my projects (https://pyrustic.github.io).Braq is also used by Paradict for config files. This is what a config file in Paradict format might look like:
[user]
# no comment
id = 42
name = 'alex'
birthday = 2042-12-25T16:20:59Z
books = (dict)
romance = (list)
'Happy Place'
'Romantic Comedy'
sci_fi = (list)
'Dune'
'Neuromancer'
Braq is available on PyPI and you can learn more by reading its README or browsing the source code.Let me know what you think about all this !