diff -r fbdaca8bf3f5 Doc/faq/windows.rst --- a/Doc/faq/windows.rst Wed Mar 12 15:09:00 2014 -0500 +++ b/Doc/faq/windows.rst Wed Mar 12 23:31:04 2014 -0500 @@ -1,344 +1,424 @@ -:tocdepth: 2 - -.. _windows-faq: - -===================== -Python on Windows FAQ -===================== - -.. only:: html - - .. contents:: - -.. XXX need review for Python 3. - XXX need review for Windows Vista/Seven? - - -How do I run a Python program under Windows? --------------------------------------------- - -This is not necessarily a straightforward question. If you are already familiar -with running programs from the Windows command line then everything will seem -obvious; otherwise, you might need a little more guidance. - -.. sidebar:: |Python Development on XP|_ - :subtitle: `Python Development on XP`_ - - This series of screencasts aims to get you up and running with Python on - Windows XP. The knowledge is distilled into 1.5 hours and will get you up - and running with the right Python distribution, coding in your choice of IDE, - and debugging and writing solid code with unit-tests. - -.. |Python Development on XP| image:: python-video-icon.png -.. _`Python Development on XP`: - http://www.showmedo.com/videos/series?name=pythonOzsvaldPyNewbieSeries - -Unless you use some sort of integrated development environment, you will end up -*typing* Windows commands into what is variously referred to as a "DOS window" -or "Command prompt window". Usually you can create such a window from your -Start menu; under Windows 7 the menu selection is :menuselection:`Start --> -Programs --> Accessories --> Command Prompt`. You should be able to recognize -when you have started such a window because you will see a Windows "command -prompt", which usually looks like this:: - - C:\> - -The letter may be different, and there might be other things after it, so you -might just as easily see something like:: - - D:\YourName\Projects\Python> - -depending on how your computer has been set up and what else you have recently -done with it. Once you have started such a window, you are well on the way to -running Python programs. - -You need to realize that your Python scripts have to be processed by another -program called the Python *interpreter*. The interpreter reads your script, -compiles it into bytecodes, and then executes the bytecodes to run your -program. So, how do you arrange for the interpreter to handle your Python? - -First, you need to make sure that your command window recognises the word -"python" as an instruction to start the interpreter. If you have opened a -command window, you should try entering the command ``python`` and hitting -return.:: - - C:\Users\YourName> python - -You should then see something like:: - - Python 3.3.0 (v3.3.0:bd8afb90ebf2, Sep 29 2012, 10:55:48) [MSC v.1600 32 bit (Intel)] on win32 - Type "help", "copyright", "credits" or "license" for more information. - >>> - -You have started the interpreter in "interactive mode". That means you can enter -Python statements or expressions interactively and have them executed or -evaluated while you wait. This is one of Python's strongest features. Check it -by entering a few expressions of your choice and seeing the results:: - - >>> print("Hello") - Hello - >>> "Hello" * 3 - HelloHelloHello - -Many people use the interactive mode as a convenient yet highly programmable -calculator. When you want to end your interactive Python session, hold the Ctrl -key down while you enter a Z, then hit the "Enter" key to get back to your -Windows command prompt. - -You may also find that you have a Start-menu entry such as :menuselection:`Start ---> Programs --> Python 3.3 --> Python (command line)` that results in you -seeing the ``>>>`` prompt in a new window. If so, the window will disappear -after you enter the Ctrl-Z character; Windows is running a single "python" -command in the window, and closes it when you terminate the interpreter. - -If the ``python`` command, instead of displaying the interpreter prompt ``>>>``, -gives you a message like:: - - 'python' is not recognized as an internal or external command, operable program or batch file. - -.. sidebar:: |Adding Python to DOS Path|_ - :subtitle: `Adding Python to DOS Path`_ - - Python is not added to the DOS path by default. This screencast will walk - you through the steps to add the correct entry to the `System Path`, allowing - Python to be executed from the command-line by all users. - -.. |Adding Python to DOS Path| image:: python-video-icon.png -.. _`Adding Python to DOS Path`: - http://showmedo.com/videos/video?name=960000&fromSeriesID=96 - - -or:: - - Bad command or filename - -then you need to make sure that your computer knows where to find the Python -interpreter. To do this you will have to modify a setting called PATH, which is -a list of directories where Windows will look for programs. - -You should arrange for Python's installation directory to be added to the PATH -of every command window as it starts. If you installed Python fairly recently -then the command :: - - dir C:\py* - -will probably tell you where it is installed; the usual location is something -like ``C:\Python33``. Otherwise you will be reduced to a search of your whole -disk ... use :menuselection:`Tools --> Find` or hit the :guilabel:`Search` -button and look for "python.exe". Supposing you discover that Python is -installed in the ``C:\Python33`` directory (the default at the time of writing), -you should make sure that entering the command :: - - c:\Python33\python - -starts up the interpreter as above (and don't forget you'll need a "CTRL-Z" and -an "Enter" to get out of it). Once you have verified the directory, you can -add it to the system path to make it easier to start Python by just running -the ``python`` command. This is currently an option in the installer as of -CPython 3.3. - -More information about environment variables can be found on the -:ref:`Using Python on Windows ` page. - -How do I make Python scripts executable? ----------------------------------------- - -On Windows, the standard Python installer already associates the .py -extension with a file type (Python.File) and gives that file type an open -command that runs the interpreter (``D:\Program Files\Python\python.exe "%1" -%*``). This is enough to make scripts executable from the command prompt as -'foo.py'. If you'd rather be able to execute the script by simple typing 'foo' -with no extension you need to add .py to the PATHEXT environment variable. - -Why does Python sometimes take so long to start? ------------------------------------------------- - -Usually Python starts very quickly on Windows, but occasionally there are bug -reports that Python suddenly begins to take a long time to start up. This is -made even more puzzling because Python will work fine on other Windows systems -which appear to be configured identically. - -The problem may be caused by a misconfiguration of virus checking software on -the problem machine. Some virus scanners have been known to introduce startup -overhead of two orders of magnitude when the scanner is configured to monitor -all reads from the filesystem. Try checking the configuration of virus scanning -software on your systems to ensure that they are indeed configured identically. -McAfee, when configured to scan all file system read activity, is a particular -offender. - - -How do I make an executable from a Python script? -------------------------------------------------- - -See http://cx-freeze.sourceforge.net/ for a distutils extension that allows you -to create console and GUI executables from Python code. -`py2exe `_, the most popular extension for building -Python 2.x-based executables, does not yet support Python 3 but a version that -does is in development. - - -Is a ``*.pyd`` file the same as a DLL? --------------------------------------- - -Yes, .pyd files are dll's, but there are a few differences. If you have a DLL -named ``foo.pyd``, then it must have a function ``PyInit_foo()``. You can then -write Python "import foo", and Python will search for foo.pyd (as well as -foo.py, foo.pyc) and if it finds it, will attempt to call ``PyInit_foo()`` to -initialize it. You do not link your .exe with foo.lib, as that would cause -Windows to require the DLL to be present. - -Note that the search path for foo.pyd is PYTHONPATH, not the same as the path -that Windows uses to search for foo.dll. Also, foo.pyd need not be present to -run your program, whereas if you linked your program with a dll, the dll is -required. Of course, foo.pyd is required if you want to say ``import foo``. In -a DLL, linkage is declared in the source code with ``__declspec(dllexport)``. -In a .pyd, linkage is defined in a list of available functions. - - -How can I embed Python into a Windows application? --------------------------------------------------- - -Embedding the Python interpreter in a Windows app can be summarized as follows: - -1. Do _not_ build Python into your .exe file directly. On Windows, Python must - be a DLL to handle importing modules that are themselves DLL's. (This is the - first key undocumented fact.) Instead, link to :file:`python{NN}.dll`; it is - typically installed in ``C:\Windows\System``. *NN* is the Python version, a - number such as "33" for Python 3.3. - - You can link to Python in two different ways. Load-time linking means - linking against :file:`python{NN}.lib`, while run-time linking means linking - against :file:`python{NN}.dll`. (General note: :file:`python{NN}.lib` is the - so-called "import lib" corresponding to :file:`python{NN}.dll`. It merely - defines symbols for the linker.) - - Run-time linking greatly simplifies link options; everything happens at run - time. Your code must load :file:`python{NN}.dll` using the Windows - ``LoadLibraryEx()`` routine. The code must also use access routines and data - in :file:`python{NN}.dll` (that is, Python's C API's) using pointers obtained - by the Windows ``GetProcAddress()`` routine. Macros can make using these - pointers transparent to any C code that calls routines in Python's C API. - - Borland note: convert :file:`python{NN}.lib` to OMF format using Coff2Omf.exe - first. - - .. XXX what about static linking? - -2. If you use SWIG, it is easy to create a Python "extension module" that will - make the app's data and methods available to Python. SWIG will handle just - about all the grungy details for you. The result is C code that you link - *into* your .exe file (!) You do _not_ have to create a DLL file, and this - also simplifies linking. - -3. SWIG will create an init function (a C function) whose name depends on the - name of the extension module. For example, if the name of the module is leo, - the init function will be called initleo(). If you use SWIG shadow classes, - as you should, the init function will be called initleoc(). This initializes - a mostly hidden helper class used by the shadow class. - - The reason you can link the C code in step 2 into your .exe file is that - calling the initialization function is equivalent to importing the module - into Python! (This is the second key undocumented fact.) - -4. In short, you can use the following code to initialize the Python interpreter - with your extension module. - - .. code-block:: c - - #include "python.h" - ... - Py_Initialize(); // Initialize Python. - initmyAppc(); // Initialize (import) the helper class. - PyRun_SimpleString("import myApp"); // Import the shadow class. - -5. There are two problems with Python's C API which will become apparent if you - use a compiler other than MSVC, the compiler used to build pythonNN.dll. - - Problem 1: The so-called "Very High Level" functions that take FILE * - arguments will not work in a multi-compiler environment because each - compiler's notion of a struct FILE will be different. From an implementation - standpoint these are very _low_ level functions. - - Problem 2: SWIG generates the following code when generating wrappers to void - functions: - - .. code-block:: c - - Py_INCREF(Py_None); - _resultobj = Py_None; - return _resultobj; - - Alas, Py_None is a macro that expands to a reference to a complex data - structure called _Py_NoneStruct inside pythonNN.dll. Again, this code will - fail in a mult-compiler environment. Replace such code by: - - .. code-block:: c - - return Py_BuildValue(""); - - It may be possible to use SWIG's ``%typemap`` command to make the change - automatically, though I have not been able to get this to work (I'm a - complete SWIG newbie). - -6. Using a Python shell script to put up a Python interpreter window from inside - your Windows app is not a good idea; the resulting window will be independent - of your app's windowing system. Rather, you (or the wxPythonWindow class) - should create a "native" interpreter window. It is easy to connect that - window to the Python interpreter. You can redirect Python's i/o to _any_ - object that supports read and write, so all you need is a Python object - (defined in your extension module) that contains read() and write() methods. - -How do I keep editors from inserting tabs into my Python source? ----------------------------------------------------------------- - -The FAQ does not recommend using tabs, and the Python style guide, :pep:`8`, -recommends 4 spaces for distributed Python code; this is also the Emacs -python-mode default. - -Under any editor, mixing tabs and spaces is a bad idea. MSVC is no different in -this respect, and is easily configured to use spaces: Take :menuselection:`Tools ---> Options --> Tabs`, and for file type "Default" set "Tab size" and "Indent -size" to 4, and select the "Insert spaces" radio button. - -If you suspect mixed tabs and spaces are causing problems in leading whitespace, -run Python with the :option:`-t` switch or run ``Tools/Scripts/tabnanny.py`` to -check a directory tree in batch mode. - - -How do I check for a keypress without blocking? ------------------------------------------------ - -Use the msvcrt module. This is a standard Windows-specific extension module. -It defines a function ``kbhit()`` which checks whether a keyboard hit is -present, and ``getch()`` which gets one character without echoing it. - - -How do I emulate os.kill() in Windows? --------------------------------------- - -Prior to Python 2.7 and 3.2, to terminate a process, you can use :mod:`ctypes`:: - - import ctypes - - def kill(pid): - """kill function for Win32""" - kernel32 = ctypes.windll.kernel32 - handle = kernel32.OpenProcess(1, 0, pid) - return (0 != kernel32.TerminateProcess(handle, 0)) - -In 2.7 and 3.2, :func:`os.kill` is implemented similar to the above function, -with the additional feature of being able to send CTRL+C and CTRL+BREAK -to console subprocesses which are designed to handle those signals. See -:func:`os.kill` for further details. - -How do I extract the downloaded documentation on Windows? ---------------------------------------------------------- - -Sometimes, when you download the documentation package to a Windows machine -using a web browser, the file extension of the saved file ends up being .EXE. -This is a mistake; the extension should be .TGZ. - -Simply rename the downloaded file to have the .TGZ extension, and WinZip will be -able to handle it. (If your copy of WinZip doesn't, get a newer one from -http://www.winzip.com.) - +:tocdepth: 2 + +.. _windows-faq: + +===================== +Python on Windows FAQ +===================== + +.. only:: html + + .. contents:: + +.. XXX need review for Python 3. + XXX need review for Windows Vista/Seven? + +.. _running-windows: + +How do I run a Python program under Windows? +-------------------------------------------- + +This is not necessarily a straightforward question. If you are already familiar +with running programs from the Windows command line then everything will seem +obvious; otherwise, you might need a little more guidance. + +.. sidebar:: |Python Development on XP|_ + :subtitle: `Python Development on XP`_ + + This series of screencasts aims to get you up and running with Python on + Windows XP. The knowledge is distilled into 1.5 hours and will get you up + and running with the right Python distribution, coding in your choice of IDE, + and debugging and writing solid code with unit-tests. + +.. |Python Development on XP| image:: python-video-icon.png +.. _`Python Development on XP`: + http://www.showmedo.com/videos/series?name=pythonOzsvaldPyNewbieSeries + +Unless you use some sort of integrated development environment, you will end up +*typing* Windows commands into what is variously referred to as a "DOS window" +or "Command prompt window". Usually you can create such a window from your +Start menu; under Windows 7 the menu selection is :menuselection:`Start --> +Programs --> Accessories --> Command Prompt`; under Windows 8 right click the +Windows Icon or type Command Prompt at the Start Menu. You should be able to recognize +when you have started such a window because you will see a Windows "command +prompt", which usually looks like this:: + + C:\> + +The letter may be different, and there might be other things after it, so you +might just as easily see something like:: + + D:\YourName\Projects\Python> + +depending on how your computer has been set up and what else you have recently +done with it. Once you have started such a window, you are well on the way to +running Python programs. + +You need to realize that your Python scripts have to be processed by another +program called the Python *interpreter*. The interpreter reads your script, +compiles it into bytecodes, and then executes the bytecodes to run your +program. So, how do you arrange for the interpreter to handle your Python? + +First, you need to make sure that your command window recognises the word +"python" as an instruction to start the interpreter. If you have opened a +command window, you should try entering the command ``python`` and hitting +return.:: + + C:\Users\YourName> python + +You should then see something like:: + + Python 3.3.0 (v3.3.0:bd8afb90ebf2, Sep 29 2012, 10:55:48) [MSC v.1600 32 bit (Intel)] on win32 + Type "help", "copyright", "credits" or "license" for more information. + >>> + +You have started the interpreter in "interactive mode". That means you can enter +Python statements or expressions interactively and have them executed or +evaluated while you wait. This is one of Python's strongest features. Check it +by entering a few expressions of your choice and seeing the results:: + + >>> print("Hello") + Hello + >>> "Hello" * 3 + HelloHelloHello + +Many people use the interactive mode as a convenient yet highly programmable +calculator. When you want to end your interactive Python session, hold the Ctrl +key down while you enter a Z, then hit the "Enter" key to get back to your +Windows command prompt. + +You may also find that you have a Start-menu entry such as :menuselection:`Start +--> Programs --> Python 3.3 --> Python (command line)` that results in you +seeing the ``>>>`` prompt in a new window. If so, the window will disappear +after you enter the Ctrl-Z character; Windows is running a single "python" +command in the window, and closes it when you terminate the interpreter. + +If the ``python`` command, instead of displaying the interpreter prompt ``>>>``, +gives you a message like:: + + 'python' is not recognized as an internal or external command, operable program or batch file. + +.. sidebar:: |Adding Python to DOS Path|_ + :subtitle: `Adding Python to DOS Path`_ + + Python is not added to the DOS path by default. This screencast will walk + you through the steps to add the correct entry to the `System Path`, allowing + Python to be executed from the command-line by all users. + +.. |Adding Python to DOS Path| image:: python-video-icon.png +.. _`Adding Python to DOS Path`: + http://showmedo.com/videos/video?name=960000&fromSeriesID=96 + + +or:: + + Bad command or filename + +then you need to make sure that your computer knows where to find the Python +interpreter. To do this you will have to modify a setting called PATH, which is +a list of directories where Windows will look for programs. + +You should arrange for Python's installation directory to be added to the PATH +of every command window as it starts. If you installed Python fairly recently +then the command :: + + dir C:\py* + +will probably tell you where it is installed; the usual location is something +like ``C:\Python33``. Otherwise you will be reduced to a search of your whole +disk ... use :menuselection:`Tools --> Find` or hit the :guilabel:`Search` +button and look for "python.exe". Supposing you discover that Python is +installed in the ``C:\Python33`` directory (the default at the time of writing), +you should make sure that entering the command :: + + c:\Python33\python + +starts up the interpreter as above (and don't forget you'll need a "CTRL-Z" and +an "Enter" to get out of it). Once you have verified the directory, you can +add it to the system path to make it easier to start Python by just running +the ``python`` command. This is currently an option in the installer as of +CPython 3.3. + +More information about environment variables and path can be found +:ref:`below` . + +How do I make Python scripts executable? +---------------------------------------- + +On Windows, the standard Python installer already associates the .py +extension with a file type (Python.File) and gives that file type an open +command that runs the interpreter (``D:\Program Files\Python\python.exe "%1" +%*``). This is enough to make scripts executable from the command prompt as +'foo.py'. If you'd rather be able to execute the script by simple typing 'foo' +with no extension you need to add .py to the PATHEXT environment variable. + +Why does Python sometimes take so long to start? +------------------------------------------------ + +Usually Python starts very quickly on Windows, but occasionally there are bug +reports that Python suddenly begins to take a long time to start up. This is +made even more puzzling because Python will work fine on other Windows systems +which appear to be configured identically. + +The problem may be caused by a misconfiguration of virus checking software on +the problem machine. Some virus scanners have been known to introduce startup +overhead of two orders of magnitude when the scanner is configured to monitor +all reads from the filesystem. Try checking the configuration of virus scanning +software on your systems to ensure that they are indeed configured identically. +McAfee, when configured to scan all file system read activity, is a particular +offender. + + +How do I make an executable from a Python script? +------------------------------------------------- + +See http://cx-freeze.sourceforge.net/ for a distutils extension that allows you +to create console and GUI executables from Python code. +`py2exe `_, the most popular extension for building +Python 2.x-based executables, does not yet support Python 3 but a version that +does is in development. + + +Is a ``*.pyd`` file the same as a DLL? +-------------------------------------- + +Yes, .pyd files are dll's, but there are a few differences. If you have a DLL +named ``foo.pyd``, then it must have a function ``PyInit_foo()``. You can then +write Python "import foo", and Python will search for foo.pyd (as well as +foo.py, foo.pyc) and if it finds it, will attempt to call ``PyInit_foo()`` to +initialize it. You do not link your .exe with foo.lib, as that would cause +Windows to require the DLL to be present. + +Note that the search path for foo.pyd is PYTHONPATH, not the same as the path +that Windows uses to search for foo.dll. Also, foo.pyd need not be present to +run your program, whereas if you linked your program with a dll, the dll is +required. Of course, foo.pyd is required if you want to say ``import foo``. In +a DLL, linkage is declared in the source code with ``__declspec(dllexport)``. +In a .pyd, linkage is defined in a list of available functions. + + +How can I embed Python into a Windows application? +-------------------------------------------------- + +Embedding the Python interpreter in a Windows app can be summarized as follows: + +1. Do _not_ build Python into your .exe file directly. On Windows, Python must + be a DLL to handle importing modules that are themselves DLL's. (This is the + first key undocumented fact.) Instead, link to :file:`python{NN}.dll`; it is + typically installed in ``C:\Windows\System``. *NN* is the Python version, a + number such as "33" for Python 3.3. + + You can link to Python in two different ways. Load-time linking means + linking against :file:`python{NN}.lib`, while run-time linking means linking + against :file:`python{NN}.dll`. (General note: :file:`python{NN}.lib` is the + so-called "import lib" corresponding to :file:`python{NN}.dll`. It merely + defines symbols for the linker.) + + Run-time linking greatly simplifies link options; everything happens at run + time. Your code must load :file:`python{NN}.dll` using the Windows + ``LoadLibraryEx()`` routine. The code must also use access routines and data + in :file:`python{NN}.dll` (that is, Python's C API's) using pointers obtained + by the Windows ``GetProcAddress()`` routine. Macros can make using these + pointers transparent to any C code that calls routines in Python's C API. + + Borland note: convert :file:`python{NN}.lib` to OMF format using Coff2Omf.exe + first. + + .. XXX what about static linking? + +2. If you use SWIG, it is easy to create a Python "extension module" that will + make the app's data and methods available to Python. SWIG will handle just + about all the grungy details for you. The result is C code that you link + *into* your .exe file (!) You do _not_ have to create a DLL file, and this + also simplifies linking. + +3. SWIG will create an init function (a C function) whose name depends on the + name of the extension module. For example, if the name of the module is leo, + the init function will be called initleo(). If you use SWIG shadow classes, + as you should, the init function will be called initleoc(). This initializes + a mostly hidden helper class used by the shadow class. + + The reason you can link the C code in step 2 into your .exe file is that + calling the initialization function is equivalent to importing the module + into Python! (This is the second key undocumented fact.) + +4. In short, you can use the following code to initialize the Python interpreter + with your extension module. + + .. code-block:: c + + #include "python.h" + ... + Py_Initialize(); // Initialize Python. + initmyAppc(); // Initialize (import) the helper class. + PyRun_SimpleString("import myApp"); // Import the shadow class. + +5. There are two problems with Python's C API which will become apparent if you + use a compiler other than MSVC, the compiler used to build pythonNN.dll. + + Problem 1: The so-called "Very High Level" functions that take FILE * + arguments will not work in a multi-compiler environment because each + compiler's notion of a struct FILE will be different. From an implementation + standpoint these are very _low_ level functions. + + Problem 2: SWIG generates the following code when generating wrappers to void + functions: + + .. code-block:: c + + Py_INCREF(Py_None); + _resultobj = Py_None; + return _resultobj; + + Alas, Py_None is a macro that expands to a reference to a complex data + structure called _Py_NoneStruct inside pythonNN.dll. Again, this code will + fail in a mult-compiler environment. Replace such code by: + + .. code-block:: c + + return Py_BuildValue(""); + + It may be possible to use SWIG's ``%typemap`` command to make the change + automatically, though I have not been able to get this to work (I'm a + complete SWIG newbie). + +6. Using a Python shell script to put up a Python interpreter window from inside + your Windows app is not a good idea; the resulting window will be independent + of your app's windowing system. Rather, you (or the wxPythonWindow class) + should create a "native" interpreter window. It is easy to connect that + window to the Python interpreter. You can redirect Python's i/o to _any_ + object that supports read and write, so all you need is a Python object + (defined in your extension module) that contains read() and write() methods. + +How do I keep editors from inserting tabs into my Python source? +---------------------------------------------------------------- + +The FAQ does not recommend using tabs, and the Python style guide, :pep:`8`, +recommends 4 spaces for distributed Python code; this is also the Emacs +python-mode default. + +Under any editor, mixing tabs and spaces is a bad idea. MSVC is no different in +this respect, and is easily configured to use spaces: Take :menuselection:`Tools +--> Options --> Tabs`, and for file type "Default" set "Tab size" and "Indent +size" to 4, and select the "Insert spaces" radio button. + +If you suspect mixed tabs and spaces are causing problems in leading whitespace, +run Python with the :option:`-t` switch or run ``Tools/Scripts/tabnanny.py`` to +check a directory tree in batch mode. + + +How do I check for a keypress without blocking? +----------------------------------------------- + +Use the msvcrt module. This is a standard Windows-specific extension module. +It defines a function ``kbhit()`` which checks whether a keyboard hit is +present, and ``getch()`` which gets one character without echoing it. + + +How do I emulate os.kill() in Windows? +-------------------------------------- + +Prior to Python 2.7 and 3.2, to terminate a process, you can use :mod:`ctypes`:: + + import ctypes + + def kill(pid): + """kill function for Win32""" + kernel32 = ctypes.windll.kernel32 + handle = kernel32.OpenProcess(1, 0, pid) + return (0 != kernel32.TerminateProcess(handle, 0)) + +In 2.7 and 3.2, :func:`os.kill` is implemented similar to the above function, +with the additional feature of being able to send CTRL+C and CTRL+BREAK +to console subprocesses which are designed to handle those signals. See +:func:`os.kill` for further details. + +How do I extract the downloaded documentation on Windows? +--------------------------------------------------------- + +Sometimes, when you download the documentation package to a Windows machine +using a web browser, the file extension of the saved file ends up being .EXE. +This is a mistake; the extension should be .TGZ. + +Simply rename the downloaded file to have the .TGZ extension, and WinZip will be +able to handle it. (If your copy of WinZip doesn't, get a newer one from +http://www.winzip.com.) + +.. sectionauthor:: Kathleen Weaver +.. moved from using windows + +.. _setting-envvars: + +How do I Change Enviroment Settings? +------------------------------------ + +To change environment variables in Windows 7 and 8, you must use the built-in dialog. + +Windows has a built-in dialog for changing environment variables + + Windows XP: 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` + + Windows 7: Right-click the Windows Icon, choose :menuselection:`Contol Panel`. + Then click :guilabel:`System` and click the :guilabel:`Advanced system settings` + and click the :guilabel:`Environment Variables` button. + + In short, your path is: + + :menuselection:`Control Panel + --> System + --> Advanced system settings + --> Environment Variables` + + Windows 8: Right-click the Windows Icon, choose + :menuselection:`System` and click the :guilabel:`Advanced system settings` and click + the :guilabel:`Environment Variables` button. (Windows 8 skips the control panel) + + In short, your path is: + + :menuselection:`System + --> Advanced system settings + --> 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 in versions prior to Windows 7 and 8 +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`. :program:`msconfig` is a graphical interface to this +file. + +Viewing environment variables in all Windows versions 8.1 and below 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 + + http://www.chem.gla.ac.uk/~louis/software/faq/q1.html + Setting Environment variables, Louis J. Farrugia + diff -r fbdaca8bf3f5 Doc/using/windows.rst --- a/Doc/using/windows.rst Wed Mar 12 15:09:00 2014 -0500 +++ b/Doc/using/windows.rst Wed Mar 12 23:31:04 2014 -0500 @@ -1,604 +1,581 @@ -.. 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 no longer supported (due to the lack of users or developers). -Check :pep:`11` for details on all unsupported platforms. - -* `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 `_ -for detailed information about platforms with pre-compiled 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 - -`Enthought Python Distribution `_ - Popular modules (such as PyWin32) with their respective documentation, tool - suite for building extensible Python applications - -Notice that these packages are likely to install *older* versions of Python. - - - -Configuring Python -================== - -In order to run Python flawlessly, you might have to change certain environment -settings in Windows. - - -.. _setting-envvars: - -Excursus: Setting environment variables ---------------------------------------- - -Windows has a built-in dialog for changing environment variables (following -guide applies to XP classical view): 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`. :program:`msconfig` is a graphical interface to this -file. - -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 - - http://www.chem.gla.ac.uk/~louis/software/faq/q1.html - Setting Environment variables, Louis J. Farrugia - - -.. _windows-path-mod: - -Finding the Python executable ------------------------------ - -.. versionchanged:: 3.3 - -Besides using the automatically created start menu entry for the Python -interpreter, you might want to start Python in the command prompt. As of -Python 3.3, the installer has an option to set that up for you. - -At the "Customize Python 3.3" screen, an option called -"Add python.exe to search path" can be enabled to have the installer place -your installation into the :envvar:`%PATH%`. This allows you to type -:command:`python` to run the interpreter. Thus, you can also execute your -scripts with command line options, see :ref:`using-on-cmdline` documentation. - -If you don't enable this option at install time, you can always re-run the -installer to choose it. - -The alternative is manually modifying the :envvar:`%PATH%` using the -directions in :ref:`setting-envvars`. 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:\WINDOWS\system32;C:\WINDOWS;C:\Python33 - - -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 is how :data:`sys.path` is populated on Windows: - -* An empty entry is added at the start, which corresponds to the current - directory. - -* If the environment variable :envvar:`PYTHONPATH` exists, as described in - :ref:`using-on-envvars`, its entries are added next. Note that on Windows, - paths in this variable must be separated by semicolons, to distinguish them - from the colon used in drive identifiers (``C:\`` etc.). - -* Additional "application paths" can be added in the registry as subkeys of - :samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the - ``HKEY_CURRENT_USER`` and ``HKEY_LOCAL_MACHINE`` hives. Subkeys which have - semicolon-delimited path strings as their default value will cause each path - to be added to :data:`sys.path`. (Note that all known installers only use - HKLM, so HKCU is typically empty.) - -* If the environment variable :envvar:`PYTHONHOME` is set, it is assumed as - "Python Home". Otherwise, the path of the main Python executable is used to - locate a "landmark file" (``Lib\os.py``) to deduce the "Python Home". If a - Python home is found, the relevant sub-directories added to :data:`sys.path` - (``Lib``, ``plat-win``, etc) are based on that folder. Otherwise, the core - Python path is constructed from the PythonPath stored in the registry. - -* If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in - the environment, and no registry entries can be found, a default path with - relative entries is used (e.g. ``.\Lib;.\plat-win``, etc). - -The end result of all this is: - -* When running :file:`python.exe`, or any other .exe in the main Python - directory (either an installed version, or directly from the PCbuild - directory), the core path is deduced, and the core paths in the registry are - ignored. Other "application paths" in the registry are always read. - -* When Python is hosted in another .exe (different directory, embedded via COM, - etc), the "Python Home" will not be deduced, so the core path from the - registry is used. Other "application paths" in the registry are always read. - -* If Python can't find its home and there is no registry (eg, frozen .exe, some - very strange installation setup) you get a path with some default, but - relative, paths. - - -Executing scripts ------------------ - -As of Python 3.3, Python includes a launcher which facilitates running Python -scripts. See :ref:`launcher` for more information. - -Executing scripts without the Python launcher ---------------------------------------------- - -Without the Python launcher installed, 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 facilities, for example (might require -administrative rights): - -#. Launch a command prompt. -#. Associate the correct file group with ``.py`` scripts:: - - assoc .py=Python.File - -#. Redirect all Python files to the new executable:: - - ftype Python.File=C:\Path\to\pythonw.exe "%1" %* - - -.. _launcher: - -Python Launcher for Windows -=========================== - -.. versionadded:: 3.3 - -The Python launcher for Windows is a utility which aids in the location and -execution of different Python versions. It allows scripts (or the -command-line) to indicate a preference for a specific Python version, and -will locate and execute that version. - -Getting started ---------------- - -From the command-line -^^^^^^^^^^^^^^^^^^^^^ - -You should ensure the launcher is on your PATH - depending on how it was -installed it may already be there, but check just in case it is not. - -From a command-prompt, execute the following command: - -:: - - py - -You should find that the latest version of Python 2.x you have installed is -started - it can be exited as normal, and any additional command-line -arguments specified will be sent directly to Python. - -If you have multiple versions of Python 2.x installed (e.g., 2.6 and 2.7) you -will have noticed that Python 2.7 was started - to launch Python 2.6, try the -command: - -:: - - py -2.6 - -If you have a Python 3.x installed, try the command: - -:: - - py -3 - -You should find the latest version of Python 3.x starts. - -From a script -^^^^^^^^^^^^^ - -Let's create a test Python script - create a file called ``hello.py`` with the -following contents - -:: - - #! python - import sys - sys.stdout.write("hello from Python %s\n" % (sys.version,)) - -From the directory in which hello.py lives, execute the command: - -:: - - py hello.py - -You should notice the version number of your latest Python 2.x installation -is printed. Now try changing the first line to be: - -:: - - #! python3 - -Re-executing the command should now print the latest Python 3.x information. -As with the above command-line examples, you can specify a more explicit -version qualifier. Assuming you have Python 2.6 installed, try changing the -first line to ``#! python2.6`` and you should find the 2.6 version -information printed. - -From file associations -^^^^^^^^^^^^^^^^^^^^^^ - -The launcher should have been associated with Python files (i.e. ``.py``, -``.pyw``, ``.pyc``, ``.pyo`` files) when it was installed. This means that -when you double-click on one of these files from Windows explorer the launcher -will be used, and therefore you can use the same facilities described above to -have the script specify the version which should be used. - -The key benefit of this is that a single launcher can support multiple Python -versions at the same time depending on the contents of the first line. - -Shebang Lines -------------- - -If the first line of a script file starts with ``#!``, it is known as a -"shebang" line. Linux and other Unix like operating systems have native -support for such lines and are commonly used on such systems to indicate how -a script should be executed. This launcher allows the same facilities to be -using with Python scripts on Windows and the examples above demonstrate their -use. - -To allow shebang lines in Python scripts to be portable between Unix and -Windows, this launcher supports a number of 'virtual' commands to specify -which interpreter to use. The supported virtual commands are: - -* ``/usr/bin/env python`` -* ``/usr/bin/python`` -* ``/usr/local/bin/python`` -* ``python`` - -For example, if the first line of your script starts with - -:: - - #! /usr/bin/python - -The default Python will be located and used. As many Python scripts written -to work on Unix will already have this line, you should find these scripts can -be used by the launcher without modification. If you are writing a new script -on Windows which you hope will be useful on Unix, you should use one of the -shebang lines starting with ``/usr``. - -Arguments in shebang lines --------------------------- - -The shebang lines can also specify additional options to be passed to the -Python interpreter. For example, if you have a shebang line: - -:: - - #! /usr/bin/python -v - -Then Python will be started with the ``-v`` option - -Customization -------------- - -Customization via INI files -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Two .ini files will be searched by the launcher - ``py.ini`` in the - current user's "application data" directory (i.e. the directory returned - by calling the Windows function SHGetFolderPath with CSIDL_LOCAL_APPDATA) - and ``py.ini`` in the same directory as the launcher. The same .ini - files are used for both the 'console' version of the launcher (i.e. - py.exe) and for the 'windows' version (i.e. pyw.exe) - - Customization specified in the "application directory" will have - precedence over the one next to the executable, so a user, who may not - have write access to the .ini file next to the launcher, can override - commands in that global .ini file) - -Customizing default Python versions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In some cases, a version qualifier can be included in a command to dictate -which version of Python will be used by the command. A version qualifier -starts with a major version number and can optionally be followed by a period -('.') and a minor version specifier. If the minor qualifier is specified, it -may optionally be followed by "-32" to indicate the 32-bit implementation of -that version be used. - -For example, a shebang line of ``#!python`` has no version qualifier, while -``#!python3`` has a version qualifier which specifies only a major version. - -If no version qualifiers are found in a command, the environment variable -``PY_PYTHON`` can be set to specify the default version qualifier - the default -value is "2". Note this value could specify just a major version (e.g. "2") or -a major.minor qualifier (e.g. "2.6"), or even major.minor-32. - -If no minor version qualifiers are found, the environment variable -``PY_PYTHON{major}`` (where ``{major}`` is the current major version qualifier -as determined above) can be set to specify the full version. If no such option -is found, the launcher will enumerate the installed Python versions and use -the latest minor release found for the major version, which is likely, -although not guaranteed, to be the most recently installed version in that -family. - -On 64-bit Windows with both 32-bit and 64-bit implementations of the same -(major.minor) Python version installed, the 64-bit version will always be -preferred. This will be true for both 32-bit and 64-bit implementations of the -launcher - a 32-bit launcher will prefer to execute a 64-bit Python installation -of the specified version if available. This is so the behavior of the launcher -can be predicted knowing only what versions are installed on the PC and -without regard to the order in which they were installed (i.e., without knowing -whether a 32 or 64-bit version of Python and corresponding launcher was -installed last). As noted above, an optional "-32" suffix can be used on a -version specifier to change this behaviour. - -Examples: - -* If no relevant options are set, the commands ``python`` and - ``python2`` will use the latest Python 2.x version installed and - the command ``python3`` will use the latest Python 3.x installed. - -* The commands ``python3.1`` and ``python2.7`` will not consult any - options at all as the versions are fully specified. - -* If ``PY_PYTHON=3``, the commands ``python`` and ``python3`` will both use - the latest installed Python 3 version. - -* If ``PY_PYTHON=3.1-32``, the command ``python`` will use the 32-bit - implementation of 3.1 whereas the command ``python3`` will use the latest - installed Python (PY_PYTHON was not considered at all as a major - version was specified.) - -* If ``PY_PYTHON=3`` and ``PY_PYTHON3=3.1``, the commands - ``python`` and ``python3`` will both use specifically 3.1 - -In addition to environment variables, the same settings can be configured -in the .INI file used by the launcher. The section in the INI file is -called ``[defaults]`` and the key name will be the same as the -environment variables without the leading ``PY_`` prefix (and note that -the key names in the INI file are case insensitive.) The contents of -an environment variable will override things specified in the INI file. - -For example: - -* Setting ``PY_PYTHON=3.1`` is equivalent to the INI file containing: - -:: - - [defaults] - python=3.1 - -* Setting ``PY_PYTHON=3`` and ``PY_PYTHON3=3.1`` is equivalent to the INI file - containing: - -:: - - [defaults] - python=3 - python3=3.1 - -Diagnostics ------------ - -If an environment variable ``PYLAUNCH_DEBUG`` is set (to any value), the -launcher will print diagnostic information to stderr (i.e. to the console). -While this information manages to be simultaneously verbose *and* terse, it -should allow you to see what versions of Python were located, why a -particular version was chosen and the exact command-line used to execute the -target Python. - - -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 -utilities 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 - - -cx_Freeze ---------- - -`cx_Freeze `_ 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 -`_. - -The source tree contains a build solution and project files for Microsoft -Visual C++, which is the compiler used to build the official Python releases. -View the :file:`readme.txt` in their respective directories: - -+--------------------+--------------+-----------------------+ -| Directory | MSVC version | Visual Studio version | -+====================+==============+=======================+ -| :file:`PC/VS9.0/` | 9.0 | 2008 | -+--------------------+--------------+-----------------------+ -| :file:`PCbuild/` | 10.0 | 2010 | -+--------------------+--------------+-----------------------+ - -Note that any build directories within the :file:`PC` directory are not -necessarily fully supported. The :file:`PCbuild` directory contains the files -for the compiler used to build the official release. - -Check :file:`PCbuild/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 - - :pep:`397` - Python launcher for Windows - The proposal for the launcher to be included in the Python distribution. - - +.. 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. + +.. sectionauthor:: Kathleen Weaver + +After running the installer, the following programs will be available in the +Start Menu under the title Python x.x where x.x is the version number. + + * IDLE (Python GUI) - suitable for creating and running Python Scripts along with being a command line interpreter + * Python (command line) - Python command line interpreter + * Python Manuals - Python documentation + * Uninstall Python - which will uninstall these programs. + +.. sectionauthor:: Robert Lehmann + +All versions can be installed and will run independently. The Windows command +prompt typically runs the last installed version of Python. + +With ongoing development of Python, some platforms that used to be supported +earlier are no longer supported (due to the lack of users or developers). +Check :pep:`11` for details on all unsupported platforms. + +* `Windows CE `_ is still supported. +* The `Cygwin `_ installer offers to install the Python + interpreter as well; it is located under "Interpreters." + +See `Python for Windows `_ +for detailed information about platforms with pre-compiled installers. + +.. see also:: + + `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 + +`Enthought Python Distribution `_ + Popular modules (such as PyWin32) with their respective documentation, tool + suite for building extensible Python applications + +Notice that these packages are likely to install *older* versions of Python. + +.. sectionauthor:: Kathleen Weaver + +Running Python +============== + +The following shortcuts are creating during installation and can be used to run Python: + +* Python (command line) - Python command line interpreter +* IDLE (Python GUI) - suitable for creating and running Python Scripts along with being a command line interpreter +* Select Python through File Explorer - this works the same as running the Python shortcut. + Find the Python directory and double click python + +While these tools are useful to get started, it is still recommended to run +Python through the Windows Command line and set environment variables. +Directions for setting environments are located at :ref:`setting-envvars`. +Detailed directions for running Python are at :ref:`running-windows`. + + +Python scripts are associated with Python and will run when opened, but the +window will close immediately, usually faster than the user can read. A work +around is to add:: + + raw_input() + +to the end of the script. The window will remain open until the user hits the enter key. + +.. sectionauthor:: Robert Lehmann + +Finding the Python executable +----------------------------- + +.. versionchanged:: 3.3 + +Besides using the automatically created start menu entry for the Python +interpreter, you might want to start Python in the command prompt. As of +Python 3.3, the installer has an option to set that up for you. + +At the "Customize Python 3.3" screen, an option called +"Add python.exe to search path" can be enabled to have the installer place +your installation into the :envvar:`%PATH%`. This allows you to type +:command:`python` to run the interpreter. Thus, you can also execute your +scripts with command line options, see :ref:`using-on-cmdline` documentation. + +If you don't enable this option at install time, you can always re-run the +installer to choose it. + +The alternative is manually modifying the :envvar:`%PATH%` using the +directions in :ref:`setting-envvars`. 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:\WINDOWS\system32;C:\WINDOWS;C:\Python33 + + +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 is how :data:`sys.path` is populated on Windows: + +* An empty entry is added at the start, which corresponds to the current + directory. + +* If the environment variable :envvar:`PYTHONPATH` exists, as described in + :ref:`using-on-envvars`, its entries are added next. Note that on Windows, + paths in this variable must be separated by semicolons, to distinguish them + from the colon used in drive identifiers (``C:\`` etc.). + +* Additional "application paths" can be added in the registry as subkeys of + :samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the + ``HKEY_CURRENT_USER`` and ``HKEY_LOCAL_MACHINE`` hives. Subkeys which have + semicolon-delimited path strings as their default value will cause each path + to be added to :data:`sys.path`. (Note that all known installers only use + HKLM, so HKCU is typically empty.) + +* If the environment variable :envvar:`PYTHONHOME` is set, it is assumed as + "Python Home". Otherwise, the path of the main Python executable is used to + locate a "landmark file" (``Lib\os.py``) to deduce the "Python Home". If a + Python home is found, the relevant sub-directories added to :data:`sys.path` + (``Lib``, ``plat-win``, etc) are based on that folder. Otherwise, the core + Python path is constructed from the PythonPath stored in the registry. + +* If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in + the environment, and no registry entries can be found, a default path with + relative entries is used (e.g. ``.\Lib;.\plat-win``, etc). + +The end result of all this is: + +* When running :file:`python.exe`, or any other .exe in the main Python + directory (either an installed version, or directly from the PCbuild + directory), the core path is deduced, and the core paths in the registry are + ignored. Other "application paths" in the registry are always read. + +* When Python is hosted in another .exe (different directory, embedded via COM, + etc), the "Python Home" will not be deduced, so the core path from the + registry is used. Other "application paths" in the registry are always read. + +* If Python can't find its home and there is no registry (eg, frozen .exe, some + very strange installation setup) you get a path with some default, but + relative, paths. + + +Executing scripts +----------------- + +As of Python 3.3, Python includes a launcher which facilitates running Python +scripts. See :ref:`launcher` for more information. + +Executing scripts without the Python launcher +--------------------------------------------- + +Without the Python launcher installed, 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 facilities, for example (might require +administrative rights): + +#. Launch a command prompt [Windows 8 - Launch Command Prompt (Admin)] +#. Associate the correct file group with ``.py`` scripts:: + + assoc .py=Python.File + +#. Redirect all Python files to the new executable:: + + ftype Python.File=C:\Path\to\pythonw.exe "%1" %* + +.. _launcher: + +Python Launcher for Windows +=========================== + +.. versionadded:: 3.3 + +The Python launcher for Windows is a utility which aids in the location and +execution of different Python versions. It allows scripts (or the +command-line) to indicate a preference for a specific Python version, and +will locate and execute that version. + +Getting started +--------------- + +From the command-line +^^^^^^^^^^^^^^^^^^^^^ + +You should ensure the launcher is on your PATH - depending on how it was +installed it may already be there, but check just in case it is not. + +From a command-prompt, execute the following command: + +:: + + py + +You should find that the latest version of Python 2.x you have installed is +started - it can be exited as normal, and any additional command-line +arguments specified will be sent directly to Python. + +If you have multiple versions of Python 2.x installed (e.g., 2.6 and 2.7) you +will have noticed that Python 2.7 was started - to launch Python 2.6, try the +command: + +:: + + py -2.6 + +If you have a Python 3.x installed, try the command: + +:: + + py -3 + +You should find the latest version of Python 3.x starts. + +From a script +^^^^^^^^^^^^^ + +Let's create a test Python script - create a file called ``hello.py`` with the +following contents + +:: + + #! python + import sys + sys.stdout.write("hello from Python %s\n" % (sys.version,)) + +From the directory in which hello.py lives, execute the command: + +:: + + py hello.py + +You should notice the version number of your latest Python 2.x installation +is printed. Now try changing the first line to be: + +:: + + #! python3 + +Re-executing the command should now print the latest Python 3.x information. +As with the above command-line examples, you can specify a more explicit +version qualifier. Assuming you have Python 2.6 installed, try changing the +first line to ``#! python2.6`` and you should find the 2.6 version +information printed. + +From file associations +^^^^^^^^^^^^^^^^^^^^^^ + +The launcher should have been associated with Python files (i.e. ``.py``, +``.pyw``, ``.pyc``, ``.pyo`` files) when it was installed. This means that +when you double-click on one of these files from Windows explorer the launcher +will be used, and therefore you can use the same facilities described above to +have the script specify the version which should be used. + +The key benefit of this is that a single launcher can support multiple Python +versions at the same time depending on the contents of the first line. + +Shebang Lines +------------- + +If the first line of a script file starts with ``#!``, it is known as a +"shebang" line. Linux and other Unix like operating systems have native +support for such lines and are commonly used on such systems to indicate how +a script should be executed. This launcher allows the same facilities to be +using with Python scripts on Windows and the examples above demonstrate their +use. + +To allow shebang lines in Python scripts to be portable between Unix and +Windows, this launcher supports a number of 'virtual' commands to specify +which interpreter to use. The supported virtual commands are: + +* ``/usr/bin/env python`` +* ``/usr/bin/python`` +* ``/usr/local/bin/python`` +* ``python`` + +For example, if the first line of your script starts with + +:: + + #! /usr/bin/python + +The default Python will be located and used. As many Python scripts written +to work on Unix will already have this line, you should find these scripts can +be used by the launcher without modification. If you are writing a new script +on Windows which you hope will be useful on Unix, you should use one of the +shebang lines starting with ``/usr``. + +Arguments in shebang lines +-------------------------- + +The shebang lines can also specify additional options to be passed to the +Python interpreter. For example, if you have a shebang line: + +:: + + #! /usr/bin/python -v + +Then Python will be started with the ``-v`` option + +Customization +------------- + +Customization via INI files +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Two .ini files will be searched by the launcher - ``py.ini`` in the + current user's "application data" directory (i.e. the directory returned + by calling the Windows function SHGetFolderPath with CSIDL_LOCAL_APPDATA) + and ``py.ini`` in the same directory as the launcher. The same .ini + files are used for both the 'console' version of the launcher (i.e. + py.exe) and for the 'windows' version (i.e. pyw.exe) + + Customization specified in the "application directory" will have + precedence over the one next to the executable, so a user, who may not + have write access to the .ini file next to the launcher, can override + commands in that global .ini file) + +Customizing default Python versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In some cases, a version qualifier can be included in a command to dictate +which version of Python will be used by the command. A version qualifier +starts with a major version number and can optionally be followed by a period +('.') and a minor version specifier. If the minor qualifier is specified, it +may optionally be followed by "-32" to indicate the 32-bit implementation of +that version be used. + +For example, a shebang line of ``#!python`` has no version qualifier, while +``#!python3`` has a version qualifier which specifies only a major version. + +If no version qualifiers are found in a command, the environment variable +``PY_PYTHON`` can be set to specify the default version qualifier - the default +value is "2". Note this value could specify just a major version (e.g. "2") or +a major.minor qualifier (e.g. "2.6"), or even major.minor-32. + +If no minor version qualifiers are found, the environment variable +``PY_PYTHON{major}`` (where ``{major}`` is the current major version qualifier +as determined above) can be set to specify the full version. If no such option +is found, the launcher will enumerate the installed Python versions and use +the latest minor release found for the major version, which is likely, +although not guaranteed, to be the most recently installed version in that +family. + +On 64-bit Windows with both 32-bit and 64-bit implementations of the same +(major.minor) Python version installed, the 64-bit version will always be +preferred. This will be true for both 32-bit and 64-bit implementations of the +launcher - a 32-bit launcher will prefer to execute a 64-bit Python installation +of the specified version if available. This is so the behavior of the launcher +can be predicted knowing only what versions are installed on the PC and +without regard to the order in which they were installed (i.e., without knowing +whether a 32 or 64-bit version of Python and corresponding launcher was +installed last). As noted above, an optional "-32" suffix can be used on a +version specifier to change this behaviour. + +Examples: + +* If no relevant options are set, the commands ``python`` and + ``python2`` will use the latest Python 2.x version installed and + the command ``python3`` will use the latest Python 3.x installed. + +* The commands ``python3.1`` and ``python2.7`` will not consult any + options at all as the versions are fully specified. + +* If ``PY_PYTHON=3``, the commands ``python`` and ``python3`` will both use + the latest installed Python 3 version. + +* If ``PY_PYTHON=3.1-32``, the command ``python`` will use the 32-bit + implementation of 3.1 whereas the command ``python3`` will use the latest + installed Python (PY_PYTHON was not considered at all as a major + version was specified.) + +* If ``PY_PYTHON=3`` and ``PY_PYTHON3=3.1``, the commands + ``python`` and ``python3`` will both use specifically 3.1 + +In addition to environment variables, the same settings can be configured +in the .INI file used by the launcher. The section in the INI file is +called ``[defaults]`` and the key name will be the same as the +environment variables without the leading ``PY_`` prefix (and note that +the key names in the INI file are case insensitive.) The contents of +an environment variable will override things specified in the INI file. + +For example: + +* Setting ``PY_PYTHON=3.1`` is equivalent to the INI file containing: + +:: + + [defaults] + python=3.1 + +* Setting ``PY_PYTHON=3`` and ``PY_PYTHON3=3.1`` is equivalent to the INI file + containing: + +:: + + [defaults] + python=3 + python3=3.1 + +Diagnostics +----------- + +If an environment variable ``PYLAUNCH_DEBUG`` is set (to any value), the +launcher will print diagnostic information to stderr (i.e. to the console). +While this information manages to be simultaneously verbose *and* terse, it +should allow you to see what versions of Python were located, why a +particular version was chosen and the exact command-line used to execute the +target Python. + + +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 +utilities 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 + + +cx_Freeze +--------- + +`cx_Freeze `_ 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 +`_. + +The source tree contains a build solution and project files for Microsoft +Visual C++, which is the compiler used to build the official Python releases. +View the :file:`readme.txt` in their respective directories: + ++--------------------+--------------+-----------------------+ +| Directory | MSVC version | Visual Studio version | ++====================+==============+=======================+ +| :file:`PC/VS9.0/` | 9.0 | 2008 | ++--------------------+--------------+-----------------------+ +| :file:`PCbuild/` | 10.0 | 2010 | ++--------------------+--------------+-----------------------+ + +Note that any build directories within the :file:`PC` directory are not +necessarily fully supported. The :file:`PCbuild` directory contains the files +for the compiler used to build the official release. + +Check :file:`PCbuild/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 + + :pep:`397` - Python launcher for Windows + The proposal for the launcher to be included in the Python distribution. + +