blob: 2207ec59cdc05ea8b3eb411d604c70583808d65d [file] [log] [blame]
Guido van Rossumf30bec71997-08-29 22:30:45 +00001"""Append module search paths for third-party packages to sys.path.
Guido van Rossume57c96e1996-08-17 19:56:26 +00002
Guido van Rossumf30bec71997-08-29 22:30:45 +00003****************************************************************
4* This module is automatically imported during initialization. *
5****************************************************************
Guido van Rossume57c96e1996-08-17 19:56:26 +00006
Guido van Rossumf30bec71997-08-29 22:30:45 +00007In earlier versions of Python (up to 1.5a3), scripts or modules that
8needed to use site-specific modules would place ``import site''
9somewhere near the top of their code. Because of the automatic
10import, this is no longer necessary (but code that does it still
11works).
Guido van Rossume57c96e1996-08-17 19:56:26 +000012
Walter Dörwaldf0dfc7a2003-10-20 14:01:56 +000013This will append site-specific paths to the module search path. On
Guido van Rossum0d8fcb21998-01-13 18:32:40 +000014Unix, it starts with sys.prefix and sys.exec_prefix (if different) and
15appends lib/python<version>/site-packages as well as lib/site-python.
16On other platforms (mainly Mac and Windows), it uses just sys.prefix
Barry Warsaw6e1c5762001-12-17 15:40:24 +000017(and sys.exec_prefix, if different, but this is unlikely). The
Guido van Rossum62b297b1997-09-08 02:14:09 +000018resulting directories, if they exist, are appended to sys.path, and
19also inspected for path configuration files.
Guido van Rossume57c96e1996-08-17 19:56:26 +000020
Guido van Rossumf30bec71997-08-29 22:30:45 +000021A path configuration file is a file whose name has the form
22<package>.pth; its contents are additional directories (one per line)
23to be added to sys.path. Non-existing directories (or
24non-directories) are never added to sys.path; no directory is added to
25sys.path more than once. Blank lines and lines beginning with
Guido van Rossumfacf24b2001-12-17 16:07:06 +000026'#' are skipped. Lines starting with 'import' are executed.
Guido van Rossume57c96e1996-08-17 19:56:26 +000027
Guido van Rossumf30bec71997-08-29 22:30:45 +000028For example, suppose sys.prefix and sys.exec_prefix are set to
Guido van Rossume7201761998-11-25 15:57:47 +000029/usr/local and there is a directory /usr/local/lib/python1.5/site-packages
Guido van Rossum62b297b1997-09-08 02:14:09 +000030with three subdirectories, foo, bar and spam, and two path
31configuration files, foo.pth and bar.pth. Assume foo.pth contains the
32following:
Guido van Rossumf30bec71997-08-29 22:30:45 +000033
34 # foo package configuration
35 foo
36 bar
37 bletch
38
39and bar.pth contains:
40
41 # bar package configuration
42 bar
43
44Then the following directories are added to sys.path, in this order:
45
Guido van Rossum62b297b1997-09-08 02:14:09 +000046 /usr/local/lib/python1.5/site-packages/bar
47 /usr/local/lib/python1.5/site-packages/foo
Guido van Rossumf30bec71997-08-29 22:30:45 +000048
49Note that bletch is omitted because it doesn't exist; bar precedes foo
50because bar.pth comes alphabetically before foo.pth; and spam is
51omitted because it is not mentioned in either path configuration file.
Guido van Rossume57c96e1996-08-17 19:56:26 +000052
53After these path manipulations, an attempt is made to import a module
Guido van Rossumf30bec71997-08-29 22:30:45 +000054named sitecustomize, which can perform arbitrary additional
55site-specific customizations. If this import fails with an
56ImportError exception, it is silently ignored.
Guido van Rossume57c96e1996-08-17 19:56:26 +000057
Guido van Rossume57c96e1996-08-17 19:56:26 +000058"""
59
Brett Cannon0096e262004-06-05 01:12:51 +000060import sys
61import os
62import __builtin__
Guido van Rossume57c96e1996-08-17 19:56:26 +000063
Guido van Rossumd74fb6b2001-03-02 06:43:49 +000064
Fred Drake38cb9f12000-09-28 16:52:36 +000065def makepath(*paths):
Fred Drake1fb5ce02001-07-02 16:55:42 +000066 dir = os.path.abspath(os.path.join(*paths))
67 return dir, os.path.normcase(dir)
Fred Drake38cb9f12000-09-28 16:52:36 +000068
Brett Cannon0096e262004-06-05 01:12:51 +000069def abs__file__():
70 """Set all module' __file__ attribute to an absolute path"""
71 for m in sys.modules.values():
72 try:
73 m.__file__ = os.path.abspath(m.__file__)
74 except AttributeError:
75 continue
Fred Drake38cb9f12000-09-28 16:52:36 +000076
Brett Cannon0096e262004-06-05 01:12:51 +000077def removeduppaths():
78 """ Remove duplicate entries from sys.path along with making them
79 absolute"""
80 # This ensures that the initial path provided by the interpreter contains
81 # only absolute pathnames, even if we're running from the build directory.
82 L = []
83 known_paths = set()
84 for dir in sys.path:
85 # Filter out duplicate paths (on case-insensitive file systems also
86 # if they only differ in case); turn relative paths into absolute
87 # paths.
88 dir, dircase = makepath(dir)
89 if not dircase in known_paths:
90 L.append(dir)
91 known_paths.add(dircase)
92 sys.path[:] = L
93 return known_paths
Fred Drake38cb9f12000-09-28 16:52:36 +000094
Fred Drakee80c0d32002-07-25 20:13:03 +000095# XXX This should not be part of site.py, since it is needed even when
96# using the -S option for Python. See http://www.python.org/sf/586680
Brett Cannon0096e262004-06-05 01:12:51 +000097def addbuilddir():
98 """Append ./build/lib.<platform> in case we're running in the build dir
99 (especially for Guido :-)"""
Jeremy Hylton6d58bf62003-07-18 17:45:33 +0000100 from distutils.util import get_platform
101 s = "build/lib.%s-%.3s" % (get_platform(), sys.version)
Guido van Rossum48eb9cd2001-01-19 21:54:59 +0000102 s = os.path.join(os.path.dirname(sys.path[-1]), s)
103 sys.path.append(s)
Guido van Rossum48eb9cd2001-01-19 21:54:59 +0000104
Fred Drake7f5296e2001-07-20 20:06:17 +0000105def _init_pathinfo():
Brett Cannon0096e262004-06-05 01:12:51 +0000106 """Return a set containing all existing directory entries from sys.path"""
107 d = set()
Fred Drake7f5296e2001-07-20 20:06:17 +0000108 for dir in sys.path:
Brett Cannon0096e262004-06-05 01:12:51 +0000109 try:
110 if os.path.isdir(dir):
111 dir, dircase = makepath(dir)
112 d.add(dircase)
113 except TypeError:
Fred Drake7f5296e2001-07-20 20:06:17 +0000114 continue
Brett Cannon0096e262004-06-05 01:12:51 +0000115 return d
Fred Drake7f5296e2001-07-20 20:06:17 +0000116
Brett Cannon0096e262004-06-05 01:12:51 +0000117def addpackage(sitedir, name, known_paths):
118 """Add a new path to known_paths by combining sitedir and 'name' or execute
119 sitedir if it starts with 'import'"""
120 if known_paths is None:
Fred Drake7f5296e2001-07-20 20:06:17 +0000121 _init_pathinfo()
122 reset = 1
123 else:
124 reset = 0
Brett Cannon0096e262004-06-05 01:12:51 +0000125 fullname = os.path.join(sitedir, name)
126 try:
Brett Cannon4d0bddf2004-07-20 02:28:28 +0000127 f = open(fullname, "rU")
Brett Cannon0096e262004-06-05 01:12:51 +0000128 except IOError:
129 return
130 try:
131 for line in f:
132 if line.startswith("#"):
133 continue
134 if line.startswith("import"):
135 exec line
136 continue
137 line = line.rstrip()
138 dir, dircase = makepath(sitedir, line)
139 if not dircase in known_paths and os.path.exists(dir):
140 sys.path.append(dir)
141 known_paths.add(dircase)
142 finally:
143 f.close()
144 if reset:
145 known_paths = None
146 return known_paths
147
Brett Cannon12f8c4d2004-07-09 23:38:18 +0000148def addsitedir(sitedir, known_paths=None):
Brett Cannon0096e262004-06-05 01:12:51 +0000149 """Add 'sitedir' argument to sys.path if missing and handle .pth files in
150 'sitedir'"""
151 if known_paths is None:
Brett Cannon4d0bddf2004-07-20 02:28:28 +0000152 known_paths = _init_pathinfo()
Brett Cannon0096e262004-06-05 01:12:51 +0000153 reset = 1
154 else:
155 reset = 0
Fred Drake1fb5ce02001-07-02 16:55:42 +0000156 sitedir, sitedircase = makepath(sitedir)
Brett Cannon0096e262004-06-05 01:12:51 +0000157 if not sitedircase in known_paths:
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000158 sys.path.append(sitedir) # Add path component
Guido van Rossumf30bec71997-08-29 22:30:45 +0000159 try:
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000160 names = os.listdir(sitedir)
Guido van Rossumf30bec71997-08-29 22:30:45 +0000161 except os.error:
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000162 return
Guido van Rossumf30bec71997-08-29 22:30:45 +0000163 names.sort()
164 for name in names:
Brett Cannon4d0bddf2004-07-20 02:28:28 +0000165 if name.endswith(os.extsep + "pth"):
Brett Cannon0096e262004-06-05 01:12:51 +0000166 addpackage(sitedir, name, known_paths)
Fred Drake7f5296e2001-07-20 20:06:17 +0000167 if reset:
Brett Cannon0096e262004-06-05 01:12:51 +0000168 known_paths = None
169 return known_paths
Guido van Rossumf30bec71997-08-29 22:30:45 +0000170
Brett Cannon0096e262004-06-05 01:12:51 +0000171def addsitepackages(known_paths):
172 """Add site-packages (and possibly site-python) to sys.path"""
173 prefixes = [sys.prefix]
174 if sys.exec_prefix != sys.prefix:
175 prefixes.append(sys.exec_prefix)
176 for prefix in prefixes:
177 if prefix:
178 if sys.platform in ('os2emx', 'riscos'):
179 sitedirs = [os.path.join(prefix, "Lib", "site-packages")]
180 elif os.sep == '/':
181 sitedirs = [os.path.join(prefix,
182 "lib",
183 "python" + sys.version[:3],
184 "site-packages"),
185 os.path.join(prefix, "lib", "site-python")]
186 else:
187 sitedirs = [prefix, os.path.join(prefix, "lib", "site-packages")]
188 if sys.platform == 'darwin':
189 # for framework builds *only* we add the standard Apple
190 # locations. Currently only per-user, but /Library and
191 # /Network/Library could be added too
192 if 'Python.framework' in prefix:
193 home = os.environ.get('HOME')
194 if home:
195 sitedirs.append(
196 os.path.join(home,
197 'Library',
198 'Python',
199 sys.version[:3],
200 'site-packages'))
201 for sitedir in sitedirs:
202 if os.path.isdir(sitedir):
203 addsitedir(sitedir, known_paths)
204 return None
Fred Drake7f5296e2001-07-20 20:06:17 +0000205
Fred Drake1fb5ce02001-07-02 16:55:42 +0000206
Brett Cannon0096e262004-06-05 01:12:51 +0000207def setBEGINLIBPATH():
208 """The OS/2 EMX port has optional extension modules that do double duty
209 as DLLs (and must use the .DLL file extension) for other extensions.
210 The library search path needs to be amended so these will be found
211 during module import. Use BEGINLIBPATH so that these are at the start
212 of the library search path.
Tim Peters4e0e1b62004-07-07 20:54:48 +0000213
Brett Cannon0096e262004-06-05 01:12:51 +0000214 """
Andrew MacIntyre2e8a6e02003-12-02 12:27:25 +0000215 dllpath = os.path.join(sys.prefix, "Lib", "lib-dynload")
216 libpath = os.environ['BEGINLIBPATH'].split(';')
217 if libpath[-1]:
218 libpath.append(dllpath)
219 else:
220 libpath[-1] = dllpath
221 os.environ['BEGINLIBPATH'] = ';'.join(libpath)
222
223
Brett Cannon0096e262004-06-05 01:12:51 +0000224def setquit():
225 """Define new built-ins 'quit' and 'exit'.
226 These are simply strings that display a hint on how to exit.
Guido van Rossumd89fa0c1998-08-07 18:01:14 +0000227
Brett Cannon0096e262004-06-05 01:12:51 +0000228 """
229 if os.sep == ':':
230 exit = 'Use Cmd-Q to quit.'
231 elif os.sep == '\\':
232 exit = 'Use Ctrl-Z plus Return to exit.'
233 else:
234 exit = 'Use Ctrl-D (i.e. EOF) to exit.'
235 __builtin__.quit = __builtin__.exit = exit
236
237
238class _Printer(object):
239 """interactive prompt objects for printing the license text, a list of
240 contributors and the copyright notice."""
241
Guido van Rossumd1252392000-09-05 04:39:55 +0000242 MAXLINES = 23
243
Guido van Rossumf19a7ac2000-10-03 17:11:37 +0000244 def __init__(self, name, data, files=(), dirs=()):
245 self.__name = name
246 self.__data = data
247 self.__files = files
248 self.__dirs = dirs
249 self.__lines = None
250
251 def __setup(self):
252 if self.__lines:
253 return
254 data = None
255 for dir in self.__dirs:
Brett Cannon0096e262004-06-05 01:12:51 +0000256 for filename in self.__files:
257 filename = os.path.join(dir, filename)
Guido van Rossumf19a7ac2000-10-03 17:11:37 +0000258 try:
Brett Cannon0096e262004-06-05 01:12:51 +0000259 fp = file(filename, "rU")
Guido van Rossumf19a7ac2000-10-03 17:11:37 +0000260 data = fp.read()
261 fp.close()
262 break
263 except IOError:
264 pass
265 if data:
266 break
267 if not data:
268 data = self.__data
269 self.__lines = data.split('\n')
Guido van Rossumd1252392000-09-05 04:39:55 +0000270 self.__linecnt = len(self.__lines)
271
272 def __repr__(self):
Guido van Rossumf19a7ac2000-10-03 17:11:37 +0000273 self.__setup()
274 if len(self.__lines) <= self.MAXLINES:
275 return "\n".join(self.__lines)
276 else:
277 return "Type %s() to see the full %s text" % ((self.__name,)*2)
278
279 def __call__(self):
280 self.__setup()
Guido van Rossumd1252392000-09-05 04:39:55 +0000281 prompt = 'Hit Return for more, or q (and Return) to quit: '
282 lineno = 0
283 while 1:
284 try:
285 for i in range(lineno, lineno + self.MAXLINES):
286 print self.__lines[i]
287 except IndexError:
288 break
289 else:
290 lineno += self.MAXLINES
291 key = None
292 while key is None:
293 key = raw_input(prompt)
294 if key not in ('', 'q'):
295 key = None
296 if key == 'q':
297 break
Guido van Rossumd1252392000-09-05 04:39:55 +0000298
Brett Cannon0096e262004-06-05 01:12:51 +0000299def setcopyright():
300 """Set 'copyright' and 'credits' in __builtin__"""
301 __builtin__.copyright = _Printer("copyright", sys.copyright)
302 if sys.platform[:4] == 'java':
303 __builtin__.credits = _Printer(
304 "credits",
305 "Jython is maintained by the Jython developers (www.jython.org).")
306 else:
307 __builtin__.credits = _Printer("credits", """\
308 Thanks to CWI, CNRI, BeOpen.com, Zope Corporation and a cast of thousands
309 for supporting Python development. See www.python.org for more information.""")
310 here = os.path.dirname(os.__file__)
311 __builtin__.license = _Printer(
312 "license", "See http://www.python.org/%.3s/license.html" % sys.version,
313 ["LICENSE.txt", "LICENSE"],
314 [os.path.join(here, os.pardir), here, os.curdir])
Guido van Rossumd1252392000-09-05 04:39:55 +0000315
316
Brett Cannon0096e262004-06-05 01:12:51 +0000317class _Helper(object):
318 """Define the built-in 'help'.
319 This is a wrapper around pydoc.help (with a twist).
Guido van Rossum83213cc2001-06-12 16:48:52 +0000320
Brett Cannon0096e262004-06-05 01:12:51 +0000321 """
322
Guido van Rossum83213cc2001-06-12 16:48:52 +0000323 def __repr__(self):
324 return "Type help() for interactive help, " \
325 "or help(object) for help about object."
326 def __call__(self, *args, **kwds):
327 import pydoc
328 return pydoc.help(*args, **kwds)
329
Brett Cannon0096e262004-06-05 01:12:51 +0000330def sethelper():
331 __builtin__.help = _Helper()
332
333def aliasmbcs():
334 """On Windows, some default encodings are not provided by Python,
335 while they are always available as "mbcs" in each locale. Make
336 them usable by aliasing to "mbcs" in such a case."""
337 if sys.platform == 'win32':
338 import locale, codecs
339 enc = locale.getdefaultlocale()[1]
340 if enc.startswith('cp'): # "cp***" ?
341 try:
342 codecs.lookup(enc)
343 except LookupError:
344 import encodings
345 encodings._cache[enc] = encodings._unknown
346 encodings.aliases.aliases[enc] = 'mbcs'
347
348def setencoding():
349 """Set the string encoding used by the Unicode implementation. The
350 default is 'ascii', but if you're willing to experiment, you can
351 change this."""
352 encoding = "ascii" # Default value set by _PyUnicode_Init()
353 if 0:
354 # Enable to support locale aware default string encodings.
355 import locale
356 loc = locale.getdefaultlocale()
357 if loc[1]:
358 encoding = loc[1]
359 if 0:
360 # Enable to switch off string to Unicode coercion and implicit
361 # Unicode to string conversion.
362 encoding = "undefined"
363 if encoding != "ascii":
364 # On Non-Unicode builds this will raise an AttributeError...
365 sys.setdefaultencoding(encoding) # Needs Python Unicode build !
Guido van Rossum83213cc2001-06-12 16:48:52 +0000366
367
Brett Cannon0096e262004-06-05 01:12:51 +0000368def execsitecustomize():
369 """Run custom site specific code, if available."""
370 try:
371 import sitecustomize
372 except ImportError:
373 pass
Martin v. Löwis4eab4862003-03-03 09:34:01 +0000374
Martin v. Löwis4eab4862003-03-03 09:34:01 +0000375
Brett Cannon0096e262004-06-05 01:12:51 +0000376def main():
377 abs__file__()
378 paths_in_sys = removeduppaths()
379 if (os.name == "posix" and sys.path and
380 os.path.basename(sys.path[-1]) == "Modules"):
381 addbuilddir()
382 paths_in_sys = addsitepackages(paths_in_sys)
383 if sys.platform == 'os2emx':
384 setBEGINLIBPATH()
385 setquit()
386 setcopyright()
387 sethelper()
388 aliasmbcs()
389 setencoding()
390 execsitecustomize()
391 # Remove sys.setdefaultencoding() so that users cannot change the
392 # encoding after initialization. The test for presence is needed when
393 # this module is run as a script, because this code is executed twice.
394 if hasattr(sys, "setdefaultencoding"):
395 del sys.setdefaultencoding
Marc-André Lemburg990bbe92000-06-07 09:12:09 +0000396
Brett Cannon0096e262004-06-05 01:12:51 +0000397main()
Guido van Rossumf30bec71997-08-29 22:30:45 +0000398
399def _test():
400 print "sys.path = ["
401 for dir in sys.path:
Walter Dörwald70a6b492004-02-12 17:35:32 +0000402 print " %r," % (dir,)
Guido van Rossumf30bec71997-08-29 22:30:45 +0000403 print "]"
404
405if __name__ == '__main__':
406 _test()