Command line use

#> python [options] INFILE [OUTFILE]

Convert between (reStructured) text source with embedded code, and code source with embedded documentation (comment blocks)

The special file name ‘-’ stands for standard in and output.

Find more details in the tutorial.



show program’s version number and exit

-h, --help

show this help message and exit

-c, --code2txt

convert code source to text source

-t, --txt2code

convert text source to code source


use LANGUAGE native comment style


documentation block marker in code source (including trailing whitespace, default: language dependent)


syntax token starting a code block. (default ‘::’)


Number of spaces to indent code blocks with text2code (default 2)


overwrite output file (default ‘update’)


move infile to a backup copy (appending ‘~’)

-s, --strip

“export” by stripping documentation or code

-d, --diff

test for differences to existing file


run doctest.testfile() on the text version

-e, --execute

execute code (Python only)

Filename Extensions

By default .txt will be appended for literate code and stripped by the conversion to executable code. I.e. for a Python module foo:

  • the code source is called

  • the text source is called

  • the HTML rendering is called

Programmatic use

If is in the Python Module Path, it can be imported and used from other Python programs. The simplest example is the executable wrapper script pylit that can also be used for customisation:

#!/usr/bin/env python

# Load the pylit module::

import pylit

# Configure default settings, e.g. ::

## pylit.defaults.code_block_marker['c++'] = '.. code-block:: c++'
## pylit.defaults.languages['.def'] = 'latex'
## pylit.defaults.languages['.dfu'] = 'latex'

# call the text <--> code converter::


For more details see e.g. the helper functions in the literate source.


Customisation is possible by overwriting default values in a wrapper script like pylit, e.g.

#!/usr/bin/env python

import pylit

pylit.defaults.code_block_marker = '.. code-block:: python'
pylit.defaults.comment_string = "## "
pylit.defaults.codeindent = 4
defaults.text_extensions = [".rst"]


To overwrite the “intelligent guesses” by PylitOptions and command line options, pass the option as argument to pylit.main(), e.g.:

#!/usr/bin/env python

import pylit
pylit.main(comment_string = "## ")