= 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 a test server

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 .5s delay 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 strings to determine where the script will look for the flags (the strings 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 in installed Python you may need to manually run a command
after Python's installer finishes, to install SSL certificates for 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"
----
