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