Starting a Python Project

This guide documents the steps I take to set up the foundation of any Python project, with a focus on environment setup, version control, and project structure.

1. Git & GitHub Repository

If your project doesn’t have a local and a remote repository, you could be in danger, Git and GitHub is essential for tracking changes and backing up your code.

Steps:

  • Create a local repository in your project directory:
git init
  • Create a remote repository on GitHub.
  • Link the remote repository to your local one and send your first commit:
echo "# python-requests-site" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/lorenzouriel/python-requests-site.git
git push -u origin main

A project without version control could be at risk if anything goes wrong with your code

2. Virtual Environment

Using a virtual environment ensures that your project dependencies do not interfere with other Python projects on your system. It isolates your environment and keeps everything clean.

Steps:

  • Create a virtual environment:
python -m venv venv
  • Activate the virtual environment:
# Windows
.\venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

Once activated, any Python packages you install will go to the .venv folder and not affect other projects.

3. Use Pyenv

Pyenv allows you to manage multiple Python versions on your system.

It’s useful if you need to test your project with different Python versions or if you want to keep the Python versions for your projects isolated.

Steps:

  • Install Pyenv on your system by following the installation guide.
  • Install a specific version of Python:
pyenv install 3.12.0
  • Set the local Python version for your project
pyenv local 3.12.0

A file called .python-version will be created in your project tree.

This ensures that your project will use the specified Python version, no matter what the global system version is.

4. Use Poetry

Poetry is a dependency manager and build tool for Python projects.

It simplifies dependency management and packaging, making it easier to maintain and share Python projects.

Steps:

  • Install Poetry by following the installation guide.
  • Once installed, initialize Poetry in your project:
poetry init
  • Poetry will guide you through creating a pyproject.toml file, where your dependencies will be listed.
  • To install dependencies, run:
poetry install
  • Poetry also allows you to create a virtual environment and set the python version:
poetry shell  # Create and log into a shell within the virtual environment
poetry env use 3.12.0  # Sets the version of Python to be used by virtual project environment

The main point is dependency resolution in a clean and efficient way.

Here is a example of a pyproject.toml file with the lib requests installed:

[tool.poetry]
name = "python-requests-site"
version = "0.1.0"
description = ""
authors = ["Lorenzo Uriel <your-email@gmail.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.12"
requests = "^2.32.3"


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

5. Create a .gitignore and a .env

.gitignore: This file tells Git which files and directories should not be tracked by version control. This helps prevent sensitive or unnecessary files from being pushed to GitHub.

.env: This file contains environment variables such as API keys, database URLs and other configuration values. It’s important to keep this file private, so it should never be committed to the repository.

Steps:

  • In the case of .gitignore I always use the toptal model, you can check here.
  • Just create the files and add the values:
# Windows
New-Item .gitignore
New-Item .env


# macOS/Linux
touch .gitignore
touch .env

Here’s a great starting point for creating a Python project from scratch, there are several other approaches you can take to ensure the project is maintained according to best practices.