vault backup: 2026-05-30 16:02:33

note/python/python tool/poetry_guide.md

@@ -0,0 +1,93 @@
+---
+title: Poetry Setup and Project Initialization Guide
+created: 2026-05-22
+tags:
+  - python
+  - python_tool
+  - poetry
+  - guide
+category: python_tool
+status: reference
+up: "[[project/index]]"
+related:
+  - "[[poetry_project_ideas]]"
+  - "[[__init__.py explained]]"
+source:
+author:
+published:
+---
+# Poetry Setup and Project Initialization Guide
+
+This guide explains how to install Poetry and start a new Python project, based on the concepts from "Introduction to Poetry - Python Dependency Management".
+
+## 1. How to Install Poetry
+
+While the introductory notes focus on usage, the standard way to install Poetry is via the official installer script.
+
+### macOS / Linux / WSL
+Open your terminal and run:
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+### Windows (PowerShell)
+Open PowerShell and run:
+```powershell
+(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
+```
+
+### Verification
+After installation, restart your terminal and verify by running:
+```bash
+poetry --version
+```
+
+---
+
+## 2. How to Start a Project
+
+There are two main ways to start a project with Poetry:
+
+### Method A: Creating a New Project (Recommended for new folders)
+To create a new project with a predefined folder structure:
+```bash
+poetry new my-project
+```
+This creates a directory named `my-project` with the following structure:
+```text
+my-project/
+├── pyproject.toml
+├── README.md
+├── my_project/
+│   └── __init__.py
+└── tests/
+    └── __init__.py
+```
+
+### Method B: Initializing an Existing Project
+If you already have a project folder and want to add Poetry to it:
+1. Navigate to your project directory:
+   ```bash
+   cd my-existing-project
+   ```
+2. Run the interactive initialization command mentioned in the introduction:
+   ```bash
+   poetry init
+   ```
+   This will walk you through creating your `pyproject.toml` file interactively.
+
+---
+
+## 3. Key Concepts from the Introduction
+
+- **`pyproject.toml`**: The single source of truth for your project configuration (replaces `requirements.txt`, `setup.py`, etc.).
+- **Deterministic Resolution**: Poetry ensures your dependencies are resolved correctly using a lockfile (`poetry.lock`).
+- **Isolation**: Poetry automatically manages virtual environments for you, ensuring your global Python installation stays clean.
+
+## 4. Basic Workflow Commands
+
+Once your project is started, use these commands to manage it:
+- `poetry add <package>`: Add and install a new dependency.
+- `poetry install`: Install all dependencies defined in `pyproject.toml`.
+- `poetry shell`: Activate the project's virtual environment.
+- `poetry run <command>`: Run a command inside the virtual environment without activating it.