/Doc/tutorial/interactive.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 167 lines · 121 code · 46 blank · 0 comment · 0 complexity · 5d034d454b1af35490098c003285e85b MD5 · raw file

  1. .. _tut-interacting:
  2. **************************************************
  3. Interactive Input Editing and History Substitution
  4. **************************************************
  5. Some versions of the Python interpreter support editing of the current input
  6. line and history substitution, similar to facilities found in the Korn shell and
  7. the GNU Bash shell. This is implemented using the *GNU Readline* library, which
  8. supports Emacs-style and vi-style editing. This library has its own
  9. documentation which I won't duplicate here; however, the basics are easily
  10. explained. The interactive editing and history described here are optionally
  11. available in the Unix and Cygwin versions of the interpreter.
  12. This chapter does *not* document the editing facilities of Mark Hammond's
  13. PythonWin package or the Tk-based environment, IDLE, distributed with Python.
  14. The command line history recall which operates within DOS boxes on NT and some
  15. other DOS and Windows flavors is yet another beast.
  16. .. _tut-lineediting:
  17. Line Editing
  18. ============
  19. If supported, input line editing is active whenever the interpreter prints a
  20. primary or secondary prompt. The current line can be edited using the
  21. conventional Emacs control characters. The most important of these are:
  22. :kbd:`C-A` (Control-A) moves the cursor to the beginning of the line, :kbd:`C-E`
  23. to the end, :kbd:`C-B` moves it one position to the left, :kbd:`C-F` to the
  24. right. Backspace erases the character to the left of the cursor, :kbd:`C-D` the
  25. character to its right. :kbd:`C-K` kills (erases) the rest of the line to the
  26. right of the cursor, :kbd:`C-Y` yanks back the last killed string.
  27. :kbd:`C-underscore` undoes the last change you made; it can be repeated for
  28. cumulative effect.
  29. .. _tut-history:
  30. History Substitution
  31. ====================
  32. History substitution works as follows. All non-empty input lines issued are
  33. saved in a history buffer, and when a new prompt is given you are positioned on
  34. a new line at the bottom of this buffer. :kbd:`C-P` moves one line up (back) in
  35. the history buffer, :kbd:`C-N` moves one down. Any line in the history buffer
  36. can be edited; an asterisk appears in front of the prompt to mark a line as
  37. modified. Pressing the :kbd:`Return` key passes the current line to the
  38. interpreter. :kbd:`C-R` starts an incremental reverse search; :kbd:`C-S` starts
  39. a forward search.
  40. .. _tut-keybindings:
  41. Key Bindings
  42. ============
  43. The key bindings and some other parameters of the Readline library can be
  44. customized by placing commands in an initialization file called
  45. :file:`~/.inputrc`. Key bindings have the form ::
  46. key-name: function-name
  47. or ::
  48. "string": function-name
  49. and options can be set with ::
  50. set option-name value
  51. For example::
  52. # I prefer vi-style editing:
  53. set editing-mode vi
  54. # Edit using a single line:
  55. set horizontal-scroll-mode On
  56. # Rebind some keys:
  57. Meta-h: backward-kill-word
  58. "\C-u": universal-argument
  59. "\C-x\C-r": re-read-init-file
  60. Note that the default binding for :kbd:`Tab` in Python is to insert a :kbd:`Tab`
  61. character instead of Readline's default filename completion function. If you
  62. insist, you can override this by putting ::
  63. Tab: complete
  64. in your :file:`~/.inputrc`. (Of course, this makes it harder to type indented
  65. continuation lines if you're accustomed to using :kbd:`Tab` for that purpose.)
  66. .. index::
  67. module: rlcompleter
  68. module: readline
  69. Automatic completion of variable and module names is optionally available. To
  70. enable it in the interpreter's interactive mode, add the following to your
  71. startup file: [#]_ ::
  72. import rlcompleter, readline
  73. readline.parse_and_bind('tab: complete')
  74. This binds the :kbd:`Tab` key to the completion function, so hitting the
  75. :kbd:`Tab` key twice suggests completions; it looks at Python statement names,
  76. the current local variables, and the available module names. For dotted
  77. expressions such as ``string.a``, it will evaluate the expression up to the
  78. final ``'.'`` and then suggest completions from the attributes of the resulting
  79. object. Note that this may execute application-defined code if an object with a
  80. :meth:`__getattr__` method is part of the expression.
  81. A more capable startup file might look like this example. Note that this
  82. deletes the names it creates once they are no longer needed; this is done since
  83. the startup file is executed in the same namespace as the interactive commands,
  84. and removing the names avoids creating side effects in the interactive
  85. environment. You may find it convenient to keep some of the imported modules,
  86. such as :mod:`os`, which turn out to be needed in most sessions with the
  87. interpreter. ::
  88. # Add auto-completion and a stored history file of commands to your Python
  89. # interactive interpreter. Requires Python 2.0+, readline. Autocomplete is
  90. # bound to the Esc key by default (you can change it - see readline docs).
  91. #
  92. # Store the file in ~/.pystartup, and set an environment variable to point
  93. # to it: "export PYTHONSTARTUP=/home/user/.pystartup" in bash.
  94. #
  95. # Note that PYTHONSTARTUP does *not* expand "~", so you have to put in the
  96. # full path to your home directory.
  97. import atexit
  98. import os
  99. import readline
  100. import rlcompleter
  101. historyPath = os.path.expanduser("~/.pyhistory")
  102. def save_history(historyPath=historyPath):
  103. import readline
  104. readline.write_history_file(historyPath)
  105. if os.path.exists(historyPath):
  106. readline.read_history_file(historyPath)
  107. atexit.register(save_history)
  108. del os, atexit, readline, rlcompleter, save_history, historyPath
  109. .. _tut-commentary:
  110. Commentary
  111. ==========
  112. This facility is an enormous step forward compared to earlier versions of the
  113. interpreter; however, some wishes are left: It would be nice if the proper
  114. indentation were suggested on continuation lines (the parser knows if an indent
  115. token is required next). The completion mechanism might use the interpreter's
  116. symbol table. A command to check (or even suggest) matching parentheses,
  117. quotes, etc., would also be useful.
  118. .. rubric:: Footnotes
  119. .. [#] Python will execute the contents of a file identified by the
  120. :envvar:`PYTHONSTARTUP` environment variable when you start an interactive
  121. interpreter.