/Doc/using/windows.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 320 lines · 222 code · 98 blank · 0 comment · 0 complexity · 1198939dc28a620110b8f7ea7c812506 MD5 · raw file

  1. .. highlightlang:: none
  2. .. _using-on-windows:
  3. *************************
  4. Using Python on Windows
  5. *************************
  6. .. sectionauthor:: Robert Lehmann <lehmannro@gmail.com>
  7. This document aims to give an overview of Windows-specific behaviour you should
  8. know about when using Python on Microsoft Windows.
  9. Installing Python
  10. =================
  11. Unlike most Unix systems and services, Windows does not require Python natively
  12. and thus does not pre-install a version of Python. However, the CPython team
  13. has compiled Windows installers (MSI packages) with every `release
  14. <http://www.python.org/download/releases/>`_ for many years.
  15. With ongoing development of Python, some platforms that used to be supported
  16. earlier are no longer supported (due to the lack of users or developers).
  17. Check :pep:`11` for details on all unsupported platforms.
  18. * DOS and Windows 3.x are deprecated since Python 2.0 and code specific to these
  19. systems was removed in Python 2.1.
  20. * Up to 2.5, Python was still compatible with Windows 95, 98 and ME (but already
  21. raised a deprecation warning on installation). For Python 2.6 (and all
  22. following releases), this support was dropped and new releases are just
  23. expected to work on the Windows NT family.
  24. * `Windows CE <http://pythonce.sourceforge.net/>`_ is still supported.
  25. * The `Cygwin <http://cygwin.com/>`_ installer offers to install the `Python
  26. interpreter <http://cygwin.com/packages/python>`_ as well; it is located under
  27. "Interpreters." (cf. `Cygwin package source
  28. <ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/mirrors/cygnus/
  29. release/python>`_, `Maintainer releases
  30. <http://www.tishler.net/jason/software/python/>`_)
  31. See `Python for Windows (and DOS) <http://www.python.org/download/windows/>`_
  32. for detailed information about platforms with precompiled installers.
  33. .. seealso::
  34. `Python on XP <http://www.richarddooling.com/index.php/2006/03/14/python-on-xp-7-minutes-to-hello-world/>`_
  35. "7 Minutes to "Hello World!""
  36. by Richard Dooling, 2006
  37. `Installing on Windows <http://diveintopython.org/installing_python/windows.html>`_
  38. in "`Dive into Python: Python from novice to pro
  39. <http://diveintopython.org/index.html>`_"
  40. by Mark Pilgrim, 2004,
  41. ISBN 1-59059-356-1
  42. `For Windows users <http://swaroopch.com/text/Byte_of_Python:Installing_Python#For_Windows_users>`_
  43. in "Installing Python"
  44. in "`A Byte of Python <http://www.byteofpython.info>`_"
  45. by Swaroop C H, 2003
  46. Alternative bundles
  47. ===================
  48. Besides the standard CPython distribution, there are modified packages including
  49. additional functionality. The following is a list of popular versions and their
  50. key features:
  51. `ActivePython <http://www.activestate.com/Products/activepython/>`_
  52. Installer with multi-platform compatibility, documentation, PyWin32
  53. `Python Enthought Edition <http://code.enthought.com/enthon/>`_
  54. Popular modules (such as PyWin32) with their respective documentation, tool
  55. suite for building extensible python applications
  56. Notice that these packages are likely to install *older* versions of Python.
  57. Configuring Python
  58. ==================
  59. In order to run Python flawlessly, you might have to change certain environment
  60. settings in Windows.
  61. Excursus: Setting environment variables
  62. ---------------------------------------
  63. Windows has a built-in dialog for changing environment variables (following
  64. guide applies to XP classical view): Right-click the icon for your machine
  65. (usually located on your Desktop and called "My Computer") and choose
  66. :menuselection:`Properties` there. Then, open the :guilabel:`Advanced` tab
  67. and click the :guilabel:`Environment Variables` button.
  68. In short, your path is:
  69. :menuselection:`My Computer
  70. --> Properties
  71. --> Advanced
  72. --> Environment Variables`
  73. In this dialog, you can add or modify User and System variables. To change
  74. System variables, you need non-restricted access to your machine
  75. (i.e. Administrator rights).
  76. Another way of adding variables to your environment is using the :command:`set`
  77. command::
  78. set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
  79. To make this setting permanent, you could add the corresponding command line to
  80. your :file:`autoexec.bat`. :program:`msconfig` is a graphical interface to this
  81. file.
  82. Viewing environment variables can also be done more straight-forward: The
  83. command prompt will expand strings wrapped into percent signs automatically::
  84. echo %PATH%
  85. Consult :command:`set /?` for details on this behaviour.
  86. .. seealso::
  87. http://support.microsoft.com/kb/100843
  88. Environment variables in Windows NT
  89. http://support.microsoft.com/kb/310519
  90. How To Manage Environment Variables in Windows XP
  91. http://www.chem.gla.ac.uk/~louis/software/faq/q1.html
  92. Setting Environment variables, Louis J. Farrugia
  93. Finding the Python executable
  94. -----------------------------
  95. Besides using the automatically created start menu entry for the Python
  96. interpreter, you might want to start Python in the DOS prompt. To make this
  97. work, you need to set your :envvar:`%PATH%` environment variable to include the
  98. directory of your Python distribution, delimited by a semicolon from other
  99. entries. An example variable could look like this (assuming the first two
  100. entries are Windows' default)::
  101. C:\WINDOWS\system32;C:\WINDOWS;C:\Python25
  102. Typing :command:`python` on your command prompt will now fire up the Python
  103. interpreter. Thus, you can also execute your scripts with command line options,
  104. see :ref:`using-on-cmdline` documentation.
  105. Finding modules
  106. ---------------
  107. Python usually stores its library (and thereby your site-packages folder) in the
  108. installation directory. So, if you had installed Python to
  109. :file:`C:\\Python\\`, the default library would reside in
  110. :file:`C:\\Python\\Lib\\` and third-party modules should be stored in
  111. :file:`C:\\Python\\Lib\\site-packages\\`.
  112. .. `` this fixes syntax highlighting errors in some editors due to the \\ hackery
  113. You can add folders to your search path to make Python's import mechanism search
  114. in these directories as well. Use :envvar:`PYTHONPATH`, as described in
  115. :ref:`using-on-envvars`, to modify :data:`sys.path`. On Windows, paths are
  116. separated by semicolons, though, to distinguish them from drive identifiers
  117. (:file:`C:\\` etc.).
  118. .. ``
  119. Modifying the module search path can also be done through the Windows registry:
  120. Edit
  121. :file:`HKEY_LOCAL_MACHINE\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath\\`,
  122. as described above for the environment variable :envvar:`%PYTHONPATH%`. A
  123. convenient registry editor is :program:`regedit` (start it by typing "regedit"
  124. into :menuselection:`Start --> Run`).
  125. Executing scripts
  126. -----------------
  127. Python scripts (files with the extension ``.py``) will be executed by
  128. :program:`python.exe` by default. This executable opens a terminal, which stays
  129. open even if the program uses a GUI. If you do not want this to happen, use the
  130. extension ``.pyw`` which will cause the script to be executed by
  131. :program:`pythonw.exe` by default (both executables are located in the top-level
  132. of your Python installation directory). This suppresses the terminal window on
  133. startup.
  134. You can also make all ``.py`` scripts execute with :program:`pythonw.exe`,
  135. setting this through the usual facilities, for example (might require
  136. administrative rights):
  137. #. Launch a command prompt.
  138. #. Associate the correct file group with ``.py`` scripts::
  139. assoc .py=Python.File
  140. #. Redirect all Python files to the new executable::
  141. ftype Python.File=C:\Path\to\pythonw.exe "%1" %*
  142. Additional modules
  143. ==================
  144. Even though Python aims to be portable among all platforms, there are features
  145. that are unique to Windows. A couple of modules, both in the standard library
  146. and external, and snippets exist to use these features.
  147. The Windows-specific standard modules are documented in
  148. :ref:`mswin-specific-services`.
  149. PyWin32
  150. -------
  151. The `PyWin32 <http://python.net/crew/mhammond/win32/>`_ module by Mark Hammond
  152. is a collection of modules for advanced Windows-specific support. This includes
  153. utilities for:
  154. * `Component Object Model <http://www.microsoft.com/com/>`_ (COM)
  155. * Win32 API calls
  156. * Registry
  157. * Event log
  158. * `Microsoft Foundation Classes <http://msdn.microsoft.com/library/
  159. en-us/vclib/html/_mfc_Class_Library_Reference_Introduction.asp>`_ (MFC)
  160. user interfaces
  161. `PythonWin <http://web.archive.org/web/20060524042422/
  162. http://www.python.org/windows/pythonwin/>`_ is a sample MFC application
  163. shipped with PyWin32. It is an embeddable IDE with a built-in debugger.
  164. .. seealso::
  165. `Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_
  166. by Tim Golden
  167. `Python and COM <http://www.boddie.org.uk/python/COM.html>`_
  168. by David and Paul Boddie
  169. Py2exe
  170. ------
  171. `Py2exe <http://www.py2exe.org/>`_ is a :mod:`distutils` extension (see
  172. :ref:`extending-distutils`) which wraps Python scripts into executable Windows
  173. programs (:file:`{*}.exe` files). When you have done this, you can distribute
  174. your application without requiring your users to install Python.
  175. WConio
  176. ------
  177. Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to
  178. Unix-like systems, there is a library exclusive to Windows as well: Windows
  179. Console I/O for Python.
  180. `WConio <http://newcenturycomputers.net/projects/wconio.html>`_ is a wrapper for
  181. Turbo-C's :file:`CONIO.H`, used to create text user interfaces.
  182. Compiling Python on Windows
  183. ===========================
  184. If you want to compile CPython yourself, first thing you should do is get the
  185. `source <http://python.org/download/source/>`_. You can download either the
  186. latest release's source or just grab a fresh `checkout
  187. <http://www.python.org/dev/faq/#how-do-i-get-a-checkout-of-the-repository-read-only-and-read-write>`_.
  188. For Microsoft Visual C++, which is the compiler with which official Python
  189. releases are built, the source tree contains solutions/project files. View the
  190. :file:`readme.txt` in their respective directories:
  191. +--------------------+--------------+-----------------------+
  192. | Directory | MSVC version | Visual Studio version |
  193. +====================+==============+=======================+
  194. | :file:`PC/VC6/` | 6.0 | 97 |
  195. +--------------------+--------------+-----------------------+
  196. | :file:`PC/VS7.1/` | 7.1 | 2003 |
  197. +--------------------+--------------+-----------------------+
  198. | :file:`PC/VS8.0/` | 8.0 | 2005 |
  199. +--------------------+--------------+-----------------------+
  200. | :file:`PCbuild/` | 9.0 | 2008 |
  201. +--------------------+--------------+-----------------------+
  202. Note that not all of these build directories are fully supported. Read the
  203. release notes to see which compiler version the official releases for your
  204. version are built with.
  205. Check :file:`PC/readme.txt` for general information on the build process.
  206. For extension modules, consult :ref:`building-on-windows`.
  207. .. seealso::
  208. `Python + Windows + distutils + SWIG + gcc MinGW <http://sebsauvage.net/python/mingw.html>`_
  209. or "Creating Python extensions in C/C++ with SWIG and compiling them with
  210. MinGW gcc under Windows" or "Installing Python extension with distutils
  211. and without Microsoft Visual C++" by SĂŠbastien Sauvage, 2003
  212. `MingW -- Python extensions <http://www.mingw.org/MinGWiki/index.php/Python%20extensions>`_
  213. by Trent Apted et al, 2007
  214. Other resources
  215. ===============
  216. .. seealso::
  217. `Python Programming On Win32 <http://www.oreilly.com/catalog/pythonwin32/>`_
  218. "Help for Windows Programmers"
  219. by Mark Hammond and Andy Robinson, O'Reilly Media, 2000,
  220. ISBN 1-56592-621-8
  221. `A Python for Windows Tutorial <http://www.imladris.com/Scripts/PythonForWindows.html>`_
  222. by Amanda Birmingham, 2004