Which tool to choose, editor and project structure

Comparison

My recommendation

I would choose uv for new projects because it covers the entire cycle with a single tool. I would choose Poetry if the team is already using it and the poetry.lock is in production: switching managers for trendiness is a cost without return. I would choose pip and venv to learn and for restricted environments where only the system's Python is available: what you learn there applies to everything else. I would choose pyenv if I needed a specific build of Python. I would choose pipx for global tools on machines where uv is not available.

Editor

VS Code with the Microsoft Python extension solves most cases. After opening the project folder, choose the interpreter with the command Python: Select Interpreter (the command palette opens with Ctrl+Shift+P, or Cmd+Shift+P on macOS) and point to the .venv of the project. PyCharm is a complete alternative if you prefer an IDE.

Be careful with the Code Runner extension

By default, Code Runner executes the file in the Output panel of VS Code, which does not accept input. Examples with input() get stuck or fail there. Run in the integrated terminal (python3 arquivo.py) or use the Run Python File button from the official extension.

The minimum structure of a project

meu-projeto/
  pyproject.toml
  README.md
  .python-version
  .gitignore
  src/
    meu_projeto/
      __init__.py
      __main__.py
  tests/
    test_basico.py

Every entry point should be importable without executing anything. The default is a main() protected:

def main() -> None:
    print("projeto funcionando")


if __name__ == "__main__":
    main()

projeto funcionando

I explain the reason for this protection in the modules chapter.