"I'm not much but I'm all I have." — Philip K. Dick
This repository is to assist a new Python developer in getting set up and pointed in the right direction with a dev environment and basic development workflow.
This document is written in markdown. It is a lightweight text markup language that many people find ideally suited for documenting lots of things--especially software projects.
To see how this document looks in markdown (before it is rendered by github), click here.
Documentation isn't a nice-to-have, and it should never be done as an afterthought. It is a good idea to try to write it as you go and then it isn't this major task that awaits you to tackle all at once.
Also, it helps you to remember stuff. See "Automation" below.
Follow this guide to install Python 3 on your system.
Install virtualenv:
$ pip install virtualenv
Add this line to ~/.bash_profile:
export PIP_REQUIRE_VIRTUALENV=true
https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/
This allows you to maintain separate Python installations (e.g. 3.6, 3.7, 3.8) and to switch easily. The approach it takes is lightweight and elegant, and easy to undo if you need to rip it all out.
pyenv creates shims and points those shims at the currently-activated Python installation:
$ which python
/Users/Me/.pyenv/shims/python
$ python --version
Python 3.6.7
Check which Python installation we are currently using:
$ pyenv version
system (set by /Users/Me/.pyenv/version)
Check all locally-installed python versions:
$ pyenv versions
* system (set by /Users/Me/.pyenv/version)
3.5.7
Install a new Python version, v3.8.3:
$ pyenv install 3.8.3
python-build: use openssl@1.1 from homebrew
python-build: use readline from homebrew
Downloading Python-3.8.3.tar.xz...
-> https://www.python.org/ftp/python/3.8.3/Python-3.8.3.tar.xz
Installing Python-3.8.3...
python-build: use readline from homebrew
python-build: use zlib from xcode sdk
Installed Python-3.8.3 to /Users/Me/.pyenv/versions/3.8.3
Create a new virtualenv using Python 3.8.3:
$ pyenv virtualenv 3.8.3 my-virtual-env-3.8.3
Looking in links: /var/folders/2b/yhg7v3mzcc62s5mm5mjm00gq/T/tmpmq7q6no
Requirement already satisfied: setuptools in /Users/Me/.pyenv/versions/3.8.3/envs/my-virtual-env-3.8.3/lib/python3.8/site-packages (41.2.0)
Requirement already satisfied: pip in /Users/Me/.pyenv/versions/3.8.3/envs/my-virtual-env-3.8.3/lib/python3.8/site-packages (19.2.3)
We created the virtualenv but note that it isn't activated yet:
$ python --version
Python 3.6.7
Set the current folder to use this virtualenv:
$ pyenv local my-virtual-env-3.8.3
Now we see we are pointed at the new Python version:
$ python --version
Python 3.8.3
pyenv drops a file into the current directory with the virtualenv name:
$ cat .python-version
my-virtual-env-3.8.3
Some great choices for Python:
- Visual Studio Code (make sure you install the Python extension)
- Free
- Cross-platform (Linux, MacOS, Windows)
- At one time a runner-up to PyCharm, vscode now boasts rich Python support and beyond that a fabulous ecosystem of extensions for virtually everything
- PyCharm
- Free community version (see here)
- Cross-platform (Linux, MacOS, Windows)
- vim
- Free
- Found on virtually any *nix box
- super hip?
- JupyterLab
- Free
- Cross-platform
- Good for data science / data munging
- Not great for debugging
The more that you can automate your dev workflow, the better results you will achieve for multiple reasons.
Automation...
- is a form of functional documentation
- provides consistency in execution
- allows iterative refinement
- saves time
- minimizes cognitive overhead
- is portable to other projects
How you achieve this automation is largely up to you. My personal bias is for tools that are commonly found on Linux systems and tools that I know well.
I am a big fan of writing shell scripts and stitching things together with a Makefile. This is probably because I have a long history of working on *nix systems. Do what works for you and your team, but keep it simple. Baroque things tend to break more easily.
Here is a sample Makefile for this project.
More resources:
Set up editor integration so that the formatter is automatically run on files on every save.
make format-code
make lint-code
PEP257 -- Docstring Conventions
make lint-docstring
make test
Use pytest fixtures to initialize test functions by setting up services, state, or other environment configuration.
make coverage
Note: You must run make test first to generate the coverage analysis.
>>> import this
fizzbuzz = [
f'fizzbuzz {n}' if n % 3 == 0 and n % 5 == 0
else f'fizz {n}' if n % 3 == 0
else f'buzz {n}' if n % 5 == 0
else n
for n in range(100)
]
Use this as a force multiplier and to increase the reliability and precision of each part of your development workflow.
It's not optional.
Do it as you go. Document modules, classes, and functions as you create them. The project should always have an up-to-date README with all the info a new dev needs to jump into the project and get an application stack running without any other assistance.
Good logging and enabling application monitoring is part of our job as software engineers. This can really set you and the systems you help to build apart from the rest of the crowd. Educate yourself on these topics. Don't automatically settle for the way you see things being done; there's almost certainly a better way.
Like a lot of these general recommendations, this could be an entire workshop in and of itself. To get you thinking about the possibilities, listen to this talk by consummate engineer Kelsey Hightower.
Maintain a personal toolkit that contains functions, code snippets, examples, etc. that you find yourself using again and again in a variety of different tasks and jobs.
Maintain the configs for your dev environment (e.g. vscode config file, vim config) in VCS or something that allows to quickly and easily land on a brand new box and have a working dev environment that is customized to your preferences.
It is critical for one's development as a programmer to read good code written by many different people. Set aside time each day to read through some code for projects that are good examples of Python. There are suggestions in the guide below for some projects; reading through the Python standard library is also a great idea.
A lot of the advice here is echoed in this guide, likely because I originally learned a lot of this stuff there. Read the whole thing. The part on organizing code is especially useful early on in your Python career.