-
Notifications
You must be signed in to change notification settings - Fork 173
/
pre-requisite-installations.asciidoc
503 lines (369 loc) · 18.7 KB
/
pre-requisite-installations.asciidoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
[[pre-requisites]]
[preface]
== Prerequisites and Assumptions
((("prerequisite knowledge", id="prereq00")))
((("Test-Driven Development (TDD)", "prerequisite knowledge assumed", id="TDDprereq00")))
Here's an outline of what I'm assuming about you and what you already know,
as well as what software you'll need ready and installed on your computer.
=== Python 3 and Programming
((("Python 3", "introductory books on")))
I've tried to write this book with beginners in mind,
but if you're new to programming, I'm assuming that you've already learned the basics of Python.
So if you haven't already, do run through a Python beginner's tutorial
or get an introductory book like https://www.manning.com/books/the-quick-python-book-third-edition[_The Quick Python Book_]
or https://greenteapress.com/thinkpython/html/index.html[_Think Python_],
or, just for fun, https://inventwithpython.com/#invent[_Invent Your Own Computer Games with Python_],
all of which are excellent introductions.
If you're an experienced programmer but new to Python, you should get along just fine.
Python is joyously simple to understand.
You should be able to follow this book on Mac, Windows, or Linux.
Detailed installation instructions for each OS follow.
TIP: This book was tested against Python 3.12.
If you're on an earlier version, you will find minor differences
in the way things look in my command output listings
(tracebacks won't have the `^^^^^^` carets marking error locations for example)
so you're best off upgrading, ideally, if you can.
// TODO a tip about installing multiple python 3 versions?
// CSANAD: Yes! I use PyEnv, and it has a PyEnv-win fork for Windows.
// Important to note the installation docs aren't complete: on Linux, for PyEnv to work, we have to install
// the optional Python modules' package dependencies:
// https://devguide.python.org/getting-started/setup-building/index.html#install-dependencies
//
// after that, we can just `pyenv install 3.12`, then navigate to the project directory, and then
// enter `pyenv local 3.12`. Then reopen the terminal, navigate back to the project directory, and the python version
// should be 3.12 now.
// I was unable to test it under Windows or Mac.
// SEBASTIAN: I second the idea of mentioning multiple Python installs
// TODO: remove this note and its appendix?
// SEBASTIAN: I meant to advice to remove this note, but I see the 'TODO' comment was already there :)
// I'm not sure if PythonAnywhere is recognizable anymore among beginners.
((("PythonAnywhere")))
If you are thinking of using http://www.pythonanywhere.com[PythonAnywhere]
rather than a locally installed Python,
you should go and take a quick look at <<appendix1>> before you get started.
In any case, I expect you to have access to Python,
to know how to launch it from a command line,
and to know how to edit a Python file and run it.
Again, have a look at the three books I recommended previously if you're in any doubt.
=== How HTML Works
((("HTML", "tutorials")))I'm
also assuming you have a basic grasp of how the web works--what HTML is,
what a POST request is, and so on. If you're not sure about those, you'll need to
find a basic HTML tutorial; there are a few at http://www.webplatform.org/. If
you can figure out how to create an HTML page on your PC and look at it in your
browser, and understand what a form is and how it might work, then you're
probably OK.
=== Django
((("Django framework", "tutorials")))The
book uses the Django framework, which is (probably) the most well-established web framework
in the Python world.
I've written the book assuming that the reader has no prior knowledge of Django,
but if you're new to Python _and_ new to web development _and_ new to testing,
you may occasionally find that there's just one too many topics and sets of concepts
to try and take on board.
If that's the case, I recommend taking a break from the book,
and taking a look at a Django tutorial.
https://tutorial.djangogirls.org/[DjangoGirls] is the best, most beginner-friendly tutorial I know of.
The https://docs.djangoproject.com/en/4.2/intro/tutorial01/[official tutorial]
is also excellent for more experienced programmers.
=== JavaScript
There's a little bit of JavaScript in the second half of the book. If you
don't know JavaScript, don't worry about it until then, and if you find
yourself a little confused, I'll recommend a couple of guides at that point.
Read on for installation instructions.
=== Required Software Installations
((("software requirements", id="soft00")))
Aside from Python, you'll need:
The Firefox web browser::
Selenium can actually drive any of the major browsers,
but I chose Firefox because it's the least in hock to corporate interests.
((("Firefox", "benefits of")))
The Git version control system::
This is available for any platform, at http://git-scm.com/.
On Windows, it comes with the _Bash_ command line, which is needed for the book.
See <<windows-notes>>.
((("Git", "downloading")))
A virtualenv with Python 3.12, Django 4.2, and Selenium 4 in it::
Python's virtualenv and pip tools now come bundled with Python (they
didn't always used to, so this is a big hooray). Detailed instructions for
preparing your virtualenv follow.
[role="pagebreak-before less_space"]
[[windows-notes]]
.Windows Notes
*******************************************************************************
((("Windows", "tips")))
((("Python 3", "installation and setup", "Windows installation")))
Windows users can sometimes feel a little neglected in the open source world,
since MacOS and Linux are so prevalent,
making it easy to forget there's a world outside the Unix paradigm.
Backslashes as directory separators? Drive letters? What?
Still, it is absolutely possible to follow along with this book on Windows.
Here are a few tips:
1. When you install Git for Windows, it will include "Git Bash".
Use this as your main command prompt throughout the book,
and you'll get all the useful GNU command-line tools
like `ls`, `touch`, and `grep`, plus forward-slash directory separators.
2. During the Git installation,
you'll get the option to choose the **default editor used by Git**.
Unless you're already a Vim user (or are desperate to learn),
I'd suggest using a more familiar editor, even just Notepad!
See <<git-windows-default-editor>>.
3. Also in the Git installer, choose *"Use Windows' default console"*;
otherwise, Python won't work properly in the Git-Bash window.
4. When you install Python, tick the option that says *"Add python.exe to PATH"*
as in <<add-python-to-path>>,
so that you can easily run Python from the command line.
[[git-windows-default-editor]]
.Choose a nice default editor for Git
image::images/git_windows_installer_choose_editor.png["Screenshot of Git installer"]
[[add-python-to-path]]
.Add Python to the system path from the installer
image::images/python_install_add_to_path.png["Screenshot of python installer"]
The test for all this is that you should be able to go to a Git-Bash command prompt
and just run `python` or `pip` from any folder.
*******************************************************************************
.MacOS Notes
*******************************************************************************
((("MacOS")))((("Python 3", "installation and setup", "MacOS installation")))
MacOS installations for Python and Git are relatively straightforward:
* Python 3.12 should install without a fuss from its
http://www.python.org[downloadable installer]. It will automatically install
`pip`, too.
* Git's installer should also "just work".
Similarly to Windows, the test for all this is that you should be able to open
a terminal and just run `git`, `python3`, or `pip` from anywhere. If you run
into any trouble, the search terms "system path" and "command not found" should
provide good troubleshooting resources.
TIP: You might also want to check out http://brew.sh//[Homebrew].
It's a fairly reliable way of installing common Unixy tools on a Mac.footnote:[I wouldn't recommend
installing Firefox via Homebrew though:
`brew` puts the Firefox binary in a strange location,
and it confuses Selenium.
You can work around it, but it's simpler to just install Firefox in the normal way.]
Although the normal Python installer is now fine, you may find Homebrew
useful in future. It does require you to download all 1.1 GB of Xcode, but
that also gives you a C compiler, which is a useful side effect.
*******************************************************************************
[role="pagebreak-before less_space"]
.Linux Notes
*******************************************************************************
If you're on Linux, I'm assuming you're already a glutton for punishment,
so you don't need detailed installation instructions.
But in brief, if Python 3.12 isn't available directly from your package manager,
* On Ubuntu you can install the
https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa[Deadsnakes PPA].
Make sure you `apt install python3.12-venv` as well as just `python3.12` to
un-break the default Debian version of Python.
* Alternatively, https://github.com/pyenv/pyenv[pyenv] is a tool
that lets you manage multiple Python versions on the same machine,
but it is one more thing to have to learn and remember.
* Alternatively, compiling Python from source is actually surprisingly
easy!
However you install it, make sure you can run Python 3.12 from a terminal.
*******************************************************************************
[[firefox_gecko]]
==== Installing Firefox
((("Firefox", "installing")))
Firefox is available as a download for Windows and MacOS from https://www.mozilla.org/firefox/.
On Linux, you probably already have it installed,
but otherwise your package manager will have it.
((("geckodriver")))
Make sure you have the latest version,
so that the "geckodriver" browser automation module is available.
=== Setting Up Your Virtualenv
((("Python 3", "installation and setup", "virtualenv set up and activation", id="P3installvirt00")))
((("virtual environment (virtualenv)", "installation and setup", id="VEinstall00")))
((("", startref="soft00")))
A Python virtualenv (short for virtual environment) is how you set up your
environment for different Python projects. It allows you to use different
packages (e.g., different versions of Django, and even different versions of
Python) in each project. And because you're not installing things
system-wide, it means you don't need root [keep-together]#permissions#.
Let's create a virtualenv. I'm assuming you're working in a folder
called _goat-book_, but you can name your work folder whatever you like.
Stick to the name ".venv" for the virtualenv, though.
[subs=quotes]
.on Windows:
----
$ *cd goat-book*
$ *py -3.12 -m venv .venv*
----
On Windows, the `py` executable is a shortcut for different Python versions. On
Mac or Linux, we use `python3.12`:
[subs=quotes]
.on Mac/Linux:
----
$ *cd goat-book*
$ *python3.12 -m venv .venv*
----
==== Activating and Deactivating the Virtualenv
Whenever you're working through the book,
you'll want to make sure your virtualenv has been "activated".
You can always tell when your virtualenv is active
because you'll see `(.venv)` in parentheses, in your prompt.
But you can also check by running `which python`
to check whether Python is currently the system-installed one, or the virtualenv one.
The command to activate the virtualenv is `source .venv/Scripts/activate` on Windows
and `source .venv/bin/activate` on Mac/Linux.
The command to deactivate is just `deactivate`.
Try it out like this:
[subs=quotes]
.on Windows
----
$ *source .venv/Scripts/activate*
(.venv)$
(.venv)$ *which python*
/C/Users/harry/goat-book/.venv/Scripts/python
(.venv)$ *deactivate*
$
$ *which python*
/c/Users/harry/AppData/Local/Programs/Python/Python312-32/python
----
[subs=quotes]
.on Mac/Linux
----
$ *source .venv/bin/activate*
(.venv)$
(.venv)$ *which python*
/home/myusername/goat-book/.venv/bin/python
(.venv)$ *deactivate*
$
$ *which python*
/usr/bin/python
----
TIP: Always make sure your virtualenv is active when working on the book. Look
out for the `(.venv)` in your prompt, or run `which python` to check.
.Virtualenvs and IDEs
*******************************************************************************
If you're using an IDE like Pycharm or Visual Studio Code,
you should be able to configure them to use the virtualenv
as the default Python interpreter for the project.
You should then be able to launch a terminal inside the IDE
with the virtualenv already activated.
*******************************************************************************
.Activate Not Working on Windows?
*******************************************************************************
((("troubleshooting", "virtualenv activation")))If
you see an error like this:
----
bash: .venv/Scripts/activate: No such file or directory
----
First, double-check you're in the right folder. Assuming you are,
or if you see an error like this:
[role="small-code"]
----
bash: @echo: command not found
bash: .venv/Scripts/activate.bat: line 4:
syntax error near unexpected token `(
bash: .venv/Scripts/activate.bat: line 4: `if not defined PROMPT ('
----
Then you've probably run into a old bug where Python wouldn't install an
activate script that was compatible with Git-Bash. Reinstall the latest Python
3, then delete and re-create your virtualenv.
*******************************************************************************
==== Installing Django and Selenium
((("Django framework", "installation")))
((("Selenium", "installation")))
We'll install Django 4.2 and the latest Seleniumfootnote:[
You might be wondering why I'm not mentioning a specific version of Selenium.
It's because Selenium is constantly being updated
to keep up with changes in web browsers,
and since we can't really pin our browser to a specific version,
we're best off using the latest Selenium.
It was version 4.9 at the time of writing.
]. Remember to make sure your virtualenv is active first!
[subs="specialcharacters,quotes"]
----
(.venv) $ *pip install "django<4.3" "selenium"*
Collecting django<4.3
Downloading Django-4.2.7-py3-none-any.whl (8.0 MB)
---------------------------------------- 8.1/8.1 MB 7.6 MB/s eta 0:00:00
Collecting selenium
Downloading selenium-4.15.0-py3-none-any.whl (6.5 MB)
---------------------------------------- 6.5/6.5 MB 6.3 MB/s eta 0:00:00
Installing collected packages: django, selenium
Successfully installed [...] django-4.2.7 [...] selenium-4.15.0 [...]
----
// CSANAD: The output of the pip installation include the dependencies as well, maybe this way
// it would better illustrate that?
Checking it works:
[subs="specialcharacters,quotes"]
----
(.venv) $ *python -c "from selenium import webdriver; webdriver.Firefox()"*
----
this should pop open a Firefox web browser,
which you'll then need to close.
TIP: If you see an error, you'll need to debug it before you go further.
On Linux/Ubuntu, I ran into https://github.com/mozilla/geckodriver/issues/2010[this bug]
which you need to fix by setting an environment variable called `TMPDIR`.
.Warning, Django 4 upgrade in progress!
*******************************************************************************
If you're reading this message, then you're currently reading a preview
version of the third edition of TDDwP.
I'm currently working on upgrading the book to Python 3.12 and Django 4.x.
At the time of writing, this was completed up to the end of Part 1 / Chapter 7,
but parts 2 and 3, ie chapters 8 and up, are still on Django 1.11.
*******************************************************************************
==== Some Error Messages You're Likely to See When You 'Inevitably' Fail to Activate Your Virtualenv
((("troubleshooting", "virtualenv activation")))
If you're new to virtualenvs--or even if you're not, to be honest--at some point
you're 'guaranteed' to forget to activate it,
and then you'll be staring at an error message.
Happens to me all the time.
Here are some of the things to look out for:
----
ModuleNotFoundError: No module named 'selenium'
----
// CSANAD: in newer versions Python use a more specific ModuleNotFoundError which is a subclass of ImportError
Or:
----
ImportError: No module named django.core.management
----
// CSANAD: TODO check later what it says for this kind of import
As always, look out for that `(.venv)` in your command prompt, and a
quick `source .venv/Scripts/activate` or `source
.venv/bin/activate` is probably what you need to get it working again.
Here's a couple more, for good measure:
----
bash: .venv/Scripts/activate: No such file or directory
----
This means you're not currently in the right directory for working on the
project. Try a `cd goat-book`, or similar.
Alternatively, if you're sure you're in the right place, you may have run into
a bug from an older version of Python, where it wouldn't install
an activate script that was compatible with Git-Bash. Reinstall Python 3, and
make sure you have version 3.6.3 or later, and then delete and re-create your
virtualenv.
If you see something like this, it's probably the same issue, you need to
upgrade Python:
----
bash: @echo: command not found
bash: .venv/Scripts/activate.bat: line 4:
syntax error near unexpected token `(
bash: .venv/Scripts/activate.bat: line 4: `if not defined PROMPT ('
----
Final one! If you see this:
----
'source' is not recognized as an internal or external command,
operable program or batch file.
----
It's because you've launched the default Windows command prompt, +cmd+,
instead of Git-Bash. Close it and open the latter.
.On Anaconda
*******************************************************************************
Anaconda is another tool for managing different Python environments. It's
particularly popular on Windows and for scientific computing, where it can
be hard to get some of the compiled libraries to install.
In the world of web programming it's much less necessary,
so _I recommend you do not use Anaconda for this book_.
Apart from anything else I don't know enough about it to help you debug any
problems with it if they occur!
// DAVID: This, combined with the note at the bottom, feels like it's sending
// a mixed message. On the one hand, it comes across as a slightly harsh
// "you're on your own", then you seem to be offering to help.
// Also maybe it's worth suggesting using a search engine or online forum
// to solve the problem.
*******************************************************************************
Happy coding!((("", startref="prereq00")))((("", startref="TDDprereq00")))((("", startref="P3installvirt00")))((("", startref="VEinstall00")))
NOTE: Did these instructions not work for you? Or have you got better ones? Get
in touch: obeythetestinggoat@gmail.com!