cuz-guide/1.getting-started.md

Getting Started

1. Create a Git repository

Start by creating a repository on GitHub or another Git hosting platform.

• Give it a descriptive name.
• Add a README.md explaining what the project does.
• Add a .gitignore to prevent unnecessary files from being committed. Github has a Python template you should use, which prevents cache or build data to be commited
• Commit changes regularly with descriptive commit messages.

2. Recommended project structure

my-project/
├── src/
│   ├── main.py
│   ├── utils.py
│   └── ...
├── .venv/
├── .gitignore
├── requirements.txt
└── README.md

3. requirements.txt

Use requirements.txt to keep track of external Python packages your project depends on.

Example:

requests==2.32.5
beautifulsoup4==4.14.2

• One package per line.
• Pin versions to make installations reproducible.
• Update the file whenever you add or remove dependencies.

Install all dependencies with:

pip install -r requirements.txt

Next step: Set up a virtual environment

A virtual environment (venv) creates an isolated Python environment for your project.

This means:

• Each project can have its own dependencies.
• Installing packages won't affect your system Python installation.
• Different projects can use different package versions.

1. Check your Python installation

python3 --version

2. Create the virtual environment

Navigate to your project directory:

cd my-project

Create the environment:

python3 -m venv .venv

This creates a .venv/ directory containing the isolated Python environment.

3. Activate the virtual environment

source .venv/bin/activate

Once activated, your terminal should show something similar to:

(.venv) user@computer:~/my-project$

4. Install dependencies

With the virtual environment activated:

pip install -r requirements.txt

You can now install additional packages:

pip install requests

If you add a new dependency, update requirements.txt by running pip freeze which lists all installed packages.:

pip freeze > requirements.txt

5. Deactivate the environment

When you're finished working or want to change to a different virtual environment:

deactivate