Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 1 | :tocdepth: 2 |
| 2 | |
| 3 | .. _windows-faq: |
| 4 | |
| 5 | ===================== |
| 6 | Python on Windows FAQ |
| 7 | ===================== |
| 8 | |
Georg Brandl | 44ea77b | 2013-03-28 13:28:44 +0100 | [diff] [blame] | 9 | .. only:: html |
| 10 | |
| 11 | .. contents:: |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 12 | |
Georg Brandl | 62423cb | 2009-12-19 17:59:59 +0000 | [diff] [blame] | 13 | .. XXX need review for Python 3. |
| 14 | XXX need review for Windows Vista/Seven? |
| 15 | |
| 16 | |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 17 | How do I run a Python program under Windows? |
| 18 | -------------------------------------------- |
| 19 | |
| 20 | This is not necessarily a straightforward question. If you are already familiar |
| 21 | with running programs from the Windows command line then everything will seem |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 22 | obvious; otherwise, you might need a little more guidance. |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 23 | |
| 24 | .. sidebar:: |Python Development on XP|_ |
| 25 | :subtitle: `Python Development on XP`_ |
| 26 | |
| 27 | This series of screencasts aims to get you up and running with Python on |
| 28 | Windows XP. The knowledge is distilled into 1.5 hours and will get you up |
| 29 | and running with the right Python distribution, coding in your choice of IDE, |
| 30 | and debugging and writing solid code with unit-tests. |
| 31 | |
| 32 | .. |Python Development on XP| image:: python-video-icon.png |
| 33 | .. _`Python Development on XP`: |
| 34 | http://www.showmedo.com/videos/series?name=pythonOzsvaldPyNewbieSeries |
| 35 | |
| 36 | Unless you use some sort of integrated development environment, you will end up |
| 37 | *typing* Windows commands into what is variously referred to as a "DOS window" |
| 38 | or "Command prompt window". Usually you can create such a window from your |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 39 | Start menu; under Windows 7 the menu selection is :menuselection:`Start --> |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 40 | Programs --> Accessories --> Command Prompt`. You should be able to recognize |
| 41 | when you have started such a window because you will see a Windows "command |
| 42 | prompt", which usually looks like this:: |
| 43 | |
| 44 | C:\> |
| 45 | |
| 46 | The letter may be different, and there might be other things after it, so you |
| 47 | might just as easily see something like:: |
| 48 | |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 49 | D:\YourName\Projects\Python> |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 50 | |
| 51 | depending on how your computer has been set up and what else you have recently |
| 52 | done with it. Once you have started such a window, you are well on the way to |
| 53 | running Python programs. |
| 54 | |
| 55 | You need to realize that your Python scripts have to be processed by another |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 56 | program called the Python *interpreter*. The interpreter reads your script, |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 57 | compiles it into bytecodes, and then executes the bytecodes to run your |
| 58 | program. So, how do you arrange for the interpreter to handle your Python? |
| 59 | |
| 60 | First, you need to make sure that your command window recognises the word |
| 61 | "python" as an instruction to start the interpreter. If you have opened a |
| 62 | command window, you should try entering the command ``python`` and hitting |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 63 | return.:: |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 64 | |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 65 | C:\Users\YourName> python |
| 66 | |
| 67 | You should then see something like:: |
| 68 | |
| 69 | Python 3.3.0 (v3.3.0:bd8afb90ebf2, Sep 29 2012, 10:55:48) [MSC v.1600 32 bit (Intel)] on win32 |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 70 | Type "help", "copyright", "credits" or "license" for more information. |
| 71 | >>> |
| 72 | |
| 73 | You have started the interpreter in "interactive mode". That means you can enter |
| 74 | Python statements or expressions interactively and have them executed or |
| 75 | evaluated while you wait. This is one of Python's strongest features. Check it |
| 76 | by entering a few expressions of your choice and seeing the results:: |
| 77 | |
Georg Brandl | 62423cb | 2009-12-19 17:59:59 +0000 | [diff] [blame] | 78 | >>> print("Hello") |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 79 | Hello |
| 80 | >>> "Hello" * 3 |
| 81 | HelloHelloHello |
| 82 | |
| 83 | Many people use the interactive mode as a convenient yet highly programmable |
| 84 | calculator. When you want to end your interactive Python session, hold the Ctrl |
| 85 | key down while you enter a Z, then hit the "Enter" key to get back to your |
| 86 | Windows command prompt. |
| 87 | |
| 88 | You may also find that you have a Start-menu entry such as :menuselection:`Start |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 89 | --> Programs --> Python 3.3 --> Python (command line)` that results in you |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 90 | seeing the ``>>>`` prompt in a new window. If so, the window will disappear |
| 91 | after you enter the Ctrl-Z character; Windows is running a single "python" |
| 92 | command in the window, and closes it when you terminate the interpreter. |
| 93 | |
| 94 | If the ``python`` command, instead of displaying the interpreter prompt ``>>>``, |
| 95 | gives you a message like:: |
| 96 | |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 97 | 'python' is not recognized as an internal or external command, operable program or batch file. |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 98 | |
| 99 | .. sidebar:: |Adding Python to DOS Path|_ |
| 100 | :subtitle: `Adding Python to DOS Path`_ |
| 101 | |
| 102 | Python is not added to the DOS path by default. This screencast will walk |
| 103 | you through the steps to add the correct entry to the `System Path`, allowing |
| 104 | Python to be executed from the command-line by all users. |
| 105 | |
| 106 | .. |Adding Python to DOS Path| image:: python-video-icon.png |
| 107 | .. _`Adding Python to DOS Path`: |
| 108 | http://showmedo.com/videos/video?name=960000&fromSeriesID=96 |
| 109 | |
| 110 | |
| 111 | or:: |
| 112 | |
| 113 | Bad command or filename |
| 114 | |
| 115 | then you need to make sure that your computer knows where to find the Python |
| 116 | interpreter. To do this you will have to modify a setting called PATH, which is |
| 117 | a list of directories where Windows will look for programs. |
| 118 | |
| 119 | You should arrange for Python's installation directory to be added to the PATH |
| 120 | of every command window as it starts. If you installed Python fairly recently |
| 121 | then the command :: |
| 122 | |
| 123 | dir C:\py* |
| 124 | |
| 125 | will probably tell you where it is installed; the usual location is something |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 126 | like ``C:\Python33``. Otherwise you will be reduced to a search of your whole |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 127 | disk ... use :menuselection:`Tools --> Find` or hit the :guilabel:`Search` |
| 128 | button and look for "python.exe". Supposing you discover that Python is |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 129 | installed in the ``C:\Python33`` directory (the default at the time of writing), |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 130 | you should make sure that entering the command :: |
| 131 | |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 132 | c:\Python33\python |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 133 | |
| 134 | starts up the interpreter as above (and don't forget you'll need a "CTRL-Z" and |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 135 | an "Enter" to get out of it). Once you have verified the directory, you can |
| 136 | add it to the system path to make it easier to start Python by just running |
| 137 | the ``python`` command. This is currently an option in the installer as of |
| 138 | CPython 3.3. |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 139 | |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 140 | More information about environment variables can be found on the |
| 141 | :ref:`Using Python on Windows <setting-envvars>` page. |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 142 | |
Ezio Melotti | 0639d5a | 2009-12-19 23:26:38 +0000 | [diff] [blame] | 143 | How do I make Python scripts executable? |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 144 | ---------------------------------------- |
| 145 | |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 146 | On Windows, the standard Python installer already associates the .py |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 147 | extension with a file type (Python.File) and gives that file type an open |
| 148 | command that runs the interpreter (``D:\Program Files\Python\python.exe "%1" |
| 149 | %*``). This is enough to make scripts executable from the command prompt as |
| 150 | 'foo.py'. If you'd rather be able to execute the script by simple typing 'foo' |
| 151 | with no extension you need to add .py to the PATHEXT environment variable. |
| 152 | |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 153 | Why does Python sometimes take so long to start? |
| 154 | ------------------------------------------------ |
| 155 | |
| 156 | Usually Python starts very quickly on Windows, but occasionally there are bug |
| 157 | reports that Python suddenly begins to take a long time to start up. This is |
| 158 | made even more puzzling because Python will work fine on other Windows systems |
| 159 | which appear to be configured identically. |
| 160 | |
| 161 | The problem may be caused by a misconfiguration of virus checking software on |
| 162 | the problem machine. Some virus scanners have been known to introduce startup |
| 163 | overhead of two orders of magnitude when the scanner is configured to monitor |
| 164 | all reads from the filesystem. Try checking the configuration of virus scanning |
| 165 | software on your systems to ensure that they are indeed configured identically. |
| 166 | McAfee, when configured to scan all file system read activity, is a particular |
| 167 | offender. |
| 168 | |
| 169 | |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 170 | How do I make an executable from a Python script? |
| 171 | ------------------------------------------------- |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 172 | |
Zachary Ware | 9fc0e99 | 2014-01-17 08:59:44 -0600 | [diff] [blame] | 173 | See http://cx-freeze.sourceforge.net/ for a distutils extension that allows you |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 174 | to create console and GUI executables from Python code. |
Zachary Ware | 9fc0e99 | 2014-01-17 08:59:44 -0600 | [diff] [blame] | 175 | `py2exe <http://www.py2exe.org/>`_, the most popular extension for building |
| 176 | Python 2.x-based executables, does not yet support Python 3 but a version that |
| 177 | does is in development. |
| 178 | |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 179 | |
| 180 | Is a ``*.pyd`` file the same as a DLL? |
| 181 | -------------------------------------- |
| 182 | |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 183 | Yes, .pyd files are dll's, but there are a few differences. If you have a DLL |
Zachary Ware | 9fc0e99 | 2014-01-17 08:59:44 -0600 | [diff] [blame] | 184 | named ``foo.pyd``, then it must have a function ``PyInit_foo()``. You can then |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 185 | write Python "import foo", and Python will search for foo.pyd (as well as |
Zachary Ware | 9fc0e99 | 2014-01-17 08:59:44 -0600 | [diff] [blame] | 186 | foo.py, foo.pyc) and if it finds it, will attempt to call ``PyInit_foo()`` to |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 187 | initialize it. You do not link your .exe with foo.lib, as that would cause |
| 188 | Windows to require the DLL to be present. |
| 189 | |
| 190 | Note that the search path for foo.pyd is PYTHONPATH, not the same as the path |
| 191 | that Windows uses to search for foo.dll. Also, foo.pyd need not be present to |
| 192 | run your program, whereas if you linked your program with a dll, the dll is |
| 193 | required. Of course, foo.pyd is required if you want to say ``import foo``. In |
| 194 | a DLL, linkage is declared in the source code with ``__declspec(dllexport)``. |
| 195 | In a .pyd, linkage is defined in a list of available functions. |
| 196 | |
| 197 | |
| 198 | How can I embed Python into a Windows application? |
| 199 | -------------------------------------------------- |
| 200 | |
| 201 | Embedding the Python interpreter in a Windows app can be summarized as follows: |
| 202 | |
| 203 | 1. Do _not_ build Python into your .exe file directly. On Windows, Python must |
| 204 | be a DLL to handle importing modules that are themselves DLL's. (This is the |
Georg Brandl | 4985ff2 | 2010-10-17 10:14:38 +0000 | [diff] [blame] | 205 | first key undocumented fact.) Instead, link to :file:`python{NN}.dll`; it is |
| 206 | typically installed in ``C:\Windows\System``. *NN* is the Python version, a |
Brian Curtin | 655b0c4 | 2012-12-16 23:58:09 -0600 | [diff] [blame] | 207 | number such as "33" for Python 3.3. |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 208 | |
Georg Brandl | 4985ff2 | 2010-10-17 10:14:38 +0000 | [diff] [blame] | 209 | You can link to Python in two different ways. Load-time linking means |
| 210 | linking against :file:`python{NN}.lib`, while run-time linking means linking |
| 211 | against :file:`python{NN}.dll`. (General note: :file:`python{NN}.lib` is the |
Georg Brandl | fc9794a | 2010-10-17 10:15:50 +0000 | [diff] [blame] | 212 | so-called "import lib" corresponding to :file:`python{NN}.dll`. It merely |
Georg Brandl | 4985ff2 | 2010-10-17 10:14:38 +0000 | [diff] [blame] | 213 | defines symbols for the linker.) |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 214 | |
Georg Brandl | 4985ff2 | 2010-10-17 10:14:38 +0000 | [diff] [blame] | 215 | Run-time linking greatly simplifies link options; everything happens at run |
| 216 | time. Your code must load :file:`python{NN}.dll` using the Windows |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 217 | ``LoadLibraryEx()`` routine. The code must also use access routines and data |
| 218 | in :file:`python{NN}.dll` (that is, Python's C API's) using pointers obtained |
| 219 | by the Windows ``GetProcAddress()`` routine. Macros can make using these |
| 220 | pointers transparent to any C code that calls routines in Python's C API. |
| 221 | |
| 222 | Borland note: convert :file:`python{NN}.lib` to OMF format using Coff2Omf.exe |
| 223 | first. |
| 224 | |
Georg Brandl | 4985ff2 | 2010-10-17 10:14:38 +0000 | [diff] [blame] | 225 | .. XXX what about static linking? |
| 226 | |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 227 | 2. If you use SWIG, it is easy to create a Python "extension module" that will |
| 228 | make the app's data and methods available to Python. SWIG will handle just |
| 229 | about all the grungy details for you. The result is C code that you link |
| 230 | *into* your .exe file (!) You do _not_ have to create a DLL file, and this |
| 231 | also simplifies linking. |
| 232 | |
| 233 | 3. SWIG will create an init function (a C function) whose name depends on the |
| 234 | name of the extension module. For example, if the name of the module is leo, |
| 235 | the init function will be called initleo(). If you use SWIG shadow classes, |
| 236 | as you should, the init function will be called initleoc(). This initializes |
| 237 | a mostly hidden helper class used by the shadow class. |
| 238 | |
| 239 | The reason you can link the C code in step 2 into your .exe file is that |
| 240 | calling the initialization function is equivalent to importing the module |
| 241 | into Python! (This is the second key undocumented fact.) |
| 242 | |
| 243 | 4. In short, you can use the following code to initialize the Python interpreter |
| 244 | with your extension module. |
| 245 | |
| 246 | .. code-block:: c |
| 247 | |
| 248 | #include "python.h" |
| 249 | ... |
| 250 | Py_Initialize(); // Initialize Python. |
| 251 | initmyAppc(); // Initialize (import) the helper class. |
Serhiy Storchaka | f47036c | 2013-12-24 11:04:36 +0200 | [diff] [blame] | 252 | PyRun_SimpleString("import myApp"); // Import the shadow class. |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 253 | |
| 254 | 5. There are two problems with Python's C API which will become apparent if you |
| 255 | use a compiler other than MSVC, the compiler used to build pythonNN.dll. |
| 256 | |
| 257 | Problem 1: The so-called "Very High Level" functions that take FILE * |
| 258 | arguments will not work in a multi-compiler environment because each |
| 259 | compiler's notion of a struct FILE will be different. From an implementation |
| 260 | standpoint these are very _low_ level functions. |
| 261 | |
| 262 | Problem 2: SWIG generates the following code when generating wrappers to void |
| 263 | functions: |
| 264 | |
| 265 | .. code-block:: c |
| 266 | |
| 267 | Py_INCREF(Py_None); |
| 268 | _resultobj = Py_None; |
| 269 | return _resultobj; |
| 270 | |
| 271 | Alas, Py_None is a macro that expands to a reference to a complex data |
| 272 | structure called _Py_NoneStruct inside pythonNN.dll. Again, this code will |
| 273 | fail in a mult-compiler environment. Replace such code by: |
| 274 | |
| 275 | .. code-block:: c |
| 276 | |
| 277 | return Py_BuildValue(""); |
| 278 | |
| 279 | It may be possible to use SWIG's ``%typemap`` command to make the change |
| 280 | automatically, though I have not been able to get this to work (I'm a |
| 281 | complete SWIG newbie). |
| 282 | |
| 283 | 6. Using a Python shell script to put up a Python interpreter window from inside |
| 284 | your Windows app is not a good idea; the resulting window will be independent |
| 285 | of your app's windowing system. Rather, you (or the wxPythonWindow class) |
| 286 | should create a "native" interpreter window. It is easy to connect that |
| 287 | window to the Python interpreter. You can redirect Python's i/o to _any_ |
| 288 | object that supports read and write, so all you need is a Python object |
| 289 | (defined in your extension module) that contains read() and write() methods. |
| 290 | |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 291 | How do I keep editors from inserting tabs into my Python source? |
| 292 | ---------------------------------------------------------------- |
| 293 | |
| 294 | The FAQ does not recommend using tabs, and the Python style guide, :pep:`8`, |
| 295 | recommends 4 spaces for distributed Python code; this is also the Emacs |
| 296 | python-mode default. |
| 297 | |
| 298 | Under any editor, mixing tabs and spaces is a bad idea. MSVC is no different in |
| 299 | this respect, and is easily configured to use spaces: Take :menuselection:`Tools |
| 300 | --> Options --> Tabs`, and for file type "Default" set "Tab size" and "Indent |
| 301 | size" to 4, and select the "Insert spaces" radio button. |
| 302 | |
| 303 | If you suspect mixed tabs and spaces are causing problems in leading whitespace, |
| 304 | run Python with the :option:`-t` switch or run ``Tools/Scripts/tabnanny.py`` to |
| 305 | check a directory tree in batch mode. |
| 306 | |
| 307 | |
| 308 | How do I check for a keypress without blocking? |
| 309 | ----------------------------------------------- |
| 310 | |
| 311 | Use the msvcrt module. This is a standard Windows-specific extension module. |
| 312 | It defines a function ``kbhit()`` which checks whether a keyboard hit is |
| 313 | present, and ``getch()`` which gets one character without echoing it. |
| 314 | |
| 315 | |
| 316 | How do I emulate os.kill() in Windows? |
| 317 | -------------------------------------- |
| 318 | |
Brian Curtin | f4ed206 | 2010-04-12 18:10:10 +0000 | [diff] [blame] | 319 | Prior to Python 2.7 and 3.2, to terminate a process, you can use :mod:`ctypes`:: |
Georg Brandl | ff24c8e | 2010-03-21 09:52:24 +0000 | [diff] [blame] | 320 | |
| 321 | import ctypes |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 322 | |
| 323 | def kill(pid): |
| 324 | """kill function for Win32""" |
Georg Brandl | ff24c8e | 2010-03-21 09:52:24 +0000 | [diff] [blame] | 325 | kernel32 = ctypes.windll.kernel32 |
| 326 | handle = kernel32.OpenProcess(1, 0, pid) |
| 327 | return (0 != kernel32.TerminateProcess(handle, 0)) |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 328 | |
Brian Curtin | f4ed206 | 2010-04-12 18:10:10 +0000 | [diff] [blame] | 329 | In 2.7 and 3.2, :func:`os.kill` is implemented similar to the above function, |
| 330 | with the additional feature of being able to send CTRL+C and CTRL+BREAK |
| 331 | to console subprocesses which are designed to handle those signals. See |
| 332 | :func:`os.kill` for further details. |
| 333 | |
Georg Brandl | d741315 | 2009-10-11 21:25:26 +0000 | [diff] [blame] | 334 | How do I extract the downloaded documentation on Windows? |
| 335 | --------------------------------------------------------- |
| 336 | |
| 337 | Sometimes, when you download the documentation package to a Windows machine |
| 338 | using a web browser, the file extension of the saved file ends up being .EXE. |
| 339 | This is a mistake; the extension should be .TGZ. |
| 340 | |
| 341 | Simply rename the downloaded file to have the .TGZ extension, and WinZip will be |
| 342 | able to handle it. (If your copy of WinZip doesn't, get a newer one from |
| 343 | http://www.winzip.com.) |
| 344 | |