| 1 |
Metadata-Version: 1.1 |
| 2 |
Name: zc.customdoctests |
| 3 |
Version: 1.0.1 |
| 4 |
Summary: ===================================================== |
| 5 |
Home-page: http://pypi.python.org/pypi/zc.customdoctests |
| 6 |
Author: Jim Fulton |
| 7 |
Author-email: [email protected] |
| 8 |
License: ZPL 2.1 |
| 9 |
Description: ===================================================== |
| 10 |
zc.customdoctests -- Use doctest with other languages |
| 11 |
===================================================== |
| 12 |
|
| 13 |
doctest (and recently manuel) provide hooks for using custom doctest |
| 14 |
parsers. `zc.customdoctests` helps to leverage this to support other |
| 15 |
languages, such as JavaScript:: |
| 16 |
|
| 17 |
js> function double (x) { |
| 18 |
... return x*2; |
| 19 |
... } |
| 20 |
js> double(2) |
| 21 |
4 |
| 22 |
|
| 23 |
And with `manuel <http://pypi.python.org/pypi/manuel>`_, it |
| 24 |
facilitates doctests that mix multiple languages, such as Python, |
| 25 |
JavaScript, and sh. |
| 26 |
|
| 27 |
.. contents:: |
| 28 |
|
| 29 |
|
| 30 |
Detailed documentation |
| 31 |
====================== |
| 32 |
|
| 33 |
Custom doctest parsers |
| 34 |
---------------------- |
| 35 |
|
| 36 |
zc.customdoctests provides a little bit of help with creating custom |
| 37 |
doctest parsers that work pretty muct like regular doctests, but that |
| 38 |
use an alternate means of evaluating examples. To use it, you call |
| 39 |
zc.customdoctests.DocTestParser and pass any of the following options: |
| 40 |
|
| 41 |
ps1 |
| 42 |
The first-line prompt, which defaultd to ``'>>>'``. |
| 43 |
|
| 44 |
This must be a regular expression that matches exactly 3 characters. |
| 45 |
|
| 46 |
(Note that you can't override the second-line prompt.) |
| 47 |
|
| 48 |
comment_prefix |
| 49 |
The comment prefix regular expression, which defaults to '#'. |
| 50 |
|
| 51 |
transform |
| 52 |
A function used to transform example source, which defaults to a |
| 53 |
no-operation function. |
| 54 |
|
| 55 |
The js module provides support for using JavaScript in doctests using |
| 56 |
`python-spidermonkey |
| 57 |
<http://pypi.python.org/pypi/python-spidermonkey>`_. It provides some |
| 58 |
examples of defining custom doctest parsers. |
| 59 |
|
| 60 |
|
| 61 |
Javascript and Python-Spidermonkey support |
| 62 |
------------------------------------------ |
| 63 |
|
| 64 |
.. This file shows some examples of using spidermonkey APIs in doctests. |
| 65 |
|
| 66 |
To wire this up, you'd use something like:: |
| 67 |
|
| 68 |
import doctest, zc.customdoctests.js |
| 69 |
|
| 70 |
test_suite = doctest.DocTestSuite( |
| 71 |
parser=zc.customdoctests.js.parser, |
| 72 |
setUp=zc.customdoctests.js.spidermonkeySetUp) |
| 73 |
|
| 74 |
Or, with manuel:: |
| 75 |
|
| 76 |
test_suite = manuel.testing.TestSuite( |
| 77 |
manuel.doctest.Manuel(parser=zc.customdoctests.js.parser) + |
| 78 |
manuel.doctest.Manuel(parser=zc.customdoctests.js.eq_parser) + |
| 79 |
manuel.doctest.Manuel() + |
| 80 |
manuel.capture.Manuel(), |
| 81 |
'spidermonkey.txt', |
| 82 |
setUp=zc.customdoctests.js.spidermonkeySetUp) |
| 83 |
|
| 84 |
Note that zc.customdoctests doesn't require spidermonkey, so you need |
| 85 |
to install spidermonkey seperately if you want to use it. |
| 86 |
|
| 87 |
An advantage of using manuel is that you can use multiple parsers in |
| 88 |
the same document. In the example, above, 2 javascript example |
| 89 |
syntaxes (described below) as well as the standard doctest syntax are |
| 90 |
supported. This document is run with manuel to allow all 3 syntaxes. |
| 91 |
|
| 92 |
For the rest of this document, we'll show examples of JavaScript |
| 93 |
doctests as well as helper APIs used to support JavaScript and to |
| 94 |
integrate JavaScript and Python. |
| 95 |
|
| 96 |
Javascript doctests use a "js>" prompt (as used in rhino and the |
| 97 |
spidermonkey interpreter):: |
| 98 |
|
| 99 |
js> 2 + |
| 100 |
... 'Hi world' // doctest: +ELLIPSIS |
| 101 |
u'2Hi... |
| 102 |
|
| 103 |
Assignments return values. This can generate annoying output |
| 104 |
in doctests:: |
| 105 |
|
| 106 |
js> ob = {a: 1, b: 2} |
| 107 |
[object Object] |
| 108 |
|
| 109 |
If you're using manuel, you can avoid this by using js!:: |
| 110 |
|
| 111 |
js! x = 3 |
| 112 |
|
| 113 |
which suppresses expression values. |
| 114 |
|
| 115 |
load and print functions (similar to those found in rhino) are |
| 116 |
provided. For example, given a javascript file, double.js:: |
| 117 |
|
| 118 |
function double (x) { |
| 119 |
return x*2; |
| 120 |
} |
| 121 |
|
| 122 |
.. -> src |
| 123 |
|
| 124 |
>>> with open('double.js', 'w') as f: |
| 125 |
... f.write(src) |
| 126 |
|
| 127 |
We can load the file:: |
| 128 |
|
| 129 |
js> load('double.js') |
| 130 |
js> double(10) |
| 131 |
20 |
| 132 |
|
| 133 |
We can print values:: |
| 134 |
|
| 135 |
js> print('Hi') |
| 136 |
Hi |
| 137 |
|
| 138 |
A python object provides access to the open function and the os |
| 139 |
module:: |
| 140 |
|
| 141 |
js> python.os.path.exists('double.js') |
| 142 |
True |
| 143 |
|
| 144 |
js! f = python.open('double.js') |
| 145 |
js> print(f.read()) |
| 146 |
function double (x) { |
| 147 |
return x*2; |
| 148 |
} |
| 149 |
<BLANKLINE> |
| 150 |
|
| 151 |
js> f.close() |
| 152 |
|
| 153 |
|
| 154 |
If you're using manuel, you can intermix Python and and JavaScript |
| 155 |
examples and there are a number of APIs to facilitate using Python and |
| 156 |
JavaScript together. |
| 157 |
|
| 158 |
There's an add_js_global function to copy data from Python:: |
| 159 |
|
| 160 |
>>> add_js_global('y', 1) |
| 161 |
|
| 162 |
js> y |
| 163 |
1 |
| 164 |
|
| 165 |
There's also a js object that provides attribute access to js globals:: |
| 166 |
|
| 167 |
>>> js.x |
| 168 |
3 |
| 169 |
|
| 170 |
>>> js.z = 4 |
| 171 |
|
| 172 |
js> z |
| 173 |
4 |
| 174 |
|
| 175 |
You can also call this to run JS code without returning the resulting value:: |
| 176 |
|
| 177 |
>>> js('a = x + y') |
| 178 |
|
| 179 |
js> a |
| 180 |
4 |
| 181 |
|
| 182 |
|
| 183 |
Changelog |
| 184 |
========= |
| 185 |
|
| 186 |
1.0.1 (2013-02-14) |
| 187 |
------------------ |
| 188 |
|
| 189 |
- Nothing changed yet. |
| 190 |
|
| 191 |
|
| 192 |
1.0.0 (2013-02-13) |
| 193 |
------------------ |
| 194 |
|
| 195 |
- Added Python 3.3 support. |
| 196 |
|
| 197 |
- Cleanup `setup.py`, add `tox.ini` and manifest. |
| 198 |
|
| 199 |
|
| 200 |
0.1.0 (2011-05-19) |
| 201 |
------------------ |
| 202 |
|
| 203 |
- Initial release |
| 204 |
|
| 205 |
Platform: UNKNOWN |
| 206 |
Classifier: Development Status :: 4 - Beta |
| 207 |
Classifier: Intended Audience :: Developers |
| 208 |
Classifier: License :: OSI Approved :: Zope Public License |
| 209 |
Classifier: Programming Language :: Python |
| 210 |
Classifier: Programming Language :: Python :: 2 |
| 211 |
Classifier: Programming Language :: Python :: 2.6 |
| 212 |
Classifier: Programming Language :: Python :: 2.7 |
| 213 |
Classifier: Programming Language :: Python :: 3 |
| 214 |
Classifier: Programming Language :: Python :: 3.3 |
| 215 |
Classifier: Programming Language :: Python :: Implementation :: CPython |
| 216 |
Classifier: Natural Language :: English |
| 217 |
Classifier: Operating System :: OS Independent |
| 218 |
Classifier: Topic :: Software Development |