You can also use pydoc to start an HTTP server on the local machine that will serve
documentation to visiting Web browsers. pydoc -p 1234 will start a HTTP server on port
1234, allowing you to browse the documentation at 
http://localhost:1234/
in your
preferred Web browser. pydoc -g will start the server and additionally bring up a small
Tkinter
-based graphical interface to help you search for documentation pages.
When pydoc generates documentation, it uses the current environment and path to
locate  modules. Thus,  invoking pydoc spam documents precisely the version of the
module you would get if you started the Python interpreter and typed 
import spam
.
Module docs for core modules are assumed to reside in http://docs.python.org/library/.
This can be overridden by setting the 
PYTHONDOCS
environment variable to a different URL
or to a local directory containing the Library Reference Manual pages.
index
modules |
next |
previous |
Python » Python v2.7.6 documentation » The Python Standard Library » 25. Development
Tools »
© Copyright
1990-2013, Python Software Foundation. 
The Python Software Foundation is a non-profit corporation. Please donate.
Last updated on Nov 10, 2013. Found a bug
Created using Sphinx
1.0.7.
Pdf secure signature - C# PDF Digital Signature Library: add, remove, update PDF digital signatures in C#.net, ASP.NET, MVC, WPF
Help to Improve the Security of Your PDF File by Adding Digital Signatures
decrypt a pdf file online; decrypt pdf password
Pdf secure signature - VB.NET PDF Digital Signature Library: add, remove, update PDF digital signatures in vb.net, ASP.NET, MVC, WPF
Guide VB.NET Programmers to Improve the Security of Your PDF File by Adding Digital Signatures
add security to pdf file; pdf secure signature
index
modules |
next |
previous |
25.2. 
doctest
— Test interactive Python
examples
The 
doctest
module searches for pieces of text that look like interactive Python sessions,
and then executes those sessions to verify that they work exactly as shown. There are
several common ways to use doctest:
To check that a module’s docstrings are up-to-date by verifying that all interactive
examples still work as documented.
To perform regression testing by verifying that interactive examples from a test file or
a test object work as expected.
To write tutorial documentation for a package, liberally illustrated with input-output
examples. Depending  on  whether  the  examples  or  the  expository  text  are
emphasized, this has the flavor of “literate testing” or “executable documentation”.
Here’s a complete but small example module:
Python » Python v2.7.6 documentation » The Python Standard Library » 25. Development
Tools »
XDoc.HTML5 Viewer for .NET, All Mature Features Introductions
to search text-based documents, like PDF, Microsoft Office typing new signature, deleting added signature from the text selecting in order to secure your web
pdf security settings; pdf password unlock
C# Create PDF Library SDK to convert PDF from other file formats
for C# developers to create a highly-secure and industry What's more, you can also protect created PDF file by adding digital signature (watermark) on PDF
decrypt pdf file online; decrypt pdf online
"""
This is the "example" module.
The example module supplies one function, factorial().  For example,
>>> factorial(5)
120
"""
def factorial(n):
"""Return the factorial of n, an exact integer >= 0.
If the result is small enough to fit in an int, return an int.
Else return a long.
>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
>>> [factorial(long(n)) for n in range(6)]
[1, 1, 2, 6, 24, 120]
>>> factorial(30)
265252859812191058636308480000000L
>>> factorial(30L)
265252859812191058636308480000000L
>>> factorial(-1)
Traceback (most recent call last):
...
ValueError: n must be >= 0
Factorials of floats are OK, but the float must be an exact integer:
>>> factorial(30.1)
Traceback (most recent call last):
...
ValueError: n must be exact integer
>>> factorial(30.0)
265252859812191058636308480000000L
It must also not be ridiculously large:
>>> factorial(1e100)
Traceback (most recent call last):
...
OverflowError: n too large
"""
import math
if not n >= 0:
raise ValueError("n must be >= 0")
if math.floor(n) != n:
raise ValueError("n must be exact integer")
if n+1 == n: # catch a value like 1e300
raise OverflowError("n too large")
result = 1
factor = 2
while factor <= n:
result *= factor
factor += 1
return result
if __name__ == "__main__":
import doctest
doctest.testmod()
If you run 
example.py
directly from the command line, 
doctest
works its magic:
DocImage SDK for .NET: HTML Viewer, View, Annotate, Convert, Print
from popular documents & images in .NET, including Microsoft Word, Excel, PPT, PDF, Tiff, Dicom type(s). Later, you can make an order in our secure online store
decrypt pdf with password; pdf file security
WinForms .NET Imaging SDK | Royalty-free Image SDK
Support common image and document file format, including BMP, Gif, PNG, PDF, JPEG 2000 our License Agreement and choose a suitable one in our secure online store
change security settings on pdf; change pdf security settings reader
$ python example.py
$
There’s no output! That’s normal, and it means all the examples worked. Pass 
-v
to the
script, and 
doctest
prints a detailed log of what it’s trying, and prints a summary at the
end:
$ python example.py -v
Trying:
factorial(5)
Expecting:
120
ok
Trying:
[factorial(n) for n in range(6)]
Expecting:
[1, 1, 2, 6, 24, 120]
ok
Trying:
[factorial(long(n)) for n in range(6)]
Expecting:
[1, 1, 2, 6, 24, 120]
ok
And so on, eventually ending with:
Trying:
factorial(1e100)
Expecting:
Traceback (most recent call last):
...
OverflowError: n too large
ok
2 items passed all tests:
1 tests in __main__
8 tests in __main__.factorial
9 tests in 2 items.
9 passed and 0 failed.
Test passed.
$
That’s all you need to know to start making productive use of 
doctest
! Jump in. The
following sections provide full details. Note that there are many examples of doctests in
the standard Python test suite and libraries. Especially useful examples can be found in
the standard test file 
Lib/test/test_doctest.py
.
25.2.1. Simple Usage: Checking Examples in Docstrings
The simplest way to start using doctest (but not necessarily the way you’ll continue to do
Java Imaging SDK Library: Document Image Scan, Process, PDF
View, edit, re-order, clean-up and convert documents/image from PDF, Tiff, Png Read our license Agreement and choose a suitable one in our secure online store!
copy text from locked pdf; pdf security remover
.NET DICOM SDK | DICOM Image Viewing
Developed based on the latest DICOM specification, RasterEdge DICOM codec provides complete DICOM Data Sets, secure communication and more.
decrypt pdf file; change security settings pdf
it) is to end each module 
M
with:
if __name__ == "__main__":
import doctest
doctest.testmod()
doctest
then examines docstrings in module 
M
.
Running the module as a script causes the examples in the docstrings to get executed
and verified:
python M.py
This won’t display anything unless an example fails, in which case the failing example(s)
and the cause(s) of the failure(s) are printed to stdout, and the final line of output is
***Test Failed*** N failures.
, where N is the number of examples that failed.
Run it with the 
-v
switch instead:
python M.py -v
and a detailed report of all examples tried is printed to standard output, along with
assorted summaries at the end.
You can force verbose mode by passing 
verbose=True
to 
testmod()
, or prohibit it by
passing 
verbose=False
. In either of those cases, 
sys.argv
is not examined by 
testmod()
(so passing 
-v
or not has no effect).
Since Python 2.6, there is also a command line shortcut for running 
testmod()
. You can
instruct the Python interpreter to run the doctest module directly from the standard library
and pass the module name(s) on the command line:
python -m doctest -v example.py
This will import 
example.py
as a standalone module and run 
testmod()
on it. Note that
this may not work correctly if the file is part of a package and imports other submodules
from that package.
For more information on 
testmod()
, see section Basic API.
25.2.2. Simple Usage: Checking Examples in a Text File
Another simple application of doctest is testing interactive examples in a text file. This can
PDF Image Viewer| What is PDF
information; Royalty-free to develop PDF compatible software; Open standard for more secure, dependable electronic information exchange.
pdf encryption; change pdf security settings
DICOM Image Viewer| What is DICOM
SDK and Web Document Viewer provide high-quality, full-featured and secure medical image into other file formats, including Bitmap, Png, Gif, Tiff, PDF, MS-Word
convert secure pdf to word; create pdf the security level is set to high
be done with the 
testfile()
function:
import doctest
doctest.testfile("example.txt")
That short script executes and verifies any interactive Python examples contained in the
file 
example.txt
. The file content is treated as if it were a single giant docstring; the file
doesn’t need to contain a Python program! For example, perhaps 
example.txt
contains
this:
The ``example`` module
======================
Using ``factorial``
-------------------
This is an example text file in reStructuredText format.  First import
``factorial`` from the ``example`` module:
>>> from example import factorial
Now use it:
>>> factorial(6)
120
Running 
doctest.testfile("example.txt")
then finds the error in this documentation:
File "./example.txt", line 14, in example.txt
Failed example:
factorial(6)
Expected:
120
Got:
720
As  with 
testmod()
testfile()
won’t display anything unless an example fails. If an
example does fail, then the failing example(s) and the cause(s) of the failure(s) are
printed to stdout, using the same format as 
testmod()
.
By default, 
testfile()
looks for files in the calling module’s directory. See section Basic
API for a description of the optional arguments that can be used to tell it to look for files in
other locations.
Like 
testmod()
testfile()
‘s verbosity can be set with the 
-v
command-line switch or
with the optional keyword argument verbose.
Since Python 2.6, there is also a command line shortcut for running 
testfile()
. You can
instruct the Python interpreter to run the doctest module directly from the standard library
and pass the file name(s) on the command line:
python -m doctest -v example.txt
Because the file name does not end with 
.py
doctest
infers that it must be run with
testfile()
, not 
testmod()
.
For more information on 
testfile()
, see section Basic API.
25.2.3. How It Works
This section examines in detail how doctest works: which docstrings it looks at, how it
finds interactive examples, what execution context it uses, how it handles exceptions, and
how option flags can be used to control its behavior. This is the information that you need
to know to write doctest examples; for information about actually running doctest on
these examples, see the following sections.
25.2.3.1. Which Docstrings Are Examined?
The module docstring, and all function, class and method docstrings are searched.
Objects imported into the module are not searched.
In addition, if 
M.__test__
exists and “is true”, it must be a dict, and each entry maps a
(string) name to a function object, class object, or string. Function and class object
docstrings found from 
M.__test__
are searched, and strings are treated as if they were
docstrings. In output, a key 
K
in 
M.__test__
appears with name
<name of M>.__test__.K
Any classes found are recursively searched similarly, to test docstrings in their contained
methods and nested classes.
Changed  in  version  2.4: A  “private name”  concept  is  deprecated  and no longer
documented.
25.2.3.2. How are Docstring Examples Recognized?
In most cases a copy-and-paste of an interactive console session works fine, but doctest
isn’t trying to do an exact emulation of any specific Python shell.
>>> # comments are ignored
>>> = 12
>>> x
12
>>> if x == 13:
...  print "yes"
... else:
...  print "no"
...  print "NO"
...  print "NO!!!"
...
no
NO
NO!!!
>>>
Any expected output must immediately follow the final 
'>>> '
or 
'... '
line containing
the code, and the expected output (if any) extends to the next 
'>>> '
or all-whitespace
line.
The fine print:
Expected output cannot contain an all-whitespace line, since such a line is taken to
signal the end of expected output. If expected output does contain a blank line, put
<BLANKLINE>
in your doctest example each place a blank line is expected.
New in version 2.4: 
<BLANKLINE>
was added; there was no way to use expected
output containing empty lines in previous versions.
All hard tab characters are expanded to spaces, using 8-column tab stops. Tabs in
output generated by the tested code are not modified. Because any hard tabs in the
sample output are expanded, this means that if the code output includes hard tabs,
the only way the doctest can pass is if the 
NORMALIZE_WHITESPACE
option or directive
is in effect. Alternatively, the test can be rewritten to capture the output and compare
it to an expected value as part of the test. This handling of tabs in the source was
arrived at through trial and error, and has proven to be the least error prone way of
handling them. It is possible to use a different algorithm for handling tabs by writing a
custom 
DocTestParser
class.
Changed in version 2.4: Expanding tabs to spaces is new; previous versions tried to
preserve hard tabs, with confusing results.
Output to stdout is captured, but not output to stderr (exception tracebacks are
captured via a different means).
If you continue a line via backslashing in an interactive session, or for any other
reason use a backslash, you should use a raw docstring, which will preserve your
backslashes exactly as you type them:
>>> def f(x):
...  r'''Backslashes in a raw docstring: m\n'''
>>> print f.__doc__
Backslashes in a raw docstring: m\n
Otherwise, the backslash will be interpreted as part of the string. For example, the
\n
above would be interpreted as a newline character. Alternatively, you can double
each backslash in the doctest version (and not use a raw string):
>>> def f(x):
...  '''Backslashes in a raw docstring: m\\n'''
>>> print f.__doc__
Backslashes in a raw docstring: m\n
The starting column doesn’t matter:
>>> assert "Easy!"
>>> import math
>>> math.floor(1.9)
1.0
and as many leading whitespace characters are stripped from the expected output
as appeared in the initial 
'>>> '
line that started the example.
25.2.3.3. What’s the Execution Context?
By default, each time 
doctest
finds a docstring to test, it uses a shallow copy of 
M
‘s
globals, so that running tests doesn’t change the module’s real globals, and so that one
test in 
M
can’t leave behind crumbs that accidentally allow another test to work. This
means examples can freely use any names defined at top-level in 
M
, and names defined
earlier in the  docstring  being run.  Examples  cannot  see  names defined  in  other
docstrings.
You can force use of your own dict as the execution context by passing 
globs=your_dict
to 
testmod()
or 
testfile()
instead.
25.2.3.4. What About Exceptions?
No problem, provided that the traceback is the only output produced by the example: just
paste in the traceback. [1] Since tracebacks contain details that are likely to change
rapidly (for example, exact file paths and line numbers), this is one case where doctest
works hard to be flexible in what it accepts.
Simple example:
>>> [123].remove(42)
Traceback (most recent call last):
File "<stdin>", line 1, in ?
ValueError: list.remove(x): x not in list
That doctest succeeds if 
ValueError
is raised, with the 
list.remove(x): x not in list
detail as shown.
The expected output for an exception must start with a traceback header, which may be
either of the following two lines, indented the same as the first line of the example:
Traceback (most recent call last):
Traceback (innermost last):
The traceback header is followed by an optional traceback stack, whose contents are
ignored by doctest. The traceback stack is typically omitted, or copied verbatim from an
interactive session.
The traceback stack is followed by the most interesting part: the line(s) containing the
exception type and detail. This is usually the last line of a traceback, but can extend
across multiple lines if the exception has a multi-line detail:
>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
File "<stdin>", line 1, in ?
ValueError: multi
line
detail
The last three lines (starting with 
ValueError
) are compared against the exception’s type
and detail, and the rest are ignored.
Changed in version 2.4: Previous versions were unable to handle multi-line exception
details.
Best practice is to omit the traceback stack, unless it adds significant documentation
value to the example. So the last example is probably better as:
Documents you may be interested
Documents you may be interested