path: root/plac/doc/plac_adv.pdf

%PDF-1.3
%“Œ‹ž ReportLab Generated PDF document http://www.reportlab.com
% 'BasicFonts': class PDFDictionary 
1 0 obj
% The standard fonts dictionary
<< /F1 2 0 R
 /F2 3 0 R
 /F3 7 0 R
 /F4 13 0 R >>
endobj
% 'F1': class PDFType1Font 
2 0 obj
% Font Helvetica
<< /BaseFont /Helvetica
 /Encoding /WinAnsiEncoding
 /Name /F1
 /Subtype /Type1
 /Type /Font >>
endobj
% 'F2': class PDFType1Font 
3 0 obj
% Font Helvetica-Bold
<< /BaseFont /Helvetica-Bold
 /Encoding /WinAnsiEncoding
 /Name /F2
 /Subtype /Type1
 /Type /Font >>
endobj
% 'Annot.NUMBER1': class PDFDictionary 
4 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://pypi.python.org/pypi/plac) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 62.69291
 693.5936
 84.3779
 705.5936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Annot.NUMBER2': class PDFDictionary 
5 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://pypi.python.org/pypi/plac) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 93.0279
 669.5936
 115.0329
 681.5936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Annot.NUMBER3': class PDFDictionary 
6 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://pypi.python.org/pypi/plac) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 62.69291
 633.5936
 83.81291
 645.5936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'F3': class PDFType1Font 
7 0 obj
% Font Courier
<< /BaseFont /Courier
 /Encoding /WinAnsiEncoding
 /Name /F3
 /Subtype /Type1
 /Type /Font >>
endobj
% 'Page1': class PDFPage 
8 0 obj
% Page dictionary
<< /Annots [ 4 0 R
 5 0 R
 6 0 R ]
 /Contents 40 0 R
 /MediaBox [ 0
 0
 595.2756
 841.8898 ]
 /Parent 39 0 R
 /Resources << /Font 1 0 R
 /ProcSet [ /PDF
 /Text
 /ImageB
 /ImageC
 /ImageI ] >>
 /Rotate 0
 /Trans <<  >>
 /Type /Page >>
endobj
% 'Page2': class PDFPage 
9 0 obj
% Page dictionary
<< /Contents 41 0 R
 /MediaBox [ 0
 0
 595.2756
 841.8898 ]
 /Parent 39 0 R
 /Resources << /Font 1 0 R
 /ProcSet [ /PDF
 /Text
 /ImageB
 /ImageC
 /ImageI ] >>
 /Rotate 0
 /Trans <<  >>
 /Type /Page >>
endobj
% 'Page3': class PDFPage 
10 0 obj
% Page dictionary
<< /Contents 42 0 R
 /MediaBox [ 0
 0
 595.2756
 841.8898 ]
 /Parent 39 0 R
 /Resources << /Font 1 0 R
 /ProcSet [ /PDF
 /Text
 /ImageB
 /ImageC
 /ImageI ] >>
 /Rotate 0
 /Trans <<  >>
 /Type /Page >>
endobj
% 'Annot.NUMBER4': class PDFDictionary 
11 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://pypi.python.org/pypi/plac) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 117.8279
 729.5936
 139.5429
 741.5936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Annot.NUMBER5': class PDFDictionary 
12 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://pypi.python.org/pypi/plac) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 503.6477
 729.5936
 525.3627
 741.5936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'F4': class PDFType1Font 
13 0 obj
% Font Helvetica-Oblique
<< /BaseFont /Helvetica-Oblique
 /Encoding /WinAnsiEncoding
 /Name /F4
 /Subtype /Type1
 /Type /Font >>
endobj
% 'Page4': class PDFPage 
14 0 obj
% Page dictionary
<< /Annots [ 11 0 R
 12 0 R ]
 /Contents 43 0 R
 /MediaBox [ 0
 0
 595.2756
 841.8898 ]
 /Parent 39 0 R
 /Resources << /Font 1 0 R
 /ProcSet [ /PDF
 /Text
 /ImageB
 /ImageC
 /ImageI ] >>
 /Rotate 0
 /Trans <<  >>
 /Type /Page >>
endobj
% 'Page5': class PDFPage 
15 0 obj
% Page dictionary
<< /Contents 44 0 R
 /MediaBox [ 0
 0
 595.2756
 841.8898 ]
 /Parent 39 0 R
 /Resources << /Font 1 0 R
 /ProcSet [ /PDF
 /Text
 /ImageB
 /ImageC
 /ImageI ] >>
 /Rotate 0
 /Trans <<  >>
 /Type /Page >>
endobj
% 'Annot.NUMBER6': class PDFDictionary 
16 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://pypi.python.org/pypi/plac) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 62.69291
 119.9936
 83.9079
 131.9936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Annot.NUMBER7': class PDFDictionary 
17 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://argparse.googlecode.com) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 133.1029
 119.9936
 175.4379
 131.9936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Annot.NUMBER8': class PDFDictionary 
18 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://argparse.googlecode.com) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 454.1177
 119.9936
 496.4527
 131.9936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Page6': class PDFPage 
19 0 obj
% Page dictionary
<< /Annots [ 16 0 R
 17 0 R
 18 0 R ]
 /Contents 45 0 R
 /MediaBox [ 0
 0
 595.2756
 841.8898 ]
 /Parent 39 0 R
 /Resources << /Font 1 0 R
 /ProcSet [ /PDF
 /Text
 /ImageB
 /ImageC
 /ImageI ] >>
 /Rotate 0
 /Trans <<  >>
 /Type /Page >>
endobj
% 'Annot.NUMBER9': class PDFDictionary 
20 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://argparse.googlecode.com/svn/tags/r11/doc/other-utilities.html?highlight=filetype#FileType) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 455.2227
 744.5936
 534.3667
 756.5936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Annot.NUMBER10': class PDFDictionary 
21 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://pypi.python.org/pypi/plac) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 127.99
 577.3936
 149.3857
 589.3936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Annot.NUMBER11': class PDFDictionary 
22 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://argparse.googlecode.com) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 166.3664
 476.1936
 209.1976
 488.1936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Annot.NUMBER12': class PDFDictionary 
23 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://argparse.googlecode.com) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 307.9178
 176.9936
 351.5999
 188.9936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Annot.NUMBER13': class PDFDictionary 
24 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://pypi.python.org/pypi/plac) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 317.2329
 152.9936
 338.3529
 164.9936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Annot.NUMBER14': class PDFDictionary 
25 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://argparse.googlecode.com/svn/tags/r11/doc/ArgumentParser.html) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 327.2261
 134.9936
 410.5152
 146.9936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Page7': class PDFPage 
26 0 obj
% Page dictionary
<< /Annots [ 20 0 R
 21 0 R
 22 0 R
 23 0 R
 24 0 R
 25 0 R ]
 /Contents 46 0 R
 /MediaBox [ 0
 0
 595.2756
 841.8898 ]
 /Parent 39 0 R
 /Resources << /Font 1 0 R
 /ProcSet [ /PDF
 /Text
 /ImageB
 /ImageC
 /ImageI ] >>
 /Rotate 0
 /Trans <<  >>
 /Type /Page >>
endobj
% 'Annot.NUMBER15': class PDFDictionary 
27 0 obj
<< /A << /S /URI
 /Type /Action
 /URI (http://pypi.python.org/pypi/plac) >>
 /Border [ 0
 0
 0 ]
 /Rect [ 106.6216
 576.3936
 128.3202
 588.3936 ]
 /Subtype /Link
 /Type /Annot >>
endobj
% 'Page8': class PDFPage 
28 0 obj
% Page dictionary
<< /Annots [ 27 0 R ]
 /Contents 47 0 R
 /MediaBox [ 0
 0
 595.2756
 841.8898 ]
 /Parent 39 0 R
 /Resources << /Font 1 0 R
 /ProcSet [ /PDF
 /Text
 /ImageB
 /ImageC
 /ImageI ] >>
 /Rotate 0
 /Trans <<  >>
 /Type /Page >>
endobj
% 'Page9': class PDFPage 
29 0 obj
% Page dictionary
<< /Contents 48 0 R
 /MediaBox [ 0
 0
 595.2756
 841.8898 ]
 /Parent 39 0 R
 /Resources << /Font 1 0 R
 /ProcSet [ /PDF
 /Text
 /ImageB
 /ImageC
 /ImageI ] >>
 /Rotate 0
 /Trans <<  >>
 /Type /Page >>
endobj
% 'R30': class PDFCatalog 
30 0 obj
% Document Root
<< /Outlines 32 0 R
 /PageLabels 49 0 R
 /PageMode /UseNone
 /Pages 39 0 R
 /Type /Catalog >>
endobj
% 'R31': class PDFInfo 
31 0 obj
<< /Author ()
 /CreationDate (D:20100611140831-01'00')
 /Keywords ()
 /Producer (ReportLab http://www.reportlab.com)
 /Subject (\(unspecified\))
 /Title (Testing and scripting your applications with plac) >>
endobj
% 'R32': class PDFOutlines 
32 0 obj
<< /Count 6
 /First 33 0 R
 /Last 38 0 R
 /Type /Outlines >>
endobj
% 'Outline.0': class OutlineEntryObject 
33 0 obj
<< /Dest [ 8 0 R
 /XYZ
 62.69291
 729.0236
 0 ]
 /Next 34 0 R
 /Parent 32 0 R
 /Title (Introduction) >>
endobj
% 'Outline.1': class OutlineEntryObject 
34 0 obj
<< /Dest [ 8 0 R
 /XYZ
 62.69291
 618.0236
 0 ]
 /Next 35 0 R
 /Parent 32 0 R
 /Prev 33 0 R
 /Title (Testing applications with plac) >>
endobj
% 'Outline.2': class OutlineEntryObject 
35 0 obj
<< /Dest [ 9 0 R
 /XYZ
 62.69291
 390.6236
 0 ]
 /Next 36 0 R
 /Parent 32 0 R
 /Prev 34 0 R
 /Title (Writing command-line interpreters with plac) >>
endobj
% 'Outline.3': class OutlineEntryObject 
36 0 obj
<< /Dest [ 14 0 R
 /XYZ
 62.69291
 765.0236
 0 ]
 /Next 37 0 R
 /Parent 32 0 R
 /Prev 35 0 R
 /Title (Multi-parsers) >>
endobj
% 'Outline.4': class OutlineEntryObject 
37 0 obj
<< /Dest [ 19 0 R
 /XYZ
 62.69291
 155.4236
 0 ]
 /Next 38 0 R
 /Parent 32 0 R
 /Prev 36 0 R
 /Title (Advanced usage) >>
endobj
% 'Outline.5': class OutlineEntryObject 
38 0 obj
<< /Dest [ 28 0 R
 /XYZ
 62.69291
 611.8236
 0 ]
 /Parent 32 0 R
 /Prev 37 0 R
 /Title (Custom annotation objects) >>
endobj
% 'R39': class PDFPages 
39 0 obj
% page tree
<< /Count 9
 /Kids [ 8 0 R
 9 0 R
 10 0 R
 14 0 R
 15 0 R
 19 0 R
 26 0 R
 28 0 R
 29 0 R ]
 /Type /Pages >>
endobj
% 'R40': class PDFStream 
40 0 obj
% page stream
<< /Length 3854 >>
stream
1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
q
1 0 0 1 62.69291 741.0236 cm
q
BT 1 0 0 1 0 9.64 Tm 2.664882 0 Td 24 TL /F2 20 Tf 0 0 0 rg (Testing and scripting your applications with plac) Tj T* -2.664882 0 Td ET
Q
Q
q
1 0 0 1 62.69291 708.0236 cm
q
BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Introduction) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 630.0236 cm
q
BT 1 0 0 1 0 64.82 Tm .564989 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (has been designed to be simple to use for simple stuff, but in truth it is a quite advanced tool with a) Tj T* 0 Tw 1.986905 Tw (field of applicability which far outreaches the specific domain of command-line arguments parsers. In) Tj T* 0 Tw .884985 Tw (reality ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is a generic tool to write domain specific languages \(DSL\). This document explains how you) Tj T* 0 Tw 1.766303 Tw (can use plac to test your application, and how you can use it to provide a scripting interface to your) Tj T* 0 Tw 1.384651 Tw (application. Notice that your application does not need to be a command-line application: you can use) Tj T* 0 Tw 0 0 .501961 rg (plac ) Tj 0 0 0 rg (whenever you have an API with strings in input and strings in output.) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 597.0236 cm
q
BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Testing applications with plac) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 531.0236 cm
q
BT 1 0 0 1 0 52.82 Tm .352209 Tw 12 TL /F1 10 Tf 0 0 0 rg (In the standard usage, ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (is called only once on the main function; however in the tests it quite) Tj T* 0 Tw .297126 Tw (natural to invoke ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (multiple times on the same function with different arguments. For instance,) Tj T* 0 Tw .436457 Tw (suppose you want to store the configuration of your application into a Python shelve; then, you may want) Tj T* 0 Tw .683318 Tw (to write a command-line tool to edit your configuration, i.e. a shelve interface. A possible implementation) Tj T* 0 Tw (could be the following:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 89.82362 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 432 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 413.71 Tm /F3 10 Tf 12 TL (import shelve) Tj T* (import plac) Tj T*  T* (@plac.annotations\() Tj T* (    help=\('show help', 'flag'\),) Tj T* (    all=\('show all parameters in the shelve', 'flag'\),) Tj T* (    clear=\('clear the shelve', 'flag'\),) Tj T* (    delete=\('delete an element', 'option'\),) Tj T* (    filename=\('filename of the shelve', 'option'\),) Tj T* (    params='names of the parameters in the shelve',) Tj T* (    setters='setters param=value'\)) Tj T* (def ishelve\(help, all, clear, delete, filename='conf.shelve',) Tj T* (            *params, **setters\):) Tj T* (    sh = shelve.open\(filename\)) Tj T* (    try:) Tj T* (        if help:) Tj T* (            yield 'Special commands:') Tj T* (            yield 'help, all, clear, delete') Tj T* (        elif all:) Tj T* (            for param, name in sh.items\(\):) Tj T* (                yield '%s=%s' % \(param, name\)) Tj T* (        elif clear:) Tj T* (            sh.clear\(\)) Tj T* (            yield 'cleared the shelve') Tj T* (        elif delete:) Tj T* (            try:) Tj T* (                del sh[delete]) Tj T* (            except KeyError:) Tj T* (                yield '%s: not found' % delete) Tj T* (            else:) Tj T* (                yield 'deleted %s' % delete) Tj T* (        for param in params:) Tj T* (            try:) Tj T* (                yield sh[param]) Tj T* (            except KeyError:) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 56.69291 56.69291 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (1) Tj T* -238.1649 0 Td ET
Q
Q
 
endstream

endobj
% 'R41': class PDFStream 
41 0 obj
% page stream
<< /Length 3706 >>
stream
1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
q
1 0 0 1 62.69291 607.8236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 156 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 137.71 Tm /F3 10 Tf 12 TL (                yield '%s: not found' % param           ) Tj T* (        for param, value in setters.items\(\):) Tj T* (            sh[param] = value) Tj T* (            yield 'setting %s=%s' % \(param, value\)) Tj T* (    finally:) Tj T* (        sh.close\(\)) Tj T*  T* (ishelve.add_help = False # there is a custom help) Tj T*  T* (if __name__ == '__main__':) Tj T* (    for output in plac.call\(ishelve\):) Tj T* (        print\(output\)) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 587.8236 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (You can write the tests for such implementation as follows:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 446.6236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 132 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 113.71 Tm /F3 10 Tf 12 TL (import plac) Tj T* (from ishelve import ishelve) Tj T*  T* (def test\(\):) Tj T* (    assert plac.call\(ishelve, []\) == []) Tj T* (    assert plac.call\(ishelve, ['--clear']\) == ['cleared the shelve']) Tj T* (    assert plac.call\(ishelve, ['a=1']\) == ['setting a=1']) Tj T* (    assert plac.call\(ishelve, ['a']\) == ['1']) Tj T* (    assert plac.call\(ishelve, ['--delete=a']\) == ['deleted a']) Tj T* (    assert plac.call\(ishelve, ['a']\) == ['a: not found']) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 402.6236 cm
q
BT 1 0 0 1 0 28.82 Tm .344651 Tw 12 TL /F1 10 Tf 0 0 0 rg (There is a small optimization here: once ) Tj /F3 10 Tf (plac.call\(func\) ) Tj /F1 10 Tf (has been called, a ) Tj /F3 10 Tf (.p ) Tj /F1 10 Tf (attribute is attached) Tj T* 0 Tw 7.140814 Tw (to ) Tj /F3 10 Tf (func) Tj /F1 10 Tf (, containing the parser associated to the function annotations. The second time) Tj T* 0 Tw /F3 10 Tf (plac.call\(func\) ) Tj /F1 10 Tf (is invoked, the parser is re-used.) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 369.6236 cm
q
BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Writing command-line interpreters with plac) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 327.6236 cm
q
BT 1 0 0 1 0 28.82 Tm .677485 Tw 12 TL /F1 10 Tf 0 0 0 rg (Apart from testing, there is another typical use case where ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (is invoked multiple times, in the) Tj T* 0 Tw .334269 Tw (implementation of command interpreters. For instance, you could define an interative interpreter on top of) Tj T* 0 Tw /F3 10 Tf (ishelve ) Tj /F1 10 Tf (as follows:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 90.42362 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 228 re B*
Q
q
BT 1 0 0 1 0 209.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (import plac) Tj T* (from ishelve import ishelve) Tj T*  T* (ishelve.prefix_chars = '.') Tj T* (ishelve.add_help = False) Tj T*  T* (@plac.annotations\() Tj T* (    interactive=\('start interactive interface', 'flag'\)\)) Tj T* (def main\(interactive, *args\):) Tj T* (    if interactive:) Tj T* (        import shlex) Tj T* (        while True:) Tj T* (            try:) Tj T* (                line = raw_input\('i) Tj (>) Tj ( '\)) Tj T* (            except EOFError:) Tj T* (                break) Tj T* (            cmd = shlex.split\(line\)) Tj T* (            for out in plac.call\(ishelve, cmd\):) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 56.69291 56.69291 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (2) Tj T* -238.1649 0 Td ET
Q
Q
 
endstream

endobj
% 'R42': class PDFStream 
42 0 obj
% page stream
<< /Length 3636 >>
stream
1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
q
1 0 0 1 62.69291 679.8236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 84 re B*
Q
q
BT 1 0 0 1 0 65.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (                print\(out\)) Tj T* (    else:) Tj T* (        plac.call\(ishelve, args\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.call\(main\)) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 659.8236 cm
q
BT 1 0 0 1 0 4.82 Tm 12 TL /F1 10 Tf 0 0 0 rg (Here is an usage session, usinng ) Tj /F3 10 Tf (rlwrap ) Tj /F1 10 Tf (to enable readline features:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 398.6236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 252 re B*
Q
q
BT 1 0 0 1 0 233.71 Tm 12 TL /F3 10 Tf 0 0 0 rg ($ rlwrap python shelve_interpreter.py -i) Tj T*  T* (i) Tj (>) Tj ( ..clear) Tj T* (cleared the shelve) Tj T* (i) Tj (>) Tj ( a=1) Tj T* (setting a=1) Tj T* (i) Tj (>) Tj ( a) Tj T* (1) Tj T* (i) Tj (>) Tj ( b=2) Tj T* (setting b=2) Tj T* (i) Tj (>) Tj ( a b) Tj T* (1) Tj T* (2) Tj T* (i) Tj (>) Tj ( ..delete a) Tj T* (deleted a) Tj T* (i) Tj (>) Tj ( a) Tj T* (a: not found) Tj T* (i) Tj (>) Tj ( ..all) Tj T* (b=2) Tj T* (i) Tj (>) Tj ( [CTRL-D]) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 282.6236 cm
q
BT 1 0 0 1 0 100.82 Tm 1.991654 Tw 12 TL /F1 10 Tf 0 0 0 rg (As you see, it is possibly to write command interpreters directly on top of ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (and it is not) Tj T* 0 Tw 5.022126 Tw (particularly difficult. However, the devil is in the details \(I mean error management\) and my) Tj T* 0 Tw 5.139269 Tw (recommendation, if you want to implement an interpreter of commands, is to use the class) Tj T* 0 Tw .05229 Tw /F3 10 Tf (plac.Interpreter ) Tj /F1 10 Tf (which is especially suited for this task. ) Tj /F3 10 Tf (plac.Interpreter ) Tj /F1 10 Tf (is available only if you) Tj T* 0 Tw .454488 Tw (are using a recent version of Python \() Tj (>) Tj (= 2.5\), because it is a context manager object to be used with the) Tj T* 0 Tw .38229 Tw /F3 10 Tf (with ) Tj /F1 10 Tf (statement. The only important method of ) Tj /F3 10 Tf (plac.Interpreter ) Tj /F1 10 Tf (is the ) Tj /F3 10 Tf (.send ) Tj /F1 10 Tf (method, which takes) Tj T* 0 Tw .057209 Tw (a string in input and returns a string in output. Internally the input string is splitted with ) Tj /F3 10 Tf (shlex.split ) Tj /F1 10 Tf (and) Tj T* 0 Tw 2.706136 Tw (passed to ) Tj /F3 10 Tf (plac.call) Tj /F1 10 Tf (, with some trick to manage exceptions correctly. Moreover long options are) Tj T* 0 Tw (managed with a single prefix character.) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 105.4236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 168 re B*
Q
q
BT 1 0 0 1 0 149.71 Tm 12 TL /F3 10 Tf 0 0 0 rg ("""Call this script with rlwrap and you will be happy""") Tj T* (from __future__ import with_statement) Tj T* (from plac_shell import Interpreter) Tj T* (from shelve_interface import interpreter) Tj T*  T* (if __name__ == '__main__':) Tj T* (    with Interpreter\(interpreter\) as i:) Tj T* (        while True:) Tj T* (            try:) Tj T* (                line = raw_input\('i) Tj (>) Tj ( '\)) Tj T* (            except EOFError:) Tj T* (                break) Tj T* (            print\(i.send\(line\)\)) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 56.69291 56.69291 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (3) Tj T* -238.1649 0 Td ET
Q
Q
 
endstream

endobj
% 'R43': class PDFStream 
43 0 obj
% page stream
<< /Length 3539 >>
stream
1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
q
1 0 0 1 62.69291 744.0236 cm
q
BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Multi-parsers) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 690.0236 cm
q
BT 1 0 0 1 0 40.82 Tm .594988 Tw 12 TL /F1 10 Tf 0 0 0 rg (As we saw, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is able to infer an arguments parser from the signature of a function. In addition, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (is) Tj T* 0 Tw 1.96186 Tw (also able to infer a multi-parser from a container of commands, by inferring the subparsers from the) Tj T* 0 Tw .352651 Tw (commands. That is useful if you want to implement ) Tj /F4 10 Tf (subcommands ) Tj /F1 10 Tf (\(a familiar example of a command-line) Tj T* 0 Tw (application featuring subcommands is subversion\).) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 648.0236 cm
q
BT 1 0 0 1 0 28.82 Tm .636457 Tw 12 TL /F1 10 Tf 0 0 0 rg (A container of commands is any object with a ) Tj /F3 10 Tf (.commands ) Tj /F1 10 Tf (attribute listing a set of functions or methods) Tj T* 0 Tw 1.50936 Tw (which are valid commands. In particular, a Python module is a perfect container of commands. As an) Tj T* 0 Tw (example, consider the following module implementing a fake Version Control System:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 350.8236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 288 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 269.71 Tm /F3 10 Tf 12 TL ("A Fake Version Control System") Tj T*  T* (import plac) Tj T*  T* (commands = 'checkout', 'commit', 'status') Tj T*  T* (@plac.annotations\() Tj T* (    url=\('url of the source code', 'positional'\)\)) Tj T* (def checkout\(url\):) Tj T* (    return \('checkout ', url\)) Tj T*  T* (@plac.annotations\() Tj T* (    message=\('commit message', 'option'\)\)) Tj T* (def commit\(message\):) Tj T* (    return \('commit ', message\)) Tj T*  T* (@plac.annotations\(quiet=\('summary information', 'flag'\)\)) Tj T* (def status\(quiet\):) Tj T* (    return \('status ', quiet\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import __main__) Tj T* (    print\(plac.call\(__main__\)\)) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 330.8236 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is the usage message:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 189.6236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 132 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 113.71 Tm /F3 10 Tf 12 TL (usage: vcs.py [-h] {status,commit,checkout} ...) Tj T*  T* (A Fake Version Control System) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T*  T* (subcommands:) Tj T* (  {status,commit,checkout}) Tj T* (                        -h to get additional help) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 133.6236 cm
q
0 0 0 rg
BT 1 0 0 1 0 40.82 Tm /F1 10 Tf 12 TL 1.614104 Tw (If the commands are completely independent, a module is a good fit for a method container. In other) Tj T* 0 Tw .876654 Tw (situations, it is best to use a custom class. For instance, suppose you want to store the configuration of) Tj T* 0 Tw 2.040574 Tw (your application into a Python shelve; then, you may want to write a command-line tool to edit your) Tj T* 0 Tw (configuration, i.e. a shelve interface:) Tj T* ET
Q
Q
q
1 0 0 1 56.69291 56.69291 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (4) Tj T* -238.1649 0 Td ET
Q
Q
 
endstream

endobj
% 'R44': class PDFStream 
44 0 obj
% page stream
<< /Length 2642 >>
stream
1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
q
1 0 0 1 62.69291 295.8236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 468 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 449.71 Tm /F3 10 Tf 12 TL (import shelve) Tj T* (import plac) Tj T*  T* (# error checking is missing: this is left to the reader) Tj T* (class ShelveInterface\(object\):) Tj T* (    "A minimal interface over a shelve object") Tj T* (    commands = 'set', 'show', 'show_all', 'delete') Tj T* (    def __init__\(self, fname\):) Tj T* (        self.fname = fname) Tj T* (        self.sh = shelve.open\(fname\)) Tj T* (    def set\(self, name, value\):) Tj T* (        "set name value") Tj T* (        yield 'setting %s=%s' % \(name, value\)) Tj T* (        self.sh[name] = value) Tj T* (    def show\(self, *names\):) Tj T* (        "show given parameters") Tj T* (        for name in names:) Tj T* (            yield '%s = %s\\n' % \(name, self.sh[name]\)) Tj T* (    def show_all\(self\):) Tj T* (        "show all parameters") Tj T* (        for name in self.sh:) Tj T* (            yield '%s = %s\\n' % \(name, self.sh[name]\)) Tj T* (    def delete\(self, name=None\):) Tj T* (        "delete given parameter \(or everything\)") Tj T* (        if name is None:) Tj T* (            yield 'deleting everything') Tj T* (            self.sh.clear\(\)) Tj T* (        else:) Tj T* (            yield 'deleting %s' % name) Tj T* (            del self.sh[name]) Tj T*  T* (if __name__ == '__main__':) Tj T* (    interface = ShelveInterface\('conf.shelve'\)) Tj T* (    try:) Tj T* (        for output in plac.call\(interface\):) Tj T* (            print\(output\)) Tj T* (    finally:) Tj T* (        interface.sh.close\(\)) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 275.8236 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is a session of usage on an Unix-like operating system:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 98.62362 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 168 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 149.71 Tm /F3 10 Tf 12 TL ($ alias conf="python shelve_interface.py") Tj T* ($ conf set a pippo) Tj T* (setting a=pippo) Tj T* ($ conf set b lippo) Tj T* (setting b=lippo) Tj T* ($ conf show_all) Tj T* (b = lippo) Tj T* (a = pippo) Tj T* ($ conf show a b) Tj T* (a = pippo) Tj T* (b = lippo) Tj T* ($ conf delete a) Tj T* (deleting a) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 56.69291 56.69291 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (5) Tj T* -238.1649 0 Td ET
Q
Q
 
endstream

endobj
% 'R45': class PDFStream 
45 0 obj
% page stream
<< /Length 3421 >>
stream
1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
q
1 0 0 1 62.69291 727.8236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 36 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 17.71 Tm /F3 10 Tf 12 TL ($ conf show_all) Tj T* (b = lippo) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 671.8236 cm
q
BT 1 0 0 1 0 40.82 Tm .581235 Tw 12 TL /F1 10 Tf 0 0 0 rg (Technically a multi-parser is a parser object with an attribute ) Tj /F3 10 Tf (.subp ) Tj /F1 10 Tf (which is a dictionary of subparsers;) Tj T* 0 Tw 1.757984 Tw (each of the methods listed in the attribute ) Tj /F3 10 Tf (.commands ) Tj /F1 10 Tf (corresponds to a subparser inferred from the) Tj T* 0 Tw .593984 Tw (method signature. The original object gets a ) Tj /F3 10 Tf (.p ) Tj /F1 10 Tf (attribute containing the main parser which is associated) Tj T* 0 Tw (to an internal function which dispatches on the right method depending on the method name.) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 653.8236 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is the usage message:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 308.6236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 336 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 317.71 Tm /F3 10 Tf 12 TL (import plac) Tj T*  T* (class FVCS\(object\):) Tj T* (    "A Fake Version Control System") Tj T* (    commands = 'checkout', 'commit', 'status', 'help') Tj T*  T* (    @plac.annotations\() Tj T* (        name=\('a recognized command', 'positional', None, str, commands\)\)) Tj T* (    def help\(self, name\):) Tj T* (        self.p.subp[name].print_help\(\)) Tj T*  T* (    @plac.annotations\() Tj T* (        url=\('url of the source code', 'positional'\)\)) Tj T* (    def checkout\(self, url\):) Tj T* (        print\('checkout', url\)) Tj T*  T* (    def commit\(self\):) Tj T* (        print\('commit'\)) Tj T*  T* (    @plac.annotations\(quiet=\('summary information', 'flag'\)\)) Tj T* (    def status\(self, quiet\):) Tj T* (        print\('status', quiet\)) Tj T*  T* (main = FVCS\(\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.call\(main\)) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 167.4236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 132 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 113.71 Tm /F3 10 Tf 12 TL (usage: example13.py [-h] {status,commit,checkout,help} ...) Tj T*  T* (A Fake Version Control System) Tj T*  T* (optional arguments:) Tj T* (  -h, --help            show this help message and exit) Tj T*  T* (subcommands:) Tj T* (  {status,commit,checkout,help}) Tj T* (                        -h to get additional help) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 134.4236 cm
q
BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Advanced usage) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 104.4236 cm
q
BT 1 0 0 1 0 16.82 Tm .094988 Tw 12 TL /F1 10 Tf 0 0 .501961 rg (plac ) Tj 0 0 0 rg (relies on a ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (for all of the heavy lifting work and it is possible to leverage on ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (features) Tj T* 0 Tw (directly or indirectly.) Tj T* ET
Q
Q
q
1 0 0 1 56.69291 56.69291 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (6) Tj T* -238.1649 0 Td ET
Q
Q
 
endstream

endobj
% 'R46': class PDFStream 
46 0 obj
% page stream
<< /Length 5867 >>
stream
1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
q
1 0 0 1 62.69291 729.0236 cm
q
BT 1 0 0 1 0 28.82 Tm 5.575697 Tw 12 TL /F1 10 Tf 0 0 0 rg (For instance, you can make invisible an argument in the usage message simply by using) Tj T* 0 Tw 1.435976 Tw /F3 10 Tf ('==SUPPRESS==' ) Tj /F1 10 Tf (as help string \(or ) Tj /F3 10 Tf (argparse.SUPPRESS) Tj /F1 10 Tf (\). Similarly, you can use ) Tj 0 0 .501961 rg (argparse.FileType) Tj T* 0 Tw 0 0 0 rg (directly.) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 675.0236 cm
q
BT 1 0 0 1 0 40.82 Tm 1.639213 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is also possible to pass options to the underlying ) Tj /F3 10 Tf (argparse.ArgumentParser ) Tj /F1 10 Tf (object \(currently it) Tj T* 0 Tw .285529 Tw (accepts the default arguments ) Tj /F3 10 Tf (description) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (epilog) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (prog) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (usage) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (add_help) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (argument_default) Tj /F1 10 Tf (,) Tj T* 0 Tw 1.439953 Tw /F3 10 Tf (parents) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (prefix_chars) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (fromfile_prefix_chars) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (conflict_handler) Tj /F1 10 Tf (, ) Tj /F3 10 Tf (formatter_class) Tj /F1 10 Tf (\). It) Tj T* 0 Tw (is enough to set such attributes on the ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (function. For instance) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 605.8236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 60 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 41.71 Tm /F3 10 Tf 12 TL (def main\(...\):) Tj T* (    pass) Tj T*  T* (main.add_help = False) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 525.8236 cm
q
BT 1 0 0 1 0 64.82 Tm 1.256457 Tw 12 TL /F1 10 Tf 0 0 0 rg (disable the recognition of the help flag ) Tj /F3 10 Tf (-h, --help) Tj /F1 10 Tf (. This is not particularly elegant, but I assume the) Tj T* 0 Tw .275703 Tw (typical user of ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (will be happy with the defaults and would not want to change them; still it is possible if) Tj T* 0 Tw .365542 Tw (she wants to. For instance, by setting the ) Tj /F3 10 Tf (description ) Tj /F1 10 Tf (attribute, it is possible to add a comment to the) Tj T* 0 Tw .602339 Tw (usage message \(by default the docstring of the ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (function is used as description\). It is also possible) Tj T* 0 Tw .322988 Tw (to change the option prefix; for instance if your script must run under Windows and you want to use "/" as) Tj T* 0 Tw (option prefix you can add the line:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 492.6236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 24 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 5.71 Tm /F3 10 Tf 12 TL (main.prefix_chars='/-') Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 436.6236 cm
q
BT 1 0 0 1 0 40.82 Tm .591163 Tw 12 TL /F3 10 Tf 0 0 0 rg (prefix_chars ) Tj /F1 10 Tf (is an ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (feature. The first prefix char \() Tj /F3 10 Tf (/) Tj /F1 10 Tf (\) is used as the default in the construction) Tj T* 0 Tw .266098 Tw (of both short and long options; the second prefix char \() Tj /F3 10 Tf (-) Tj /F1 10 Tf (\) is kept to keep the ) Tj /F3 10 Tf (-h/--help ) Tj /F1 10 Tf (option working:) Tj T* 0 Tw .107209 Tw (however you can disable it and reimplement it if you like. For instance, here is how you could reimplement) Tj T* 0 Tw (the ) Tj /F3 10 Tf (help ) Tj /F1 10 Tf (command in the Fake VCS example:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 235.4236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 192 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 173.71 Tm /F3 10 Tf 12 TL (import plac) Tj T* (from example13 import FVCS) Tj T*  T* (class VCS_with_help\(FVCS\):) Tj T* (    commands = FVCS.commands + \('help',\)) Tj T*  T* (    @plac.annotations\() Tj T* (        name=\('a recognized command', 'positional', None, str, commands\)\)) Tj T* (    def help\(self, name\):) Tj T* (        self.p.subp[name].print_help\(\)) Tj T*  T* (main = VCS_with_help\(\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    plac.call\(main\)) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 191.4236 cm
q
BT 1 0 0 1 0 28.82 Tm 1.938443 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj /F3 10 Tf (plac.call ) Tj /F1 10 Tf (uses ) Tj /F3 10 Tf (plac.parser_from ) Tj /F1 10 Tf (and adds the parser as an attribute ) Tj /F3 10 Tf (.p) Tj /F1 10 Tf (. This also) Tj T* 0 Tw 8.165366 Tw (happers for multiparsers and you can take advantage of the ) Tj /F3 10 Tf (.p ) Tj /F1 10 Tf (attribute to invoke) Tj T* 0 Tw /F3 10 Tf (argparse.ArgumentParser ) Tj /F1 10 Tf (methods.) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 149.4236 cm
q
BT 1 0 0 1 0 28.82 Tm 1.442126 Tw 12 TL /F1 10 Tf 0 0 0 rg (Interested readers should read the documentation of ) Tj 0 0 .501961 rg (argparse ) Tj 0 0 0 rg (to understand the meaning of the other) Tj T* 0 Tw .771567 Tw (options. If there is a set of options that you use very often, you may consider writing a decorator adding) Tj T* 0 Tw (such options to the ) Tj /F3 10 Tf (main ) Tj /F1 10 Tf (function for you. For simplicity, ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (does not perform any magic of that kind.) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 119.4236 cm
q
BT 1 0 0 1 0 16.82 Tm 7.709147 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is possible to access directly the underlying ) Tj 0 0 .501961 rg (ArgumentParser ) Tj 0 0 0 rg (object, by invoking the) Tj T* 0 Tw /F3 10 Tf (plac.parser_from ) Tj /F1 10 Tf (utility function:) Tj T* ET
Q
Q
q
1 0 0 1 56.69291 56.69291 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (7) Tj T* -238.1649 0 Td ET
Q
Q
 
endstream

endobj
% 'R47': class PDFStream 
47 0 obj
% page stream
<< /Length 3975 >>
stream
1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
q
1 0 0 1 62.69291 655.8236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 108 re B*
Q
q
BT 1 0 0 1 0 89.71 Tm 12 TL /F3 10 Tf 0 0 0 rg (>) Tj (>) Tj (>) Tj ( import plac) Tj T* (>) Tj (>) Tj (>) Tj ( def main\(arg\):) Tj T* (...     pass) Tj T* (...) Tj T* (>) Tj (>) Tj (>) Tj ( print plac.parser_from\(main\)) Tj T* (ArgumentParser\(prog='', usage=None, description=None, version=None,) Tj T* (formatter_class=) Tj (<) Tj (class 'argparse.HelpFormatter') Tj (>) Tj (, conflict_handler='error',) Tj T* (add_help=True\)) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 623.8236 cm
q
BT 1 0 0 1 0 16.82 Tm .365542 Tw 12 TL /F1 10 Tf 0 0 0 rg (I use ) Tj /F3 10 Tf (plac.parser_from ) Tj /F1 10 Tf (in the unit tests of the module, but regular users should never need to use it,) Tj T* 0 Tw (since the parser is also available as an attribute of the main function.) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 590.8236 cm
q
BT 1 0 0 1 0 8.435 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Custom annotation objects) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 560.8236 cm
q
BT 1 0 0 1 0 16.82 Tm .578651 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj 0 0 .501961 rg (plac ) Tj 0 0 0 rg (uses an ) Tj /F3 10 Tf (Annotation ) Tj /F1 10 Tf (class to convert the tuples in the function signature into annotation) Tj T* 0 Tw (objects, i.e. objects with six attributes ) Tj /F3 10 Tf (help, kind, short, type, choices, metavar) Tj /F1 10 Tf (.) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 530.8236 cm
q
0 0 0 rg
BT 1 0 0 1 0 16.82 Tm /F1 10 Tf 12 TL .083735 Tw (Advanced users can implement their own annotation objects. For instance, here is an example of how you) Tj T* 0 Tw (could implement annotations for positional arguments:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 401.6236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 120 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 101.71 Tm /F3 10 Tf 12 TL (# annotations.py) Tj T* (class Positional\(object\):) Tj T* (    def __init__\(self, help='', type=None, choices=None, metavar=None\):) Tj T* (        self.help = help) Tj T* (        self.kind = 'positional') Tj T* (        self.abbrev = None) Tj T* (        self.type = type) Tj T* (        self.choices = choices) Tj T* (        self.metavar = metavar) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 381.6236 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (You can use such annotations objects as follows:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 204.4236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 168 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 149.71 Tm /F3 10 Tf 12 TL (# example11.py) Tj T* (import plac) Tj T* (from annotations import Positional) Tj T*  T* (@plac.annotations\() Tj T* (    i=Positional\("This is an int", int\),) Tj T* (    n=Positional\("This is a float", float\),) Tj T* (    rest=Positional\("Other arguments"\)\)) Tj T* (def main\(i, n, *rest\):) Tj T* (    print\(i, n, rest\)) Tj T*  T* (if __name__ == '__main__':) Tj T* (    import plac; plac.call\(main\)) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 184.4236 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL (Here is the usage message you get:) Tj T* ET
Q
Q
q
1 0 0 1 62.69291 91.22362 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 84 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 65.71 Tm /F3 10 Tf 12 TL (usage: example11.py [-h] i n [rest [rest ...]]) Tj T*  T* (positional arguments:) Tj T* (  i           This is an int) Tj T* (  n           This is a float) Tj T* (  rest        Other arguments) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 56.69291 56.69291 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (8) Tj T* -238.1649 0 Td ET
Q
Q
 
endstream

endobj
% 'R48': class PDFStream 
48 0 obj
% page stream
<< /Length 1026 >>
stream
1 0 0 1 0 0 cm BT /F1 12 Tf 14.4 TL ET
q
1 0 0 1 62.69291 715.8236 cm
q
q
1 0 0 1 0 0 cm
q
1 0 0 1 6.6 6.6 cm
q
.662745 .662745 .662745 RG
.5 w
.960784 .960784 .862745 rg
n -6 -6 468.6898 48 re B*
Q
q
0 0 0 rg
BT 1 0 0 1 0 29.71 Tm /F3 10 Tf 12 TL  T* (optional arguments:) Tj T* (  -h, --help  show this help message and exit) Tj T* ET
Q
Q
Q
Q
Q
q
1 0 0 1 62.69291 671.8236 cm
q
BT 1 0 0 1 0 28.82 Tm .713516 Tw 12 TL /F1 10 Tf 0 0 0 rg (You can go on and define ) Tj /F3 10 Tf (Option ) Tj /F1 10 Tf (and ) Tj /F3 10 Tf (Flag ) Tj /F1 10 Tf (classes, if you like. Using custom annotation objects you) Tj T* 0 Tw .17528 Tw (could do advanced things like extracting the annotations from a configuration file or from a database, but I) Tj T* 0 Tw (expect such use cases to be quite rare: the default mechanism should work pretty well for most users.) Tj T* ET
Q
Q
q
1 0 0 1 56.69291 56.69291 cm
q
0 0 0 rg
BT 1 0 0 1 0 4.82 Tm /F1 10 Tf 12 TL 238.1649 0 Td (9) Tj T* -238.1649 0 Td ET
Q
Q
 
endstream

endobj
% 'R49': class PDFPageLabels 
49 0 obj
% Document Root
<< /Nums [ 0
 50 0 R
 1
 51 0 R
 2
 52 0 R
 3
 53 0 R
 4
 54 0 R
 5
 55 0 R
 6
 56 0 R
 7
 57 0 R
 8
 58 0 R ] >>
endobj
% 'R50': class PDFPageLabel 
50 0 obj
% None
<< /S /D
 /St 1 >>
endobj
% 'R51': class PDFPageLabel 
51 0 obj
% None
<< /S /D
 /St 2 >>
endobj
% 'R52': class PDFPageLabel 
52 0 obj
% None
<< /S /D
 /St 3 >>
endobj
% 'R53': class PDFPageLabel 
53 0 obj
% None
<< /S /D
 /St 4 >>
endobj
% 'R54': class PDFPageLabel 
54 0 obj
% None
<< /S /D
 /St 5 >>
endobj
% 'R55': class PDFPageLabel 
55 0 obj
% None
<< /S /D
 /St 6 >>
endobj
% 'R56': class PDFPageLabel 
56 0 obj
% None
<< /S /D
 /St 7 >>
endobj
% 'R57': class PDFPageLabel 
57 0 obj
% None
<< /S /D
 /St 8 >>
endobj
% 'R58': class PDFPageLabel 
58 0 obj
% None
<< /S /D
 /St 9 >>
endobj
xref
0 59
0000000000 65535 f
0000000113 00000 n
0000000246 00000 n
0000000411 00000 n
0000000598 00000 n
0000000847 00000 n
0000001096 00000 n
0000001334 00000 n
0000001493 00000 n
0000001808 00000 n
0000002087 00000 n
0000002381 00000 n
0000002632 00000 n
0000002871 00000 n
0000003051 00000 n
0000003361 00000 n
0000003655 00000 n
0000003905 00000 n
0000004154 00000 n
0000004389 00000 n
0000004722 00000 n
0000005038 00000 n
0000005288 00000 n
0000005538 00000 n
0000005788 00000 n
0000006040 00000 n
0000006312 00000 n
0000006673 00000 n
0000006910 00000 n
0000007211 00000 n
0000007492 00000 n
0000007651 00000 n
0000007912 00000 n
0000008037 00000 n
0000008209 00000 n
0000008414 00000 n
0000008632 00000 n
0000008821 00000 n
0000009011 00000 n
0000009181 00000 n
0000009359 00000 n
0000013314 00000 n
0000017121 00000 n
0000020858 00000 n
0000024498 00000 n
0000027241 00000 n
0000030763 00000 n
0000036731 00000 n
0000040807 00000 n
0000041938 00000 n
0000042135 00000 n
0000042212 00000 n
0000042289 00000 n
0000042366 00000 n
0000042443 00000 n
0000042520 00000 n
0000042597 00000 n
0000042674 00000 n
0000042751 00000 n
trailer
<< /ID 
 % ReportLab generated PDF document -- digest (http://www.reportlab.com) 
 [(\030N\026;L\241\300\254\011\265\273\363\247\201 N) (\030N\026;L\241\300\254\011\265\273\363\247\201 N)] 

 /Info 31 0 R
 /Root 30 0 R
 /Size 59 >>
startxref
42798
%%EOF