davidbgk/python.md

## python.md

      
    Raw
  

              python.md
            
          
    Python

This is my recommended Python setup, as of Fall 2022. The Python landscape can be a confusing mess of overlapping tools that sometimes don't work well together. This is an effort to standardize our approach and environments.
Tools and helpful links:


Python docs: https://docs.python.org/3/
Python Standard Library: https://docs.python.org/3/library/index.html - Start here when you're trying to solve a specific problem
pip: https://pip.pypa.io/en/stable/ - Python's standard package installer, included with the language itself
pipx: https://pipxproject.github.io/pipx/ - Global script installer, built on top of pip
pipenv: https://pipenv.pypa.io/en/latest/ - Package installer for projects, manages both dependencies and virtual environments
pyenv: https://github.com/pyenv/pyenv - Manage different versions of Python itself
homebrew: https://brew.sh/ - Package manager for macOs, use for specific needs
Postgres.app: https://postgresapp.com/ - Preferred database server for macOs

Installing the right Python

Python 3 is now the right version of Python to use. We may have projects running different minor versions – such as 3.7 or 3.9 – but we should always default to the latest available version. As of this writing, that's 3.10.8. The must up-to-date Python documentation will always be here: https://docs.python.org/3/.
In the past, you might have seen recommendations to install Python with homebrew. This is now strongly discouraged. Let me say that louder: DO NOT INSTALL PYTHON WITH HOMEBREW. Homebrew can be very aggressive and expansive with upgrades, and upgrading one package often results in lots of seemingly unrelated upgrades, which will frequently break dependencies for other packages.
Use pyenv. To install and manage different Python versions, use pyenv. In most cases, I recommend either the homebrew installation or the git installation:
brew update
brew install pyenv
Is it weird that I recommend using homebrew to install pyenv but not Python? Yes it is. But pyenv is built entirely with shell scripts, so it's relatively safe, and pyenv itself will keep your Python versions safely isolated from homebrew's aggressive upgrades.
Follow the instructions to configure your shell profile (https://github.com/pyenv/pyenv#installation) so that the pyenv command is available and you are able to install new versions of Python as needed.
From there, install at least the latest stable version of Python (again, probably 3.10.8) and make that your global default. This will make the right version of pip available for installing new packages.
pyenv install --list # see a list of installable versions
pyenv install 3.10.8 # or something different
pyenv global 3.10.8

python --version
# Python 3.10.8

which python
# /Users/camico/.pyenv/shims/python

which pip
# /Users/camico/.pyenv/shims/pip
Global scripts and utilities

For any tools built in Python you want available across projects, use pipx. Install it with pip:
pip install --user pipx # install it
pipx ensurepath # make sure your system can find it
(Note that pipx's documentation recommends installing with Homebrew. As noted above, I don't recommend using Homebrew with Python projects, except for pyenv.)
Among the first things you should install with pipx is pipenv, which we'll use for specific projects.
Virtual environments

Python uses virtual environments to separate dependencies for different projects. This can be a frustrating step, especially if you are used to having a local node_modules folder. In the past, this also meant having to install a separate virtualenv library. In Python 3, it's now part of the standard library as the venv package.
This is a good tutorial that covers how virtual environments work: https://docs.python.org/3/tutorial/venv.html
Here's the tl;dr:
python -m venv project-dir

source project-dir/bin/activate
That will create a virtual environment in the project-dir folder. The second command will run the activate script, which will tell your shell to use a local version of Python and locally installed dependencies. For the most part, you won't have to do this by hand, but it's useful to know what's happening under the hood.
In a project with a Pipfile, like alltheplaces-datasette, we can use pipenv to both manage our virtual environment and install dependencies. In that case, navigate to the directory and run pipenv sync:
cd alltheplaces-datasette
pipenv sync
This will also, assuming you have pyenv installed and working, switch to the version of Python listed in the Pipfile (installing it if needed). Consult the pipenv docs to see what else it can do.
Installing local Python packages

For the most part, we're going to work on projects where we have a Pipfile managing dependencies. In that case, installing something new is a one-liner:
pipenv install django
That will install the django package, add it to our Pipfile and update our Pipfile.lock file, pinning a specific version. Running pipenv sync, as above, installs dependencies from Pipfile.lock, much like npm ci installs from package-lock.json, ensuring we get the same version of every dependency every time.
Databases

There are two databases we're likely to use with Python: SQLite and Postgres.
SQLite comes bundled with Python. It runs as an embedded process, with all data contained in a single file, and it can be very useful for data analysis. 
Postgres is the best database available for web applications. For local development, I recommend Postgres.app, which the easiest way to manage a database server on your laptop.