# How I Setup a Python Project from Scratch


<!--more-->

# Prerequisites

Before you begin, ensure you have:

* A Git repository
* A working Python environment

---

# Setting Up Poetry

## Install Poetry (if not already installed)

Use the following command to install Poetry:

```bash
curl -sSL https://install.python-poetry.org | python3 -
```

📘 Reference: [Poetry Installation Guide](https://python-poetry.org/docs/#installation)

---

## Initialize Poetry in Your Project

If you're setting up Poetry in an existing project:

```bash
poetry init
```

📘 Reference: [Initializing a Pre-Existing Project](https://python-poetry.org/docs/basic-usage/#initialising-a-pre-existing-project)

---

# Adding Linters

Use the `--group dev` option to manage development tools as development dependencies.

## Option 1: Traditional Approach

### Commonly Used Tools

* `black`: Code formatting
* `isort`: Import sorting
* `flake8`: Code style checking

```bash
poetry add --group dev "black^24.2.0"
poetry add --group dev "isort^5.13.2"
poetry add --group dev "flake8^7.0.0"
```

### Style Configuration

Create a configuration file:

```bash
touch setup.cfg
```

Add the following configuration to `setup.cfg`:

```ini
[flake8]
max-line-length = 120
extend-ignore = E203
exclude =
    .git,
    __pycache__,
    build,
    dist,
    *.egg-info
per-file-ignores =
    __init__.py: F401
```

> ⚠️ Note: `flake8` does **not** support `pyproject.toml` for configuration.

---

## Option 2: Modern Approach (I Personally Recommend This Way)

Use `ruff`, a fast all-in-one linter and formatter.

```bash
poetry add --group dev "ruff^0.11.10"
```

> ✅ Widely adopted by many modern open-source Python projects.

---

# Setting Up Pre-commit Hooks (Optional but Recommended)

`pre-commit` helps enforce code style and quality checks before commits.

## Install Pre-commit

```bash
poetry add --dev pre-commit
```

## Initialize Pre-commit in Your Repo

```bash
poetry run pre-commit install
```

---

## Create Configuration File

Create the configuration file at the root of your project:

```bash
touch .pre-commit-config.yaml
```

### Configuration for Option 1 (Traditional Linters)

```yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
        exclude: ^scripts/.*
      - id: end-of-file-fixer
        exclude: ^scripts/.*
      - id: check-added-large-files
        exclude: ^scripts/.*

  - repo: https://github.com/psf/black
    rev: 24.2.0
    hooks:
      - id: black

  - repo: https://github.com/pycqa/isort
    rev: 5.13.2
    hooks:
      - id: isort

  - repo: https://github.com/pycqa/flake8
    rev: 7.0.0
    hooks:
      - id: flake8
```

### Configuration for Option 2 (`ruff`)

```yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.11.10
    hooks:
      - id: ruff
        args: [--fix]
```

---

# Using a Makefile for Developer Workflow

A `Makefile` can help streamline common tasks like setting up the development environment, running tests, or starting services.

## Create a Makefile

```bash
touch Makefile
```

## Add a Setup Command

Add the following to your `Makefile`:

```makefile
setup-project-dev:
	poetry install
	poetry run pre-commit install
```

This command will install dependencies and set up the pre-commit hooks.

---

# Conclusion

I personally have the demand to create a project from scratch when I write this article. -> [github-repo](https://github.com/ycc789741ycc/api-client-examples)  
The article can also help me to on board a new developer If there is a need one day in the future.  
Although it might be over simplified for a big project but it is a correct way to start a Python project.