Python CommonMark parser
Python
#86 Compare This branch is 187 commits ahead, 1 commit behind rolandshoemaker:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
CommonMark Update commonmark spec to 0.27 Jan 5, 2017
docs
.gitignore
.travis.yml
CHANGELOG.md
LICENSE
MANIFEST.in
README.rst
setup.cfg
setup.py
spec.txt

README.rst

CommonMark-py

Pure Python port of jgm's commonmark.js, a Markdown parser and renderer for the CommonMark specification, using only native modules. Once both this project and the CommonMark specification are stable we will release the first 1.0 version and attempt to keep up to date with changes in commonmark.js.

We are currently at the same development stage (actually a bit ahead because we have implemented HTML entity conversion and href URL escaping) as commonmark.js. Since Python versions pre-3.4 use outdated (i.e. not HTML5 spec) entity conversion, I've converted the 3.4 implementation into a single file, entitytrans.py which so far seems to work (all tests pass on 2.6, 2.7, 3.3, 3.4, and 3.5).

Current version: 0.7.3

Build Status Documentation Status

Installation

$ pip install commonmark

Usage

>>> import CommonMark
>>> CommonMark.commonmark('*hello!*')
'<p><em>hello!</em></p>\n'

Or, without the syntactic sugar:

import CommonMark
parser = CommonMark.Parser()
ast = parser.parse("Hello *World*")

renderer = CommonMark.HtmlRenderer()
html = renderer.render(ast)
print(html) # <p>Hello <em>World</em><p/>

# inspecting the abstract syntax tree
json = CommonMark.dumpJSON(ast)
CommonMark.dumpAST(ast) # pretty print generated AST structure

There is also a CLI:

$ cmark README.md -o README.html
$ cmark README.md -o README.json -aj # output AST as JSON
$ cmark README.md -a # pretty print generated AST structure
$ cmark -h
usage: cmark [-h] [-o [O]] [-a] [-aj] [infile]

Process Markdown according to the CommonMark specification.

positional arguments:
  infile      Input Markdown file to parse, defaults to stdin

optional arguments:
  -h, --help  show this help message and exit
  -o [O]      Output HTML/JSON file, defaults to stdout
  -a          Print formatted AST
  -aj         Output JSON AST

Contributing

If you would like to offer suggestions/optimizations/bugfixes through pull requests please do! Also if you find an error in the parser/renderer that isn't caught by the current test suite please open a new issue and I would also suggest you send the commonmark.js project a pull request adding your test to the existing test suite.

Tests

To work on CommonMark-py, you will need to be able to run the test suite to make sure your changes don't break anything. To run the tests, you can do something like this:

$ pyvenv venv
$ ./venv/bin/python setup.py develop test

The tests script, CommonMark/tests/run_spec_tests.py, is pretty much a devtool. As well as running all the tests embedded in spec.txt it also allows you to run specific tests using the -t argument, provide information about passed tests with -p, percentage passed by category of test with -s, and enter markdown interactively with -i (In interactive mode end a block by inputting a line with just end, to quit do the same but with quit). -d can be used to print call tracing.

$ python run_spec_tests.py -h
usage: run_spec_tests.py [-h] [-t T] [-p] [-f] [-i] [-d] [-np] [-s]

script to run the CommonMark specification tests against the CommonMark.py
parser

optional arguments:
  -h, --help  show this help message and exit
  -t T        Single test to run or comma separated list of tests (-t 10 or -t 10,11,12,13)
  -p          Print passed test information
  -f          Print failed tests (during -np...)
  -i          Interactive Markdown input mode
  -d          Debug, trace calls
  -np         Only print section header, tick, or cross
  -s          Print percent of tests passed by category

Authors