Basic Setup for a Python Repo
software Python

I’ve been getting back into the Python world after spending a lot of time in TypeScript and I finally see the similarities in project setup. There are certain things you always do regardless of the programming language you’re using, especially object-oriented languages. Things like, installing packages, setting up linters, and having a sensible folder structure. This becomes even more apparent on backend apps because they follow pretty similar pattern when you’re working with API endpoints.

Dependencies

After you’ve set up your virtual env in Python:

python3 -m venv .venv
source .venv/bin/active

You can start by getting your Pipfile initialized. One way you can do this is to have a requirements.txt file and run:

pip install requirements.txt

Or you could take advantage of pipenv. This will generate a Pipfile and a Pipfile.lock which is very similar to having a package.json and package-lock.json. Then you can either use a requirements.txt to add the initial dependencies or you can add them directly in the file. The commands for this are:

pip install pipenv
pipenv install

Linting

Having linting enabled will save you time with small code fixes and potential build errors because it will highlight any issues early. A common tool for this is Pylint which is similar to eslint. Add a new .pylintrc to the root of your project with:

pylint --generate-rcfile > .pylintrc

This will generate standard defaults for you that you and your team can tweak based on needs and preferences. Then you can execute it with a command like:

pylint ./src

where ./src is the path to where your Python files are. After you run this, you’ll get some output similar to this:

MacBook-Pro brands % pylint ./src
************* Module lib.errors
src/lib/errors.py:5:0: C0303: Trailing whitespace (trailing-whitespace)
src/lib/errors.py:8:0: C0304: Final newline missing (missing-final-newline)
************* Module handlers.get_brand
src/handlers/get_brand.py:7:0: C0116: Missing function or method docstring (missing-function-docstring)

-----------------------------------
Your code has been rated at 2.94/10

Now you can go through your files and clean up the lint issues. After your initial run of pylint, you might notice a lot of errors and warnings that aren’t relevant to your project. If there are rules you want to turn off, search for the I suggest using a tool like pre-commit to automatically run this check every time you make a Git commit.

Testing

Regardless of what kind of app you’re building, it’s always helpful to have some unit tests. I’d recommend pytest, but it does have a bit of a learning curve. You could use the built-in unittest functionality, though you might find it more limited compared to what pytest can do.

Other considerations

You should include some type of authentication and authorization capabilities to your template. Since this is a Flask template, consider using Flask-login. Something else to consider is using the Flask middleware hook before_request to handle common input validation. There’s also Flask-CORS to handle CORS for your requests and Flask-Limiter to provide rate limiting.

Convenient skeleton template

If you want to create a Flask app with a scalable structure to start from, check out my template repo. This is what I use both personally and professionally and I’ll keep it updated as I learn more best practices. If you aren’t sure how to get started, try this and modify it for what you need. This has everything I discussed above and it has the full setup for a Flask app.

Thanks for taking the time to read this. You never know what the next post will be.

If you ever hear of any tech writing or senior software engineering jobs, reach out to me on LinkedIn! While I have a job I like, I’m always open to hear about cool new roles.