Debian Codegraph @

Doc/faq/windows.rst

raw
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.