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

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]"

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.

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

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

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.

First, install uv:

pip install uv

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

uv python install 3.12

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

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

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].

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

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

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

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

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

ruff format [target_file.py]

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

• GitHub CLI quickstart
• uv deep dive
• uv Documentation
• ruff Documentation