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