Debian Codegraph @

Lib/idlelib/README.txt

raw
1 README.txt: an index to idlelib files and the IDLE menu.
2
3 IDLE is Python's Integrated Development and Learning
4 Environment. The user documentation is part of the Library Reference and
5 is available in IDLE by selecting Help => IDLE Help. This README documents
6 idlelib for IDLE developers and curious users.
7
8 IDLELIB FILES lists files alphabetically by category,
9 with a short description of each.
10
11 IDLE MENU show the menu tree, annotated with the module
12 or module object that implements the corresponding function.
13
14 This file is descriptive, not prescriptive, and may have errors
15 and omissions and lag behind changes in idlelib.
16
17
18 IDLELIB FILES
19 =============
20
21 Implementation files not in IDLE MENU are marked (nim).
22
23 Startup
24 -------
25 __init__.py # import, does nothing
26 __main__.py # -m, starts IDLE
27 idle.bat
28 idle.py
29 idle.pyw
30
31 Implementation
32 --------------
33 autocomplete.py # Complete attribute names or filenames.
34 autocomplete_w.py # Display completions.
35 autoexpand.py # Expand word with previous word in file.
36 browser.py # Create module browser window.
37 calltip.py # Create calltip text.
38 calltip_w.py # Display calltip.
39 codecontext.py # Show compound statement headers otherwise not visible.
40 colorizer.py # Colorize text (nim).
41 config.py # Load, fetch, and save configuration (nim).
42 configdialog.py # Display user configuration dialogs.
43 config_key.py # Change keybindings.
44 debugger.py # Debug code run from shell or editor; show window.
45 debugger_r.py # Debug code run in remote process.
46 debugobj.py # Define class used in stackviewer.
47 debugobj_r.py # Communicate objects between processes with rpc (nim).
48 delegator.py # Define base class for delegators (nim).
49 dynoption.py # Define mutable OptionMenu widget (nim)
50 editor.py # Define most of editor and utility functions.
51 filelist.py # Open files and manage list of open windows (nim).
52 format.py # Define format menu options.
53 grep.py # Find all occurrences of pattern in multiple files.
54 help.py # Display IDLE's html doc.
55 help_about.py # Display About IDLE dialog.
56 history.py # Get previous or next user input in shell (nim)
57 hyperparser.py # Parse code around a given index.
58 iomenu.py # Open, read, and write files
59 macosx.py # Help IDLE run on Macs (nim).
60 mainmenu.py # Define most of IDLE menu.
61 multicall.py # Wrap tk widget to allow multiple calls per event (nim).
62 outwin.py # Create window for grep output.
63 parenmatch.py # Match fenceposts: (), [], and {}.
64 pathbrowser.py # Create path browser window.
65 percolator.py # Manage delegator stack (nim).
66 pyparse.py # Give information on code indentation
67 pyshell.py # Start IDLE, manage shell, complete editor window
68 query.py # Query user for information
69 redirector.py # Intercept widget subcommands (for percolator) (nim).
70 replace.py # Search and replace pattern in text.
71 rpc.py # Communicate between idle and user processes (nim).
72 run.py # Manage user code execution subprocess.
73 runscript.py # Check and run user code.
74 scrolledlist.py # Define scrolledlist widget for IDLE (nim).
75 search.py # Search for pattern in text.
76 searchbase.py # Define base for search, replace, and grep dialogs.
77 searchengine.py # Define engine for all 3 search dialogs.
78 sidebar.py # Define line number and shell prompt sidebars.
79 squeezer.py # Squeeze long shell output (nim).
80 stackviewer.py # View stack after exception.
81 statusbar.py # Define status bar for windows (nim).
82 tabbedpages.py # Define tabbed pages widget (nim).
83 textview.py # Define read-only text widget (nim).
84 tooltip.py # Define popups for calltips, squeezer (nim).
85 tree.py # Define tree widget, used in browsers (nim).
86 undo.py # Manage undo stack.
87 util.py # Define common objects imported elsewhere (nim).
88 windows.py # Manage window list and define listed top level.
89 zoomheight.py # Zoom window to full height of screen.
90 zzdummy.py # Example extension.
91
92 Configuration
93 -------------
94 config-extensions.def # Defaults for extensions
95 config-highlight.def # Defaults for colorizing
96 config-keys.def # Defaults for key bindings
97 config-main.def # Defaults for font and general tabs
98
99 Text
100 ----
101 CREDITS.txt # not maintained, displayed by About IDLE
102 HISTORY.txt # NEWS up to July 2001
103 NEWS.txt # commits, displayed by About IDLE
104 NEWS2.txt # commits to Python2
105 README.txt # this file, displayed by About IDLE
106 TODO.txt # needs review
107 extend.txt # about writing extensions
108 help.html # copy of idle.html in docs, displayed by IDLE Help
109
110 Subdirectories
111 --------------
112 Icons # small image files
113 idle_test # files for human test and automated unit tests
114
115
116 IDLE MENUS
117 ==========
118
119 Top level items and most submenu items are defined in mainmenu.
120 Extensions add submenu items when active. The names given are
121 found, quoted, in one of these modules, paired with a '<<pseudoevent>>'.
122 Each pseudoevent is bound to an event handler. Some event handlers
123 call another function that does the actual work. The annotations below
124 are intended to at least give the module where the actual work is done.
125 'eEW' = editor.EditorWindow
126
127 File
128 New File # eEW.new_callback
129 Open... # iomenu.open
130 Open Module # eEw.open_module
131 Recent Files
132 Class Browser # eEW.open_class_browser, browser.ClassBrowser
133 Path Browser # eEW.open_path_browser, pathbrowser
134 ---
135 Save # iomenu.save
136 Save As... # iomenu.save_as
137 Save Copy As... # iomenu.save_a_copy
138 ---
139 Print Window # iomenu.print_window
140 ---
141 Close # eEW.close_event
142 Exit # flist.close_all_callback (bound in eEW)
143
144 Edit
145 Undo # undodelegator
146 Redo # undodelegator
147 --- # eEW.right_menu_event
148 Cut # eEW.cut
149 Copy # eEW.copy
150 Paste # eEW.past
151 Select All # eEW.select_all (+ see eEW.remove_selection)
152 --- # Next 5 items use searchengine; dialogs use searchbase
153 Find # eEW.find_event, search.SearchDialog.find
154 Find Again # eEW.find_again_event, sSD.find_again
155 Find Selection # eEW.find_selection_event, sSD.find_selection
156 Find in Files... # eEW.find_in_files_event, grep
157 Replace... # eEW.replace_event, replace.ReplaceDialog.replace
158 Go to Line # eEW.goto_line_event
159 Show Completions # autocomplete extension and autocompleteWidow (&HP)
160 Expand Word # autoexpand extension
161 Show call tip # Calltips extension and CalltipWindow (& Hyperparser)
162 Show surrounding parens # parenmatch (& Hyperparser)
163
164 Format (Editor only) [fFR = format.FormatRegion]
165 Format Paragraph # format.FormatParagraph.format_paragraph_event
166 Indent Region # fFR.indent_region_event
167 Dedent Region # fFR.dedent_region_event
168 Comment Out Reg. # fFR.comment_region_event
169 Uncomment Region # fFR.uncomment_region_event
170 Tabify Region # fFR.tabify_region_event
171 Untabify Region # fFR.untabify_region_event
172 Toggle Tabs # format.Indents.toggle_tabs_event
173 New Indent Width # format.Indents.change_indentwidth_event
174 Strip tailing whitespace # format.rstrip
175 Zin # zzdummy
176 Zout # zzdummy
177
178 Run (Editor only)
179 Run Module # runscript.ScriptBinding.run_module_event
180 Run... Customized # runscript.ScriptBinding.run_custom_event
181 Check Module # runscript.ScriptBinding.check_module_event
182 Python Shell # pyshell.Pyshell, pyshell.ModifiedInterpreter
183
184 Shell # pyshell
185 View Last Restart # pyshell.PyShell.view_restart_mark
186 Restart Shell # pyshell.PyShell.restart_shell
187 Previous History # history.History.history_prev
188 Next History # history.History.history_next
189 Interrupt Execution # pyshell.PyShell.cancel_callback
190
191 Debug (Shell only)
192 Go to File/Line # outwin.OutputWindow.goto_file_line
193 debugger # debugger, debugger_r, PyShell.toggle_debugger
194 Stack Viewer # stackviewer, PyShell.open_stack_viewer
195 Auto-open Stack Viewer # stackviewer
196
197 Options
198 Configure IDLE # eEW.config_dialog, config, configdialog (cd)
199 (Parts of the dialog)
200 Buttons # cd.ConfigDialog
201 Font tab # cd.FontPage, config-main.def
202 Highlight tab # cd.HighPage, query, config-highlight.def
203 Keys tab # cd.KeysPage, query, config_key, config_keys.def
204 Windows tab # cd.WinPage, config_main.def
205 Shell/Ed tab # cd.ShedPage, config-main.def
206 Extensions tab # config-extensions.def, corresponding .py files
207 ---
208 ... Code Context # codecontext
209 ... Line Numbers # sidebar
210 Zoomheight # zoomheight
211
212 Window
213 <open windows> # windows
214
215 Help
216 About IDLE # eEW.about_dialog, help_about.AboutDialog
217 ---
218 IDLE Help # eEW.help_dialog, help.show_idlehelp
219 Python Docs # eEW.python_docs
220 Turtle Demo # eEW.open_turtle_demo
221 ---
222 <other help sources>
223
224 <Context Menu> (right click)
225 Defined in editor, PyShell.pyshell
226 Cut
227 Copy
228 Paste
229 ---
230 Go to file/line (shell and output only)
231 Set Breakpoint (editor only)
232 Clear Breakpoint (editor only)
233 Defined in debugger
234 Go to source line
235 Show stack frame
236
237 <No menu>
238 Center Insert # eEW.center_insert_event
239
240
241 OTHER TOPICS
242 ============
243
244 Generally use PEP 8.
245
246 import statements
247 -----------------
248 Put imports at the top, unless there is a good reason otherwise.
249 PEP 8 says to group stdlib, 3rd-party dependencies, and package imports.
250 For idlelib, the groups are general stdlib, tkinter, and idlelib.
251 Sort modules within each group, except that tkinter.ttk follows tkinter.
252 Sort 'from idlelib import mod1' and 'from idlelib.mod2 import object'
253 together by module, ignoring within module objects.
254 Put 'import __main__' after other idlelib imports.
255
256 Imports only needed for testing are put not at the top but in an
257 htest function def or "if __name__ == '__main__'" clause.
258
259 Within module imports like "from idlelib.mod import class" may cause
260 circular imports to deadlock. Even without this, circular imports may
261 require at least one of the imports to be delayed until a function call.
262
263 What's New entries
264 ------------------
265
266 Repository directory Doc/whatsnew/ has a file 3.n.rst for each 3.n
267 Python version. For the first entry in each file, add subsection
268 'IDLE and idlelib', in alphabetical position, to the 'Improved Modules'
269 section. For the rest of cpython, entries to 3.(n+1).rst begin with
270 the release of 3.n.0b1. For IDLE, entries for features backported from
271 'main' to '3.n' during its beta period do not got in 3.(n+1).rst. The
272 latter usually gets its first entry during the 3.n.0 candidate period
273 or after the 3.n.0 release.
274
275 When, as per PEP 434, feature changes are backported, entries are placed
276 in the 3.n.rst file *in the main branch* for each Python version n that
277 gets the backport. (Note: the format of entries have varied between
278 versions.) Add a line "New in 3.n maintenance releases." before the
279 first back-ported feature after 3.n.0 is released. Since each older
280 version file gets a different number of backports, it is easiest to
281 make a separate PR for each file and label it with the backports
282 needed.
283
284 Github repository and issues
285 ----------------------------
286
287 The CPython repository is https://github.com/python/cpython. The
288 IDLE Issues listing is https://github.com/orgs/python/projects/31.
289 The main classification is by Topic, based on the IDLE menu. View the
290 topics list by clicking the [<]] button in the upper right.