Show More
@@ -81,7 +81,7 b' from warnings import warn' | |||
|
81 | 81 | from logging import error |
|
82 | 82 | import IPython.core.hooks |
|
83 | 83 | |
|
84 | from typing import List as ListType | |
|
84 | from typing import List as ListType, Tuple | |
|
85 | 85 | from ast import AST |
|
86 | 86 | |
|
87 | 87 | # NoOpContext is deprecated, but ipykernel imports it from here. |
@@ -3287,7 +3287,7 b' class InteractiveShell(SingletonConfigurable):' | |||
|
3287 | 3287 | # For backwards compatibility |
|
3288 | 3288 | runcode = run_code |
|
3289 | 3289 | |
|
3290 | def check_complete(self, code): | |
|
3290 | def check_complete(self, code: str) -> Tuple[str, str]: | |
|
3291 | 3291 | """Return whether a block of code is ready to execute, or should be continued |
|
3292 | 3292 | |
|
3293 | 3293 | Parameters |
@@ -2,12 +2,67 b'' | |||
|
2 | 2 | """ |
|
3 | 3 | Sphinx directive to support embedded IPython code. |
|
4 | 4 | |
|
5 | IPython provides an extension for `Sphinx <http://www.sphinx-doc.org/>`_ to | |
|
6 | highlight and run code. | |
|
7 | ||
|
5 | 8 | This directive allows pasting of entire interactive IPython sessions, prompts |
|
6 | 9 | and all, and their code will actually get re-executed at doc build time, with |
|
7 | 10 | all prompts renumbered sequentially. It also allows you to input code as a pure |
|
8 | 11 | python input by giving the argument python to the directive. The output looks |
|
9 | 12 | like an interactive ipython section. |
|
10 | 13 | |
|
14 | Here is an example of how the IPython directive can | |
|
15 | **run** python code, at build time. | |
|
16 | ||
|
17 | .. ipython:: | |
|
18 | ||
|
19 | In [1]: 1+1 | |
|
20 | ||
|
21 | In [1]: import datetime | |
|
22 | ...: datetime.datetime.now() | |
|
23 | ||
|
24 | It supports IPython construct that plain | |
|
25 | Python does not understand (like magics): | |
|
26 | ||
|
27 | .. ipython:: | |
|
28 | ||
|
29 | In [0]: import time | |
|
30 | ||
|
31 | In [0]: %timeit time.sleep(0.05) | |
|
32 | ||
|
33 | This will also support top-level async when using IPython 7.0+ | |
|
34 | ||
|
35 | .. ipython:: | |
|
36 | ||
|
37 | In [2]: import asyncio | |
|
38 | ...: print('before') | |
|
39 | ...: await asyncio.sleep(1) | |
|
40 | ...: print('after') | |
|
41 | ||
|
42 | ||
|
43 | The namespace will persist across multiple code chucks, Let's define a variable: | |
|
44 | ||
|
45 | .. ipython:: | |
|
46 | ||
|
47 | In [0]: who = "World" | |
|
48 | ||
|
49 | And now say hello: | |
|
50 | ||
|
51 | .. ipython:: | |
|
52 | ||
|
53 | In [0]: print('Hello,', who) | |
|
54 | ||
|
55 | If the current section raises an exception, you can add the ``:okexcept:`` flag | |
|
56 | to the current block, otherwise the build will fail. | |
|
57 | ||
|
58 | .. ipython:: | |
|
59 | :okexcept: | |
|
60 | ||
|
61 | In [1]: 1/0 | |
|
62 | ||
|
63 | IPython Sphinx directive module | |
|
64 | =============================== | |
|
65 | ||
|
11 | 66 | To enable this directive, simply list it in your Sphinx ``conf.py`` file |
|
12 | 67 | (making sure the directory where you placed it is visible to sphinx, as is |
|
13 | 68 | needed for all Sphinx directives). For example, to enable syntax highlighting |
@@ -27,19 +82,19 b' ipython_savefig_dir:' | |||
|
27 | 82 | Sphinx source directory. The default is `html_static_path`. |
|
28 | 83 | ipython_rgxin: |
|
29 | 84 | The compiled regular expression to denote the start of IPython input |
|
30 | lines. The default is re.compile('In \[(\d+)\]:\s?(.*)\s*'). You | |
|
85 | lines. The default is ``re.compile('In \[(\d+)\]:\s?(.*)\s*')``. You | |
|
31 | 86 | shouldn't need to change this. |
|
32 | 87 | ipython_rgxout: |
|
33 | 88 | The compiled regular expression to denote the start of IPython output |
|
34 | lines. The default is re.compile('Out\[(\d+)\]:\s?(.*)\s*'). You | |
|
89 | lines. The default is ``re.compile('Out\[(\d+)\]:\s?(.*)\s*')``. You | |
|
35 | 90 | shouldn't need to change this. |
|
36 | 91 | ipython_promptin: |
|
37 | 92 | The string to represent the IPython input prompt in the generated ReST. |
|
38 | The default is 'In [%d]:'. This expects that the line numbers are used | |
|
93 | The default is ``'In [%d]:'``. This expects that the line numbers are used | |
|
39 | 94 | in the prompt. |
|
40 | 95 | ipython_promptout: |
|
41 | 96 | The string to represent the IPython prompt in the generated ReST. The |
|
42 | default is 'Out [%d]:'. This expects that the line numbers are used | |
|
97 | default is ``'Out [%d]:'``. This expects that the line numbers are used | |
|
43 | 98 | in the prompt. |
|
44 | 99 | ipython_mplbackend: |
|
45 | 100 | The string which specifies if the embedded Sphinx shell should import |
@@ -54,7 +109,7 b' ipython_execlines:' | |||
|
54 | 109 | A list of strings to be exec'd in the embedded Sphinx shell. Typical |
|
55 | 110 | usage is to make certain packages always available. Set this to an empty |
|
56 | 111 | list if you wish to have no imports always available. If specified in |
|
57 | conf.py as `None`, then it has the effect of making no imports available. | |
|
112 | ``conf.py`` as `None`, then it has the effect of making no imports available. | |
|
58 | 113 | If omitted from conf.py altogether, then the default value of |
|
59 | 114 | ['import numpy as np', 'import matplotlib.pyplot as plt'] is used. |
|
60 | 115 | ipython_holdcount |
@@ -105,21 +160,22 b' or :okwarning: options:' | |||
|
105 | 160 | In [2]: # raise warning. |
|
106 | 161 | |
|
107 | 162 | To Do |
|
108 | ----- | |
|
163 | ===== | |
|
109 | 164 | |
|
110 | 165 | - Turn the ad-hoc test() function into a real test suite. |
|
111 | 166 | - Break up ipython-specific functionality from matplotlib stuff into better |
|
112 | 167 | separated code. |
|
113 | 168 | |
|
114 | Authors | |
|
115 | ------- | |
|
116 | ||
|
117 | - John D Hunter: original author. | |
|
118 | - Fernando Perez: refactoring, documentation, cleanups, port to 0.11. | |
|
119 | - VáclavŠmilauer <eudoxos-AT-arcig.cz>: Prompt generalizations. | |
|
120 | - Skipper Seabold, refactoring, cleanups, pure python addition | |
|
121 | 169 | """ |
|
122 | 170 | |
|
171 | # Authors | |
|
172 | # ======= | |
|
173 | # | |
|
174 | # - John D Hunter: original author. | |
|
175 | # - Fernando Perez: refactoring, documentation, cleanups, port to 0.11. | |
|
176 | # - VáclavŠmilauer <eudoxos-AT-arcig.cz>: Prompt generalizations. | |
|
177 | # - Skipper Seabold, refactoring, cleanups, pure python addition | |
|
178 | ||
|
123 | 179 | #----------------------------------------------------------------------------- |
|
124 | 180 | # Imports |
|
125 | 181 | #----------------------------------------------------------------------------- |
@@ -145,6 +201,14 b' from traitlets.config import Config' | |||
|
145 | 201 | from IPython import InteractiveShell |
|
146 | 202 | from IPython.core.profiledir import ProfileDir |
|
147 | 203 | |
|
204 | ||
|
205 | use_matpltolib = False | |
|
206 | try: | |
|
207 | import matplotlib | |
|
208 | use_matpltolib = True | |
|
209 | except Exception: | |
|
210 | pass | |
|
211 | ||
|
148 | 212 | #----------------------------------------------------------------------------- |
|
149 | 213 | # Globals |
|
150 | 214 | #----------------------------------------------------------------------------- |
@@ -325,13 +389,12 b' class EmbeddedSphinxShell(object):' | |||
|
325 | 389 | |
|
326 | 390 | def process_input_line(self, line, store_history=True): |
|
327 | 391 | """process the input, capturing stdout""" |
|
328 | ||
|
329 | 392 | stdout = sys.stdout |
|
330 | 393 | try: |
|
331 | 394 | sys.stdout = self.cout |
|
332 | 395 | self.lines_waiting.append(line) |
|
333 | if self.IP.check_complete()[0] != 'incomplete': | |
|
334 | source_raw = ''.join(self.lines_waiting) | |
|
396 | source_raw = ''.join(self.lines_waiting) | |
|
397 | if self.IP.check_complete(source_raw)[0] != 'incomplete': | |
|
335 | 398 | self.lines_waiting = [] |
|
336 | 399 | self.IP.run_cell(source_raw, store_history=store_history) |
|
337 | 400 | finally: |
@@ -501,6 +564,7 b' class EmbeddedSphinxShell(object):' | |||
|
501 | 564 | sys.stdout.write(s) |
|
502 | 565 | sys.stdout.write(processed_output) |
|
503 | 566 | sys.stdout.write('<<<' + ('-' * 73) + '\n\n') |
|
567 | raise RuntimeError('Non Expected exception in `{}` line {}'.format(filename, lineno)) | |
|
504 | 568 | |
|
505 | 569 | # output any warning raised during execution to stdout |
|
506 | 570 | # unless :okwarning: has been specified. |
@@ -515,6 +579,7 b' class EmbeddedSphinxShell(object):' | |||
|
515 | 579 | w.filename, w.lineno, w.line) |
|
516 | 580 | sys.stdout.write(s) |
|
517 | 581 | sys.stdout.write('<<<' + ('-' * 73) + '\n') |
|
582 | raise RuntimeError('Non Expected warning in `{}` line {}'.format(filename, lineno)) | |
|
518 | 583 | |
|
519 | 584 | self.cout.truncate(0) |
|
520 | 585 | |
@@ -866,7 +931,7 b' class IPythonDirective(Directive):' | |||
|
866 | 931 | # EmbeddedSphinxShell is created, its interactive shell member |
|
867 | 932 | # is the same for each instance. |
|
868 | 933 | |
|
869 | if mplbackend and 'matplotlib.backends' not in sys.modules: | |
|
934 | if mplbackend and 'matplotlib.backends' not in sys.modules and use_matpltolib: | |
|
870 | 935 | import matplotlib |
|
871 | 936 | matplotlib.use(mplbackend) |
|
872 | 937 | |
@@ -985,7 +1050,9 b' def setup(app):' | |||
|
985 | 1050 | |
|
986 | 1051 | # If the user sets this config value to `None`, then EmbeddedSphinxShell's |
|
987 | 1052 | # __init__ method will treat it as []. |
|
988 |
execlines = ['import numpy as np' |
|
|
1053 | execlines = ['import numpy as np'] | |
|
1054 | if use_matpltolib: | |
|
1055 | execlines.append('import matplotlib.pyplot as plt') | |
|
989 | 1056 | app.add_config_value('ipython_execlines', execlines, 'env') |
|
990 | 1057 | |
|
991 | 1058 | app.add_config_value('ipython_holdcount', True, 'env') |
General Comments 0
You need to be logged in to leave comments.
Login now