Require implementations for warnings.showwarning() support the 'line' argument.
[python.git] / Lib / py_compile.py
blob89e80f8e6fb25fb79f2b131a92ff6a58bea01b1d
1 """Routine to "compile" a .py file to a .pyc (or .pyo) file.
3 This module has intimate knowledge of the format of .pyc files.
4 """
6 import __builtin__
7 import imp
8 import marshal
9 import os
10 import sys
11 import traceback
13 MAGIC = imp.get_magic()
15 __all__ = ["compile", "main", "PyCompileError"]
18 class PyCompileError(Exception):
19 """Exception raised when an error occurs while attempting to
20 compile the file.
22 To raise this exception, use
24 raise PyCompileError(exc_type,exc_value,file[,msg])
26 where
28 exc_type: exception type to be used in error message
29 type name can be accesses as class variable
30 'exc_type_name'
32 exc_value: exception value to be used in error message
33 can be accesses as class variable 'exc_value'
35 file: name of file being compiled to be used in error message
36 can be accesses as class variable 'file'
38 msg: string message to be written as error message
39 If no value is given, a default exception message will be given,
40 consistent with 'standard' py_compile output.
41 message (or default) can be accesses as class variable 'msg'
43 """
45 def __init__(self, exc_type, exc_value, file, msg=''):
46 exc_type_name = exc_type.__name__
47 if exc_type is SyntaxError:
48 tbtext = ''.join(traceback.format_exception_only(exc_type, exc_value))
49 errmsg = tbtext.replace('File "<string>"', 'File "%s"' % file)
50 else:
51 errmsg = "Sorry: %s: %s" % (exc_type_name,exc_value)
53 Exception.__init__(self,msg or errmsg,exc_type_name,exc_value,file)
55 self.exc_type_name = exc_type_name
56 self.exc_value = exc_value
57 self.file = file
58 self.msg = msg or errmsg
60 def __str__(self):
61 return self.msg
64 # Define an internal helper according to the platform
65 if os.name == "mac":
66 import MacOS
67 def set_creator_type(file):
68 MacOS.SetCreatorAndType(file, 'Pyth', 'PYC ')
69 else:
70 def set_creator_type(file):
71 pass
73 def wr_long(f, x):
74 """Internal; write a 32-bit int to a file in little-endian order."""
75 f.write(chr( x & 0xff))
76 f.write(chr((x >> 8) & 0xff))
77 f.write(chr((x >> 16) & 0xff))
78 f.write(chr((x >> 24) & 0xff))
80 def compile(file, cfile=None, dfile=None, doraise=False):
81 """Byte-compile one Python source file to Python bytecode.
83 Arguments:
85 file: source filename
86 cfile: target filename; defaults to source with 'c' or 'o' appended
87 ('c' normally, 'o' in optimizing mode, giving .pyc or .pyo)
88 dfile: purported filename; defaults to source (this is the filename
89 that will show up in error messages)
90 doraise: flag indicating whether or not an exception should be
91 raised when a compile error is found. If an exception
92 occurs and this flag is set to False, a string
93 indicating the nature of the exception will be printed,
94 and the function will return to the caller. If an
95 exception occurs and this flag is set to True, a
96 PyCompileError exception will be raised.
98 Note that it isn't necessary to byte-compile Python modules for
99 execution efficiency -- Python itself byte-compiles a module when
100 it is loaded, and if it can, writes out the bytecode to the
101 corresponding .pyc (or .pyo) file.
103 However, if a Python installation is shared between users, it is a
104 good idea to byte-compile all modules upon installation, since
105 other users may not be able to write in the source directories,
106 and thus they won't be able to write the .pyc/.pyo file, and then
107 they would be byte-compiling every module each time it is loaded.
108 This can slow down program start-up considerably.
110 See compileall.py for a script/module that uses this module to
111 byte-compile all installed files (or all files in selected
112 directories).
115 f = open(file, 'U')
116 try:
117 timestamp = long(os.fstat(f.fileno()).st_mtime)
118 except AttributeError:
119 timestamp = long(os.stat(file).st_mtime)
120 codestring = f.read()
121 f.close()
122 if codestring and codestring[-1] != '\n':
123 codestring = codestring + '\n'
124 try:
125 codeobject = __builtin__.compile(codestring, dfile or file,'exec')
126 except Exception,err:
127 py_exc = PyCompileError(err.__class__,err.args,dfile or file)
128 if doraise:
129 raise py_exc
130 else:
131 sys.stderr.write(py_exc.msg + '\n')
132 return
133 if cfile is None:
134 cfile = file + (__debug__ and 'c' or 'o')
135 fc = open(cfile, 'wb')
136 fc.write('\0\0\0\0')
137 wr_long(fc, timestamp)
138 marshal.dump(codeobject, fc)
139 fc.flush()
140 fc.seek(0, 0)
141 fc.write(MAGIC)
142 fc.close()
143 set_creator_type(cfile)
145 def main(args=None):
146 """Compile several source files.
148 The files named in 'args' (or on the command line, if 'args' is
149 not specified) are compiled and the resulting bytecode is cached
150 in the normal manner. This function does not search a directory
151 structure to locate source files; it only compiles files named
152 explicitly.
155 if args is None:
156 args = sys.argv[1:]
157 rv = 0
158 for filename in args:
159 try:
160 compile(filename, doraise=True)
161 except PyCompileError, err:
162 # return value to indicate at least one failure
163 rv = 1
164 sys.stderr.write(err.msg)
165 return rv
167 if __name__ == "__main__":
168 sys.exit(main())