Building Python Projects The Right Way with Poetry and VS Code

Play this article

Hey there, it's Theo! If you're anything like me—passionate about Python development, and always eager to dive into new tech stuff—you'll love what I've got to share today. A few months ago, I was stuck in a messy situation with a project that had grown wild and disorganized, like an untamed garden. It had sprawling dependencies, inconsistent environments, and let's not even talk about testing—it was a nightmare!

That's when I decided to revamp the way I structure my Python projects, and boy, has it been a game-changer! In today's blog, we'll deep dive into how to set up a Python project using Poetry for managing dependencies and performing tests in VS Code. Buckle up!

Project Structure

Let's start by organizing the files and folders. I mean, what's a good house without a strong foundation, right?

my_project/                     # Project root directory
├── pyproject.toml              # Poetry configuration and dependencies
├──                   # Project description and setup guide
├── .gitignore                  # Git ignore rules
├── .vscode/                    # VS Code specific settings
│   └── settings.json           # Editor settings
├── src/                        # Your Python source code
│   ├──             # Makes src a Python package
│   └── my_module/              # A Python module
│       └──         # Makes my_module a Python package
└── tests/                      # Test suites
    ├──             # Makes tests a Python package
    └── test_my_module/         # Tests for my_module
        └──  # Actual test file

Why this structure?

  1. pyproject.toml: The heart of your project when using Poetry. It keeps track of your project metadata and dependencies.

    • Inline Comment: Run poetry init to generate this file.
  2. The front page of your codebase. It's essential for explaining what your project is about and how to use it.

    • Inline Comment: Use Markdown for styling.
  3. .gitignore: Keeps your repository clean by ignoring files like .env, __pycache__, etc.

    • Inline Comment: Check out templates online based on your project needs.
  4. .vscode/settings.json: Customize your VS Code editor settings for this project.

    • Inline Comment: Add settings like test configurations or Python paths.
  5. src/ and tests/: The src/ directory contains the source code, and tests/ is for your test suites. Separating source and test code makes your project more maintainable.

    • Inline Comment: Always import your source code in your tests as you would in a third-party package.

Poetry for Dependency Management

Once you've got your structure set up, it's time for some Poetry magic.

  1. Install Poetry: First, you'll need to install Poetry if you haven't yet.

     curl -sSL | python3
  2. Initialize Your Project: Navigate to your project's root directory and run poetry init.

     poetry init

    This command will guide you through creating your pyproject.toml.

  3. Adding Dependencies: To add a package, simply run:

     poetry add <package-name>

Example: Adding Flask

poetry add flask

This will update your pyproject.toml file with Flask and its dependencies.

  1. Installing Dependencies: Poetry automatically installs the added packages, but if you've cloned a project or need to re-install, just run:

     poetry install
  2. Virtual Environments: Poetry creates a virtual environment for your project, ensuring that dependencies are isolated.

VS Code for Efficient Coding

Setting the Python Interpreter

To tell VS Code to use Poetry’s virtual environment, you can either:

  1. Modify .vscode/settings.json:

         "python.pythonPath": "${workspaceFolder}/.venv/bin/python"
  2. Or use Python: Select Interpreter from the Command Palette and choose the virtual environment generated by Poetry.

Configure Testing

To run tests within VS Code, you'll need to specify the testing framework in .vscode/settings.json:

  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests"]

Putting it All Together

By now, you should have a robust, manageable Python project that you can be proud of.

poetry install  # Install the project and its dependencies
poetry run pytest  # Run tests using the Poetry environment

README: The First Impression

A isn’t just a file; it’s the first impression people get of your project. So make it count!

# My Awesome Project

## Description
This project does amazing things with Python.

## Setup
Run `poetry install` to install dependencies.

## Testing
Run `poetry run pytest` to execute tests.


Phew! We've covered quite a lot, haven't we? From setting up a clean project structure to managing dependencies with Poetry, and making the whole thing sing together in VS Code. Now, you're not just writing code; you're crafting an art piece.

Until next time, happy coding!

Did you find this article valuable?

Support Theo van der Sluijs by becoming a sponsor. Any amount is appreciated!