01 Getting Started - Observatorio-do-Trabalho-de-Pernambuco/documentation GitHub Wiki

1. Getting Started

This page covers essential information to help new contributors set up their environment and understand our documentation approach.

1.1. Configuring git locally and cloning the GitHub repository

With Git already installed in your machine, make sure your user and email are configured:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Installing the GitHub CLI

One of the easiest ways to interact with GitHub is through their official CLI. Make sure you install it following the steps in the official page.

Cloning the repository

With GitHub CLI installed you can clone the team repository with:

gh repo clone Observatorio-do-Trabalho-de-Pernambuco/infraestrutura-de-dados

1.2. Creating a development environment with uv from scratch

This session guides contributors on how to setup a local development environment. In order to have a reproducible development environment for the team, uv is used to manage local Python environments. uv is a fast, dependency resolver and Python environment manager written in Rust.

Installing uv

First, install uv:

pip install uv

Setting up Python

Make sure the right Python version is installed using the following command:

uv python install 3.12

Creating a new project

To create a new project (pyproject.toml) with uv and Python 3.12:

uv venv --python 3.12
uv init --bare --name data-infrastructure

Installing dependencies

Install the desired Python libraries using uv add [lib-name]:

uv add jupyterlab ipykernel polars tqdm boto3 pyiceberg ruff

This command will add the packages to your pyproject.toml, update the uv.lock file, and sync your environment[5].

Activating the environment

To activate the uv environment:

source .venv/bin/activate  # For Unix/Mac
# or
.venv\Scripts\activate     # For Windows

Alternatively, you can run commands directly using uv run:

uv run python main.py

To open JupyterLab:

uv run jupyter lab

Creating a uv environment from an existing pyproject.toml

If you already have a pyproject.toml, you can easily create a uv environment with the following commands:

uv venv
uv sync

The uv sync command will:

  • Find or download an appropriate Python version to use
  • Create and set up your environment in the .venv folder (if it doesn't exist)
  • Build your complete dependency list and write to your uv.lock file
  • Sync your project dependencies into your virtual environment

Managing dependencies with uv

Operation Command Description
Add a package uv add Adds the package to pyproject.toml, uv.lock, and syncs your environment
Remove a package uv remove Removes the package from pyproject.toml, uv.lock, and syncs your environment
Upgrade a package uv sync --upgrade-package Upgrades the package in your uv.lock file and syncs your environment
Upgrade all packages uv lock --upgrade Upgrades all packages in your uv.lock file (according to constraints in pyproject.toml)

Common uv Operations Cheatsheet

What Command Explanation
Create virtual environment uv venv Creates a virtual environment in .venv directory
Create with specific Python uv venv --python 3.11 Creates a virtual environment with Python 3.11
Install dependencies uv sync Installs dependencies from pyproject.toml to your environment
Run a command uv run Runs a command in the virtual environment

1.3. Checking code quality with ruff

ruff can be used as a linter and formatter, replacing libraries like flake8, isort, and black. It's suggested that you install ruff in your local environment, separate from the uv environment created above.

pip install ruff

This way you can run it with:

ruff --help

If you want to execute using the uv environment, use:

uv run ruff --help

ruff default configurations

You can define the behavior for ruff by specifying configuration values in the pyproject.toml:

[tool.ruff]
line-length = 79

[tool.ruff.format]
quote-style = "single"
indent-style = "space"
docstring-code-format = true
docstring-code-line-length = 30

Using ruff as formatter

One of the features from ruff is code formatting, replacing black with its same default rules:

ruff format [target_file.py]

Using ruff as linter

To check if your code follows PEP8 conventions:

ruff check

You'll see a list of conventions your code is breaking. To automatically fix issues:

ruff check --fix

1.4. References