quick linux/windows python dev setup

README.md

linux/windows dev environment setup

It's dangerous to go alone! Take this.

TL:DR;

• install pipenv
• install git

#!/usr/bin/env bash
mkdir your-project
cd your-project
git init
echo "what this project does" > README.md
pipenv --python 3.7
pipenv install 'python-language-server[all]' flake8 black pyls-black
git add Pipfile
git commit
mkdir src # project source files go here
mkdir scripts # for automating common tasks
pipenv shell # start coding!

Step 0: git gud

git init

This creates a directory, .git, which houses materials git uses to keep track of versioning info for your project directory. ALWAYS use version control. Commit your changes early and often, 'cause nothing feels worse than losing untracked work. Your most common commands will be git add <path/to/file> and git commit. You'll likely do your commits from within your IDE or something like https://desktop.github.com/, but if you've got time / the stomach for it, I'd recommend learning the terminal commands.

[advanced] If you want your git log to work as a descriptive changelog, you can use

git config alias.snapshot '!git stash --include-untracked && git stash apply'
# this alias will be local to this project unles you do git config --global ...
git checkpoint # takes a complete snapshot of your project
git stash show # shows what's in that snapshot

Now hit git snapshot whenever something works or something doesn't work or you want to go get a coffee. Just do it (tm)

Step 1: use pipenv to keep track of dependencies

pipenv --three # or pipenv --python 3.7

This creates a Pipfile and Pipfile.lock you've now working within a virtual environment (a.k.a. virtualenv):

• python on the command line now points to a different, custom python executable
  • in this case the 3.7 you installed
  • you can have multiple versions going in different projects
• pipenv and python now look first in a custom directory for installed packages and executables and installing packages within that directory.
  • This means you shouldn't have version conflicts with any other projects on your machine
• you can look up your environments using pipenv list
• you can exit your virtualenv using exit

step 2: get a smart IDE

You'll want some basic functionality for any language you work with:

• Code completion
• type hints, docs on Hover
• Jump to def
• outline of symbols in a script/workspace
• Find references
• Diagnostics (style and logic checking)

Your editor shouldn't have to understand every language you might work with well enough to implement these. That's what the python language server is for: a separate service will parse the code in your project and communicate with your IDE, so the IDE only has to implement UI for completion, jumping, etc. See langserver.org/#implementations-client for IDEs that can do this. VSCode and Atom are fairly feature-rich.

Once you've installed an IDE, install the language server:

pipenv install 'python-language-server[all]' flake8 black pyls-black

If your language server client doesn't use the pyls-black plugin, uninstall the plugin and either use a linting plugin for black or use black directly. Black is named after Ford's comment on customizing the model T: you can get it in "any color you like" so long as it's black. It looks good and works FAST. black --test your/file.py your/directory will test the style therein, while black you/file.py your/directory will correct all style in the python files indicated. The .flake8 config included is a fallback in case your IDE well and truly doesn't support black; it configures flake8 to implement the same checks. Also, black and flake8 check for syntax and logic errors.

Personal advice: use the Atom IDE with the Hydrogen plugin.

Step 3: automate everything

Keep a directory scripts; call them with python scripts/myscript.py

• simplest
• works cross-platform
• pure python Alternately you could use make, or yarn run, but those rely on non-python software and will involve some cross-platform gotchas (i.e. '/' vs '\' in paths).
  • Note that if you're using git for windows, you've got access to git bash, which includes make.

Step 4: go forth and program

Here are some acronyms to help:

• OOFP: Object-Oriented Functional Programming
  • A method is just a regular function with the instance passed as the first parameter
  • A function should do one thing
  • A function should have no side-effects outside of its local scope
• KISS: Keep It Simple Stupid
  • There are many nice things that you might not need (testing, type annotations, etc). Reach for them when you need them: later.
  • Something that works but is ugly is ok. Anything that doesn't work is not.
  • A hack beats doing it right any day 'cause doing it right takes a week