1 :tocdepth: 2 2 3 .. _windows-faq: 4 5 ===================== 6 Python on Windows FAQ 7 ===================== 8 9 .. only:: html 10 11 .. contents:: 12 13 .. XXX need review for Python 3. 14 XXX need review for Windows Vista/Seven? 15 16 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 22 obvious; otherwise, you might need a little more guidance. 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://showmedo.com/videotutorials/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 39 Start menu; under Windows 7 the menu selection is :menuselection:`Start --> 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 49 D:\YourName\Projects\Python> 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 56 program called the Python *interpreter*. The interpreter reads your script, 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 63 return.:: 64 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 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 78 >>> print("Hello") 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 :kbd:`Ctrl` 85 key down while you enter a :kbd:`Z`, then hit the ":kbd:`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 89 --> Programs --> Python 3.3 --> Python (command line)` that results in you 90 seeing the ``>>>`` prompt in a new window. If so, the window will disappear 91 after you enter the :kbd:`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 97 'python' is not recognized as an internal or external command, operable program or batch file. 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/videotutorials/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 126 like ``C:\Python33``. Otherwise you will be reduced to a search of your whole 127 disk ... use :menuselection:`Tools --> Find` or hit the :guilabel:`Search` 128 button and look for "python.exe". Supposing you discover that Python is 129 installed in the ``C:\Python33`` directory (the default at the time of writing), 130 you should make sure that entering the command :: 131 132 c:\Python33\python 133 134 starts up the interpreter as above (and don't forget you'll need a ":kbd:`Ctrl-Z`" and 135 an ":kbd:`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. 139 140 More information about environment variables can be found on the 141 :ref:`Using Python on Windows <setting-envvars>` page. 142 143 How do I make Python scripts executable? 144 ---------------------------------------- 145 146 On Windows, the standard Python installer already associates the .py 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 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 170 How do I make an executable from a Python script? 171 ------------------------------------------------- 172 173 See http://cx-freeze.sourceforge.net/ for a distutils extension that allows you 174 to create console and GUI executables from Python code. 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 179 180 Is a ``*.pyd`` file the same as a DLL? 181 -------------------------------------- 182 183 Yes, .pyd files are dll's, but there are a few differences. If you have a DLL 184 named ``foo.pyd``, then it must have a function ``PyInit_foo()``. You can then 185 write Python "import foo", and Python will search for foo.pyd (as well as 186 foo.py, foo.pyc) and if it finds it, will attempt to call ``PyInit_foo()`` to 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 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 207 number such as "33" for Python 3.3. 208 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 212 so-called "import lib" corresponding to :file:`python{NN}.dll`. It merely 213 defines symbols for the linker.) 214 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 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 225 .. XXX what about static linking? 226 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. 252 PyRun_SimpleString("import myApp"); // Import the shadow class. 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 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 Python raises :exc:`IndentationError` or :exc:`TabError` if mixed tabs 304 and spaces are causing problems in leading whitespace. 305 You may also run the :mod:`tabnanny` module to check a directory tree 306 in batch mode. 307 308 309 How do I check for a keypress without blocking? 310 ----------------------------------------------- 311 312 Use the msvcrt module. This is a standard Windows-specific extension module. 313 It defines a function ``kbhit()`` which checks whether a keyboard hit is 314 present, and ``getch()`` which gets one character without echoing it. 315 316 317 How do I emulate os.kill() in Windows? 318 -------------------------------------- 319 320 Prior to Python 2.7 and 3.2, to terminate a process, you can use :mod:`ctypes`:: 321 322 import ctypes 323 324 def kill(pid): 325 """kill function for Win32""" 326 kernel32 = ctypes.windll.kernel32 327 handle = kernel32.OpenProcess(1, 0, pid) 328 return (0 != kernel32.TerminateProcess(handle, 0)) 329 330 In 2.7 and 3.2, :func:`os.kill` is implemented similar to the above function, 331 with the additional feature of being able to send :kbd:`Ctrl+C` and :kbd:`Ctrl+Break` 332 to console subprocesses which are designed to handle those signals. See 333 :func:`os.kill` for further details. 334 335 How do I extract the downloaded documentation on Windows? 336 --------------------------------------------------------- 337 338 Sometimes, when you download the documentation package to a Windows machine 339 using a web browser, the file extension of the saved file ends up being .EXE. 340 This is a mistake; the extension should be .TGZ. 341 342 Simply rename the downloaded file to have the .TGZ extension, and WinZip will be 343 able to handle it. (If your copy of WinZip doesn't, get a newer one from 344 https://www.winzip.com.) 345 346