##// END OF EJS Templates
Whoops! Removed sphinx references
Jonathan Frederic -
Show More
@@ -1,280 +1,279 b''
1 """This module defines Exporter, a highly configurable converter
1 """This module defines Exporter, a highly configurable converter
2 that uses Jinja2 to export notebook files into different formats.
2 that uses Jinja2 to export notebook files into different formats.
3 """
3 """
4
4
5 #-----------------------------------------------------------------------------
5 #-----------------------------------------------------------------------------
6 # Copyright (c) 2013, the IPython Development Team.
6 # Copyright (c) 2013, the IPython Development Team.
7 #
7 #
8 # Distributed under the terms of the Modified BSD License.
8 # Distributed under the terms of the Modified BSD License.
9 #
9 #
10 # The full license is in the file COPYING.txt, distributed with this software.
10 # The full license is in the file COPYING.txt, distributed with this software.
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12
12
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14 # Imports
14 # Imports
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16
16
17 from __future__ import print_function, absolute_import
17 from __future__ import print_function, absolute_import
18
18
19 # Stdlib imports
19 # Stdlib imports
20 import io
20 import io
21 import os
21 import os
22 import copy
22 import copy
23 import collections
23 import collections
24 import datetime
24 import datetime
25
25
26
26
27 # IPython imports
27 # IPython imports
28 from IPython.config.configurable import LoggingConfigurable
28 from IPython.config.configurable import LoggingConfigurable
29 from IPython.config import Config
29 from IPython.config import Config
30 from IPython.nbformat import current as nbformat
30 from IPython.nbformat import current as nbformat
31 from IPython.utils.traitlets import MetaHasTraits, Unicode, List
31 from IPython.utils.traitlets import MetaHasTraits, Unicode, List
32 from IPython.utils.importstring import import_item
32 from IPython.utils.importstring import import_item
33 from IPython.utils import text, py3compat
33 from IPython.utils import text, py3compat
34
34
35 from IPython.nbconvert import preprocessors as nbpreprocessors
35 from IPython.nbconvert import preprocessors as nbpreprocessors
36
36
37
37
38 #-----------------------------------------------------------------------------
38 #-----------------------------------------------------------------------------
39 # Class
39 # Class
40 #-----------------------------------------------------------------------------
40 #-----------------------------------------------------------------------------
41
41
42 class ResourcesDict(collections.defaultdict):
42 class ResourcesDict(collections.defaultdict):
43 def __missing__(self, key):
43 def __missing__(self, key):
44 return ''
44 return ''
45
45
46
46
47 class Exporter(LoggingConfigurable):
47 class Exporter(LoggingConfigurable):
48 """
48 """
49 Class containing methods that sequentially run a list of preprocessors on a
49 Class containing methods that sequentially run a list of preprocessors on a
50 NotebookNode object and then return the modified NotebookNode object and
50 NotebookNode object and then return the modified NotebookNode object and
51 accompanying resources dict.
51 accompanying resources dict.
52 """
52 """
53
53
54 file_extension = Unicode(
54 file_extension = Unicode(
55 'txt', config=True,
55 'txt', config=True,
56 help="Extension of the file that should be written to disk"
56 help="Extension of the file that should be written to disk"
57 )
57 )
58
58
59 #Configurability, allows the user to easily add filters and preprocessors.
59 #Configurability, allows the user to easily add filters and preprocessors.
60 preprocessors = List(config=True,
60 preprocessors = List(config=True,
61 help="""List of preprocessors, by name or namespace, to enable.""")
61 help="""List of preprocessors, by name or namespace, to enable.""")
62
62
63 _preprocessors = None
63 _preprocessors = None
64
64
65 default_preprocessors = List([nbpreprocessors.coalesce_streams,
65 default_preprocessors = List([nbpreprocessors.coalesce_streams,
66 nbpreprocessors.SVG2PDFPreprocessor,
66 nbpreprocessors.SVG2PDFPreprocessor,
67 nbpreprocessors.ExtractOutputPreprocessor,
67 nbpreprocessors.ExtractOutputPreprocessor,
68 nbpreprocessors.CSSHTMLHeaderPreprocessor,
68 nbpreprocessors.CSSHTMLHeaderPreprocessor,
69 nbpreprocessors.RevealHelpPreprocessor,
69 nbpreprocessors.RevealHelpPreprocessor,
70 nbpreprocessors.LatexPreprocessor,
70 nbpreprocessors.LatexPreprocessor,
71 nbpreprocessors.SphinxPreprocessor,
72 nbpreprocessors.HighlightMagicsPreprocessor],
71 nbpreprocessors.HighlightMagicsPreprocessor],
73 config=True,
72 config=True,
74 help="""List of preprocessors available by default, by name, namespace,
73 help="""List of preprocessors available by default, by name, namespace,
75 instance, or type.""")
74 instance, or type.""")
76
75
77
76
78 def __init__(self, config=None, **kw):
77 def __init__(self, config=None, **kw):
79 """
78 """
80 Public constructor
79 Public constructor
81
80
82 Parameters
81 Parameters
83 ----------
82 ----------
84 config : config
83 config : config
85 User configuration instance.
84 User configuration instance.
86 """
85 """
87 if not config:
86 if not config:
88 config = self.default_config
87 config = self.default_config
89
88
90 super(Exporter, self).__init__(config=config, **kw)
89 super(Exporter, self).__init__(config=config, **kw)
91
90
92 #Init
91 #Init
93 self._init_preprocessors()
92 self._init_preprocessors()
94
93
95
94
96 @property
95 @property
97 def default_config(self):
96 def default_config(self):
98 return Config()
97 return Config()
99
98
100 def _config_changed(self, name, old, new):
99 def _config_changed(self, name, old, new):
101 """When setting config, make sure to start with our default_config"""
100 """When setting config, make sure to start with our default_config"""
102 c = self.default_config
101 c = self.default_config
103 if new:
102 if new:
104 c.merge(new)
103 c.merge(new)
105 if c != old:
104 if c != old:
106 self.config = c
105 self.config = c
107 super(Exporter, self)._config_changed(name, old, c)
106 super(Exporter, self)._config_changed(name, old, c)
108
107
109
108
110 def from_notebook_node(self, nb, resources=None, **kw):
109 def from_notebook_node(self, nb, resources=None, **kw):
111 """
110 """
112 Convert a notebook from a notebook node instance.
111 Convert a notebook from a notebook node instance.
113
112
114 Parameters
113 Parameters
115 ----------
114 ----------
116 nb : Notebook node
115 nb : Notebook node
117 resources : dict (**kw)
116 resources : dict (**kw)
118 of additional resources that can be accessed read/write by
117 of additional resources that can be accessed read/write by
119 preprocessors.
118 preprocessors.
120 """
119 """
121 nb_copy = copy.deepcopy(nb)
120 nb_copy = copy.deepcopy(nb)
122 resources = self._init_resources(resources)
121 resources = self._init_resources(resources)
123
122
124 # Preprocess
123 # Preprocess
125 nb_copy, resources = self._preprocess(nb_copy, resources)
124 nb_copy, resources = self._preprocess(nb_copy, resources)
126
125
127 return nb_copy, resources
126 return nb_copy, resources
128
127
129
128
130 def from_filename(self, filename, resources=None, **kw):
129 def from_filename(self, filename, resources=None, **kw):
131 """
130 """
132 Convert a notebook from a notebook file.
131 Convert a notebook from a notebook file.
133
132
134 Parameters
133 Parameters
135 ----------
134 ----------
136 filename : str
135 filename : str
137 Full filename of the notebook file to open and convert.
136 Full filename of the notebook file to open and convert.
138 """
137 """
139
138
140 # Pull the metadata from the filesystem.
139 # Pull the metadata from the filesystem.
141 if resources is None:
140 if resources is None:
142 resources = ResourcesDict()
141 resources = ResourcesDict()
143 if not 'metadata' in resources or resources['metadata'] == '':
142 if not 'metadata' in resources or resources['metadata'] == '':
144 resources['metadata'] = ResourcesDict()
143 resources['metadata'] = ResourcesDict()
145 basename = os.path.basename(filename)
144 basename = os.path.basename(filename)
146 notebook_name = basename[:basename.rfind('.')]
145 notebook_name = basename[:basename.rfind('.')]
147 resources['metadata']['name'] = notebook_name
146 resources['metadata']['name'] = notebook_name
148
147
149 modified_date = datetime.datetime.fromtimestamp(os.path.getmtime(filename))
148 modified_date = datetime.datetime.fromtimestamp(os.path.getmtime(filename))
150 resources['metadata']['modified_date'] = modified_date.strftime(text.date_format)
149 resources['metadata']['modified_date'] = modified_date.strftime(text.date_format)
151
150
152 with io.open(filename) as f:
151 with io.open(filename) as f:
153 return self.from_notebook_node(nbformat.read(f, 'json'), resources=resources, **kw)
152 return self.from_notebook_node(nbformat.read(f, 'json'), resources=resources, **kw)
154
153
155
154
156 def from_file(self, file_stream, resources=None, **kw):
155 def from_file(self, file_stream, resources=None, **kw):
157 """
156 """
158 Convert a notebook from a notebook file.
157 Convert a notebook from a notebook file.
159
158
160 Parameters
159 Parameters
161 ----------
160 ----------
162 file_stream : file-like object
161 file_stream : file-like object
163 Notebook file-like object to convert.
162 Notebook file-like object to convert.
164 """
163 """
165 return self.from_notebook_node(nbformat.read(file_stream, 'json'), resources=resources, **kw)
164 return self.from_notebook_node(nbformat.read(file_stream, 'json'), resources=resources, **kw)
166
165
167
166
168 def register_preprocessor(self, preprocessor, enabled=False):
167 def register_preprocessor(self, preprocessor, enabled=False):
169 """
168 """
170 Register a preprocessor.
169 Register a preprocessor.
171 Preprocessors are classes that act upon the notebook before it is
170 Preprocessors are classes that act upon the notebook before it is
172 passed into the Jinja templating engine. preprocessors are also
171 passed into the Jinja templating engine. preprocessors are also
173 capable of passing additional information to the Jinja
172 capable of passing additional information to the Jinja
174 templating engine.
173 templating engine.
175
174
176 Parameters
175 Parameters
177 ----------
176 ----------
178 preprocessor : preprocessor
177 preprocessor : preprocessor
179 """
178 """
180 if preprocessor is None:
179 if preprocessor is None:
181 raise TypeError('preprocessor')
180 raise TypeError('preprocessor')
182 isclass = isinstance(preprocessor, type)
181 isclass = isinstance(preprocessor, type)
183 constructed = not isclass
182 constructed = not isclass
184
183
185 # Handle preprocessor's registration based on it's type
184 # Handle preprocessor's registration based on it's type
186 if constructed and isinstance(preprocessor, py3compat.string_types):
185 if constructed and isinstance(preprocessor, py3compat.string_types):
187 # Preprocessor is a string, import the namespace and recursively call
186 # Preprocessor is a string, import the namespace and recursively call
188 # this register_preprocessor method
187 # this register_preprocessor method
189 preprocessor_cls = import_item(preprocessor)
188 preprocessor_cls = import_item(preprocessor)
190 return self.register_preprocessor(preprocessor_cls, enabled)
189 return self.register_preprocessor(preprocessor_cls, enabled)
191
190
192 if constructed and hasattr(preprocessor, '__call__'):
191 if constructed and hasattr(preprocessor, '__call__'):
193 # Preprocessor is a function, no need to construct it.
192 # Preprocessor is a function, no need to construct it.
194 # Register and return the preprocessor.
193 # Register and return the preprocessor.
195 if enabled:
194 if enabled:
196 preprocessor.enabled = True
195 preprocessor.enabled = True
197 self._preprocessors.append(preprocessor)
196 self._preprocessors.append(preprocessor)
198 return preprocessor
197 return preprocessor
199
198
200 elif isclass and isinstance(preprocessor, MetaHasTraits):
199 elif isclass and isinstance(preprocessor, MetaHasTraits):
201 # Preprocessor is configurable. Make sure to pass in new default for
200 # Preprocessor is configurable. Make sure to pass in new default for
202 # the enabled flag if one was specified.
201 # the enabled flag if one was specified.
203 self.register_preprocessor(preprocessor(parent=self), enabled)
202 self.register_preprocessor(preprocessor(parent=self), enabled)
204
203
205 elif isclass:
204 elif isclass:
206 # Preprocessor is not configurable, construct it
205 # Preprocessor is not configurable, construct it
207 self.register_preprocessor(preprocessor(), enabled)
206 self.register_preprocessor(preprocessor(), enabled)
208
207
209 else:
208 else:
210 # Preprocessor is an instance of something without a __call__
209 # Preprocessor is an instance of something without a __call__
211 # attribute.
210 # attribute.
212 raise TypeError('preprocessor')
211 raise TypeError('preprocessor')
213
212
214
213
215 def _init_preprocessors(self):
214 def _init_preprocessors(self):
216 """
215 """
217 Register all of the preprocessors needed for this exporter, disabled
216 Register all of the preprocessors needed for this exporter, disabled
218 unless specified explicitly.
217 unless specified explicitly.
219 """
218 """
220 if self._preprocessors is None:
219 if self._preprocessors is None:
221 self._preprocessors = []
220 self._preprocessors = []
222
221
223 #Load default preprocessors (not necessarly enabled by default).
222 #Load default preprocessors (not necessarly enabled by default).
224 if self.default_preprocessors:
223 if self.default_preprocessors:
225 for preprocessor in self.default_preprocessors:
224 for preprocessor in self.default_preprocessors:
226 self.register_preprocessor(preprocessor)
225 self.register_preprocessor(preprocessor)
227
226
228 #Load user preprocessors. Enable by default.
227 #Load user preprocessors. Enable by default.
229 if self.preprocessors:
228 if self.preprocessors:
230 for preprocessor in self.preprocessors:
229 for preprocessor in self.preprocessors:
231 self.register_preprocessor(preprocessor, enabled=True)
230 self.register_preprocessor(preprocessor, enabled=True)
232
231
233
232
234 def _init_resources(self, resources):
233 def _init_resources(self, resources):
235
234
236 #Make sure the resources dict is of ResourcesDict type.
235 #Make sure the resources dict is of ResourcesDict type.
237 if resources is None:
236 if resources is None:
238 resources = ResourcesDict()
237 resources = ResourcesDict()
239 if not isinstance(resources, ResourcesDict):
238 if not isinstance(resources, ResourcesDict):
240 new_resources = ResourcesDict()
239 new_resources = ResourcesDict()
241 new_resources.update(resources)
240 new_resources.update(resources)
242 resources = new_resources
241 resources = new_resources
243
242
244 #Make sure the metadata extension exists in resources
243 #Make sure the metadata extension exists in resources
245 if 'metadata' in resources:
244 if 'metadata' in resources:
246 if not isinstance(resources['metadata'], ResourcesDict):
245 if not isinstance(resources['metadata'], ResourcesDict):
247 resources['metadata'] = ResourcesDict(resources['metadata'])
246 resources['metadata'] = ResourcesDict(resources['metadata'])
248 else:
247 else:
249 resources['metadata'] = ResourcesDict()
248 resources['metadata'] = ResourcesDict()
250 if not resources['metadata']['name']:
249 if not resources['metadata']['name']:
251 resources['metadata']['name'] = 'Notebook'
250 resources['metadata']['name'] = 'Notebook'
252
251
253 #Set the output extension
252 #Set the output extension
254 resources['output_extension'] = self.file_extension
253 resources['output_extension'] = self.file_extension
255 return resources
254 return resources
256
255
257
256
258 def _preprocess(self, nb, resources):
257 def _preprocess(self, nb, resources):
259 """
258 """
260 Preprocess the notebook before passing it into the Jinja engine.
259 Preprocess the notebook before passing it into the Jinja engine.
261 To preprocess the notebook is to apply all of the
260 To preprocess the notebook is to apply all of the
262
261
263 Parameters
262 Parameters
264 ----------
263 ----------
265 nb : notebook node
264 nb : notebook node
266 notebook that is being exported.
265 notebook that is being exported.
267 resources : a dict of additional resources that
266 resources : a dict of additional resources that
268 can be accessed read/write by preprocessors
267 can be accessed read/write by preprocessors
269 """
268 """
270
269
271 # Do a copy.deepcopy first,
270 # Do a copy.deepcopy first,
272 # we are never safe enough with what the preprocessors could do.
271 # we are never safe enough with what the preprocessors could do.
273 nbc = copy.deepcopy(nb)
272 nbc = copy.deepcopy(nb)
274 resc = copy.deepcopy(resources)
273 resc = copy.deepcopy(resources)
275
274
276 #Run each preprocessor on the notebook. Carry the output along
275 #Run each preprocessor on the notebook. Carry the output along
277 #to each preprocessor
276 #to each preprocessor
278 for preprocessor in self._preprocessors:
277 for preprocessor in self._preprocessors:
279 nbc, resc = preprocessor(nbc, resc)
278 nbc, resc = preprocessor(nbc, resc)
280 return nbc, resc
279 return nbc, resc
@@ -1,13 +1,12 b''
1 # Class base Preprocessors
1 # Class base Preprocessors
2 from .base import Preprocessor
2 from .base import Preprocessor
3 from .convertfigures import ConvertFiguresPreprocessor
3 from .convertfigures import ConvertFiguresPreprocessor
4 from .svg2pdf import SVG2PDFPreprocessor
4 from .svg2pdf import SVG2PDFPreprocessor
5 from .extractoutput import ExtractOutputPreprocessor
5 from .extractoutput import ExtractOutputPreprocessor
6 from .revealhelp import RevealHelpPreprocessor
6 from .revealhelp import RevealHelpPreprocessor
7 from .latex import LatexPreprocessor
7 from .latex import LatexPreprocessor
8 from .sphinx import SphinxPreprocessor
9 from .csshtmlheader import CSSHTMLHeaderPreprocessor
8 from .csshtmlheader import CSSHTMLHeaderPreprocessor
10 from .highlightmagics import HighlightMagicsPreprocessor
9 from .highlightmagics import HighlightMagicsPreprocessor
11
10
12 # decorated function Preprocessors
11 # decorated function Preprocessors
13 from .coalescestreams import coalesce_streams
12 from .coalescestreams import coalesce_streams
General Comments 0
You need to be logged in to leave comments. Login now