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