Welcome, guest | Sign In | My Account | Store | Cart

Notice! PyPM is being replaced with the ActiveState Platform, which enhances PyPM’s build and deploy capabilities. Create your free Platform account to download ActivePython or customize Python with the packages you require and get automatic updates.

pypm install wordish

How to install wordish

  1. Download and install ActivePython
  2. Open Command Prompt
  3. Type pypm install wordish
 Python 2.7Python 3.2Python 3.3
Windows (32-bit)
1.0.2 Failed View build log
Windows (64-bit)
1.0.2 Failed View build log
Mac OS X (10.5+)
1.0.2 Available View build log
Linux (32-bit)
1.0.2 Available View build log
Linux (64-bit)
1.0.2 Available View build log
Lastest release
version 1.0.2 on Jan 5th, 2011

Wordish is a script which executes a shell session parsed from a documentation in the restructured text [1] format, then tests and builds a report of the execution. To mark up shell code in an article, wordish uses the custom directive sourcecode, with the rquired argument sh. When presented with an article:

#. wordish filters out the text which is not marked with sourcecode,

#. then, separates the blocks of shell codes between commands and outputs:

#. wordish consumes the prompt, parses for the newline which ends command,

  1. then parses for the prompt which ends the output,


.. sourcecode:: sh

~$ echo "hello world" # Mmmh, insightful comment hello world

This simply renders like:

~$ echo "hello world"   # Mmmh, insightful comment

System Message: ERROR/3 (<string>, line 30)

Inconsistent literal block quoting.

hello world

The command starts after the prompt ("~$ ") and continues until the first newline is found in the source code block. Here, it is just after the word comment. The command is echo "hello world" # Mmmh, insightful comment The output is the text block found until the next prompt: this is hello world. There are two possible prompts: ~$, and ~#. Both are required to be followed by a space are are treated the same.

Note: the newlines which are nested in curly brackets or parentheses are not interpreted as an end of command character. Shells do the same: curly brackets are used to define functions and parentheses makes the nested command to be interpreted in a subprocess shell. The two following examples from the introduction make it clear:

~$ (

System Message: ERROR/3 (<string>, line 49)

Inconsistent literal block quoting.

echo $((1+1)) ) 2

~$ sum () { echo $(( $1 + $2 )) }

The first command is echo $((1+1)) in a subproces, and it's output is 2. The second command is the definition of a function named sum and has no output. Defining functions sometimes clarify the intent in subsequent uses of the function. For functions to be re-used, the state of the shell must be kept between each snippets. wordish keep a connection with the same shell subprocess (bash is used) for the duration of the article.

~$ sum 42 58

System Message: ERROR/3 (<string>, line 67)

Inconsistent literal block quoting.


See how the output is obviously incorrect? we will see later how this is reported.

When the output can not be completely predicted, such as when displaying $RANDOM, or displaying the size of a partitions in bytes, there is a handy wildcard pattern which can be used: .... It matches everything like .* in regexp [2].

~$ echo "a random number: " $RANDOM

System Message: ERROR/3 (<string>, line 80)

Inconsistent literal block quoting.


One last thing, if a command does not exit gracefully, wordish precautiously aborts, refusing to execute commands on the system under test which is in an undefined state. wordish displays the remaining unexecuted commands.

~$ What have the Romans ever done for us

System Message: ERROR/3 (<string>, line 90)

Inconsistent literal block quoting.

aqueduct? roads? wine !

~$ echo "Bye bye" Bye bye

This introduction is embedded in the wordish module as the docstring. Just run wordish with no argument to get the example report of this article:

~$ python -m wordish

System Message: ERROR/3 (<string>, line 102)

Inconsistent literal block quoting.

Trying: echo "hello world" # Mmmh, insightful comment... Expecting: hello world ok

Trying: ( echo $((1+1)) ) Expecting: 2 ok

Trying: sum () { echo $(( $1 + $2 )) } Expecting: ok

Trying: sum 42 58 Expecting: 3 Failed, got: 100, 0

Trying: echo "a random number: " $RANDOM Expecting: ... ok

Trying: What have the Romans ever done for us Expecting: aqueduct? roads? wine ! Failed, got: /bin/bash: line 19: What: command not found, 127

Command aborted, bailing out Untested command: echo "Bye bye" python -m wordish 6 tests found. 4 tests passed, 2 tests failed.

There is another example real world article which is also included in the sources distribution, and tested before each release. This is the article which prompted the need for the development of wordish.

[1]This syntax can be seen as light and readable version of html

System Message: WARNING/2 (<string>, line 143)

Explicit markup ends without a blank line; unexpected unindent.

or latex, and was designed with the experience of existing Wiki syntaxes. The Sphinx project has a nice introduction on rst, the reference documentation is here.

[2]Regexp are not directly used so that the various special regexp

System Message: WARNING/2 (<string>, line 152)

Explicit markup ends without a blank line; unexpected unindent.

characters do not need to be escaped.

Subscribe to package updates

Last updated Jan 5th, 2011

Download Stats

Last month:1

What does the lock icon mean?

Builds marked with a lock icon are only available via PyPM to users with a current ActivePython Business Edition subscription.

Need custom builds or support?

ActivePython Enterprise Edition guarantees priority access to technical support, indemnification, expert consulting and quality-assured language builds.

Plan on re-distributing ActivePython?

Get re-distribution rights and eliminate legal risks with ActivePython OEM Edition.