123 lines
6.0 KiB
Plaintext
123 lines
6.0 KiB
Plaintext
= Experimenting with the `flags2*` examples
|
|
|
|
The `flags2*` examples enhance the `flags*` examples with error handling and reporting.
|
|
Therefore, we need a server that generates errors and delays to experiment with them.
|
|
|
|
The main reason for these instructions is to document how to configure one such server
|
|
in your machine, and how to tell the `flags2*` clients to access it.
|
|
The other reason is to alert of an installation step that MacOS users sometimes overlook.
|
|
|
|
Contents:
|
|
|
|
* <<server_setup>>
|
|
* <<client_setup>>
|
|
* <<macos_certificates>>
|
|
|
|
[[server_setup]]
|
|
== Setting up test servers
|
|
|
|
If you don't already have a local HTTP server for testing,
|
|
here are the steps to experiment with the `flags2*` examples
|
|
using just the Python ≥ 3.9 distribution:
|
|
|
|
. Clone or download the https://github.com/fluentpython/example-code-2e[_Fluent Python 2e_ code repository] (this repo!).
|
|
. Open your shell and go to the _20-futures/getflags/_ directory of your local copy of the repository (this directory!)
|
|
. Unzip the _flags.zip_ file, creating a _flags_ directory at _20-futures/getflags/flags/_.
|
|
. Open a second shell, go to the _20-futures/getflags/_ directory and run `python3 -m http.server`. This will start a `ThreadingHTTPServer` listening to port 8000, serving the local files. If you open the URL http://localhost:8000/flags/[http://localhost:8000/flags/] with your browser, you'll see a long list of directories named with two-letter country codes from `ad/` to `zw/`.
|
|
. Now you can go back to the first shell and run the _flags2*.py_ examples with the default `--server LOCAL` option.
|
|
. To test with the `--server DELAY` option, go to _20-futures/getflags/_ and run `python3 slow_server.py`. This binds to port 8001 by default. It will add a random delay of .5s to 5s before each response.
|
|
. To test with the `--server ERROR` option, go to _20-futures/getflags/_ and run `python3 slow_server.py 8002 --error-rate .25`.
|
|
Each request will have a 25% probability of getting a
|
|
https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/418[418 I'm a teapot] response,
|
|
and all responses will be delayed .5s.
|
|
|
|
I wrote _slow_server.py_ reusing code from Python's
|
|
https://github.com/python/cpython/blob/917eca700aa341f8544ace43b75d41b477e98b72/Lib/http/server.py[`http.server`] standard library module,
|
|
which "is not recommended for production"—according to the
|
|
https://docs.python.org/3/library/http.server.html[documentation].
|
|
|
|
[NOTE]
|
|
====
|
|
This is a simple testing environment that does not require any external libraries or
|
|
tools—apart from the libraries used in the `flags2*` scripts themselves, as discussed in the book.
|
|
|
|
For a more robust testing environment, I recommend configuring
|
|
https://www.nginx.com/[NGINX] and
|
|
https://github.com/shopify/toxiproxy[Toxiproxy] with equivalent parameters.
|
|
====
|
|
|
|
[[client_setup]]
|
|
== Running a `flags2*` script
|
|
|
|
The `flags2*` examples provide a command-line interface.
|
|
All three scripts accept the same options,
|
|
and you can see them by running any of the scripts with the `-h` option:
|
|
|
|
[[flags2_help_demo]]
|
|
.Help screen for the scripts in the flags2 series
|
|
====
|
|
[source, text]
|
|
----
|
|
$ python3 flags2_threadpool.py -h
|
|
usage: flags2_threadpool.py [-h] [-a] [-e] [-l N] [-m CONCURRENT] [-s LABEL]
|
|
[-v]
|
|
[CC [CC ...]]
|
|
|
|
Download flags for country codes. Default: top 20 countries by population.
|
|
|
|
positional arguments:
|
|
CC country code or 1st letter (eg. B for BA...BZ)
|
|
|
|
optional arguments:
|
|
-h, --help show this help message and exit
|
|
-a, --all get all available flags (AD to ZW)
|
|
-e, --every get flags for every possible code (AA...ZZ)
|
|
-l N, --limit N limit to N first codes
|
|
-m CONCURRENT, --max_req CONCURRENT
|
|
maximum concurrent requests (default=30)
|
|
-s LABEL, --server LABEL
|
|
Server to hit; one of DELAY, ERROR, LOCAL, REMOTE
|
|
(default=LOCAL)
|
|
-v, --verbose output detailed progress info
|
|
|
|
----
|
|
====
|
|
|
|
All arguments are optional. The most important arguments are discussed next.
|
|
|
|
One option you can't ignore is `-s/--server`: it lets you choose which HTTP server and base URL will be used in the test.
|
|
You can pass one of four labels to determine where the script will look for the flags (the labels are case-insensitive):
|
|
|
|
`LOCAL`:: Use `http://localhost:8000/flags`; this is the default.
|
|
You should configure a local HTTP server to answer at port 8000. See <<server_setup>> for instructions.
|
|
Feel free to hit this as hard as you can. It's your machine!
|
|
|
|
`REMOTE`:: Use `http://fluentpython.com/data/flags`; that is a public website owned by me, hosted on a shared server.
|
|
Please do not hit it with too many concurrent requests.
|
|
The `fluentpython.com` domain is handled by the http://www.cloudflare.com/[Cloudflare] CDN (Content Delivery Network)
|
|
so you may notice that the first downloads are slower, but they get faster when the CDN cache warms
|
|
up.footnote:[Before configuring Cloudflare, I got HTTP 503 errors--Service Temporarily Unavailable--when
|
|
testing the scripts with a few dozen concurrent requests on my inexpensive shared host account. Now those errors are gone.]
|
|
|
|
`DELAY`:: Use `http://localhost:8001/flags`; a server delaying HTTP responses should be listening to port 8001.
|
|
I wrote _slow_server.py_ to make it easier to experiment. See <<server_setup>> for instructions.
|
|
|
|
`ERROR`:: Use `http://localhost:8002/flags`; a server introducing HTTP errors and delaying responses should be installed at port 8002.
|
|
Running _slow_server.py_ is an easy way to do it. See <<server_setup>>.
|
|
|
|
[[macos_certificates]]
|
|
== Install SSL Certificates (for MacOS)
|
|
|
|
On Macos, depending on how you installed Python you may need to manually run a command
|
|
after Python's installer finishes, to install the SSL certificates Python uses to make HTTPS connections.
|
|
|
|
Using the Finder, open the `Python 3.X` folder inside `/Applications` folder
|
|
and double-click "Install Certificates" or "Install Certificates.command".
|
|
|
|
Using the terminal, you can type for example:
|
|
|
|
[source, text]
|
|
----
|
|
$ open /Applications/Python 3.10/"Install Certificates.command"
|
|
----
|