diff --git a/Doc/distutils/extending.rst b/Doc/distutils/extending.rst index a2930c77df7..972ff02c03e 100644 --- a/Doc/distutils/extending.rst +++ b/Doc/distutils/extending.rst @@ -1,4 +1,4 @@ -.. _extending: +.. _extending-distutils: ******************* Extending Distutils diff --git a/Doc/library/windows.rst b/Doc/library/windows.rst index a231bc2a4da..b09dd8b3f2e 100644 --- a/Doc/library/windows.rst +++ b/Doc/library/windows.rst @@ -1,3 +1,4 @@ +.. _mswin-specific-services: **************************** MS Windows Specific Services diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 8a4a9b7e5b7..84d84e20353 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -1,5 +1,7 @@ .. highlightlang:: none +.. _using-on-general: + Command line and environment ============================ @@ -12,6 +14,8 @@ settings. :ref:`implementations` for further resources. +.. _using-on-cmdline: + Command line ------------ @@ -304,39 +308,21 @@ Miscellaneous options .. cmdoption:: -3 - Warn about Python 3.x incompatibilities. + Warn about Python 3.x incompatibilities. Among these are: + + * :meth:`dict.has_key` + * :func:`apply` + * :func:`callable` + * :func:`coerce` + * :func:`execfile` + * :func:`reduce` + * :func:`reload` .. versionadded:: 2.6 -Related files -- UNIX ---------------------- - -These are subject to difference depending on local installation conventions; -:envvar:`prefix` (``${prefix}``) and :envvar:`exec_prefix` (``${exec_prefix}``) -are installation-dependent and should be interpreted as for GNU software; they -may be the same. - -For example, on most Linux systems, the default for both is :file:`/usr`. - -+-----------------------------------------------+------------------------------------------+ -| File/directory | Meaning | -+===============================================+==========================================+ -| :file:`{exec_prefix}/bin/python` | Recommended location of the interpreter. | -+-----------------------------------------------+------------------------------------------+ -| :file:`{prefix}/lib/python{version}`, | Recommended locations of the directories | -| :file:`{exec_prefix}/lib/python{version}` | containing the standard modules. | -+-----------------------------------------------+------------------------------------------+ -| :file:`{prefix}/include/python{version}`, | Recommended locations of the directories | -| :file:`{exec_prefix}/include/python{version}` | containing the include files needed for | -| | developing Python extensions and | -| | embedding the interpreter. | -+-----------------------------------------------+------------------------------------------+ -| :file:`~/.pythonrc.py` | User-specific initialization file loaded | -| | by the user module; not used by default | -| | or by most applications. | -+-----------------------------------------------+------------------------------------------+ +.. _using-on-envvars: Environment variables --------------------- diff --git a/Doc/using/index.rst b/Doc/using/index.rst index f8d8ce481f4..e2fa4b4f17f 100644 --- a/Doc/using/index.rst +++ b/Doc/using/index.rst @@ -13,5 +13,6 @@ interpreter and things that make working with Python easier. .. toctree:: cmdline.rst + windows.rst mac.rst diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst new file mode 100644 index 00000000000..db836057b71 --- /dev/null +++ b/Doc/using/windows.rst @@ -0,0 +1,316 @@ +.. highlightlang:: none + +.. _using-on-windows: + +************************* + Using Python on Windows +************************* + +.. sectionauthor:: Robert Lehmann + +This document aims to give an overview of Windows-specific behaviour you should +know about when using Python on Microsoft Windows. + + +Installing Python +================= + +Unlike most Unix systems and services, Windows does not require Python natively +and thus does not pre-install a version of Python. However, the CPython team +has compiled Windows installers (MSI packages) with every `release +`_ for many years. + +With ongoing development of Python, some platforms that used to be supported +earlier are not longer supported (due to the lack of users or developers). +Check :pep:`11` for details on all unsupported platforms. + +* DOS and Windows 3.x are deprecated since Python 2.0 and code specific to these + systems was removed in Python 2.1. +* Up to 2.5, Python was still compatible with Windows 95, 98 and ME (but already + raised a deprecation warning on installation). For Python 2.6 (and all + following releases), this support was dropped and new releases are just + expected to work on the Windows NT family. +* `Windows CE `_ is still supported. +* The `Cygwin `_ installer offers to install the `Python + interpreter `_ as well; it is located under + "Interpreters." (cf. `Cygwin package source + `_, `Maintainer releases + `_) + +See `Python for Windows (and DOS) `_ +for detailed information about platforms with precompiled installers. + +.. seealso:: + + `Python on XP `_ + "7 Minutes to "Hello World!"" + by Richard Dooling, 2006 + + `Installing on Windows `_ + in "`Dive into Python: Python from novice to pro + `_" + by Mark Pilgrim, 2004, + ISBN 1-59059-356-1 + + `For Windows users `_ + in "Installing Python" + in "`A Byte of Python `_" + by Swaroop C H, 2003 + + +Alternative bundles +=================== + +Besides the standard CPython distribution, there are modified packages including +additional functionality. The following is a list of popular versions and their +key features: + +`ActivePython `_ + Installer with multi-platform compatibility, documentation, PyWin32 + +`Python Enthought Edition `_ + Popular modules (such as PyWin32) with their respective documentation, tool + suite for building extensible python applications + + + +Configuring Python +================== + +In order to run Python flawlessly, you might have to change certain environment +settings in Windows. + + +Excursus: Setting environment variables +--------------------------------------- + +Windows has a built-in dialog for changing environment variables: Right-click +the icon for your machine (usually located on your Desktop and called "My +Computer") and choose :menuselection:`Properties` there. Then, open the +:guilabel:`Advanced` tab and click the :guilabel:`Environment Variables` button. + +In short, your path is: + + :menuselection:`My Computer + --> Properties + --> Advanced + --> Environment Variables` + +In this dialog, you can add or modify User and System variables. To change +System variables, you need non-restricted access to your machine +(i.e. Administrator rights). + +Another way of adding variables to your environment is using the :command:`set` +command:: + + set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib + +To make this setting permanent, you could add the corresponding command line to +your :file:`autoexec.bat`. + +Viewing environment variables can also be done more straight-forward: The +command prompt will expand strings wrapped into percent signs automatically:: + + echo %PATH% + +Consult :command:`set /?` for details on this behaviour. + +.. seealso:: + + http://support.microsoft.com/kb/100843 + Environment variables in Windows NT + + http://support.microsoft.com/kb/310519 + How To Manage Environment Variables in Windows XP + + +Finding the Python executable +----------------------------- + +Besides using the automatically created start menu entry for the Python +interpreter, you might want to start Python in the DOS prompt. To make this +work, you need to set your :envvar:`%PATH%` environment variable to include the +directory of your Python distribution, delimited by a semicolon from other +entries. An example variable could look like this (assuming the first two +entries are Windows' default):: + + C:\WINNT\system32;C:\WINNT;C:\Python25 + +Typing :command:`python` on your command prompt will now fire up the Python +interpreter. Thus, you can also execute your scripts with command line options, +see :ref:`using-on-cmdline` documentation. + + +Finding modules +--------------- + +Python usually stores its library (and thereby your site-packages folder) in the +installation directory. So, if you had installed Python to +:file:`C:\\Python\\`, the default library would reside in +:file:`C:\\Python\\Lib\\` and third-party modules should be stored in +:file:`C:\\Python\\Lib\\site-packages\\`. + +.. % `` this fixes syntax highlighting errors in some editors + due to the \\ hackery + +You can add folders to your search path to make Python's import mechanism search +in these directories as well. Use :envvar:`PYTHONPATH`, as described in +:ref:`using-on-envvars`, to modify :data:`sys.path`. On Windows, paths are +separated by semicolons, though, to distinguish them from drive identifiers +(:file:`C:\\` etc.). + +.. % `` + +Modifying the module search path can also be done through the Windows registry: +Edit +:file:`HKEY_LOCAL_MACHINE\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath\\`, +as described above for the environment variable :envvar:`%PYTHONPATH%`. A +convenient registry editor is :program:`regedit` (start it by typing "regedit" +into :menuselection:`Start --> Run`). + + +Executing scripts +----------------- + +Python scripts (files with the extension ``.py``) will be executed by +:program:`python.exe` by default. This executable opens a terminal, which stays +open even if the program uses a GUI. If you do not want this to happen, use the +extension ``.pyw`` which will cause the script to be executed by +:program:`pythonw.exe` by default (both executables are located in the top-level +of your Python installation directory). This suppresses the terminal window on +startup. + +You can also make all ``.py`` scripts execute with :program:`pythonw.exe`, +setting this through the usual facilites, for example (names might differ, +depending on your version of Windows): + +#. Open the context menu of a :file:`{*}.py` file. +#. Click :menuselection:`Open with...`. +#. Choose the interpreter of your choice (utilize :guilabel:`Other...` or + :guilabel:`Choose Program...` if it is not in the list of default programs). +#. Check :guilabel:`Always open files with this program`. +#. Click :guilabel:`OK`. + + + +Additional modules +================== + +Even though Python aims to be portable among all platforms, there are features +that are unique to Windows. A couple of modules, both in the standard library +and external, and snippets exist to use these features. + +The Windows-specific standard modules are documented in +:ref:`mswin-specific-services`. + + +PyWin32 +------- + +The `PyWin32 `_ module by Mark Hammond +is a collection of modules for advanced Windows-specific support. This includes +utilites for: + +* `Component Object Model `_ (COM) +* Win32 API calls +* Registry +* Event log +* `Microsoft Foundation Classes `_ (MFC) + user interfaces + +`PythonWin `_ is a sample MFC application +shipped with PyWin32. It is an embeddable IDE with a built-in debugger. + +.. seealso:: + + `Win32 How Do I...? `_ + by Tim Golden + + `Python and COM `_ + by David and Paul Boddie + + +Py2exe +------ + +`Py2exe `_ is a :mod:`distutils` extension (see +:ref:`extending-distutils`) which wraps Python scripts into executable Windows +programs (:file:`{*}.exe` files). When you have done this, you can distribute +your application without requiring your users to install Python. + + +WConio +------ + +Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to +Unix-like systems, there is a library exclusive to Windows as well: Windows +Console I/O for Python. + +`WConio `_ is a wrapper for +Turbo-C's :file:`CONIO.H`, used to create text user interfaces. + + + +Compiling Python on Windows +=========================== + +If you want to compile CPython yourself, first thing you should do is get the +`source `_. You can download either the +latest release's source or just grab a fresh `checkout +`_. + +For Microsoft Visual C++, which is the compiler with which official Python +releases are built, the source tree contains solutions/project files. View the +:file:`readme.txt` in their respective directories: + ++--------------------+--------------+-----------------------+ +| Directory | MSVC version | Visual Studio version | ++====================+==============+=======================+ +| :file:`PC/VC6/` | 5.0 | 97 | +| +--------------+-----------------------+ +| | 6.0 | 6.0 | ++--------------------+--------------+-----------------------+ +| :file:`PCbuild/` | 7.1 | 2003 | ++--------------------+--------------+-----------------------+ +| :file:`PCbuild8/` | 8.0 | 2005 | ++--------------------+--------------+-----------------------+ +| :file:`PCbuild9/` | 9.0 | 2008 | ++--------------------+--------------+-----------------------+ + +Note that not all of these build directories are fully supported. Read the +release notes to see which compiler version the official releases for your +version are built with. + +Check :file:`PC/readme.txt` for general information on the build process. + + +For extension modules, consult :ref:`building-on-windows`. + +.. seealso:: + + `Python + Windows + distutils + SWIG + gcc MinGW `_ + or "Creating Python extensions in C/C++ with SWIG and compiling them with + MinGW gcc under Windows" or "Installing Python extension with distutils + and without Microsoft Visual C++" by Sébastien Sauvage, 2003 + + `MingW -- Python extensions `_ + by Trent Apted et al, 2007 + + +Other resources +=============== + +.. seealso:: + + `Python Programming On Win32 `_ + "Help for Windows Programmers" + by Mark Hammond and Andy Robinson, O'Reilly Media, 2000, + ISBN 1-56592-621-8 + + `A Python for Windows Tutorial `_ + by Amanda Birmingham, 2004 +