NEWS 37.5 KB
Newer Older
1
2
Python Mode News
================
3

4
5
6
7
8
New in version 6.3.1
-----------------------

Minor bugfixes

Andreas Röhler's avatar
Andreas Röhler committed
9
New in version 6.3.0
10
-----------------------
11

12
13
14
15
16
- <RET> and <C-j> normalized/swapped

  <RET> now defaults to ‘py-newline-and-indent’
  <C-j> is set to ‘newline’

17
- New commands:
Andreas Röhler's avatar
Andreas Röhler committed
18
  py-prettyprint-assignment
19
20
  py-toggle-py-split-window-on-execute
  py-toggle-session-mode
Andreas Röhler's avatar
Andreas Röhler committed
21
22
23
  py-show
  py-show-all
  py-hide-section
24
25
  py-fast-send-string
  py-toggle-py-verbose-p
26
  py-execute-buffer-fast
27

28
29
30
31
32
33
34
  py-show-FORM commands replaced by single ‘py-show’

- column-marker.el removed, its provided by melpa

- py-smart-indentation defaults to nil. Setting it to `t' considered
  useful if customizing `py-indent-offset' is no option - for example
  if indentation step is unknown.
35

36
37
- ‘py-comment-auto-fill’ renamed ‘py-toggle-comment-auto-fill’

Andreas Röhler's avatar
Andreas Röhler committed
38
39
40
New in version 6.2.3
---------------------

Andreas Röhler's avatar
Andreas Röhler committed
41
42
43
Commands saying "up" reach one level less indented than start of
current form

Andreas Röhler's avatar
Andreas Röhler committed
44
45
46
47
48
49
New customizable `py-shell-fontify-style' offers some choice
how to fontify py-shell buffer:

"input" will leave previous IN/OUT unfontified.
"all" keeps output fontified too.

Andreas Röhler's avatar
Andreas Röhler committed
50
Default is nil, no fontification.
51

52
53
54
New in version 6.2.2
---------------------

55
Edit-commands will reach beginning-of-line if reasonable
56
Edit-commands suffixed "-bol" dropped
57

Andreas Röhler's avatar
Andreas Röhler committed
58
59
60
61
62
- Commands
  - py-backward-indent
    Go to the beginning of a section of equal indent
  - py-forward-indent
    Go to the end of a section of equal indentation
63
64
  - py-copy-indent
  - py-delete-indent
65
  - py-kill-indent
Andreas Röhler's avatar
Andreas Röhler committed
66
  - py-mark-indent
67
  - py-comment-indent
68
69
  - py-shift-indent-left
  - py-shift-indent-right
70
71
  - py-hide-indent
  - py-show-indent
Andreas Röhler's avatar
Andreas Röhler committed
72

73
74
75
- Make $PYTHONPATH configurable from Emacs
  Emacs doesn't read settings from .bashrc

76
77
- py-indent-paren-spanned-multilines-p new default `t'

78
79
80
New in version 6.2.1
---------------------

Andreas Röhler's avatar
Andreas Röhler committed
81
82
83
- Handle PEP 492 async coroutines

- Logic of py-indent-region WRT lp:1426903
84
85
86
87
88
  In case first line accepts an indent,
  keep the remaining lines' relative.
  Otherwise lines in region get outmost indent,
  same with optional argument

89
- Commands
90
91
92
93
  - py-match-paren
    If at a beginning, jump to end and vice versa.
    Matches lists, block, statement, string and comment

94
95
96
  - ipython2.7
  - ipython3

97
98
  - py-beginning-of-for-block
  - py-beginning-of-for-block-bol
99
100
101
  - py-end-of-statement-bol
  - py-end-of-top-level-bol

102
103
  - py-flycheck-mode - toggle `flycheck-mode' from menu "Checks"

104
105
106
107
108
109
110
111
112
  - py-execute-section - execute arbitrary chunks of code
  - py-execute-section-python
  - py-execute-section-python2
  - py-execute-section-python3
  - py-execute-section-ipython
  - py-execute-section-ipython2.7
  - py-execute-section-ipython3
  - py-execute-section-jython

113
114
115
116
  - py-sectionize-region
  - py-backward-section
  - py-forward-section

117
118
119
120
121
122
123
  - py-narrow-to-block
  - py-narrow-to-block-or-clause
  - py-narrow-to-class
  - py-narrow-to-clause
  - py-narrow-to-def
  - py-narrow-to-def-or-class
  - py-narrow-to-statement
124

125
126
127
128
129
130
131
132
133
- New helper functions, like
  - py--end-of-block-bol-p
  - py--end-of-clause-bol-p
  etc.

  Functions in a boolean sense just stating if being at an end or
  start no longer a command. Renamed as interanal
  functions with prefix `py--' now.

134
- TAB-indent from column zero: go to outmost first, lp:1375122
135
- (I)Python-shell setup made more reliable
136

Andreas Röhler's avatar
Andreas Röhler committed
137
138
New customizables:

139
140
141
- py-imenu-max-items, default is 99
  Sets `imenu-max-items'

142
143
- py-python-edit-version, default is ""
  When not empty, fontify according to Python version specified.
144

Andreas Röhler's avatar
Andreas Röhler committed
145
146
147
148
149
150
- py-pdb-executable, default is nil
  Indicate PATH/TO/pdb.

- py-update-gud-pdb-history-p, default is t
  If pdb should provide suggestions WRT file and pdb-path.

151
- py-split-window-on-execute-threshold, default is 3
152
  Don't split when max number of displayed windows is reached.
153

154
155
Renamed:
- py-beginning-of-commented-section --> py-beginning-of-comments
156
- py-narrow-to-defun --> py-narrow-to-def
157

Andreas Röhler's avatar
Andreas Röhler committed
158
New in version 6.2.0
159
160
---------------------

161
162
163
164
165
166
167
168
169
170
171
172
- Support for large output
  new commands py-fast-process, py-fast-...
  Fixes: large output makes Emacs freeze, lp:1253907

  Python code now might be processed by an
  - interactive Python shell (DEFAULT)
  - non-interactive Python (`py-fast-process-p', if large output)

  Both processes might run in
  - session, i.e. start from possible previous state (DEFAULT)
  - dedicated, (`py-dedicated-process-p', run in separate process)

173
174
175
176
- TAB bound to `py-indent-or-complete', completes at EOL.
  Calls to `tab-to-tab-stop' removed, as these would conflict.
  Use `C-q TAB' to insert a literally TAB-character.

177
- py-fast-complete
Andreas Röhler's avatar
Andreas Röhler committed
178
  Complete word before point, if any, use `py-fast-process'
179

Andreas Röhler's avatar
Andreas Röhler committed
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
- `py-shell-complete-or-indent'
  In shell: complete or indent depending on the context.
  If cursor is at current-indentation and further indent
  seems reasonable, indent. Otherwise try to complete.

- Python specific hide-show
  py-hide-region
  py-show-region
  py-hide-statement
  py-show-statement
  py-hide-block
  py-show-block
  py-hide-clause
  py-show-clause
  py-hide-block-or-clause
  py-show-block-or-clause
  py-hide-def
  py-show-def
  py-hide-class
  py-show-class
  py-hide-expression
  py-show-expression
  py-hide-partial-expression
  py-show-partial-expression
  py-hide-line
  py-show-line
  py-hide-top-level
  py-show-top-level
208

209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
- `py-shell' uses new `py-shell-mode', `py-shell-mode-map'
  M-x describe-mode RET mentions edit available commands
  Menu "Py-Shell"

- Improved customization of Python2, Python3, IPython executables
  receive defaults depending from system
  py-python-command - defaults to python2
  py-python2-command
  py-python3-command
  py-ipython-command

  py-python-command-args
  py-python2-command-args
  py-python3-command-args
  py-ipython-command-args

225
226
227
228
229
- info-lookup-symbol made working with Python
  patched python-info.el available at
  https://bitbucket.org/andreas_roehler/pydoc-info
  See also INSTALL-INFO-FILES

Andreas Röhler's avatar
Andreas Röhler committed
230
231
232
233
234
- `py-backward-same-level'
  While `py-up' will go upward from beginning of block, this travels
  same level, but goes up if no element left in level.  If callled
  from inside a string or list, go to its beginning.

Andreas Röhler's avatar
Andreas Röhler committed
235
- `py-kill-shell-unconditional'
236
237
238
  With optional argument SHELL, otherwise kill default
  (I)Python shell.

239
240
241
- py-info-lookup-symbol ()
  Calls `info-lookup-symbol'. Sends help if stuff is missing.

242
- py-toggle-split-window-function
243
244
  If window is splitted vertically or horizontally.
  Sets customizable variable
245
  `py-split-window-on-execute-function'
246
247
  Also in menu Python/Customize/Switches/Display/Which split windows

248
249
250
- py-symbol-at-point
  Return the Python symbol under cursor

251
252
253
- py-report-comint-variable-setting
  Display Py-shell' comint-mode variables of interest.

254
- variables-state
255
  Diplays state of python-mode variables in an org-mode buffer
256

257
258
259
- py-kill-buffer-unconditional
  Kill buffer unconditional; kill also any buffer-process.

260
Setting docstring style simplified; a style is all needed.
Andreas Röhler's avatar
Andreas Röhler committed
261
  New commands
262
263
264
265
266
267
268
 -py-set-nil-docstring-style
 -py-set-pep-257-nn-docstring-style
 -py-set-pep-257-docstring-style
 -py-set-django-docstring-style
 -py-set-symmetric-docstring-style
 -py-set-onetwo-docstring-style

269
270
271
272
- new indent feature/behavior, lp:1280982
  If an empty line was dedented deliberatly, this is
  honored by next lines indent

273
- py-object-reference-face
274
275
276
277
278
  commonly "self" or "cls", inherits default face

- py-error
  In case of error, list messages from Python process

279
280
281
282
283
284
285
- `py-split-windows-on-execute-p' renamed `py-split-window-on-execute'
  Not a boolean any more, new option 'just-two: When code is send to
  interpreter, split screen into source-code buffer and current
  --maybe reused-- py-shell.  When set to `t' --default--, python-mode
  will keep existing windows and split only if needed. Alternatively
  if a multitude of python-shells/buffers should be visible, open them
  manually and set `py-keep-windows-configuration' to `t'.
286

287
288
  If `always' split according to settings of `split-height-threshold', `split-width-threshold'; with `t' keep just two windows

289
290
291
292
293
294
295
296
297
298
299
300
301
302
- For completeness some commands user might expect
  py-execute-statement-dedicated
  py-execute-block-dedicated
  py-execute-clause-dedicated
  py-execute-block-or-clause-dedicated
  py-execute-def-dedicated
  py-execute-class-dedicated
  py-execute-region-dedicated
  py-execute-buffer-dedicated
  py-execute-expression-dedicated
  py-execute-partial-expression-dedicated
  py-execute-line-dedicated
  py-execute-top-level-dedicated

303
304
- `py-unload-python-el'
  Normally commands delivered by python.el are usable alongside with
305
306
  python-mode.el. Some old version of python.el might write skeletons into
  python-mode-abbrev-table, which is removed that way.
307

308
309
310
311
Internally used functions preferably are prefixed `py--':
  py--statement-opens-block-p
  py--statement-opens-clause-p ...

312
313
New variable `py-ipython-command' - (PATH-TO)-IPython

314
Boolean `py-set-fill-column-p' renamed `py-auto-fill-mode'
315
316
317
 Fill according to `py-docstring-fill-column' and
`py-comment-fill-column'

318
319
320
`py-font-lock-keywords' renamed `python-font-lock-keywords',
  lp:1314921

321
New booleans
322
- py-fast-process-p
323
324
  If `t', stuff is executed through `py-fast-...'-
  commands, suitable for large output. Result arrives
325
  in py-fast-output-buffer, which is not in comint-mode
326

327
328
- py-shell-manage-windows-p
  If `t', open output buffers, split windows according to settings of
329
  `py-split-window-on-execute' and `py-switch-buffers-on-execute-p'.
330

Andreas Röhler's avatar
Andreas Röhler committed
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
Removed commands
 -toggle-py-nil-docstring-style
 -py-nil-docstring-style-on
 -py-nil-docstring-style-off
 -toggle-py-onetwo-docstring-style
 -py-onetwo-docstring-style-on
 -py-onetwo-docstring-style-off
 -toggle-py-pep-257-docstring-style
 -py-pep-257-docstring-style-on
 -py-pep-257-docstring-style-off
 -toggle-py-pep-257-nn-docstring-style
 -py-pep-257-nn-docstring-style-on
 -py-pep-257-nn-docstring-style-off
 -toggle-py-symmetric-docstring-style
 -py-symmetric-docstring-style-on
 -py-symmetric-docstring-style-off
 -toggle-py-django-docstring-style
 -py-django-docstring-style-on
 -py-django-docstring-style-off
  Some commands not so useful made common functions, like
 -py-statement-opens-block-p
 -py-statement-opens-clause-p ...

354
Dropped booleans:
355
`py-start-run-py-shell',
356
357
`py-start-run-ipython-shell',
`py-pylint-offer-current-p'
358
`py-paragraph-fill-docstring-p'
359
`py-enforce-output-buffer-p'
360
`py-cleanup-temporary', as redundant WRT `py-debug-p'
361

362
363
364
New in version 6.1.3
---------------------

365
PEP8 indent-alternatives when closing a list implemented
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389

Boolean `py-close-at-start-column-p', default is nil

my_list = [
    1, 2, 3,
    4, 5, 6,
    ]
result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
    )

When non-nil, it will be lined up under the first character of the line that starts the multi-line construct, as in:

my_list = [
    1, 2, 3,
    4, 5, 6,
]

result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
)

390
391
392
393
394
395
396
397
398
399
- Keys C-M-a, C-M-e usable for all top-level form, lp:1191078

  Boolean `py-defun-use-top-level-p'
  If non-nil, beginning- end-of-defun forms will use
  `py-beginning-of-top-level', `py-end-of-top-level',
  mark-defun marks top-level form at point etc.

Keys C-M-a, C-M-e usable for all top-level form, lp:1191078

- New commands:
400
401
402
  py-beginning-of-block-current-column
  "Reach the beginning of block which starts at current column "

403
404
405
406
407
408
409
410
411
412
413
  py-beginning-of-top-level
  py-beginning-of-top-level
  py-end-of-top-level
  py-mark-top-level
  py-copy-top-level
  py-delete-top-level
  py-kill-top-level
  py-execute-top-level
  py-top-level-form-p
  py-comment-top-level
  py-beginning-of-top-level-p
414

Andreas Röhler's avatar
Andreas Röhler committed
415
416
417
418
- `minor-block' commands added
  A minor block is started by a `for', `if', `try' or `with',
  while block covers also `def' or `class'

Andreas Röhler's avatar
Andreas Röhler committed
419
420
421
422
423
424
425
426
427
428
- variable `py-keep-windows-configuration', default is nil
  Setting `py-keep-windows-configuration' to `t' will
  restore windows-configuration regardless of
  `py-switch-buffers-on-execute-p' and
  `py-split-windows-on-execute-p' settings. However, if
  an error occurs, it's displayed.

  To suppres window-changes due to error-signaling
  also, set `py-keep-windows-configuration' onto 'force

429
- boolean empty-line-closes-p, default is nil
430
431
432
433
434
435
436
  When non-nil, dedent after empty line following block
  If non-nil, a C-j from empty line would dedent.

  if True:
      print("Part of the if-statement")

  print("Not part of the if-statement")
437

438
439
440
441
442
- boolean py-debug-p, default is nil
  When non-nil, keep resp. store information useful for
  debugging. Temporary files are not deleted. Other
  functions might implement some logging etc.

443
444
445
446
447
448
- heuristic exit
  new var `py-max-specpdl-size', default is `max-specpdl-size'
  py-end-of-statement will error if number of
  `py-max-specpdl-size' loops is completed, thus avoiding
  a hang from a possibly eternal loop.

449
450
- `py-statement' no longer refferred to `py-copy-statement'
  Same with block, def, expression etc. `py-statement' made
451
452
453
454
  own command, which returns statement, a string.

- boolean `py-max-help-buffer-p', default is nil
  If "*Python-Help*"-buffer be the only visible.
455

456
457
New in version 6.1.2
---------------------
Andreas Röhler's avatar
Andreas Röhler committed
458
- simplified menu
459

460
- `py-execute-...'-commands return result as string
461
  Controlled by boolean `py-store-result-p', Default is nil
462
  When non-nil, put resulting string of `py-execute-...' into kill-ring, so it might be yanked.
463

464
465
466
467
468
469
- commands deleting all commented lines:
  `py-delete-comments-in-def-or-class'
  `py-delete-comments-in-class'
  `py-delete-comments-in-block'
  `py-delete-comments-in-region'

470
- boolean `py-indent-paren-spanned-multilines-p, default is nil
471
  If non-nil, indents elements of list a value of `py-indent-offset' to first element:
472
473
474
475
476
477
478
479
480
481
482
483
484
  def foo():
      if (foo &&
              baz):
          bar()

  Default lines up with first element:

  def foo():
      if (foo &&
          baz):
          bar()

- `py-output-buffer' made customizable
485
  See boolean `py-enforce-output-buffer-p'
486
487
488

- exceptions following executed regions made point to source

489
-  command `py-empty-out-list-backward'
490
  Deletes all elements from list before point
491
  With when cursor after
492
493
  mystring[0:1]
  -------------^
494
  ==>
495
496
497
498
  mystring[]
  ---------^
  In result cursor is insided emptied delimited form."

499
500
501
- `py-minor-expression' reconsidered, numeric args dropped
  grasps keyword-arguments

502
503
504
505
- boolean `py-electric-kill-backward-p', default is nil.
  If behind a delimited form of braces, brackets or parentheses,
  `py-electric-backspace' runs `py-empty-out-list-backward'

506
- py-flake8-run, flake8 API
507

508
- customizable `py-backslashed-lines-indent-offset'
509

510
- boolean `py-pylint-offer-current-p'
Andreas Röhler's avatar
Andreas Röhler committed
511
512
513
  If current buffers file should be offered for check.
  Otherwise `py-pylint-run' looks up filename from history

514
515
516
517
518
- boolean `py-prompt-on-changed-p'
  When called interactively, ask for save before a
  changed buffer is sent to interpreter.

- customizable `py-closing-list-space'
519
520
  Number of chars, closing parentesis outdent from opening

521
- customizable `py-uncomment-indents-p'
Andreas Röhler's avatar
Andreas Röhler committed
522
523
  When non-nil, after uncomment indent lines.

524
- boolean `py-load-skeletons-p'
525
526
  If skeleton definitions should be loaded

527
- boolean `py-if-name-main-permission-p'
528
529
530
  Allows execution of code inside blocks started by
  if __name__== '__main__'

531
532
533
534
- boolean `py-highlight-error-source-p', default is nil
  When py-execute-... commands raise an error, respective code in source-buffer will be highlighted.

- `py-remove-overlays-at-point', command
535
  Remove overlays as set when `py-highlight-error-source-p' is non-nil.
536

537
- `py-which-def-or-class', command, now used `which-function-mode'
538
539
540

- unused variable `py-backspace-function' removed

541
542
543
- Bundled third-party-stuff removed as reported conflicting at emacs-mirror, lp:1153998
  affects autopair.el, smart-operator.el
  Kept  menu switches resp. commands will issue a warning
544

Andreas Röhler's avatar
Andreas Röhler committed
545
546
- dropped `py-paragraph-fill-docstring-p'; just `fill-paragraph' should DTRT

547
548
549
- `py-set-pager-cat-p', default is nil
   If non-nil, $PAGER is set to 'cat'

550
- in directory doc customizable variables are listed:
551
552
  variables-python-mode.org, variables-python-mode.rst

553
554
555
New in version 6.1.1
---------------------

556
- comment-related commands:
557
  py-uncomment
558
559
560
561
562
  py-comment-block, py-comment-clause,
  py-comment-block-or-clause, py-comment-def,
  py-comment-class, py-comment-def-or-class,
  py-comment-statement

563
564
565
566
- boolean `py-set-fill-column-p'
  If `t', enables use Python specific `fill-column' according to
  `py-docstring-fill-column', default is 72
  and `py-comment-fill-column, default is 79
567

568
569
570
- boolean `py-tab-shifts-region-p'
  when `t', TAB will indent/cycle the region, not just the current line.

571
- boolean `py-tab-indents-region-p'
572
  when `t', when first TAB doesn't shift, `indent-region' is called
573

574
575
576
- command from RET customizable via `py-return-key':
  `py-newline-and-indent', `newline' or `py-newline-and-dedent'

577
- boolean `py-use-font-lock-doc-face-p', default is nil
578
579
  If non-nil, documention strings get `font-lock-doc-face'

580
- boolean `py-newline-delete-trailing-whitespace-p'
581
582
  Delete trailing whitespace maybe left by `py-newline-and-indent'

583
584
- `py-electric-comment-p' new default nil

Andreas Röhler's avatar
Andreas Röhler committed
585
586
587
588
589
590
591
- py-up minor API change
  If inside a delimited form --string or list-- go to it's beginning
  If not at beginning of a statement or block, go to it's beginning
  If at beginning of a statement or block, go to beginning one level above of c

- py-down minor API change:
  Go to beginning of one level below of compound statement or definition at point.
592
  If no statement or block below, but a delimited form --string or list-- go to it's beginning.
Andreas Röhler's avatar
Andreas Röhler committed
593
594
  Repeated call from there will behave like down-list.

595
596
597
598
599
- commands make underscore syntax changes easier:
  toggle-py-underscore-word-syntax-p
  py-underscore-word-syntax-p-on
  py-underscore-word-syntax-p-off

Andreas Röhler's avatar
Andreas Röhler committed
600
601
- py-update-imports removed
  Do not maintain a static variable containing needed imports
Andreas Röhler's avatar
Andreas Röhler committed
602
  Determine imports on the fly rather, as it might have changed
Andreas Röhler's avatar
Andreas Röhler committed
603

604
605
- variable `py-fill-docstring-style' renamed `py-docstring-style'

606
607
608
New in version 6.1.0
---------------------

609
- py-up
Andreas Röhler's avatar
Andreas Röhler committed
610
611
612
613
  Go to beginning one level above of compound statement or definition at point.
- py-down
  Go to beginning one level below of compound statement or definition at point.

614
- Customizable output directory
615
616
617
618
619
620
621
622
623
624
625
626
627
628
  After checking for a remote shell, the following variables are consulted:

  py-use-current-dir-when-execute-p, default t
  When `t', current directory is used by Python-shell for output of `py-execute-buffer' and related commands

  py-fileless-buffer-use-default-directory-p, default t
  When `py-use-current-dir-when-execute-p' is non-nil and no buffer-file exists, value of `default-directory' sets current working directory of Python output shell"

  py-keep-shell-dir-when-execute-p, default nil
  Don't change Python shell's current working directory when sending code.

  `py-execute-directory', default nil

  If nothing was set so far, $VIRTUAL_ENV and $HOME are queried.
629

Andreas Röhler's avatar
Andreas Röhler committed
630
- Set of commands calling Python3.3
Andreas Röhler's avatar
Andreas Röhler committed
631

632
- fill docstrings according to style, commands
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
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
  py-fill-string-django
  py-fill-string-onetwo
  py-fill-string-pep-257
  py-fill-string-pep-257-nn
  py-fill-string-symmetric

  Customizable variable `py-fill-docstring-style' provides default value
  used by `py-fill-string', `py-fill-paragraph'

  DJANGO:

      \"\"\"
      Process foo, return bar.
      \"\"\"

      \"\"\"
      Process foo, return bar.

      If processing fails throw ProcessingError.
      \"\"\"

  ONETWO:

      \"\"\"Process foo, return bar.\"\"\"

      \"\"\"
      Process foo, return bar.

      If processing fails throw ProcessingError.

      \"\"\"

  PEP-257:

      \"\"\"Process foo, return bar.\"\"\"

      \"\"\"Process foo, return bar.

      If processing fails throw ProcessingError.

      \"\"\"

  PEP-257-NN:

      \"\"\"Process foo, return bar.\"\"\"

      \"\"\"Process foo, return bar.

      If processing fails throw ProcessingError.
      \"\"\"

  SYMMETRIC:

      \"\"\"Process foo, return bar.\"\"\"

      \"\"\"
      Process foo, return bar.

      If processing fails throw ProcessingError.
      \"\"\""

  Built upon code seen at python.el, thanks Fabian

696
- `py-down-statement', `py-up-statement'
697

698
699
700
701
702
703
704
705
- toggle-py-split-windows-on-execute-p
- py-split-windows-on-execute-p-off
- py-split-windows-on-execute-p-on

- toggle-py-switch-buffers-on-execute-p
- py-switch-buffers-on-execute-p-on
- py-switch-buffers-on-execute-p-off

706
707
- `py-shell-switch-buffers-on-execute-p' renamed `py-switch-buffers-on-execute-p'

708
709
710
New in version 6.0.12
---------------------

711
- py-sexp-function,
712
713
714
715
716
717
  When set, it's value is called instead of `forward-sexp', `backward-sexp
  Choices are py-partial-expression, py-expression, default nil

- `py-partial-expression' reconsidered.
   Beside common moves like `defun', `statement' specific Python-mode edits are delivered:

718
  `py-expression' and `py-partial-expression'.
719

720
  Statement below is considered composed of two `py-expression'
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736

  a = ['spam', 'eggs', 100, 1234]
  |_| |_________________________|

  Assigment operator and all inside comments is ignored.

  `py-partial-expression' would match six sections

   a = ['spam', 'eggs', 100, 1234]
  |_|   |_____|  |____| |__| |__|
       |_________________________|

  When traversing code, `py-partial-expression' climbs down and up
  all levels encountered, i.e. at opening `[' `py-expression' would return ['spam', 'eggs', 100, 1234], while one char behind at `''
  it yields `'spam','

737
738
- `py-find-definition' also detects non-imported definition in current buffer

739
- Choice between `py-imenu-create-index-new' and series 5.
740
741
742
  py-imenu-create-index-function made easier.
  Customizable variable `py-imenu-create-index-function' provided, see also
  command in PyTools
743

744
745
746
747
748
749
750
751
- New commands addressing BOL as start/end:
  py-beginning-of-block-bol
  py-end-of-block-bol
  py-mark-block-bol
  py-copy-block-bol
  py-kill-block-bol
  py-delete-block-bol
  py-end-of-clause-bol
Andreas Röhler's avatar
Andreas Röhler committed
752
753
  etc.

754
- While commands "py-beginning..." resp. "py-end..." compute the context,
Andreas Röhler's avatar
Andreas Röhler committed
755
  selecting the corresponding beginning or end,
756
  new "py-up...", "py-down..." jump regexp-based to the
Andreas Röhler's avatar
Andreas Röhler committed
757
  next element in buffer.
758
  See also menu PyEdit.
759

Andreas Röhler's avatar
Andreas Röhler committed
760
761
762
New in version 6.0.11
---------------------

763
764
765
766
767
768
769
770
771
772
773
774
- improved Pymacs based code completion:
  - Completion of symbols from imported modules, functions, classes,
    module/class-level data members and instance variables in the current
    buffer. The information for this completion is updated whenever the file
    is saved.
  - Completion of local variables and function parameters.
  - Type deduction from constructor calls and literals.
  - Show help for modules, classes and functions.
  - Go to definition of modules, classes and functions.
  - Show signature of functions.
  - Support for auto-complete and company.

Andreas Röhler's avatar
Andreas Röhler committed
775
- remote shell support
776

777
778
779
780
781
782
783
784
785
- extended version of smart-operator added
  original smart-operator.el authored by
  William Xu <william.xwl@gmail.com>
  Url: http://xwl.appspot.com/ref/smart-operator.el

- py-electric-colon extended
  if `py-electric-colon-newline-and-indent-p' is non-nil,
  `py-electric-colon' calls `newline-and-indent'

786
787
788
789
790
- boolean `py-no-completion-calls-dabbrev-expand-p'
  If completion function should call dabbrev-expand
  when no completion found. Default is `t'

- boolean `py-shell-prompt-read-only', default t
791
  sets `comint-prompt-read-only', avoid unintentional edits
792
793
794
795
796
797
798

- customizable history variables/files
  py-python-history defaults to "~/.python_history"
  py-ipython-history defaults to "~/.ipython/history"

  If py-honor-PYTHONHISTORY-p is `t', $PYTHONHISTORY takes precedence, default is nil
  If py-honor-IPYTHONDIR-p is `t', $IPYTHONHISTORY precedes, default is nil
799
800
801
802

- customizable boolean `py-trailing-whitespace-smart-delete-p'
  Default is nil. Some commands may delete trailing
  whitespaces by the way. When editing other peoples
803
  code, this may produce a larger diff than expected
804

Andreas Röhler's avatar
Andreas Röhler committed
805
806
807
808
809
New in version 6.0.10
--------------------

addresses bugs and speed issues

810
811
812
813
814
815
816
New in version 6.0.9
--------------------

- autopair-mode delivered
  Credits to Joao Tavora http://autopair.googlecode.com
  see README-AUTOPAIR.org for details

817
818
819
- Syntax highlighting in Python-shell buffers enabled
  boolean `py-fontify-shell-buffer-p', default is nil

Andreas Röhler's avatar
Andreas Röhler committed
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
- py-add-abbrev, new command
  Similar to `add-mode-abbrev', but uses
  `py-partial-expression' before point for expansion to
  store, not `word'. Also provides a proposal for new
  abbrevs.

  Proposal for an abbrev is composed from the downcased
  initials of expansion - provided they are of char-class
  [:alpha:]

  For example code below would be recognised as a
  `py-expression' composed by three
  py-partial-expressions.

  OrderedDict.popitem(last=True)

  Putting the curser at the EOL, M-3 M-x py-add-abbrev

  would prompt "op" for an abbrev to store, as first
  `py-partial-expression' beginns with a "(", which is
  not taken as proposal.

842
- py-edit-abbrevs
843
  Jumps to `python-mode-abbrev-table'
844

Andreas Röhler's avatar
Andreas Röhler committed
845
846
847
848
- modeline enhanced
  when a path/to/my/favoured/Python is given with `py-shell-name'
  the Python-shell buffer before would display

849
  *ND path/to/my/favoured/Python*
Andreas Röhler's avatar
Andreas Röhler committed
850
851
852
853
854

  now:

  *ptmfP Python*

855
856
  boolean `py-modeline-display-full-path-p'
  boolean `py-modeline-acronym-display-home-p'
Andreas Röhler's avatar
Andreas Röhler committed
857
858
  If the modeline acronym should contain chars indicating the home-directory.

859
- mode-line indicates "Py" by default
860
  customize  `python-mode-modeline-display'
861

862
863
- Pymacs intergration dropped from trunk
  conflicts with classic install being reported
864

865
New in version 6.0.8
866

867
868
--------------------

869
- `py-pep8-run', new command checking formatting
870
   `py-pep8-help'
871

872
- `py-pyflake-run', new command
Andreas Röhler's avatar
Andreas Röhler committed
873
874
875
876
   Pyflakes is a simple program which checks Python
   source files for errors. - It is similar to
   PyChecker in scope, but differs in - that it does
   not execute the modules to check them.
877
878
   `py-pyflake-help'

879
- `py-pylint-run', new command calls Pylint,
880
881
882
  a Python source code analyzer which looks for
  programming errors, helps enforcing a coding standard
  and sniffs for some code smells (as defined in Martin
883
  Fowler's Refactoring book) .
884
885
886
887
888
889
890

  Pylint checks length of lines of code, if variable
  names are well-formed according to your coding
  standard, if declared interfaces are truly
  implemented, and much more. Additionally, it is
  possible to write plugins.
  `py-pylint-doku', `py-pylint-help'
Andreas Röhler's avatar
Andreas Röhler committed
891

892
- py-pyflakespep8-run, combines calls to pyflakes and pep8
893

894
895
896
897
- respective flymake-modes,
  `pyflakespep8-flymake-mode', `pylint-flymake-mode'
  etc. See meny PyTools

898
899
900
New in version 6.0.7
--------------------

Andreas Röhler's avatar
Andreas Röhler committed
901
902
903
904
905
- make every Python shell acces its own history-file
  .python3_history
  .python_history
  .ipython_history etc.

906
907
908
- related to shell used
  `toggle-force-py-shell-name-p'
  `force-py-shell-name-p-on'/off
909
910
911

  making it easier to enforce default py-shell upon execution

912
913
914
915
916
917
918
  `toggle-force-local-shell'
  `py-force-local-shell-on'/off

  If locally indicated Python shell should be taken and
  enforced upon sessions execute commands, lp:988091

- specific completion:
919
920
921
  py-python2-shell-complete, py-python3-shell-complete,
  py-python2-script-complete, py-python3-script-complete

922
923
924
New in version 6.0.6
--------------------

Andreas Röhler's avatar
Andreas Röhler committed
925
- files inside a virtual machine made visible for pdbtrack
926

927
- new commands `py-toggle-split-windows-on-execute', ...-on, ...-off
928
929
930
  `py-toggle-shell-switch-buffers-on-execute', ...-on, ...-off
  allow `py-execute-buffer' etc. to split/not-split windows,
  move cursor onto output or not
931

932
933
934
935
936
937
938
939
940
941
- Behavior of C-u M-x `py-shell' closer to common shell

  C-u 4 prompts for a buffer,
  i.e. when a "*Python*" shell is running,
  C-u M-x `py-shell' opens a "*Python<2>*" per default
  C-u 2 M-x py-shell promts for command-arguments as known from 5th-series

- `py-intend-tabs-mode' sets default of `indent-tabs-mode', lp:953765

-- New boolean variable `py-intend-tabs-mode'
942
  Permits value independent from Emacs-wide `indent-tabs-mode'
943
944
945
  Commands `py-toggle-indent-tabs-mode', ...-on, ...-off
  menu PyTools "Toggle indent-tabs-mode"

946
947
948
949
950
- Extended py-execute-... forms provided for "line"

- new commands py-beginning/end-of-line
  while introduced for internal reasons --because of it's
  return values-- they allow repeats, i.e. when already
951
  at end-of-line, jumping to next end etc.
952

953
954
- new boolean `py-force-py-shell-name-p'
  When `t', execution with Python specified in `py-shell-name' is en  forced, shebang will have no effect. Default is nil.
955

956
957
-  customizable `py-separator-char', a string, see report lp:975539
  Precedes guessing when not empty, is returned by
Andreas Röhler's avatar
Andreas Röhler committed
958
  function `py-separator-char'
959

960
961
- nicer `org-cycle' behavior: when new `py-org-cycle-p' it `t',
  command `org-cycle' is available at shift-TAB, <backtab>
962

963
964
965
New in version 6.0.5
--------------------

966
- Menu reworked and extended
967

968
- extended commands combine executing statement/block... with dedidi  cated/switch... etc. This may remove some need of customization.
969

970
- local environments support started
971
972
973
  If calls to common `py-shell' should use local executable
  instead of default system Python set
  `py-use-local-default' alongside with
974
  `py-shell-local-path'
975

976
977
978
- `py-toggle-shells' alias of more powerful `py-switch-shells'
  Toggles between the interpreter customized in `py-shell-toggle-1' resp. `py-shell-toggle-2'. Was hard-coded CPython and Jython in earlier versions, now starts with Python2 and Python3 by default.

979
- `py-shell-name' accepts PATH/TO/EXECUTABLE
980
  in addition to name of an installed default Python-Shell.
981
  Permits installing commands like
982
983
984
985
986
987
  (defun python-XYZ-shell (&optional argprompt)
    "Start an Python-XYZ interpreter ... "
    (interactive)
    (let ((py-shell-name "PATH/TO/PYTHON-XYZ"))
      (py-shell argprompt)))

988
-  new commands `indent-tabs-mode', `toggle-indent-tabs-mode',
989
990
991
992
993
994
  `indent-tabs-mode-on', `indent-tabs-mode-off'

  feature after a request at Stack Exchange asked Jul
  13 '11 at 13:23 saying
  `tab-width' now follows `py-indent-offset'

995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
- new command `py-execute-region-default' forces the
  systems default Python interpreter to execute, ignores
  shebang

  related functions redesigned, `async' argument dropped
  `py-execute-region' now reads:

  (defun py-execute-region (start end &optional shell dedicated)
    "Send the region to a Python interpreter.

  When called with \\[univeral-argument], execution through `default-value' of `py-shell-name' is forced.
  When called with \\[univeral-argument] followed by a number different from 4 and 1, user is prompted to specify a shell. This might be the name of a system-wide shell or include the path to a virtual environment.

  When called from a programm, it accepts a string specifying a shell which will be forced upon execute as argument. "
  [ ... ]

1011
- new `py-number-face',
Andreas Röhler's avatar
Andreas Röhler committed
1012
1013
1014
1015
1016
  visible only when customized and `py-use-number-face-p' is `t',
  inherits default face
  With large files fontifying numbers may cause a delay
  Credits to github.com/fgallina/python.el/issues42

1017
- new boolean `py-verbose-p'
1018
  if `t', reached indent level etc. is messaged
1019

1020
- new commands py-execute-buffer-dedicated, py-execute-buffer-switch  -dedicated
1021

1022
1023
1024
- `toggle-py-smart-indentation' new command
   also `py-smart-indentation-on', -off

1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
New in version 6.0.4
--------------------

- Python shell starts with `python-mode'
  that's needed by completion for now
  boolean customizable `py-start-run-py-shell'

- outline-(minor-)mode enabled providing regular
  expressions. Customize `py-outline-minor-mode-p' to
  switch it on with python-mode

- Hook delivered to start hs-minor-mode from python-mode
  Customize `py-hide-show-minor-mode-p'
  Key setting example:
  (global-set-key [(super s)] 'hs-hide-all)
  (global-set-key [(super S)] 'hs-show-all)

- Listing of available commands in org-mode and reST
  format in directory "doc"

- Python shells and executing forms may be called as
  dedicated process. See commands available \w suffix
  "-dedicated".

- completion fixed: M-TAB completes in Python buffer, TAB
  completes in Python shells

- py-down-FORM-lc commands
  Goto beginning of line following end of FORM.
  \"-lc\" stands for \"left-corner\" - a complementary command travelling left, whilst `py-end-of-FORM' stops at right corner.
  Implemented forms are "block", "clause", "def", "class", "statement".

- py-down-FORM commands

  like py-down-block introduced in version 6.0.3,
  implemented also for "clause", "def", "class",
  "statement".
  Go to the beginning of next block below
  current level.

New in version 6.0.3
--------------------

- ipython integration started

- commands `ipython', `python2', `python3', `jython', `python'
  opening a respective python shell

-  py-shift-block-left, py-shift-block-right etc.
  Implemented forms that way are
  "paragraph" "block" "clause" "def" "class" "line" "statement"

- py-dedent
  Dedent line according to `py-indent-offset'. With
  arg, do it that many times. If point is between
  indent levels, dedent to next level. Stops at BOL.
  Returns column reached, if dedent done, nil otherwise.

- py-indent-forward-line
  Indent line and move one line forward. If
  `py-kill-empty-line' is non-nil, delete an empty
  line. When closing a form, use py-close-block et al,
  which will move and indent likewise. Returns position.

- py-close-block, -clause, -def, class
  Set indent level to that of beginning of definition.
  If final line isn't empty and
  `py-close-block-provides-newline' non-nil, insert a
  newline. Returns column.

- new commands specifying the shell override
  `py-shell-name' for execution
  implemented shells are "python" "python2" "python2.7"
  "python3" "python3.2" "jython"

  available with default, -switch and -no-switch
  option, i.e.
  py-execute-region-python3.2
  py-execute-region-python3.2-switch
  py-execute-region-python3.2-no-switch etc.

  Docstring of py-execute-region-python3.2-switch for
  example: "Send the region to a common shell calling the
  python3.2 interpreter. Ignores setting of
  `py-shell-switch-buffers-on-execute', output-buffer
  will being switched to."

- Declarations
  Deal with assigments resp. statements in current
  level which don't open blocks. Provides common edit
  functions as copy, mark, kill, goto beg/end.

  Functions will be used typically to grasp
  initialisations resp. assignements of variables
  between the definition of a class or method and it's
  body, likewise global stuff at the head of a file.

- column-marker.el
  Commands `column-marker-1', `column-marker-2', and
  `column-marker-3' each highlight a given column
  (using different background colors by default).

  M-x column-marker-1 highlights the column where the
  cursor is, in face `column-marker-1'.

  C-u 70 M-x column-marker-2 highlights column 70 in
  face `column-marker-2'.

  C-u 70 M-x column-marker-3 highlights column 70 in
  face `column-marker-3'. The face `column-marker-2'
  highlighting no longer shows.

  C-u M-x column-marker-3 turns off highlighting for
  column-marker-3, so face `column-marker-2'
  highlighting shows again for column 70.

  C-u C-u M-x column-marker-1 (or -2 or -3) erases all
  column highlighting.

  ;;

  Thanks a lot to it's author Rick Bielawski <rbielaws@i1.net>,
  to Drew Adams for his care and Emacs Wiki hosting it.

New in version 6.0.2
--------------------

- py-electric-comment

  "Insert a comment. If starting a comment, indent
   accordingly. If a numeric argument ARG is provided,
   that many colons are inserted non-electrically. With
   universal-prefix-key C-u a \"#\" Electric behavior
   is inhibited inside a string or comment."

- New commands `py-partial-expression':

  "." operators delimit a partial-expression on it's
  level.

  Given the function below, `py-partial-expression'
  called at pipe symbol would copy and return:

  def usage():
      print """Usage: %s
      ....""" % (
          os.path.basename(sys.argv[0]))
  ------------|-------------------------
  ==> path

          os.path.basename(sys.argv[0]))
  ------------------|-------------------
  ==> basename(sys.argv[0]))

          os.path.basename(sys.argv[0]))
  --------------------------|-----------
  ==> sys

          os.path.basename(sys.argv[0]))
  ------------------------------|-------
  ==> argv[0]

  while `py-expression' would copy and return

  (
          os.path.basename(sys.argv[0]))

  ;;;;;

  Also for existing commands a shorthand is defined:

  (defalias 'py-statement 'py-copy-statement)

  which will mark, copy and return.

- Commands implementing a behavior which customizing of
 `py-shell-switch-buffers-on-execute' would do:

  py-execute-buffer-no-switch
  py-execute-buffer-switch
  py-execute-region-no-switch
  py-execute-region-switch

- Several bugfixes.

New in version 6.0.1
--------------------

- New commands py-expression:

  py-copy-expression
  py-mark-expression
  py-beginning-of-expression
  py-end-of-expression
  py-kill-expression

  Also several of bugfixes are done.

New in version 6.0
--------------------

- Finer grained commands, core re-write.

  As shown below for the `mark'-command, delete,
  copy, jump to beginning and end of the respective
  programming-expressions:

  py-mark-statement
  py-mark-block
  py-mark-block-or-clause
  py-mark-def
  py-mark-def-or-class
  py-mark-class
  py-mark-clause

- Also a couple of bugfixes are done.

New in version 5.2.1
--------------------

- Syntax highlight as a keyword "lambda:" just like "lambda x:".  Given by Dan
  Davison.
- Add "python3" as a key for python-mode in interpreter-mode-alist and
  auto-mode-alist.

New in version 5.2.0
--------------------

- Fixed filling of triple-quoted strings.

- Add new font-lock faces for class names and exception names.

- Do not fill when calling fill-paragraph with point in a region of code.

- Fixed font-locking of exception names in parenthesized lists.

- Fixed font-locking of decorators with arguments.

- Fixed font-locking of triple-quoted strings; single quotes appearing in
  triple-quoted strings no longer upset font-locking.

- Fixed the stack-entry regexp used by pdbtrack so that it now works with
  module-level frames.

- Do not bind C-c C-h; `py-help-at-point' is now on C-c C-e by default.

- hide-show mode is now supported.

- When shifting regions right and left, keep the region active in Emacs.