summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/pythontex/pythontex_utils.py
blob: 2731e7ab765dbe22e2c1756ce9baea991d4fe2bd (plain)
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
# -*- coding: utf-8 -*-
'''
PythonTeX utilities class for Python scripts.

The utilities class provides variables and methods for the individual 
Python scripts created and executed by PythonTeX.  An instance of the class 
named "pytex" is automatically created in each individual script.

Copyright (c) 2012-2014, Geoffrey M. Poore
All rights reserved.
Licensed under the BSD 3-Clause License:
    http://www.opensource.org/licenses/BSD-3-Clause

'''


# Imports
import sys
import warnings
if sys.version_info.major == 2:
    import io

# Most imports are only needed for SymPy; these are brought in via 
# "lazy import."  Importing unicode_literals here shouldn't ever be necessary 
# under Python 2.  If unicode_literals is imported in the main script, then 
# all strings in this script will be treated as bytes, and the main script 
# will try to decode the strings from this script as necessary.  The decoding 
# shouldn't cause any problems, since all strings in this file may be decoded 
# as valid ASCII. (The actual file is encoded in utf-8, but only characters 
# within the ASCII subset are actually used).


class PythonTeXUtils(object):
    '''
    A class of PythonTeX utilities.
    
    Provides variables for keeping track of TeX-side information, and methods
    for formatting and saving data.
    
    The following variables and methods will be created within instances 
    of the class during execution.
    
    String variables for keeping track of TeX information.  Most are 
    actually needed; the rest are included for completeness.
        * family
        * session
        * restart
        * command
        * context
        * args
        * instance
        * line
    
    Future file handle for output that is saved via macros
        * macrofile
    
    Future formatter function that is used to format output
        * formatter
    '''
    
    def __init__(self, fmtr='str'):
        '''
        Initialize
        '''
        self.set_formatter(fmtr)
    
    # We need a function that will process the raw `context` into a 
    # dictionary with attributes
    _context_raw = None
    class _DictWithAttr(dict):
        pass
    def set_context(self, expr):
        '''
        Convert the string `{context}` into a dict with attributes
        '''
        if not expr or expr == self._context_raw:
            pass
        else:
            self._context_raw = expr
            self.context = self._DictWithAttr()
            k_and_v = [map(lambda x: x.strip(), kv.split('=')) for kv in expr.split(',')]
            for k, v in k_and_v:
                if v.startswith('!!int '):
                    v = int(float(v[6:]))
                elif v.startswith('!!float '):
                    v = float(v[8:])
                elif v.startswith('!!str '):
                    v = v[6:]
                self.context[k] = v
                setattr(self.context, k, v)
    
    # A primary use for contextual information is to pass dimensions from the
    # TeX side to the Python side.  To make that as convenient as possible,
    # we need some length conversion functions.
    # Conversion reference:  http://tex.stackexchange.com/questions/41370/what-are-the-possible-dimensions-sizes-units-latex-understands
    def pt_to_in(self, expr):
        '''
        Convert points to inches.  Accepts numbers, strings of digits, and 
        strings of digits that end with `pt`.
        '''
        try:
            ans = expr/72.27
        except:
            if expr.endswith('pt'):
                expr = expr[:-2]
            ans = float(expr)/72.27
        return ans
    def pt_to_cm(self, expr):
        '''
        Convert points to centimeters.
        '''
        return self.pt_to_in(expr)*2.54
    def pt_to_mm(self, expr):
        '''
        Convert points to millimeters.
        '''
        return self.pt_to_in(expr)*25.4
    def pt_to_bp(self, expr):
        '''
        Convert points to big (DTP or PostScript) points.
        '''
        return self.pt_to_in(expr)*72
        
    
    # We need a context-aware interface to SymPy's latex printer.  The 
    # appearance of typeset math should depend on where it appears in a 
    # document.  (We will refer to the latex printer, rather than the LaTeX 
    # printer, because the two are separate.  Compare sympy.printing.latex 
    # and sympy.galgebra.latex_ex.)  
    #
    # Creating this interface takes some work.  We don't want to import 
    # anything from SymPy unless it is actually used, to keep things clean and 
    # fast.
    
    # First we create a tuple containing all LaTeX math styles.  These are 
    # the contexts that SymPy's latex printer must adapt to.
    # The style order doesn't matter, but it corresponds to that of \mathchoice
    _sympy_latex_styles = ('display', 'text', 'script', 'scriptscript')
    
    # Create the public functions for the user, and private functions that 
    # they call.  Two layers are necessary, because we need to be able to 
    # redefine the functions that do the actual work, once things are 
    # initialized.  But we don't want to redefine the public functions, since 
    # that could cause problems if the user defines a new function to be one 
    # of the public functions--the user's function would not change when
    # the method was redefined.
    def _sympy_latex(self, expr, **settings):
        self._init_sympy_latex()
        return self._sympy_latex(expr, **settings)
    
    def sympy_latex(self, expr, **settings):
        return self._sympy_latex(expr, **settings)
    
    def _set_sympy_latex(self, style, **kwargs):
        self._init_sympy_latex()
        self._set_sympy_latex(style, **kwargs)
    
    def set_sympy_latex(self, style, **kwargs):
        self._set_sympy_latex(style, **kwargs)
    # Temporary compatibility with deprecated methods
    def init_sympy_latex(self):
        warnings.warn('Method init_sympy_latex() is deprecated; init is now automatic.')
        self._init_sympy_latex()
    
    # Next we create a method that initializes the actual context-aware 
    # interface to SymPy's latex printer.
    def _init_sympy_latex(self):
        '''
        Initialize a context-aware interface to SymPy's latex printer.
        
        This consists of creating the dictionary of settings and creating the 
        sympy_latex method that serves as an interface to SymPy's 
        LatexPrinter.  This last step is actually performed by calling 
        self._make_sympy_latex().
        '''
        # Create dictionaries of settings for different contexts.
        # 
        # Currently, the main goal is to use pmatrix (or an equivalent) 
        # in \displaystyle contexts, and smallmatrix in \textstyle, 
        # \scriptstyle (superscript or subscript), and \scriptscriptstyle
        # (superscript or subscript of a superscript or subscript) 
        # contexts.  Basically, we want matrix size to automatically 
        # scale based on context.  It is expected that additional 
        # customization may prove useful as SymPy's LatexPrinter is 
        # further developed.
        #
        # The 'fold_frac_powers' option is probably the main other 
        # setting that might sometimes be nice to invoke in a 
        # context-dependent manner.
        #
        # In the default settings below, all matrices are set to use 
        # parentheses rather than square brackets.  This is largely a 
        # matter of personal preference.  The use of parentheses is based 
        # on the rationale that parentheses are less easily confused with 
        # the determinant and are easier to write by hand than are square 
        # brackets.  The settings for 'script' and 'scriptscript' are set
        # to those of 'text', since all of these should in general 
        # require a more compact representation of things.
        self._sympy_latex_settings = {'display': {'mat_str': 'pmatrix', 'mat_delim': None},
                                      'text': {'mat_str': 'smallmatrix', 'mat_delim': '('},
                                      'script': {'mat_str': 'smallmatrix', 'mat_delim': '('},
                                      'scriptscript': {'mat_str': 'smallmatrix', 'mat_delim': '('} }
        # Now we create a function for updating the settings.
        #
        # Note that EVERY time the settings are changed, we must call 
        # self._make_sympy_latex().  This is because the _sympy_latex() 
        # method is defined based on the settings, and every time the 
        # settings change, it may need to be redefined.  It would be 
        # possible to define _sympy_latex() so that its definition remained 
        # constant, simply drawing on the settings.  But most common 
        # combinations of settings allow more efficient versions of 
        # _sympy_latex() to be defined.
        def _set_sympy_latex(style, **kwargs):
            if style in self._sympy_latex_styles:
                self._sympy_latex_settings[style].update(kwargs)
            elif style == 'all':
                for s in self._sympy_latex_styles:
                    self._sympy_latex_settings[s].update(kwargs)
            else:
                warnings.warn('Unknown LaTeX math style ' + str(style))
            self._make_sympy_latex()
        self._set_sympy_latex = _set_sympy_latex
        
        # Now that the dictionaries of settings have been created, and 
        # the function for modifying the settings is in place, we are ready 
        # to create the actual interface.
        self._make_sympy_latex()
            
    # Finally, create the actual interface to SymPy's LatexPrinter
    def _make_sympy_latex(self):
        '''
        Create a context-aware interface to SymPy's LatexPrinter class.
        
        This is an interface to the LatexPrinter class, rather than 
        to the latex function, because the function is simply a 
        wrapper for accessing the class and because settings may be 
        passed to the class more easily.
        
        Context dependence is accomplished via LaTeX's \mathchoice macro.  
        This macros takes four arguments:
            \mathchoice{<display>}{<text>}{<script>}{<scriptscript>}
        All four arguments are typeset by LaTeX, and then the appropriate one 
        is actually typeset in the document based on the current style.  This 
        may seem like a very inefficient way of doing things, but this 
        approach is necessary because LaTeX doesn't know the math style at a 
        given point until after ALL mathematics have been typeset.  This is 
        because macros such as \over and \atop change the math style of things 
        that PRECEDE them.  See the following discussion for more information:
            http://tex.stackexchange.com/questions/1223/is-there-a-test-for-the-different-styles-inside-maths-mode
        
        The interface takes optional settings.  These optional 
        settings override the default context-dependent settings.  
        Accomplishing this mixture of settings requires (deep)copying 
        the default settings, then updating the copies with the optional 
        settings.  This leaves the default settings intact, with their 
        original values, for the next usage.
        
        The interface is created in various ways depending on the specific
        combination of context-specific settings.  While a general, static 
        interface could be created, that would involve invoking LatexPrinter 
        four times, once for each math style.  It would also require that 
        LaTeX process a \mathchoice macro for everything returned by 
        _sympy_latex(), which would add more inefficiency.  In practice, there 
        will generally be enough overlap between the different settings, and 
        the settings will be focused enough, that more efficient 
        implementations of _sympy_latex() are possible.
        
        Note that we perform a "lazy import" here.  We don't want to import
        the LatexPrinter unless we are sure to use it, since the import brings
        along a number of other dependencies from SymPy.  We don't want 
        unnecessary overhead from SymPy imports.
        '''
        # sys has already been imported        
        import copy
        try:
            from sympy.printing.latex import LatexPrinter
        except ImportError:
            sys.exit('Could not import from SymPy')
        
        # Go through a number of possible scenarios, to create an efficient 
        # implementation of sympy_latex()
        if all(self._sympy_latex_settings[style] == {} for style in self._sympy_latex_styles):
            def _sympy_latex(expr, **settings):
                '''            
                Deal with the case where there are no context-specific 
                settings.
                '''
                return LatexPrinter(settings).doprint(expr)
        elif all(self._sympy_latex_settings[style] == self._sympy_latex_settings['display'] for style in self._sympy_latex_styles):
            def _sympy_latex(expr, **settings):
                '''
                Deal with the case where all settings are identical, and thus 
                the settings are really only being used to set defaults, 
                rather than context-specific behavior.
                
                Check for empty settings, so as to avoid deepcopy
                '''
                if not settings:
                    return LatexPrinter(self._sympy_latex_settings['display']).doprint(expr)
                else:
                    final_settings = copy.deepcopy(self._sympy_latex_settings['display'])
                    final_settings.update(settings)
                    return LatexPrinter(final_settings).doprint(expr)
        elif all(self._sympy_latex_settings[style] == self._sympy_latex_settings['text'] for style in ('script', 'scriptscript')):
            def _sympy_latex(expr, **settings):
                '''
                Deal with the case where only 'display' has different settings.
                
                This should be the most common case.
                '''
                if not settings:
                    display = LatexPrinter(self._sympy_latex_settings['display']).doprint(expr)
                    text = LatexPrinter(self._sympy_latex_settings['text']).doprint(expr)
                else:
                    display_settings = copy.deepcopy(self._sympy_latex_settings['display'])
                    display_settings.update(settings)
                    display = LatexPrinter(display_settings).doprint(expr)
                    text_settings = copy.deepcopy(self._sympy_latex_settings['text'])
                    text_settings.update(settings)
                    text = LatexPrinter(text_settings).doprint(expr)
                if display == text:
                    return display
                else:
                    return r'\mathchoice{' + display + '}{' + text + '}{' + text + '}{' + text + '}'
        else:
            def _sympy_latex(expr, **settings):
                '''
                If all attempts at simplification fail, create the most 
                general interface.
                
                The main disadvantage here is that LatexPrinter is invoked 
                four times and we must create many temporary variables.
                '''
                if not settings:
                    display = LatexPrinter(self._sympy_latex_settings['display']).doprint(expr)
                    text = LatexPrinter(self._sympy_latex_settings['text']).doprint(expr)
                    script = LatexPrinter(self._sympy_latex_settings['script']).doprint(expr)
                    scriptscript = LatexPrinter(self._sympy_latex_settings['scriptscript']).doprint(expr)
                else:
                    display_settings = copy.deepcopy(self._sympy_latex_settings['display'])
                    display_settings.update(settings)
                    display = LatexPrinter(display_settings).doprint(expr)
                    text_settings = copy.deepcopy(self._sympy_latex_settings['text'])
                    text_settings.update(settings)
                    text = LatexPrinter(text_settings).doprint(expr)
                    script_settings = copy.deepcopy(self._sympy_latex_settings['script'])
                    script_settings.update(settings)
                    script = LatexPrinter(script_settings).doprint(expr)
                    scriptscript_settings = copy.deepcopy(self._sympy_latex_settings['scripscript'])
                    scriptscript_settings.update(settings)
                    scriptscript = LatexPrinter(scriptscript_settings).doprint(expr)
                if display == text and display == script and display == scriptscript:
                    return display
                else:
                    return r'\mathchoice{' + display + '}{' + text + '}{' + script + '}{' + scriptscript+ '}'
        self._sympy_latex = _sympy_latex
    
    # Now we are ready to create non-SymPy formatters and a method for 
    # setting formatters
    def identity_formatter(self, expr):
        '''
        For generality, we need an identity formatter, a formatter that does
        nothing to its argument and simply returns it unchanged.
        '''
        return expr
    
    def set_formatter(self, fmtr='str'):
        '''
        Set the formatter method.
        
        This is used to process output that is brought in via macros.  It is 
        also available for the user in formatting printed or saved output.
        '''
        if fmtr == 'str':
            if sys.version_info[0] == 2:
                self.formatter = unicode
            else:
                self.formatter = str
        elif fmtr == 'sympy_latex':
            self.formatter = self.sympy_latex
        elif fmtr in ('None', 'none', 'identity') or fmtr is None:
            self.formatter = self.identity_formatter
        else:
            raise ValueError('Unsupported formatter type')
    
    # We need functions that can be executed immediately before and after
    # each chunk of code.  By default, these should do nothing; they are for
    # user customization, or customization via packages.
    def before(self):
        pass
    def after(self):
        pass
    
    
    # We need a way to keep track of dependencies
    # We create a list that stores specified dependencies, and a method that
    # adds dependencies to the list.  The contents of this list must be 
    # written to stdout at the end of the file, to be transmitted back to the 
    # main script.  So we create a method that prints them to stdout.  This is
    # called via a generic cleanup method that is always invoked at the end of 
    # the script.
    _dependencies = list()
    def add_dependencies(self, *args):
        self._dependencies.extend(list(args))
    def _save_dependencies(self):
        print('=>PYTHONTEX:DEPENDENCIES#')
        if self._dependencies:
            for dep in self._dependencies:
                print(dep)
    
    # We need a way to keep track of created files, so that they can be 
    # automatically cleaned up.  By default, all files are created within the
    # pythontex-files_<jobname> folder, and are thus contained.  If a custom
    # working directory is used, or files are otherwise created in a custom
    # location, it may be desirable to track them and keep them cleaned up.
    # Furthermore, even when files are contained in the default directory, it
    # may be desirable to delete files when they are no longer needed due to
    # program changes, renaming, etc.
    _created = list()
    def add_created(self, *args):
        self._created.extend(list(args))
    def _save_created(self):
        print('=>PYTHONTEX:CREATED#')
        if self._created:
            for creation in self._created:
                print(creation)
    
    # A custom version of `open()` is useful for automatically tracking files
    # opened for reading as dependencies and tracking files opened for 
    # writing as created files.
    def open(self, name, mode='r', *args, **kwargs):
        if mode in ('r', 'rt', 'rb'):
            self.add_dependencies(name)
        elif mode in ('w', 'wt', 'wb'):
            self.add_created(name)
        else:
            warnings.warn('Unsupported mode {0} for file tracking'.format(mode))
        if sys.version_info.major == 2 and (len(args) > 1 or 'encoding' in kwargs):
            return io.open(name, mode, *args, **kwargs)
        else:
            return open(name, mode, *args, **kwargs)
    
    def cleanup(self):
        self._save_dependencies()
        self._save_created()