This file is indexed.

/usr/share/doc/python-apsw/html/shell.html is in python-apsw-doc 3.16.2-r1-2build2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Shell &#8212; APSW 3.16.2-r1 documentation</title>
    
    <link rel="stylesheet" href="_static/classic.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '3.16.2-r1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="copyright" title="Copyright" href="copyright.html" />
    <link rel="top" title="APSW 3.16.2-r1 documentation" href="index.html" />
    <link rel="next" title="Exceptions" href="exceptions.html" />
    <link rel="prev" title="Virtual File System (VFS)" href="vfs.html" />
 
<script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-26815066-1']);
  _gaq.push(['_trackPageview']);
</script>

  </head>
  <body role="document">
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="exceptions.html" title="Exceptions"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="vfs.html" title="Virtual File System (VFS)"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">APSW 3.16.2-r1 documentation</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="shell">
<span id="id1"></span><h1>Shell<a class="headerlink" href="#shell" title="Permalink to this headline"></a></h1>
<p>The shell provides a convenient way for you to interact with SQLite,
perform administration and supply SQL for execution.  It is modelled
after the <a class="reference external" href="https://sqlite.org/sqlite.html">shell that comes with SQLite</a> which requires separate
compilation and installation.</p>
<p>A number of the quirks and bugs in the SQLite shell are also
addressed.  It provides command line editing and completion.  You can
easily include it into your own program to provide SQLite interaction
and add your own commands.</p>
<div class="section" id="commands">
<h2>Commands<a class="headerlink" href="#commands" title="Permalink to this headline"></a></h2>
<p>In addition to executing SQL, these are the commands available with
their short help description.  Use <cite>.help *command*</cite> eg (<cite>.help
autoimport</cite>) to get more detailed information.</p>
<div class="highlight-text"><div class="highlight"><pre>.autoimport FILENAME ?TABLE?  Imports filename creating a table and
                              automatically working out separators and data
                              types (alternative to .import command)
.backup ?DB? FILE             Backup DB (default &quot;main&quot;) to FILE
.bail ON|OFF                  Stop after hitting an error (default OFF)
.colour SCHEME                Selects a colour scheme from default, off
.databases                    Lists names and files of attached databases
.dump ?TABLE? [TABLE...]      Dumps all or specified tables in SQL text format
.echo ON|OFF                  If ON then each SQL statement or command is
                              printed before execution (default OFF)
.encoding ENCODING            Set the encoding used for new files opened via
                              .output and imports
.exceptions ON|OFF            If ON then detailed tracebacks are shown on
                              exceptions (default OFF)
.exit                         Exit this program
.explain ON|OFF               Set output mode suitable for explain (default OFF)
.find what ?TABLE?            Searches all columns of all tables for a value
.header(s) ON|OFF             Display the column names in output (default OFF)
.help ?COMMAND?               Shows list of commands and their usage.  If
                              COMMAND is specified then shows detail about that
                              COMMAND.  (&#39;.help all&#39; will show detailed help
                              about all commands.)
.import FILE TABLE            Imports separated data from FILE into TABLE
.indices TABLE                Lists all indices on table TABLE
.load FILE ?ENTRY?            Loads a SQLite extension library
.mode MODE ?TABLE?            Sets output mode to one of column csv html insert
                              json line list python tabs tcl
.nullvalue STRING             Print STRING in place of null values
.output FILENAME              Send output to FILENAME (or stdout)
.print STRING                 print the literal STRING
.prompt MAIN ?CONTINUE?       Changes the prompts for first line and
                              continuation lines
.quit                         Exit this program
.read FILENAME                Processes SQL and commands in FILENAME (or Python
                              if FILENAME ends with .py)
.restore ?DB? FILE            Restore database from FILE into DB (default
                              &quot;main&quot;)
.schema ?TABLE? [TABLE...]    Shows SQL for table
.separator STRING             Change separator for output mode and .import
.show                         Show the current values for various settings.
.tables ?PATTERN?             Lists names of tables matching LIKE pattern
.timeout MS                   Try opening locked tables for MS milliseconds
.timer ON|OFF                 Control printing of time and resource usage after
                              each query
.width NUM NUM ...            Set the column widths for &quot;column&quot; mode
</pre></div>
</div>
</div>
<div class="section" id="command-line-usage">
<h2>Command Line Usage<a class="headerlink" href="#command-line-usage" title="Permalink to this headline"></a></h2>
<p>You can use the shell directly from the command line.  Invoke it like
this:</p>
<div class="highlight-default"><div class="highlight"><pre>$ python -c &quot;import apsw;apsw.main()&quot;  [options and arguments]
</pre></div>
</div>
<p>The following command line options are accepted:</p>
<div class="highlight-text"><div class="highlight"><pre>Usage: program [OPTIONS] FILENAME [SQL|CMD] [SQL|CMD]...
FILENAME is the name of a SQLite database. A new database is
created if the file does not exist.
OPTIONS include:
   -init filename       read/process named file
   -echo                print commands before execution
   -[no]header          turn headers on or off
   -bail                stop after hitting an error
   -interactive         force interactive I/O
   -batch               force batch I/O
   -column              set output mode to &#39;column&#39;
   -csv                 set output mode to &#39;csv&#39;
   -html                set output mode to &#39;html&#39;
   -line                set output mode to &#39;line&#39;
   -list                set output mode to &#39;list&#39;
   -python              set output mode to &#39;python&#39;
   -separator &#39;x&#39;       set output field separator (|)
   -nullvalue &#39;text&#39;    set text string for NULL values
   -version             show SQLite version
   -encoding &#39;name&#39;     the encoding to use for files
                        opened via .import, .read &amp; .output
   -nocolour            disables colour output to screen
</pre></div>
</div>
</div>
<div class="section" id="notes">
<h2>Notes<a class="headerlink" href="#notes" title="Permalink to this headline"></a></h2>
<p>To interrupt the shell press Control-C. (On Windows if you press
Control-Break then the program will be instantly aborted.)</p>
<p>For Windows users you won&#8217;t have command line editing and completion
unless you install a <a class="reference external" href="http://docs.python.org/library/readline.html">readline module</a>.  Fortunately there
is one at <a class="reference external" href="https://ipython.org/pyreadline.html">https://ipython.org/pyreadline.html</a> which works.
However if this <a class="reference internal" href="#apsw.Shell" title="apsw.Shell"><code class="xref py py-class docutils literal"><span class="pre">Shell</span></code></a> offers no completions it will start
matching filenames even if they make no sense in the context.</p>
<p>For Windows users you won&#8217;t get colour output unless you install
<a class="reference external" href="http://pypi.python.org/pypi/colorama">colorama</a></p>
</div>
<div class="section" id="example">
<h2>Example<a class="headerlink" href="#example" title="Permalink to this headline"></a></h2>
<p>All examples of using the SQLite shell should work as is, plus you get
extra features and functionality like colour, command line completion
and better dumps.</p>
<p>You can also use the shell programmatically (or even interactively and
programmatically at the same time).  See the <a class="reference internal" href="example.html#example-shell"><span class="std std-ref">example</span></a> for using the API.</p>
</div>
<div class="section" id="unicode">
<h2>Unicode<a class="headerlink" href="#unicode" title="Permalink to this headline"></a></h2>
<p>SQLite only works with <a class="reference external" href="http://en.wikipedia.org/wiki/Unicode">Unicode</a> strings.  All data supplied
to it should be Unicode and all data retrieved is Unicode.  (APSW
functions the same way because of this.)</p>
<p>At the technical level there is a difference between bytes and
characters.  Bytes are how data is stored in files and transmitted
over the network.  In order to turn bytes into characters and
characters into bytes an encoding has to be used.  Some example
encodings are ASCII, UTF-8, ISO8859-1, SJIS etc.  (With the exception
of UTF-8/16/32, other encodings can only map a very small subset of
Unicode.)</p>
<p>If the shell reads data that is not valid for the input encoding or
cannot convert Unicode to the output encoding then you will get an
error.</p>
<p>When the shell starts Python automatically detects the encodings to
use for console input and output.  (For example on Unix like systems
the LC_CTYPE environment variable is sometimes used.  On Windows it
can find out the <a class="reference external" href="http://en.wikipedia.org/wiki/Code_page">code page</a>.)  You can override this
autodetection by setting the PYTHONIOENCODING environment variable.</p>
<p>There is also a .encoding command.  This sets what encoding is used
for any subsequent .read, .import and .output commands but does not
affect existing open files and console.  When other programs offer you
a choice for encoding the best value to pick is UTF8 as it allows full
representation of Unicode.</p>
<p>In addition to specifying the encoding, you can also specify the error
handling when a character needs to be output but is not present in the
encoding.  The default is &#8216;strict&#8217; which results in an error.
&#8216;replace&#8217; will replace the character with &#8216;?&#8217; or something similar
while &#8216;xmlcharrefreplace&#8217; uses xml entities.  To specify the error
handling add a colon and error after the encoding - eg:</p>
<div class="highlight-default"><div class="highlight"><pre><span class="o">.</span><span class="n">encoding</span> <span class="n">iso</span><span class="o">-</span><span class="mi">8859</span><span class="o">-</span><span class="mi">1</span><span class="p">:</span><span class="n">replace</span>
</pre></div>
</div>
<p>The same method is used when setting PYTHONIOENCODING.</p>
<p>This <a class="reference external" href="http://www.joelonsoftware.com/articles/Unicode.html">Joel on Software article</a> contains an
excellent overview of character sets, code pages and Unicode.</p>
</div>
<div class="section" id="shell-class">
<h2>Shell class<a class="headerlink" href="#shell-class" title="Permalink to this headline"></a></h2>
<p>This is the API should you want to integrate the code into your shell.
Not shown here are the functions that implement various commands.
They are named after the command.  For example .exit is implemented by
command_exit.  You can add new commands by having your subclass have
the relevant functions.  The doc string of the function is used by the
help command.  Output modes work in a similar way.  For example there
is an output_html method and again doc strings are used by the help
function and you add more by just implementing an appropriately named
method.</p>
<p>Note that in addition to extending the shell, you can also use the
<strong>.read</strong> command supplying a filename with a <strong>.py</strong> extension.  You
can then <a class="reference external" href="http://en.wikipedia.org/wiki/Monkey_patch">monkey patch</a>
the shell as needed.</p>
<dl class="class">
<dt id="apsw.Shell">
<em class="property">class </em><code class="descname">Shell</code><span class="sig-paren">(</span><em>stdin=None</em>, <em>stdout=None</em>, <em>stderr=None</em>, <em>encoding='utf8'</em>, <em>args=None</em>, <em>db=None</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell" title="Permalink to this definition"></a></dt>
<dd><p>Implements a SQLite shell</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>stdin</strong> &#8211; Where to read input from (default sys.stdin)</li>
<li><strong>stdout</strong> &#8211; Where to send output (default sys.stdout)</li>
<li><strong>stderr</strong> &#8211; Where to send errors (default sys.stderr)</li>
<li><strong>encoding</strong> &#8211; Default encoding for files opened/created by the
Shell.  If you want stdin/out/err to use a particular encoding
then you need to provide them <a class="reference external" href="http://docs.python.org/library/codecs.html#codecs.open">already configured</a> that way.</li>
<li><strong>args</strong> &#8211; This should be program arguments only (ie if
passing in sys.argv do not include sys.argv[0] which is the
program name.  You can also pass in None and then call
<a class="reference internal" href="#apsw.Shell.process_args" title="apsw.Shell.process_args"><code class="xref py py-meth docutils literal"><span class="pre">process_args()</span></code></a> if you want to catch any errors
in handling the arguments yourself.</li>
<li><strong>db</strong> &#8211; A existing <a class="reference internal" href="connection.html#apsw.Connection" title="apsw.Connection"><code class="xref py py-class docutils literal"><span class="pre">Connection</span></code></a> you wish to use</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>The commands and behaviour are modelled after the <a class="reference external" href="https://sqlite.org/sqlite.html">interactive
shell</a> that is part of
SQLite.</p>
<p>You can inherit from this class to embed in your own code and user
interface.  Internally everything is handled as unicode.
Conversions only happen at the point of input or output which you
can override in your own code.</p>
<p>This implementation fixes a number of bugs/quirks present in the
sqlite shell.  Its control-C handling is also friendlier.  Some
examples of issues not present in this implementation:</p>
<ul class="simple">
<li><a class="reference external" href="https://sqlite.org/src/info/c25aab7e7e">https://sqlite.org/src/info/c25aab7e7e</a></li>
<li><a class="reference external" href="https://sqlite.org/src/info/7b61b6c6ce">https://sqlite.org/src/info/7b61b6c6ce</a></li>
<li><a class="reference external" href="https://sqlite.org/src/info/ee19e690ec">https://sqlite.org/src/info/ee19e690ec</a></li>
<li><a class="reference external" href="https://sqlite.org/src/info/2466653295">https://sqlite.org/src/info/2466653295</a></li>
</ul>
<p>Errors and diagnostics are only ever sent to error output
(self.stderr) and never to the regular output (self.stdout).  This
means using shell output is always easy and consistent.</p>
<p>Shell commands begin with a dot (eg .help).  They are implemented
as a method named after the command (eg command_help).  The method
is passed one parameter which is the list of arguments to the
command.</p>
<p>Output modes are implemented by functions named after the mode (eg
output_column).</p>
<p>When you request help the help information is automatically
generated from the docstrings for the command and output
functions.</p>
<p>You should not use a Shell object concurrently from multiple
threads.  It is one huge set of state information which would
become inconsistent if used simultaneously, and then give baffling
errors.  It is safe to call methods one at a time from different
threads.  ie it doesn&#8217;t care what thread calls methods as long as
you don&#8217;t call more than one concurrently.</p>
<dl class="exception">
<dt id="apsw.Shell.Error">
<em class="property">exception </em><code class="descname">Error</code><a class="headerlink" href="#apsw.Shell.Error" title="Permalink to this definition"></a></dt>
<dd><p>Class raised on errors.  The expectation is that the error
will be displayed by the shell as text so there are no
specific subclasses as the distinctions between different
types of errors doesn&#8217;t matter.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.cmdloop">
<code class="descclassname">Shell.</code><code class="descname">cmdloop</code><span class="sig-paren">(</span><em>intro=None</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.cmdloop" title="Permalink to this definition"></a></dt>
<dd><p>Runs the main interactive command loop.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>intro</strong> &#8211; Initial text banner to display instead of the
default.  Make sure you newline terminate it.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.complete">
<code class="descclassname">Shell.</code><code class="descname">complete</code><span class="sig-paren">(</span><em>token</em>, <em>state</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.complete" title="Permalink to this definition"></a></dt>
<dd><p>Return a possible completion for readline</p>
<p>This function is called with state starting at zero to get the
first completion, then one/two/three etc until you return None.  The best
implementation is to generate the list when state==0, save it,
and provide members on each increase.</p>
<p>The default implementation extracts the current full input
from readline and then calls <a class="reference internal" href="#apsw.Shell.complete_command" title="apsw.Shell.complete_command"><code class="xref py py-meth docutils literal"><span class="pre">complete_command()</span></code></a> or
<a class="reference internal" href="#apsw.Shell.complete_sql" title="apsw.Shell.complete_sql"><code class="xref py py-meth docutils literal"><span class="pre">complete_sql()</span></code></a> as appropriate saving the results for
subsequent calls.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.complete_command">
<code class="descclassname">Shell.</code><code class="descname">complete_command</code><span class="sig-paren">(</span><em>line</em>, <em>token</em>, <em>beg</em>, <em>end</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.complete_command" title="Permalink to this definition"></a></dt>
<dd><p>Provide some completions for dot commands</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>line</strong> &#8211; The current complete input line</li>
<li><strong>token</strong> &#8211; The word readline is looking for matches</li>
<li><strong>beg</strong> &#8211; Integer offset of token in line</li>
<li><strong>end</strong> &#8211; Integer end of token in line</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">A list of completions, or an empty list if none</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.complete_sql">
<code class="descclassname">Shell.</code><code class="descname">complete_sql</code><span class="sig-paren">(</span><em>line</em>, <em>token</em>, <em>beg</em>, <em>end</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.complete_sql" title="Permalink to this definition"></a></dt>
<dd><p>Provide some completions for SQL</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>line</strong> &#8211; The current complete input line</li>
<li><strong>token</strong> &#8211; The word readline is looking for matches</li>
<li><strong>beg</strong> &#8211; Integer offset of token in line</li>
<li><strong>end</strong> &#8211; Integer end of token in line</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">A list of completions, or an empty list if none</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="attribute">
<dt id="apsw.Shell.db">
<code class="descclassname">Shell.</code><code class="descname">db</code><a class="headerlink" href="#apsw.Shell.db" title="Permalink to this definition"></a></dt>
<dd><p>The current <a class="reference internal" href="connection.html#apsw.Connection" title="apsw.Connection"><code class="xref py py-class docutils literal"><span class="pre">Connection</span></code></a></p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.display_timing">
<code class="descclassname">Shell.</code><code class="descname">display_timing</code><span class="sig-paren">(</span><em>b4</em>, <em>after</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.display_timing" title="Permalink to this definition"></a></dt>
<dd><p>Writes the difference between b4 and after to self.stderr.
The data is dictionaries returned from
<a class="reference internal" href="#apsw.Shell.get_resource_usage" title="apsw.Shell.get_resource_usage"><code class="xref py py-meth docutils literal"><span class="pre">get_resource_usage()</span></code></a>.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.fixup_backslashes">
<code class="descclassname">Shell.</code><code class="descname">fixup_backslashes</code><span class="sig-paren">(</span><em>s</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.fixup_backslashes" title="Permalink to this definition"></a></dt>
<dd><p>Implements the various backlash sequences in s such as
turning backslash t into a tab.</p>
<p>This function is needed because shlex does not do it for us.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.get_resource_usage">
<code class="descclassname">Shell.</code><code class="descname">get_resource_usage</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.get_resource_usage" title="Permalink to this definition"></a></dt>
<dd><p>Return a dict of various numbers (ints or floats).  The
.timer command shows the difference between before and after
results of what this returns by calling <a class="reference internal" href="#apsw.Shell.display_timing" title="apsw.Shell.display_timing"><code class="xref py py-meth docutils literal"><span class="pre">display_timing()</span></code></a></p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.getcompleteline">
<code class="descclassname">Shell.</code><code class="descname">getcompleteline</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.getcompleteline" title="Permalink to this definition"></a></dt>
<dd><p>Returns a complete input.</p>
<p>For dot commands it will be one line.  For SQL statements it
will be as many as is necessary to have a
<a class="reference internal" href="apsw.html#apsw.complete" title="apsw.complete"><code class="xref py py-meth docutils literal"><span class="pre">complete()</span></code></a> statement (ie semicolon terminated).
Returns None on end of file.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.getline">
<code class="descclassname">Shell.</code><code class="descname">getline</code><span class="sig-paren">(</span><em>prompt=''</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.getline" title="Permalink to this definition"></a></dt>
<dd><p>Returns a single line of input (may be incomplete SQL) from self.stdin.</p>
<p>If EOF is reached then return None.  Do not include trailing
newline in return.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.handle_exception">
<code class="descclassname">Shell.</code><code class="descname">handle_exception</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.handle_exception" title="Permalink to this definition"></a></dt>
<dd><p>Handles the current exception, printing a message to stderr as appropriate.
It will reraise the exception if necessary (eg if bail is true)</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.handle_interrupt">
<code class="descclassname">Shell.</code><code class="descname">handle_interrupt</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.handle_interrupt" title="Permalink to this definition"></a></dt>
<dd><p>Deal with keyboard interrupt (typically Control-C).  It
will <a class="reference internal" href="connection.html#apsw.Connection.interrupt" title="apsw.Connection.interrupt"><code class="xref py py-meth docutils literal"><span class="pre">interrupt()</span></code></a> the database and print&#8221;^C&#8221; if interactive.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.pop_input">
<code class="descclassname">Shell.</code><code class="descname">pop_input</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.pop_input" title="Permalink to this definition"></a></dt>
<dd><p>Restore most recently pushed input parameters (interactive,
self.stdin, linenumber etc).  Use this if implementing a
command like read.  Push the current input, read the file and
then pop the input to go back to before.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.pop_output">
<code class="descclassname">Shell.</code><code class="descname">pop_output</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.pop_output" title="Permalink to this definition"></a></dt>
<dd><p>Restores most recently pushed output.  There are many
output parameters such as nullvalue, mode
(list/tcl/html/insert etc), column widths, header etc.  If you
temporarily need to change some settings then
<a class="reference internal" href="#apsw.Shell.push_output" title="apsw.Shell.push_output"><code class="xref py py-meth docutils literal"><span class="pre">push_output()</span></code></a>, change the settings and then pop the old
ones back.</p>
<p>A simple example is implementing a command like .dump.  Push
the current output, change the mode to insert so we get SQL
inserts printed and then pop to go back to what was there
before.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.process_args">
<code class="descclassname">Shell.</code><code class="descname">process_args</code><span class="sig-paren">(</span><em>args</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.process_args" title="Permalink to this definition"></a></dt>
<dd><p>Process command line options specified in args.  It is safe to
call this multiple times.  We try to be compatible with SQLite shell
argument parsing.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>args</strong> &#8211; A list of string options.  Do not include the
program as args[0]</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">A tuple of (databasefilename, initfiles,
sqlncommands).  This is provided for informational purposes
only - they have already been acted upon.  An example use
is that the SQLite shell does not enter the main interactive
loop if any sql/commands were provided.</td>
</tr>
</tbody>
</table>
<p>The first non-option is the database file name.  Each
remaining non-option is treated as a complete input (ie it
isn&#8217;t joined with others looking for a trailing semi-colon).</p>
<p>The SQLite shell uses single dash in front of options.  We
allow both single and double dashes.  When an unrecognized
argument is encountered then
<a class="reference internal" href="#apsw.Shell.process_unknown_args" title="apsw.Shell.process_unknown_args"><code class="xref py py-meth docutils literal"><span class="pre">process_unknown_args()</span></code></a> is called.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.process_command">
<code class="descclassname">Shell.</code><code class="descname">process_command</code><span class="sig-paren">(</span><em>cmd</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.process_command" title="Permalink to this definition"></a></dt>
<dd><p>Processes a dot command.  It is split into parts using the
<a class="reference external" href="http://docs.python.org/library/shlex.html#shlex.split">shlex.split</a>
function which is roughly the same method used by Unix/POSIX
shells.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.process_complete_line">
<code class="descclassname">Shell.</code><code class="descname">process_complete_line</code><span class="sig-paren">(</span><em>command</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.process_complete_line" title="Permalink to this definition"></a></dt>
<dd><p>Given some text will call the appropriate method to process
it (eg <a class="reference internal" href="#apsw.Shell.process_sql" title="apsw.Shell.process_sql"><code class="xref py py-meth docutils literal"><span class="pre">process_sql()</span></code></a> or <a class="reference internal" href="#apsw.Shell.process_command" title="apsw.Shell.process_command"><code class="xref py py-meth docutils literal"><span class="pre">process_command()</span></code></a>)</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.process_sql">
<code class="descclassname">Shell.</code><code class="descname">process_sql</code><span class="sig-paren">(</span><em>sql</em>, <em>bindings=None</em>, <em>internal=False</em>, <em>summary=None</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.process_sql" title="Permalink to this definition"></a></dt>
<dd><p>Processes SQL text consisting of one or more statements</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>sql</strong> &#8211; SQL to execute</li>
<li><strong>bindings</strong> &#8211; bindings for the <em>sql</em></li>
<li><strong>internal</strong> &#8211; If True then this is an internal execution
(eg the .tables or .database command).  When executing
internal sql timings are not shown nor is the SQL echoed.</li>
<li><strong>summary</strong> &#8211; If not None then should be a tuple of two
items.  If the <code class="docutils literal"><span class="pre">sql</span></code> returns any data then the first item
is printed before the first row, and the second item is
printed after the last row.  An example usage is the .find
command which shows table names.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.process_unknown_args">
<code class="descclassname">Shell.</code><code class="descname">process_unknown_args</code><span class="sig-paren">(</span><em>args</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.process_unknown_args" title="Permalink to this definition"></a></dt>
<dd><p>This is called when <a class="reference internal" href="#apsw.Shell.process_args" title="apsw.Shell.process_args"><code class="xref py py-meth docutils literal"><span class="pre">process_args()</span></code></a> encounters an
argument it doesn&#8217;t understand.  Override this method if you
want to be able to understand additional command line arguments.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>args</strong> &#8211; A list of the remaining arguments.  The initial one will
have had the leading dashes removed (eg if it was &#8211;foo on the command
line then args[0] will be &#8220;foo&#8221;</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">None if you don&#8217;t recognize the argument either.  Otherwise
return the list of remaining arguments after you have processed
yours.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.push_input">
<code class="descclassname">Shell.</code><code class="descname">push_input</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.push_input" title="Permalink to this definition"></a></dt>
<dd><p>Saves the current input paramaters to a stack.  See <a class="reference internal" href="#apsw.Shell.pop_input" title="apsw.Shell.pop_input"><code class="xref py py-meth docutils literal"><span class="pre">pop_input()</span></code></a>.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.push_output">
<code class="descclassname">Shell.</code><code class="descname">push_output</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.push_output" title="Permalink to this definition"></a></dt>
<dd><p>Saves the current output settings onto a stack.  See
<a class="reference internal" href="#apsw.Shell.pop_output" title="apsw.Shell.pop_output"><code class="xref py py-meth docutils literal"><span class="pre">pop_output()</span></code></a> for more details as to why you would use
this.</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.set_encoding">
<code class="descclassname">Shell.</code><code class="descname">set_encoding</code><span class="sig-paren">(</span><em>enc</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.set_encoding" title="Permalink to this definition"></a></dt>
<dd><p>Saves <em>enc</em> as the default encoding, after verifying that
it is valid.  You can also include :error to specify error
handling - eg &#8216;cp437:replace&#8217;</p>
<p>Raises an exception on invalid encoding or error</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.usage">
<code class="descclassname">Shell.</code><code class="descname">usage</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.usage" title="Permalink to this definition"></a></dt>
<dd><p>Returns the usage message.  Make sure it is newline terminated</p>
</dd></dl>

<dl class="method">
<dt id="apsw.Shell.write">
<code class="descclassname">Shell.</code><code class="descname">write</code><span class="sig-paren">(</span><em>dest</em>, <em>text</em><span class="sig-paren">)</span><a class="headerlink" href="#apsw.Shell.write" title="Permalink to this definition"></a></dt>
<dd><p>Writes text to dest.  dest will typically be one of self.stdout or self.stderr.</p>
</dd></dl>

</dd></dl>

</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Shell</a><ul>
<li><a class="reference internal" href="#commands">Commands</a></li>
<li><a class="reference internal" href="#command-line-usage">Command Line Usage</a></li>
<li><a class="reference internal" href="#notes">Notes</a></li>
<li><a class="reference internal" href="#example">Example</a></li>
<li><a class="reference internal" href="#unicode">Unicode</a></li>
<li><a class="reference internal" href="#shell-class">Shell class</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="vfs.html"
                        title="previous chapter">Virtual File System (VFS)</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="exceptions.html"
                        title="next chapter">Exceptions</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/shell.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="exceptions.html" title="Exceptions"
             >next</a> |</li>
        <li class="right" >
          <a href="vfs.html" title="Virtual File System (VFS)"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">APSW 3.16.2-r1 documentation</a> &#187;</li> 
      </ul>
    </div>

    <div class="footer" role="contentinfo">
        &#169; <a href="copyright.html">Copyright</a> 2004-2016, Roger Binns &lt;rogerb@rogerbinns.com&gt;.
      Last updated on Jan 14, 2017.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.8.
    </div>

  </body>
</html>