-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathpython.el
7322 lines (6657 loc) · 301 KB
/
python.el
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
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
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
;;; python.el --- Python's flying circus support for Emacs -*- lexical-binding: t -*-
;; Copyright (C) 2003-2025 Free Software Foundation, Inc.
;; Author: Fabián E. Gallina <[email protected]>
;; Maintainer: [email protected]
;; URL: https://github.com/fgallina/python.el
;; Version: 0.30
;; Package-Requires: ((emacs "29.1") (compat "29.1.1.0") (seq "2.23") (project "0.1") (flymake "1.0"))
;; Created: Jul 2010
;; Keywords: languages
;; This is a GNU ELPA :core package. Avoid functionality that is not
;; compatible with the version of Emacs recorded above.
;; This file is part of GNU Emacs.
;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published
;; by the Free Software Foundation, either version 3 of the License,
;; or (at your option) any later version.
;; GNU Emacs is distributed in the hope that it will be useful, but
;; WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
;; General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; Major mode for editing Python files with some fontification and
;; indentation bits extracted from original Dave Love's python.el
;; found in GNU Emacs.
;; Implements Syntax highlighting, Indentation, Movement, Shell
;; interaction, Shell completion, Shell virtualenv support, Shell
;; package support, Shell syntax highlighting, Pdb tracking, Symbol
;; completion, Skeletons, FFAP, Code Check, ElDoc, Imenu, Flymake,
;; Import management.
;; Syntax highlighting: Fontification of code is provided and supports
;; python's triple quoted strings properly.
;; Indentation: Automatic indentation with indentation cycling is
;; provided, it allows you to navigate different available levels of
;; indentation by hitting <tab> several times. Also electric-indent-mode
;; is supported such that when inserting a colon the current line is
;; dedented automatically if needed.
;; Movement: `beginning-of-defun' and `end-of-defun' functions are
;; properly implemented. There are also specialized
;; `forward-sentence' and `backward-sentence' replacements called
;; `python-nav-forward-block', `python-nav-backward-block'
;; respectively which navigate between beginning of blocks of code.
;; Extra functions `python-nav-forward-statement',
;; `python-nav-backward-statement',
;; `python-nav-beginning-of-statement', `python-nav-end-of-statement',
;; `python-nav-beginning-of-block', `python-nav-end-of-block' and
;; `python-nav-if-name-main' are included but no bound to any key.
;; Shell interaction: is provided and allows opening Python shells
;; inside Emacs and executing any block of code of your current buffer
;; in that inferior Python process.
;; Besides that only the standard CPython (2.x and 3.x) shell and
;; IPython are officially supported out of the box, the interaction
;; should support any other readline based Python shells as well
;; (e.g. Jython and PyPy have been reported to work). You can change
;; your default interpreter and commandline arguments by setting the
;; `python-shell-interpreter' and `python-shell-interpreter-args'
;; variables. This example enables IPython globally:
;; (setq python-shell-interpreter "ipython"
;; python-shell-interpreter-args "--simple-prompt")
;; Using the "console" subcommand to start IPython in server-client
;; mode is known to fail intermittently due a bug on IPython itself
;; (see URL `https://debbugs.gnu.org/cgi/bugreport.cgi?bug=18052#27').
;; There seems to be a race condition in the IPython server (A.K.A
;; kernel) when code is sent while it is still initializing, sometimes
;; causing the shell to get stalled. With that said, if an IPython
;; kernel is already running, "console --existing" seems to work fine.
;; Running IPython on Windows needs more tweaking. The way you should
;; set `python-shell-interpreter' and `python-shell-interpreter-args'
;; is as follows (of course you need to modify the paths according to
;; your system):
;; (setq python-shell-interpreter "C:/Python27/python.exe"
;; python-shell-interpreter-args
;; "-i C:/Python27/Scripts/ipython-script.py")
;; Missing or delayed output used to happen due to differences between
;; Operating Systems' pipe buffering (e.g. CPython 3.3.4 in Windows 7.
;; See URL `https://debbugs.gnu.org/cgi/bugreport.cgi?bug=17304'). To
;; avoid this, the `python-shell-unbuffered' defaults to non-nil and
;; controls whether `python-shell--calculate-process-environment'
;; should set the "PYTHONUNBUFFERED" environment variable on startup:
;; See URL `https://docs.python.org/3/using/cmdline.html#cmdoption-u'.
;; The interaction relies upon having prompts for input (e.g. ">>> "
;; and "... " in standard Python shell) and output (e.g. "Out[1]: " in
;; IPython) detected properly. Failing that Emacs may hang but, in
;; the case that happens, you can recover with \\[keyboard-quit]. To
;; avoid this issue, a two-step prompt autodetection mechanism is
;; provided: the first step is manual and consists of a collection of
;; regular expressions matching common prompts for Python shells
;; stored in `python-shell-prompt-input-regexps' and
;; `python-shell-prompt-output-regexps', and dir-local friendly vars
;; `python-shell-prompt-regexp', `python-shell-prompt-block-regexp',
;; `python-shell-prompt-output-regexp' which are appended to the
;; former automatically when a shell spawns; the second step is
;; automatic and depends on the `python-shell-prompt-detect' helper
;; function. See its docstring for details on global variables that
;; modify its behavior.
;; Shell completion: hitting tab will try to complete the current
;; word. The two built-in mechanisms depend on Python's readline
;; module: the "native" completion is tried first and is activated
;; when `python-shell-completion-native-enable' is non-nil, the
;; current `python-shell-interpreter' is not a member of the
;; `python-shell-completion-native-disabled-interpreters' variable and
;; `python-shell-completion-native-setup' succeeds; the "fallback" or
;; "legacy" mechanism works by executing Python code in the background
;; and enables auto-completion for shells that do not support
;; receiving escape sequences (with some limitations, i.e. completion
;; in blocks does not work). The code executed for the "fallback"
;; completion can be found in `python-shell-completion-setup-code' and
;; `python-shell-completion-get-completions'. Their default values
;; enable completion for both CPython and IPython, and probably any
;; readline based shell (it's known to work with PyPy). If your
;; Python installation lacks readline (like CPython for Windows),
;; installing pyreadline (URL `https://ipython.org/pyreadline.html')
;; should suffice. To troubleshoot why you are not getting any
;; completions, you can try the following in your Python shell:
;; >>> import readline, rlcompleter
;; If you see an error, then you need to either install pyreadline or
;; setup custom code that avoids that dependency.
;; By default, the "native" completion uses the built-in rlcompleter.
;; To use other readline completer (e.g. Jedi) or a custom one, you just
;; need to set it in the PYTHONSTARTUP file. You can set an
;; Emacs-specific completer by testing the environment variable
;; INSIDE_EMACS.
;; Shell virtualenv support: The shell also contains support for
;; virtualenvs and other special environment modifications thanks to
;; `python-shell-process-environment' and `python-shell-exec-path'.
;; These two variables allows you to modify execution paths and
;; environment variables to make easy for you to setup virtualenv rules
;; or behavior modifications when running shells. Here is an example
;; of how to make shell processes to be run using the /path/to/env/
;; virtualenv:
;; (setq python-shell-process-environment
;; (list
;; (format "PATH=%s" (mapconcat
;; #'identity
;; (reverse
;; (cons (getenv "PATH")
;; '("/path/to/env/bin/")))
;; ":"))
;; "VIRTUAL_ENV=/path/to/env/"))
;; (python-shell-exec-path . ("/path/to/env/bin/"))
;; Since the above is cumbersome and can be programmatically
;; calculated, the variable `python-shell-virtualenv-root' is
;; provided. When this variable is set with the path of the
;; virtualenv to use, `process-environment' and `exec-path' get proper
;; values in order to run shells inside the specified virtualenv. So
;; the following will achieve the same as the previous example:
;; (setq python-shell-virtualenv-root "/path/to/env/")
;; Also the `python-shell-extra-pythonpaths' variable have been
;; introduced as simple way of adding paths to the PYTHONPATH without
;; affecting existing values.
;; Shell package support: you can enable a package in the current
;; shell so that relative imports work properly using the
;; `python-shell-package-enable' command.
;; Shell remote support: remote Python shells are started with the
;; correct environment for files opened remotely through tramp, also
;; respecting dir-local variables provided `enable-remote-dir-locals'
;; is non-nil. The logic for this is transparently handled by the
;; `python-shell-with-environment' macro.
;; Shell syntax highlighting: when enabled current input in shell is
;; highlighted. The variable `python-shell-font-lock-enable' controls
;; activation of this feature globally when shells are started.
;; Activation/deactivation can be also controlled on the fly via the
;; `python-shell-font-lock-toggle' command.
;; Pdb tracking: when you execute a block of code that contains some
;; call to pdb (or ipdb) it will prompt the block of code and will
;; follow the execution of pdb marking the current line with an arrow.
;; Symbol completion: you can complete the symbol at point. It uses
;; the shell completion in background so you should run
;; `python-shell-send-buffer' from time to time to get better results.
;; Skeletons: skeletons are provided for simple inserting of things like class,
;; def, for, import, if, try, and while. These skeletons are
;; integrated with abbrev. If you have `abbrev-mode' activated and
;; `python-skeleton-autoinsert' is set to t, then whenever you type
;; the name of any of those defined and hit SPC, they will be
;; automatically expanded. As an alternative you can use the defined
;; skeleton commands: `python-skeleton-<foo>'.
;; FFAP: You can find the filename for a given module when using ffap
;; out of the box. This feature needs an inferior python shell
;; running.
;; Code check: Check the current file for errors with `python-check'
;; using the program defined in `python-check-command'.
;; ElDoc: returns documentation for object at point by using the
;; inferior python subprocess to inspect its documentation. As you
;; might guessed you should run `python-shell-send-buffer' from time
;; to time to get better results too.
;; Imenu: There are two index building functions to be used as
;; `imenu-create-index-function': `python-imenu-create-index' (the
;; default one, builds the alist in form of a tree) and
;; `python-imenu-create-flat-index'. See also
;; `python-imenu-format-item-label-function',
;; `python-imenu-format-parent-item-label-function',
;; `python-imenu-format-parent-item-jump-label-function' variables for
;; changing the way labels are formatted in the tree version.
;; Flymake: A Flymake backend, using the pyflakes program by default,
;; is provided. You can also use flake8 or pylint by customizing
;; `python-flymake-command'.
;; Import management: The commands `python-sort-imports',
;; `python-add-import', `python-remove-import', and
;; `python-fix-imports' automate the editing of import statements at
;; the top of the buffer, which tend to be a tedious task in larger
;; projects. These commands require that the isort library is
;; available to the interpreter pointed at by `python-interpreter'.
;; The last command also requires pyflakes. These dependencies can be
;; installed, among other methods, with the following command:
;;
;; pip install isort pyflakes
;;; Code:
(require 'ansi-color)
(require 'cl-lib)
(require 'comint)
(eval-when-compile (require 'subr-x)) ;For `string-empty-p' and `string-join'.
(require 'treesit)
(require 'pcase)
(require 'compat)
(require 'project nil 'noerror)
(require 'seq)
(declare-function treesit-parser-create "treesit.c")
(declare-function treesit-induce-sparse-tree "treesit.c")
(declare-function treesit-node-child-by-field-name "treesit.c")
(declare-function treesit-node-type "treesit.c")
(declare-function treesit-node-start "treesit.c")
(declare-function treesit-node-end "treesit.c")
(declare-function treesit-node-parent "treesit.c")
(declare-function treesit-node-prev-sibling "treesit.c")
;; Avoid compiler warnings
(defvar compilation-error-regexp-alist)
(defvar outline-heading-end-regexp)
(autoload 'comint-mode "comint")
(autoload 'help-function-arglist "help-fns")
;;;###autoload
(defconst python--auto-mode-alist-regexp
;; (rx (or
;; (seq "." (or "py"
;; "pth" ; Python Path Configuration File
;; "pyi" ; Python Stub File (PEP 484)
;; "pyw")) ; MS-Windows specific extension
;; (seq "/" (or "SConstruct" "SConscript"))) ; SCons Build Files
;; eos)
"\\(?:\\.\\(?:p\\(?:th\\|y[iw]?\\)\\)\\|/\\(?:SCons\\(?:\\(?:crip\\|truc\\)t\\)\\)\\)\\'"
)
;;;###autoload
(add-to-list 'auto-mode-alist (cons python--auto-mode-alist-regexp 'python-mode))
;;;###autoload
(add-to-list 'interpreter-mode-alist '("python[0-9.]*" . python-mode))
(defgroup python nil
"Python Language's flying circus support for Emacs."
:group 'languages
:version "24.3"
:link '(emacs-commentary-link "python"))
(defcustom python-interpreter
(cond ((executable-find "python") "python")
(t "python3"))
"Python interpreter for noninteractive use.
Some Python interpreters also require changes to
`python-interpreter-args'.
To customize the Python interpreter for interactive use, modify
`python-shell-interpreter' instead."
:version "31.1"
:type 'string)
(defcustom python-interpreter-args ""
"Arguments for the Python interpreter for noninteractive use."
:version "30.1"
:type 'string)
(defcustom python-2-support nil
"If non-nil, enable Python 2 support.
Currently only affects highlighting.
After customizing this variable, you must restart Emacs for it to take
effect."
:version "31.1"
:type 'boolean
:safe 'booleanp)
;;; Bindings
(defvar-keymap python-base-mode-map
:doc "Keymap for `python-base-mode'."
;; Movement
"<remap> <backward-sentence>" #'python-nav-backward-block
"<remap> <forward-sentence>" #'python-nav-forward-block
"<remap> <backward-up-list>" #'python-nav-backward-up-list
"<remap> <up-list>" #'python-nav-up-list
"<remap> <mark-defun>" #'python-mark-defun
"C-c C-j" #'imenu
;; Indent specific
"DEL" #'python-indent-dedent-line-backspace
"<backtab>" #'python-indent-dedent-line
"C-c <" #'python-indent-shift-left
"C-c >" #'python-indent-shift-right
;; Skeletons
"C-c C-t c" #'python-skeleton-class
"C-c C-t d" #'python-skeleton-def
"C-c C-t f" #'python-skeleton-for
"C-c C-t i" #'python-skeleton-if
"C-c C-t m" #'python-skeleton-import
"C-c C-t t" #'python-skeleton-try
"C-c C-t w" #'python-skeleton-while
;; Shell interaction
"C-c C-p" #'run-python
"C-c C-s" #'python-shell-send-string
"C-c C-e" #'python-shell-send-statement
"C-c C-r" #'python-shell-send-region
"C-M-x" #'python-shell-send-defun
"C-c C-b" #'python-shell-send-block
"C-c C-c" #'python-shell-send-buffer
"C-c C-l" #'python-shell-send-file
"C-c C-z" #'python-shell-switch-to-shell
;; Some util commands
"C-c C-v" #'python-check
"C-c C-f" #'python-eldoc-at-point
"C-c C-d" #'python-describe-at-point
;; Import management
"C-c C-i a" #'python-add-import
"C-c C-i f" #'python-fix-imports
"C-c C-i r" #'python-remove-import
"C-c C-i s" #'python-sort-imports
;; Utilities
"<remap> <complete-symbol>" #'completion-at-point)
(defvar subword-mode nil)
(easy-menu-define python-menu python-base-mode-map
"Menu used for ´python-mode'."
'("Python"
:help "Python-specific Features"
["Shift region left" python-indent-shift-left :active mark-active
:help "Shift region left by a single indentation step"]
["Shift region right" python-indent-shift-right :active mark-active
:help "Shift region right by a single indentation step"]
"-----"
["Start of def/class" beginning-of-defun
:help "Go to start of outermost definition around point"]
["End of def/class" end-of-defun
:help "Go to end of definition around point"]
["Mark def/class" mark-defun
:help "Mark outermost definition around point"]
["Jump to def/class" imenu
:help "Jump to a class or function definition"]
"-----"
("Skeletons")
"-----"
["Start interpreter" run-python
:help "Run inferior Python process in a separate buffer"]
["Switch to shell" python-shell-switch-to-shell
:help "Switch to running inferior Python process"]
["Eval string" python-shell-send-string
:help "Eval string in inferior Python session"]
["Eval block" python-shell-send-block
:help "Eval block in inferior Python session"]
["Eval buffer" python-shell-send-buffer
:help "Eval buffer in inferior Python session"]
["Eval statement" python-shell-send-statement
:help "Eval statement in inferior Python session"]
["Eval region" python-shell-send-region
:help "Eval region in inferior Python session"]
["Eval defun" python-shell-send-defun
:help "Eval defun in inferior Python session"]
["Eval file" python-shell-send-file
:help "Eval file in inferior Python session"]
["Debugger" pdb :help "Run pdb under GUD"]
"-----"
["Check file" python-check
:help "Check file for errors"]
["Help on symbol" python-eldoc-at-point
:help "Get help on symbol at point"]
["Complete symbol" completion-at-point
:help "Complete symbol before point"]
"-----"
["Add import" python-add-import
:help "Add an import statement to the top of this buffer"]
["Remove import" python-remove-import
:help "Remove an import statement from the top of this buffer"]
["Sort imports" python-sort-imports
:help "Sort the import statements at the top of this buffer"]
["Fix imports" python-fix-imports
:help "Add missing imports and remove unused ones from the current buffer"]
"-----"
("Toggle..."
["Subword Mode" subword-mode
:style toggle :selected subword-mode
:help "Toggle subword movement and editing mode"])))
(defvar python-mode-map (make-composed-keymap nil python-base-mode-map)
"Keymap for `python-mode'.")
(defvar python-ts-mode-map (make-composed-keymap nil python-base-mode-map)
"Keymap for `python-ts-mode'.")
;;; Python specialized rx
(defmacro python-rx (&rest regexps)
"Python mode specialized rx macro.
This variant of `rx' supports common Python named REGEXPS."
`(rx-let ((sp-bsnl (or space (and ?\\ ?\n)))
(block-start (seq symbol-start
(or "def" "class" "if" "elif" "else" "try"
"except" "finally" "for" "while" "with"
;; Python 3.10+ PEP634
"match" "case"
;; Python 3.5+ PEP492
(and "async" (+ space)
(or "def" "for" "with")))
symbol-end))
(dedenter (seq symbol-start
(or "elif" "else" "except" "finally" "case")
symbol-end))
(block-ender (seq
symbol-start
(or
(seq (or
"break" "continue" "pass" "raise" "return")
symbol-end)
(seq
(or
(seq (? (or (seq "os." (? ?_)) "sys.")) "exit")
"quit")
(* space) "("))))
(decorator (seq line-start (* space) ?@ (any letter ?_)
(* (any word ?_))))
(defun (seq symbol-start
(or "def" "class"
;; Python 3.5+ PEP492
(and "async" (+ space) "def"))
symbol-end))
(if-name-main (seq line-start "if" (+ space) "__name__"
(+ space) "==" (+ space)
(any ?' ?\") "__main__" (any ?' ?\")
(* space) ?:))
(symbol-name (seq (any letter ?_) (* (any word ?_))))
(assignment-target (seq (? ?*)
(* symbol-name ?.) symbol-name
(? ?\[ (+ (not ?\])) ?\])))
(grouped-assignment-target (seq (? ?*)
(* symbol-name ?.) (group symbol-name)
(? ?\[ (+ (not ?\])) ?\])))
(open-paren (or "{" "[" "("))
(close-paren (or "}" "]" ")"))
(simple-operator (any ?+ ?- ?/ ?& ?^ ?~ ?| ?* ?< ?> ?= ?%))
(not-simple-operator (not (or simple-operator ?\n)))
(operator (or "==" ">="
"**" "//" "<<" ">>" "<=" "!="
"+" "-" "/" "&" "^" "~" "|" "*" "<" ">"
"=" "%"))
(assignment-operator (or "+=" "-=" "*=" "/=" "//=" "%=" "**="
">>=" "<<=" "&=" "^=" "|="
"="))
(string-delimiter (seq
;; Match even number of backslashes.
(or (not (any ?\\ ?\' ?\")) point
;; Quotes might be preceded by an
;; escaped quote.
(and (or (not (any ?\\)) point) ?\\
(* ?\\ ?\\) (any ?\' ?\")))
(* ?\\ ?\\)
;; Match single or triple quotes of any kind.
(group (or "\"\"\"" "\"" "'''" "'"))))
(coding-cookie (seq line-start ?# (* space)
(or
;; # coding=<encoding name>
(: "coding" (or ?: ?=) (* space)
(group-n 1 (+ (or word ?-))))
;; # -*- coding: <encoding name> -*-
(: "-*-" (* space) "coding:" (* space)
(group-n 1 (+ (or word ?-)))
(* space) "-*-")
;; # vim: set fileencoding=<encoding name> :
(: "vim:" (* space) "set" (+ space)
"fileencoding" (* space) ?= (* space)
(group-n 1 (+ (or word ?-)))
(* space) ":"))))
(bytes-escape-sequence
(seq (not "\\")
(group (or "\\\\" "\\'" "\\a" "\\b" "\\f"
"\\n" "\\r" "\\t" "\\v"
(seq "\\" (** 1 3 (in "0-7")))
(seq "\\x" hex hex)))))
(string-escape-sequence
(or bytes-escape-sequence
(seq (not "\\")
(or (group-n 1 "\\u" (= 4 hex))
(group-n 1 "\\U" (= 8 hex))
(group-n 1 "\\N{" (*? anychar) "}"))))))
(rx ,@regexps)))
;;; Font-lock and syntax
(eval-and-compile
(defun python-syntax--context-compiler-macro (form type &optional syntax-ppss)
(pcase type
(''comment
`(let ((ppss (or ,syntax-ppss (syntax-ppss))))
(and (nth 4 ppss) (nth 8 ppss))))
(''string
`(let ((ppss (or ,syntax-ppss (syntax-ppss))))
(and (nth 3 ppss) (nth 8 ppss))))
(''single-quoted-string
`(let ((ppss (or ,syntax-ppss (syntax-ppss))))
(and (characterp (nth 3 ppss)) (nth 8 ppss))))
(''triple-quoted-string
`(let ((ppss (or ,syntax-ppss (syntax-ppss))))
(and (eq t (nth 3 ppss)) (nth 8 ppss))))
(''paren
`(nth 1 (or ,syntax-ppss (syntax-ppss))))
(_ form))))
(defun python-syntax-context (type &optional syntax-ppss)
"Return non-nil if point is on TYPE using SYNTAX-PPSS.
TYPE can be `comment', `string', `single-quoted-string',
`triple-quoted-string' or `paren'. It returns the start
character address of the specified TYPE."
(declare (compiler-macro python-syntax--context-compiler-macro))
(let ((ppss (or syntax-ppss (syntax-ppss))))
(pcase type
('comment (and (nth 4 ppss) (nth 8 ppss)))
('string (and (nth 3 ppss) (nth 8 ppss)))
('single-quoted-string (and (characterp (nth 3 ppss)) (nth 8 ppss)))
('triple-quoted-string (and (eq t (nth 3 ppss)) (nth 8 ppss)))
('paren (nth 1 ppss))
(_ nil))))
(defun python-syntax-context-type (&optional syntax-ppss)
"Return the context type using SYNTAX-PPSS.
The type returned can be `comment', `string' or `paren'."
(let ((ppss (or syntax-ppss (syntax-ppss))))
(cond
((nth 8 ppss) (if (nth 4 ppss) 'comment 'string))
((nth 1 ppss) 'paren))))
(defsubst python-syntax-comment-or-string-p (&optional ppss)
"Return non-nil if PPSS is inside comment or string."
(nth 8 (or ppss (syntax-ppss))))
(defsubst python-syntax-closing-paren-p ()
"Return non-nil if char after point is a closing paren."
(eql (syntax-class (syntax-after (point)))
(syntax-class (string-to-syntax ")"))))
(defun python-font-lock-syntactic-face-function (state)
"Return syntactic face given STATE."
(if (nth 3 state)
(if (python-info-docstring-p state)
'font-lock-doc-face
'font-lock-string-face)
'font-lock-comment-face))
(defconst python--f-string-start-regexp
(rx bow
(or "f" "F" "fr" "Fr" "fR" "FR" "rf" "rF" "Rf" "RF")
(or "\"" "\"\"\"" "'" "'''"))
"A regular expression matching the beginning of an f-string.
See URL `https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals'.")
(defun python--f-string-p (ppss)
"Return non-nil if the pos where PPSS was found is inside an f-string."
(and (nth 3 ppss)
(let* ((spos (1- (nth 8 ppss)))
(before-quote
(buffer-substring-no-properties (max (- spos 4) (point-min))
(min (+ spos 2) (point-max)))))
(and (string-match-p python--f-string-start-regexp before-quote)
(or (< (point-min) spos)
(not (memq (char-syntax (char-before spos)) '(?w ?_))))))))
(defun python--font-lock-f-strings (limit)
"Mark {...} holes as being code.
Remove the (presumably `font-lock-string-face') `face' property from
the {...} holes that appear within f-strings."
;; FIXME: This will fail to properly highlight strings appearing
;; within the {...} of an f-string.
;; We could presumably fix it by running
;; `font-lock-default-fontify-syntactically-region' (as is done in
;; `sm-c--cpp-fontify-syntactically', for example) after removing
;; the `face' property, but I'm not sure it's worth the effort and
;; the risks.
(let ((ppss (syntax-ppss)))
(while
(progn
(while (and (not (python--f-string-p ppss))
(re-search-forward python--f-string-start-regexp limit 'move))
(setq ppss (syntax-ppss)))
(< (point) limit))
(cl-assert (python--f-string-p ppss))
(let ((send (save-excursion
(goto-char (nth 8 ppss))
(condition-case nil
(progn (let ((forward-sexp-function nil))
(forward-sexp 1))
(min limit (1- (point))))
(scan-error limit)))))
(while (re-search-forward "{" send t)
(if (eq ?\{ (char-after))
(forward-char 1) ;Just skip over {{
(let ((beg (match-beginning 0))
(end (condition-case nil
(let ((forward-sexp-function)
(parse-sexp-ignore-comments))
(up-list 1)
(min send (point)))
(scan-error send))))
(goto-char end)
(put-text-property beg end 'face nil))))
(goto-char (min limit (1+ send)))
(setq ppss (syntax-ppss))))))
(defconst python--not-raw-bytes-literal-start-regexp
(rx (or bos (not alnum)) (or "b" "B") (or "\"" "\"\"\"" "'" "'''") eos)
"A regular expression matching the start of a not-raw bytes literal.")
(defconst python--not-raw-string-literal-start-regexp
(rx bos (or
;; Multi-line string literals
(seq (? (? (not alnum)) (or "u" "U" "F" "f")) (or "\"\"\"" "'''"))
(seq (? anychar) (not alnum) (or "\"\"\"" "'''"))
;; Single line string literals
(seq (? (** 0 2 anychar) (not alnum)) (or "u" "U" "F" "f") (or "'" "\""))
(seq (? (** 0 3 anychar) (not (any "'\"" alnum))) (or "'" "\"")))
eos)
"A regular expression matching the start of a not-raw string literal.")
(defun python--string-bytes-literal-matcher (regexp start-regexp)
"Match REGEXP within a string or bytes literal whose start matches START-REGEXP."
(lambda (limit)
(cl-loop for result = (re-search-forward regexp limit t)
for result-valid = (and
result
(when-let* ((pos (nth 8 (syntax-ppss)))
(before-quote
(buffer-substring-no-properties
(max (- pos 4) (point-min))
(min (+ pos 1) (point-max)))))
(backward-char)
(string-match-p start-regexp before-quote)))
until (or (not result) result-valid)
finally return (and result-valid result))))
(defvar python-font-lock-keywords-level-1
`((,(python-rx symbol-start "def" (1+ space) (group symbol-name))
(1 font-lock-function-name-face))
(,(python-rx symbol-start "class" (1+ space) (group symbol-name))
(1 font-lock-type-face)))
"Font lock keywords to use in `python-mode' for level 1 decoration.
This is the minimum decoration level, including function and
class declarations.")
(defvar python-font-lock-builtin-types
'("bool" "bytearray" "bytes" "complex" "dict" "float" "frozenset"
"int" "list" "memoryview" "range" "set" "str" "tuple"))
(defvar python-font-lock-builtins-python3
'("abs" "aiter" "all" "anext" "any" "ascii" "bin" "breakpoint"
"callable" "chr" "classmethod" "compile" "delattr" "dir" "divmod"
"enumerate" "eval" "exec" "filter" "format" "getattr" "globals"
"hasattr" "hash" "help" "hex" "id" "input" "isinstance"
"issubclass" "iter" "len" "locals" "map" "max" "min" "next"
"object" "oct" "open" "ord" "pow" "print" "property" "repr"
"reversed" "round" "setattr" "slice" "sorted" "staticmethod" "sum"
"super" "type" "vars" "zip" "__import__"))
(defvar python-font-lock-builtins-python2
'("basestring" "cmp" "execfile" "file" "long" "raw_input" "reduce"
"reload" "unichr" "unicode" "xrange" "apply" "buffer" "coerce"
"intern"))
(defvar python-font-lock-builtins
(append python-font-lock-builtins-python3
(when python-2-support
python-font-lock-builtins-python2)))
(defvar python-font-lock-special-attributes
'(;; https://docs.python.org/3/reference/datamodel.html
"__annotations__" "__bases__" "__closure__" "__code__"
"__defaults__" "__dict__" "__doc__" "__firstlineno__"
"__globals__" "__kwdefaults__" "__name__" "__module__"
"__mro__" "__package__" "__qualname__"
"__static_attributes__" "__type_params__"
;; Extras:
"__all__"))
(defvar python-font-lock-keywords-level-2
`(,@python-font-lock-keywords-level-1
,(rx symbol-start
(or
"and" "del" "from" "not" "while" "as" "elif" "global" "or" "with"
"assert" "else" "if" "pass" "yield" "break" "except" "import" "class"
"in" "raise" "continue" "finally" "is" "return" "def" "for" "lambda"
"try"
;; False, None, and True are listed as keywords on the Python 3
;; documentation, but since they also qualify as constants they are
;; fontified like that in order to keep font-lock consistent between
;; Python versions.
"nonlocal"
;; Python 3.5+ PEP492
(and "async" (+ space) (or "def" "for" "with"))
"await"
;; Python 3.10+
"match" "case"
;; Extra:
"self")
symbol-end)
;; Builtins
(,(rx-to-string `(seq symbol-start
(or ,@(append python-font-lock-builtin-types
python-font-lock-builtins
python-font-lock-special-attributes))
symbol-end)) . font-lock-builtin-face))
"Font lock keywords to use in `python-mode' for level 2 decoration.
This is the medium decoration level, including everything in
`python-font-lock-keywords-level-1', as well as keywords and
builtins.")
(defun python-font-lock-assignment-matcher (regexp)
"Font lock matcher for assignments based on REGEXP.
Search for next occurrence if REGEXP matched within a `paren'
context (to avoid, e.g., default values for arguments or passing
arguments by name being treated as assignments) or is followed by
an '=' sign (to avoid '==' being treated as an assignment. Set
point to the position one character before the end of the
occurrence found so that subsequent searches can detect the '='
sign in chained assignment."
(lambda (limit)
(cl-loop while (re-search-forward regexp limit t)
unless (or (python-syntax-context 'paren)
(equal (char-after) ?=))
return (progn (backward-char) t))))
(defvar python-font-lock-builtin-exceptions-python3
'(;; Python 2 and 3:
"ArithmeticError" "AssertionError" "AttributeError" "BaseException"
"BufferError" "BytesWarning" "DeprecationWarning" "EOFError"
"EnvironmentError" "Exception" "FloatingPointError" "FutureWarning"
"GeneratorExit" "IOError" "ImportError" "ImportWarning"
"IndentationError" "IndexError" "KeyError" "KeyboardInterrupt"
"LookupError" "MemoryError" "NameError" "NotImplementedError"
"OSError" "OverflowError" "PendingDeprecationWarning"
"ReferenceError" "RuntimeError" "RuntimeWarning" "StopIteration"
"SyntaxError" "SyntaxWarning" "SystemError" "SystemExit" "TabError"
"TypeError" "UnboundLocalError" "UnicodeDecodeError"
"UnicodeEncodeError" "UnicodeError" "UnicodeTranslateError"
"UnicodeWarning" "UserWarning" "ValueError" "Warning"
"ZeroDivisionError"
;; Python 3:
"BlockingIOError" "BrokenPipeError" "ChildProcessError"
"ConnectionAbortedError" "ConnectionError" "ConnectionRefusedError"
"ConnectionResetError" "EncodingWarning" "FileExistsError"
"FileNotFoundError" "InterruptedError" "IsADirectoryError"
"NotADirectoryError" "ModuleNotFoundError" "PermissionError"
"ProcessLookupError" "PythonFinalizationError" "RecursionError"
"ResourceWarning" "StopAsyncIteration" "TimeoutError"
"BaseExceptionGroup" "ExceptionGroup"
;; OS specific
"VMSError" "WindowsError"))
(defvar python-font-lock-builtin-exceptions-python2
'("StandardError"))
(defvar python-font-lock-builtin-exceptions
(append python-font-lock-builtin-exceptions-python3
(when python-2-support
python-font-lock-builtin-exceptions-python2)))
(defvar python-font-lock-keywords-maximum-decoration
`((python--font-lock-f-strings)
,@python-font-lock-keywords-level-2
;; Constants
(,(rx symbol-start
(or
"Ellipsis" "False" "None" "NotImplemented" "True" "__debug__"
;; copyright, license, credits, quit and exit are added by the site
;; module and they are not intended to be used in programs
"copyright" "credits" "exit" "license" "quit")
symbol-end)
. font-lock-constant-face)
;; Decorators.
(,(rx line-start (* (any " \t")) (group "@" (1+ (or word ?_))
(0+ "." (1+ (or word ?_)))))
(1 font-lock-type-face))
;; Builtin Exceptions
(,(rx-to-string `(seq symbol-start
(or ,@python-font-lock-builtin-exceptions)
symbol-end)) . font-lock-type-face)
;; single assignment with/without type hints, e.g.
;; a: int = 5
;; b: Tuple[Optional[int], Union[Sequence[str], str]] = (None, 'foo')
;; c: Collection = {1, 2, 3}
;; d: Mapping[int, str] = {1: 'bar', 2: 'baz'}
(,(python-font-lock-assignment-matcher
(python-rx grouped-assignment-target (* space)
(? ?: (* space) (group (+ not-simple-operator)) (* space))
(group assignment-operator)))
(1 font-lock-variable-name-face)
(3 'font-lock-operator-face)
(,(python-rx symbol-name)
(progn
(when-let* ((type-start (match-beginning 2)))
(goto-char type-start))
(match-end 0))
nil
(0 font-lock-type-face)))
;; multiple assignment
;; (note that type hints are not allowed for multiple assignments)
;; a, b, c = 1, 2, 3
;; a, *b, c = 1, 2, 3, 4, 5
;; [a, b] = (1, 2)
;; (l[1], l[2]) = (10, 11)
;; (a, b, c, *d) = *x, y = 5, 6, 7, 8, 9
;; (a,) = 'foo'
;; (*a,) = ['foo', 'bar', 'baz']
;; d.x, d.y[0], *d.z = 'a', 'b', 'c', 'd', 'e'
;; and variants thereof
;; the cases
;; (a) = 5
;; [a] = 5,
;; [*a] = 5, 6
;; are handled separately below
(,(python-font-lock-assignment-matcher
(python-rx (? (or "[" "(") (* space))
grouped-assignment-target (* space) ?, (* space)
(* assignment-target (* space) ?, (* space))
(? assignment-target (* space))
(? ?, (* space))
(? (or ")" "]") (* space))
(group assignment-operator)))
(1 font-lock-variable-name-face)
(2 'font-lock-operator-face)
(,(python-rx grouped-assignment-target)
(progn
(goto-char (match-end 1)) ; go back after the first symbol
(match-beginning 2)) ; limit the search until the assignment
nil
(1 font-lock-variable-name-face)))
;; special cases
;; (a) = 5
;; [a] = 5,
;; [*a] = 5, 6
(,(python-font-lock-assignment-matcher
(python-rx (or line-start ?\; ?=) (* space)
(or "[" "(") (* space)
grouped-assignment-target (* space)
(or ")" "]") (* space)
(group assignment-operator)))
(1 font-lock-variable-name-face)
(2 'font-lock-operator-face))
;; Operators.
(,(python-rx operator) . 'font-lock-operator-face)
;; escape sequences within bytes literals
;; "\\" "\'" "\a" "\b" "\f" "\n" "\r" "\t" "\v"
;; "\ooo" character with octal value ooo
;; "\xhh" character with hex value hh
(,(python--string-bytes-literal-matcher
(python-rx bytes-escape-sequence)
python--not-raw-bytes-literal-start-regexp)
(1 font-lock-constant-face t))
;; escape sequences within string literals, the same as appear in bytes
;; literals in addition to:
;; "\uxxxx" Character with 16-bit hex value xxxx
;; "\Uxxxxxxxx" Character with 32-bit hex value xxxxxxxx
;; "\N{name}" Character named name in the Unicode database
(,(python--string-bytes-literal-matcher
(python-rx string-escape-sequence)
python--not-raw-string-literal-start-regexp)
(1 'font-lock-constant-face t)))
"Font lock keywords to use in `python-mode' for maximum decoration.
This decoration level includes everything in
`python-font-lock-keywords-level-2', as well as constants,
decorators, exceptions, and assignments.")
(defvar python-font-lock-keywords
'(python-font-lock-keywords-level-1 ; When `font-lock-maximum-decoration' is nil.
python-font-lock-keywords-level-1 ; When `font-lock-maximum-decoration' is 1.
python-font-lock-keywords-level-2 ; When `font-lock-maximum-decoration' is 2.
python-font-lock-keywords-maximum-decoration ; When `font-lock-maximum-decoration'
; is more than 1, or t (which it is,
; by default).
)
"List of font lock keyword specifications to use in `python-mode'.
Which one will be chosen depends on the value of
`font-lock-maximum-decoration'.")
(defconst python-syntax-propertize-function
(syntax-propertize-rules
((rx (or "\"\"\"" "'''"))
(0 (ignore (python-syntax-stringify))))))
(define-obsolete-variable-alias 'python--prettify-symbols-alist
'python-prettify-symbols-alist "26.1")
(defvar python-prettify-symbols-alist
'(("lambda" . ?λ)
("and" . ?∧)
("or" . ?∨))
"Value for `prettify-symbols-alist' in `python-mode'.")
(defsubst python-syntax-count-quotes (quote-char &optional point limit)
"Count number of quotes around point (max is 3).
QUOTE-CHAR is the quote char to count. Optional argument POINT is
the point where scan starts (defaults to current point), and LIMIT
is used to limit the scan."
(let ((i 0))
(while (and (< i 3)
(or (not limit) (< (+ point i) limit))
(eq (char-after (+ point i)) quote-char))
(setq i (1+ i)))
i))
(defun python-syntax-stringify ()
"Put `syntax-table' property correctly on single/triple quotes."
(let* ((ppss (save-excursion (backward-char 3) (syntax-ppss)))
(string-start (and (eq t (nth 3 ppss)) (nth 8 ppss)))
(string-literal-concat (numberp (nth 3 ppss)))
(quote-starting-pos (- (point) 3))
(quote-ending-pos (point)))
(cond ((or (nth 4 ppss) ;Inside a comment
(and string-start
;; Inside of a string quoted with different triple quotes.
(not (eql (char-after string-start)
(char-after quote-starting-pos)))))
;; Do nothing.
nil)
((nth 5 ppss)
;; The first quote is escaped, so it's not part of a triple quote!
(goto-char (1+ quote-starting-pos)))
;; Handle string literal concatenation (bug#45897)
(string-literal-concat nil)
((null string-start)
;; This set of quotes delimit the start of a string. Put
;; string fence syntax on last quote. (bug#49518)
;; FIXME: This makes sexp-movement a bit suboptimal since """a"""
;; is now treated as 3 strings.
;; We could probably have our cake and eat it too by
;; putting the string fence on the first quote and then
;; convincing `syntax-ppss-flush-cache' to flush to before
;; that fence when any char of the 3-char delimiter
;; is modified.
(put-text-property (1- quote-ending-pos) quote-ending-pos
'syntax-table (string-to-syntax "|")))
(t