1 :tocdepth: 2 2 3 .. highlightlang:: none 4 5 .. _windows-faq: 6 7 ===================== 8 Python on Windows FAQ 9 ===================== 10 11 .. only:: html 12 13 .. contents:: 14 15 .. XXX need review for Python 3. 16 XXX need review for Windows Vista/Seven? 17 18 19 How do I run a Python program under Windows? 20 -------------------------------------------- 21 22 This is not necessarily a straightforward question. If you are already familiar 23 with running programs from the Windows command line then everything will seem 24 obvious; otherwise, you might need a little more guidance. 25 26 Unless you use some sort of integrated development environment, you will end up 27 *typing* Windows commands into what is variously referred to as a "DOS window" 28 or "Command prompt window". Usually you can create such a window from your 29 search bar by searching for ``cmd``. You should be able to recognize 30 when you have started such a window because you will see a Windows "command 31 prompt", which usually looks like this: 32 33 .. code-block:: doscon 34 35 C:\> 36 37 The letter may be different, and there might be other things after it, so you 38 might just as easily see something like: 39 40 .. code-block:: doscon 41 42 D:\YourName\Projects\Python> 43 44 depending on how your computer has been set up and what else you have recently 45 done with it. Once you have started such a window, you are well on the way to 46 running Python programs. 47 48 You need to realize that your Python scripts have to be processed by another 49 program called the Python *interpreter*. The interpreter reads your script, 50 compiles it into bytecodes, and then executes the bytecodes to run your 51 program. So, how do you arrange for the interpreter to handle your Python? 52 53 First, you need to make sure that your command window recognises the word 54 "py" as an instruction to start the interpreter. If you have opened a 55 command window, you should try entering the command ``py`` and hitting 56 return: 57 58 .. code-block:: doscon 59 60 C:\Users\YourName> py 61 62 You should then see something like: 63 64 .. code-block:: pycon 65 66 Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit (Intel)] on win32 67 Type "help", "copyright", "credits" or "license" for more information. 68 >>> 69 70 You have started the interpreter in "interactive mode". That means you can enter 71 Python statements or expressions interactively and have them executed or 72 evaluated while you wait. This is one of Python's strongest features. Check it 73 by entering a few expressions of your choice and seeing the results: 74 75 .. code-block:: pycon 76 77 >>> print("Hello") 78 Hello 79 >>> "Hello" * 3 80 'HelloHelloHello' 81 82 Many people use the interactive mode as a convenient yet highly programmable 83 calculator. When you want to end your interactive Python session, 84 call the :func:`exit` function or hold the :kbd:`Ctrl` key down 85 while you enter a :kbd:`Z`, then hit the ":kbd:`Enter`" key to get 86 back to your Windows command prompt. 87 88 You may also find that you have a Start-menu entry such as :menuselection:`Start 89 --> Programs --> Python 3.x --> Python (command line)` that results in you 90 seeing the ``>>>`` prompt in a new window. If so, the window will disappear 91 after you call the :func:`exit` function or enter the :kbd:`Ctrl-Z` 92 character; Windows is running a single "python" 93 command in the window, and closes it when you terminate the interpreter. 94 95 Now that we know the ``py`` command is recognized, you can give your 96 Python script to it. You'll have to give either an absolute or a 97 relative path to the Python script. Let's say your Python script is 98 located in your desktop and is named ``hello.py``, and your command 99 prompt is nicely opened in your home directory so you're seeing something 100 similar to:: 101 102 C:\Users\YourName> 103 104 So now you'll ask the ``py`` command to give your script to Python by 105 typing ``py`` followed by your script path:: 106 107 108 C:\Users\YourName> py Desktop\hello.py 109 hello 110 111 How do I make Python scripts executable? 112 ---------------------------------------- 113 114 On Windows, the standard Python installer already associates the .py 115 extension with a file type (Python.File) and gives that file type an open 116 command that runs the interpreter (``D:\Program Files\Python\python.exe "%1" 117 %*``). This is enough to make scripts executable from the command prompt as 118 'foo.py'. If you'd rather be able to execute the script by simple typing 'foo' 119 with no extension you need to add .py to the PATHEXT environment variable. 120 121 Why does Python sometimes take so long to start? 122 ------------------------------------------------ 123 124 Usually Python starts very quickly on Windows, but occasionally there are bug 125 reports that Python suddenly begins to take a long time to start up. This is 126 made even more puzzling because Python will work fine on other Windows systems 127 which appear to be configured identically. 128 129 The problem may be caused by a misconfiguration of virus checking software on 130 the problem machine. Some virus scanners have been known to introduce startup 131 overhead of two orders of magnitude when the scanner is configured to monitor 132 all reads from the filesystem. Try checking the configuration of virus scanning 133 software on your systems to ensure that they are indeed configured identically. 134 McAfee, when configured to scan all file system read activity, is a particular 135 offender. 136 137 138 How do I make an executable from a Python script? 139 ------------------------------------------------- 140 141 See `cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_ for a distutils extension 142 that allows you to create console and GUI executables from Python code. 143 `py2exe <http://www.py2exe.org/>`_, the most popular extension for building 144 Python 2.x-based executables, does not yet support Python 3 but a version that 145 does is in development. 146 147 148 Is a ``*.pyd`` file the same as a DLL? 149 -------------------------------------- 150 151 Yes, .pyd files are dll's, but there are a few differences. If you have a DLL 152 named ``foo.pyd``, then it must have a function ``PyInit_foo()``. You can then 153 write Python "import foo", and Python will search for foo.pyd (as well as 154 foo.py, foo.pyc) and if it finds it, will attempt to call ``PyInit_foo()`` to 155 initialize it. You do not link your .exe with foo.lib, as that would cause 156 Windows to require the DLL to be present. 157 158 Note that the search path for foo.pyd is PYTHONPATH, not the same as the path 159 that Windows uses to search for foo.dll. Also, foo.pyd need not be present to 160 run your program, whereas if you linked your program with a dll, the dll is 161 required. Of course, foo.pyd is required if you want to say ``import foo``. In 162 a DLL, linkage is declared in the source code with ``__declspec(dllexport)``. 163 In a .pyd, linkage is defined in a list of available functions. 164 165 166 How can I embed Python into a Windows application? 167 -------------------------------------------------- 168 169 Embedding the Python interpreter in a Windows app can be summarized as follows: 170 171 1. Do _not_ build Python into your .exe file directly. On Windows, Python must 172 be a DLL to handle importing modules that are themselves DLL's. (This is the 173 first key undocumented fact.) Instead, link to :file:`python{NN}.dll`; it is 174 typically installed in ``C:\Windows\System``. *NN* is the Python version, a 175 number such as "33" for Python 3.3. 176 177 You can link to Python in two different ways. Load-time linking means 178 linking against :file:`python{NN}.lib`, while run-time linking means linking 179 against :file:`python{NN}.dll`. (General note: :file:`python{NN}.lib` is the 180 so-called "import lib" corresponding to :file:`python{NN}.dll`. It merely 181 defines symbols for the linker.) 182 183 Run-time linking greatly simplifies link options; everything happens at run 184 time. Your code must load :file:`python{NN}.dll` using the Windows 185 ``LoadLibraryEx()`` routine. The code must also use access routines and data 186 in :file:`python{NN}.dll` (that is, Python's C API's) using pointers obtained 187 by the Windows ``GetProcAddress()`` routine. Macros can make using these 188 pointers transparent to any C code that calls routines in Python's C API. 189 190 Borland note: convert :file:`python{NN}.lib` to OMF format using Coff2Omf.exe 191 first. 192 193 .. XXX what about static linking? 194 195 2. If you use SWIG, it is easy to create a Python "extension module" that will 196 make the app's data and methods available to Python. SWIG will handle just 197 about all the grungy details for you. The result is C code that you link 198 *into* your .exe file (!) You do _not_ have to create a DLL file, and this 199 also simplifies linking. 200 201 3. SWIG will create an init function (a C function) whose name depends on the 202 name of the extension module. For example, if the name of the module is leo, 203 the init function will be called initleo(). If you use SWIG shadow classes, 204 as you should, the init function will be called initleoc(). This initializes 205 a mostly hidden helper class used by the shadow class. 206 207 The reason you can link the C code in step 2 into your .exe file is that 208 calling the initialization function is equivalent to importing the module 209 into Python! (This is the second key undocumented fact.) 210 211 4. In short, you can use the following code to initialize the Python interpreter 212 with your extension module. 213 214 .. code-block:: c 215 216 #include "python.h" 217 ... 218 Py_Initialize(); // Initialize Python. 219 initmyAppc(); // Initialize (import) the helper class. 220 PyRun_SimpleString("import myApp"); // Import the shadow class. 221 222 5. There are two problems with Python's C API which will become apparent if you 223 use a compiler other than MSVC, the compiler used to build pythonNN.dll. 224 225 Problem 1: The so-called "Very High Level" functions that take FILE * 226 arguments will not work in a multi-compiler environment because each 227 compiler's notion of a struct FILE will be different. From an implementation 228 standpoint these are very _low_ level functions. 229 230 Problem 2: SWIG generates the following code when generating wrappers to void 231 functions: 232 233 .. code-block:: c 234 235 Py_INCREF(Py_None); 236 _resultobj = Py_None; 237 return _resultobj; 238 239 Alas, Py_None is a macro that expands to a reference to a complex data 240 structure called _Py_NoneStruct inside pythonNN.dll. Again, this code will 241 fail in a mult-compiler environment. Replace such code by: 242 243 .. code-block:: c 244 245 return Py_BuildValue(""); 246 247 It may be possible to use SWIG's ``%typemap`` command to make the change 248 automatically, though I have not been able to get this to work (I'm a 249 complete SWIG newbie). 250 251 6. Using a Python shell script to put up a Python interpreter window from inside 252 your Windows app is not a good idea; the resulting window will be independent 253 of your app's windowing system. Rather, you (or the wxPythonWindow class) 254 should create a "native" interpreter window. It is easy to connect that 255 window to the Python interpreter. You can redirect Python's i/o to _any_ 256 object that supports read and write, so all you need is a Python object 257 (defined in your extension module) that contains read() and write() methods. 258 259 How do I keep editors from inserting tabs into my Python source? 260 ---------------------------------------------------------------- 261 262 The FAQ does not recommend using tabs, and the Python style guide, :pep:`8`, 263 recommends 4 spaces for distributed Python code; this is also the Emacs 264 python-mode default. 265 266 Under any editor, mixing tabs and spaces is a bad idea. MSVC is no different in 267 this respect, and is easily configured to use spaces: Take :menuselection:`Tools 268 --> Options --> Tabs`, and for file type "Default" set "Tab size" and "Indent 269 size" to 4, and select the "Insert spaces" radio button. 270 271 Python raises :exc:`IndentationError` or :exc:`TabError` if mixed tabs 272 and spaces are causing problems in leading whitespace. 273 You may also run the :mod:`tabnanny` module to check a directory tree 274 in batch mode. 275 276 277 How do I check for a keypress without blocking? 278 ----------------------------------------------- 279 280 Use the msvcrt module. This is a standard Windows-specific extension module. 281 It defines a function ``kbhit()`` which checks whether a keyboard hit is 282 present, and ``getch()`` which gets one character without echoing it. 283
