It's dangerous to go alone! Take this.
TL:DR;
#!/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!
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)
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
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.
Keep a directory scripts
; call them with python scripts/myscript.py
- simplest
- works cross-platform
- pure python
Alternately you could use
make
, oryarn 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.
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