##// END OF EJS Templates
rollback singleton exporter instances in `export_foo`
MinRK -
Show More
@@ -1,176 +1,169 b''
1 """
1 """
2 Module containing single call export functions.
2 Module containing single call export functions.
3 """
3 """
4 #-----------------------------------------------------------------------------
4 #-----------------------------------------------------------------------------
5 # Copyright (c) 2013, the IPython Development Team.
5 # Copyright (c) 2013, the IPython Development Team.
6 #
6 #
7 # Distributed under the terms of the Modified BSD License.
7 # Distributed under the terms of the Modified BSD License.
8 #
8 #
9 # The full license is in the file COPYING.txt, distributed with this software.
9 # The full license is in the file COPYING.txt, distributed with this software.
10 #-----------------------------------------------------------------------------
10 #-----------------------------------------------------------------------------
11
11
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13 # Imports
13 # Imports
14 #-----------------------------------------------------------------------------
14 #-----------------------------------------------------------------------------
15
15
16 from functools import wraps
16 from functools import wraps
17
17
18 from IPython.nbformat.v3.nbbase import NotebookNode
18 from IPython.nbformat.v3.nbbase import NotebookNode
19 from IPython.config import Config
19 from IPython.config import Config
20
20
21 from .exporter import Exporter
21 from .exporter import Exporter
22 from .html import HTMLExporter
22 from .html import HTMLExporter
23 from .slides import SlidesExporter
23 from .slides import SlidesExporter
24 from .latex import LatexExporter
24 from .latex import LatexExporter
25 from .markdown import MarkdownExporter
25 from .markdown import MarkdownExporter
26 from .python import PythonExporter
26 from .python import PythonExporter
27 from .rst import RSTExporter
27 from .rst import RSTExporter
28
28
29 #-----------------------------------------------------------------------------
29 #-----------------------------------------------------------------------------
30 # Classes
30 # Classes
31 #-----------------------------------------------------------------------------
31 #-----------------------------------------------------------------------------
32
32
33 def DocDecorator(f):
33 def DocDecorator(f):
34
34
35 #Set docstring of function
35 #Set docstring of function
36 f.__doc__ = f.__doc__ + """
36 f.__doc__ = f.__doc__ + """
37 nb : Notebook node
37 nb : Notebook node
38 config : config (optional, keyword arg)
38 config : config (optional, keyword arg)
39 User configuration instance.
39 User configuration instance.
40 resources : dict (optional, keyword arg)
40 resources : dict (optional, keyword arg)
41 Resources used in the conversion process.
41 Resources used in the conversion process.
42
42
43 Returns
43 Returns
44 ----------
44 ----------
45 tuple- output, resources, exporter_instance
45 tuple- output, resources, exporter_instance
46 output : str
46 output : str
47 Jinja 2 output. This is the resulting converted notebook.
47 Jinja 2 output. This is the resulting converted notebook.
48 resources : dictionary
48 resources : dictionary
49 Dictionary of resources used prior to and during the conversion
49 Dictionary of resources used prior to and during the conversion
50 process.
50 process.
51 exporter_instance : Exporter
51 exporter_instance : Exporter
52 Instance of the Exporter class used to export the document. Useful
52 Instance of the Exporter class used to export the document. Useful
53 to caller because it provides a 'file_extension' property which
53 to caller because it provides a 'file_extension' property which
54 specifies what extension the output should be saved as.
54 specifies what extension the output should be saved as.
55
55
56 WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
56 WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
57 """
57 """
58
58
59 @wraps(f)
59 @wraps(f)
60 def decorator(*args, **kwargs):
60 def decorator(*args, **kwargs):
61 return f(*args, **kwargs)
61 return f(*args, **kwargs)
62
62
63 return decorator
63 return decorator
64
64
65
65
66 #-----------------------------------------------------------------------------
66 #-----------------------------------------------------------------------------
67 # Functions
67 # Functions
68 #-----------------------------------------------------------------------------
68 #-----------------------------------------------------------------------------
69
69
70 __all__ = [
70 __all__ = [
71 'export',
71 'export',
72 'export_html',
72 'export_html',
73 'export_custom',
73 'export_custom',
74 'export_slides',
74 'export_slides',
75 'export_latex',
75 'export_latex',
76 'export_markdown',
76 'export_markdown',
77 'export_python',
77 'export_python',
78 'export_rst',
78 'export_rst',
79 'export_by_name',
79 'export_by_name',
80 'get_export_names',
80 'get_export_names',
81 'ExporterNameError'
81 'ExporterNameError'
82 ]
82 ]
83
83
84
84
85 class ExporterNameError(NameError):
85 class ExporterNameError(NameError):
86 pass
86 pass
87
87
88 _exporters = {}
89
90 @DocDecorator
88 @DocDecorator
91 def export(exporter, nb, **kw):
89 def export(exporter, nb, **kw):
92 """
90 """
93 Export a notebook object using specific exporter class.
91 Export a notebook object using specific exporter class.
94
92
95 exporter : Exporter class type or instance
93 exporter : Exporter class type or instance
96 Class type or instance of the exporter that should be used. If the
94 Class type or instance of the exporter that should be used. If the
97 method initializes it's own instance of the class, it is ASSUMED that
95 method initializes it's own instance of the class, it is ASSUMED that
98 the class type provided exposes a constructor (__init__) with the same
96 the class type provided exposes a constructor (__init__) with the same
99 signature as the base Exporter class.
97 signature as the base Exporter class.
100 """
98 """
101
99
102 #Check arguments
100 #Check arguments
103 if exporter is None:
101 if exporter is None:
104 raise TypeError("Exporter is None")
102 raise TypeError("Exporter is None")
105 elif not isinstance(exporter, Exporter) and not issubclass(exporter, Exporter):
103 elif not isinstance(exporter, Exporter) and not issubclass(exporter, Exporter):
106 raise TypeError("exporter does not inherit from Exporter (base)")
104 raise TypeError("exporter does not inherit from Exporter (base)")
107 if nb is None:
105 if nb is None:
108 raise TypeError("nb is None")
106 raise TypeError("nb is None")
109
107
110 #Create the exporter
108 #Create the exporter
111 resources = kw.pop('resources', None)
109 resources = kw.pop('resources', None)
112 if isinstance(exporter, Exporter):
110 if isinstance(exporter, Exporter):
113 exporter_instance = exporter
111 exporter_instance = exporter
114 else:
112 else:
115 if exporter not in _exporters:
113 exporter_instance = exporter(**kw)
116 exporter_instance = _exporters[exporter] = exporter(**kw)
114
117 else:
118 exporter_instance = _exporters[exporter]
119 for attr, value in kw.items():
120 setattr(exporter_instance, attr, value)
121
122 #Try to convert the notebook using the appropriate conversion function.
115 #Try to convert the notebook using the appropriate conversion function.
123 if isinstance(nb, NotebookNode):
116 if isinstance(nb, NotebookNode):
124 output, resources = exporter_instance.from_notebook_node(nb, resources)
117 output, resources = exporter_instance.from_notebook_node(nb, resources)
125 elif isinstance(nb, basestring):
118 elif isinstance(nb, basestring):
126 output, resources = exporter_instance.from_filename(nb, resources)
119 output, resources = exporter_instance.from_filename(nb, resources)
127 else:
120 else:
128 output, resources = exporter_instance.from_file(nb, resources)
121 output, resources = exporter_instance.from_file(nb, resources)
129 return output, resources
122 return output, resources
130
123
131 exporter_map = dict(
124 exporter_map = dict(
132 custom=Exporter,
125 custom=Exporter,
133 html=HTMLExporter,
126 html=HTMLExporter,
134 slides=SlidesExporter,
127 slides=SlidesExporter,
135 latex=LatexExporter,
128 latex=LatexExporter,
136 markdown=MarkdownExporter,
129 markdown=MarkdownExporter,
137 python=PythonExporter,
130 python=PythonExporter,
138 rst=RSTExporter,
131 rst=RSTExporter,
139 )
132 )
140
133
141 def _make_exporter(name, E):
134 def _make_exporter(name, E):
142 """make an export_foo function from a short key and Exporter class E"""
135 """make an export_foo function from a short key and Exporter class E"""
143 def _export(nb, **kw):
136 def _export(nb, **kw):
144 return export(E, nb, **kw)
137 return export(E, nb, **kw)
145 _export.__doc__ = """Export a notebook object to {0} format""".format(name)
138 _export.__doc__ = """Export a notebook object to {0} format""".format(name)
146 return _export
139 return _export
147
140
148 g = globals()
141 g = globals()
149
142
150 for name, E in exporter_map.items():
143 for name, E in exporter_map.items():
151 g['export_%s' % name] = DocDecorator(_make_exporter(name, E))
144 g['export_%s' % name] = DocDecorator(_make_exporter(name, E))
152
145
153 @DocDecorator
146 @DocDecorator
154 def export_by_name(format_name, nb, **kw):
147 def export_by_name(format_name, nb, **kw):
155 """
148 """
156 Export a notebook object to a template type by its name. Reflection
149 Export a notebook object to a template type by its name. Reflection
157 (Inspect) is used to find the template's corresponding explicit export
150 (Inspect) is used to find the template's corresponding explicit export
158 method defined in this module. That method is then called directly.
151 method defined in this module. That method is then called directly.
159
152
160 format_name : str
153 format_name : str
161 Name of the template style to export to.
154 Name of the template style to export to.
162 """
155 """
163
156
164 function_name = "export_" + format_name.lower()
157 function_name = "export_" + format_name.lower()
165
158
166 if function_name in globals():
159 if function_name in globals():
167 return globals()[function_name](nb, **kw)
160 return globals()[function_name](nb, **kw)
168 else:
161 else:
169 raise ExporterNameError("template for `%s` not found" % function_name)
162 raise ExporterNameError("template for `%s` not found" % function_name)
170
163
171
164
172 def get_export_names():
165 def get_export_names():
173 """Return a list of the currently supported export targets
166 """Return a list of the currently supported export targets
174
167
175 WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT"""
168 WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT"""
176 return sorted(exporter_map.keys())
169 return sorted(exporter_map.keys())
General Comments 0
You need to be logged in to leave comments. Login now