Running locally with Python¶
Scripts¶
The scripts/
folder contains some simple scripts to help with development. To run them, ensure they are made executable in your filesystem (they may not be by default depending on your OS).
You can do that in whatever File > Permissions > Make Executable menu your desktop provides, or for *nix environments or the WSL you can type chmod +x <filename>
to add executable permissions.
Run all scripts from the root of the project, or they won't work.
Running the dGC Server locally with Python¶
Note
Some of this setup is obvious to experienced Python developers, but it's documented here so that we all know the same obvious. This helps us reduce development difficulty and speeds up onboarding of new team members.
Managing Python versions, and dependencies such as libraries¶
Managing Python versions¶
We are using Python 3.8.3 currently for these algorithms. There are tools available to help you manage multiple different Python versions on the same machine. We are using pyenv
here, however there are other ways to solve this problem, and you may already have a preferred method, in which case you should be able to use that.
Managing library / dependencies versions¶
If you pip install
all of the dependencies in requirements.txt
globally on your machine, then you can encounter problems if you develop other Python applications on the same machine, for example if ydifferent projects need different versions of the same library.
The solution we have chosen is to use pyenv-virtualenv
which is an extension to pyenv
which helps you to manage separate 'environments' for each Python project you work on. (again, other solutions are available)
If you install and set up pyenv
then the correct Python version will be selected automatically when you navigate to the directory containing this repository, because of the file .python-version
Installing pyenv
¶
Example setup commands for this repository¶
git clone
this repository into a suitable location on your development machine
git clone https://github.com/rcpch/digital-growth-charts-server.git
cd
into the directory
cd digital-growth-charts-server
Install the correct Python version
pyenv install 3.8.0
Create a virtualenv for this project 'growth-charts' abbreviated to 'gc-3.8' using Python 3.8.0
pyenv virtualenv 3.8.0 dgc-server
Auto-selection of Python and virtualenv
Using the same name 'dgc-server' will enable it to be automatically selected when navigating to this repo (but you can call your own virtualenv whatever you like). This all works using the .python-version
file in the project root, which can contain either a Python version name which pyenv
recognises, or it can contain a virtualenv name, which pyenv
will select for you, and of course this automatically selects the Python version too. A helpful article about this is here https://realpython.com/intro-to-pyenv/#activating-your-versions
Check virtualenv creation worked.
pyenv virtualenvs
should return something like:
dgc-server (created from /home/my-user/.pyenv/versions/3.8.0)
Activate the virtualenv manually if it's not already selected
pyenv activate dgc-server
Install the dependencies inside this virtualenv
pip install -r requirements.txt
Refer to the pyenv command reference if you need further information on pyenv
Extra development packages that may be required on some setups
On some platforms, you may need the additional development header packages. On Ubuntu/Linux Mint this was required when using pyenv
and thus compiling Python from source. This should not be necessary if you're running a binary Python, it only affects setups which are compiling a specific Python version from source, on demand, such as pyenv
.
sudo apt-get install liblzma-dev libbz2-dev zlib1g-dev
and then recompile the Python that pyenv
built earlier
pyenv install 3.8.3
If installing on macOS Big Sur, pyenv install of python 3.8.0 and requirements.txt may fail
To install 3.8.3 via pyenv, set the following 2 environment variables (requires homebrew installed versions of bzip2, openssl and zlib):
export CFLAGS="-I$(brew --prefix openssl)/include -I$(brew --prefix bzip2)/include -I$(brew --prefix readline)/include -I$(xcrun --show-sdk-path)/usr/include"
export LDFLAGS="-L$(brew --prefix openssl)/lib -L$(brew --prefix readline)/lib -L$(brew --prefix zlib)/lib -L$(brew --prefix bzip2)/lib"
Now, run the pyenv install with a patch for Big Sur:
pyenv install --patch 3.8.0 < <(curl -sSL https://github.com/python/cpython/commit/8ea6353.patch\?full_index\=1)
Now, once ready to install requirements.txt with pip, set one more environment variable:
export SYSTEM_VERSION_COMPAT=1
Start the API server natively with default settings¶
from the application's root directory, type
s/uvicorn-start
You should then see some messages from the uvicorn development server, which should look like:
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [61645] using watchgod
INFO: Started server process [61647]
INFO: Waiting for application startup.
INFO: Application startup complete.
There may be some other messages at the end of that output for other processes which run on server startup.
If you need to vary any of the parameters passed, you can either modify the startup script or, using the commands in the startup script as a guide, pass the commands to the shell manually.