Pycommerce is an ecommerce example application intentionally designed to showcase how a medium-sized project structured with DDD, TDD, and Clean Architecture looks using the best of modern Python.

Although it's not a fully-featured real-world ecommerce application, it serves as an inspiration project that can be easily extended. It features:

• Language: Python 3.12
• Container: Docker, and Docker Compose
• Package management: Poetry
• Web framework: FastAPI
• Web server: Uvicorn
• Database: Postgres
• Database migrations: Alembic
• ORM: SQLModel
• Password hashing: Passlib
• Authentication: OAuth2 + JWT
• Testing: Pytest
• Linter: Ruff
• Type checker: Mypy
• Code formatter: Black
• Local development hot reload, watch mode for tests, full Asyncio support, etc...

Don't forget to check the FAQ for more information about the project's structure and design decisions.

While it's possible to run the application locally just using Python, it's highly recommended to install Docker to keep your local environment clean and facilitate the use of all the features.

Pycommerce uses environment variables for configuration. You can check all the available options here. You can create and fill a .env file using the .env.example file as a reference, or set them manually like this:

export DB_URL="<database_url>"
export JWT_SECRET_KEY="<my_super_secret_key>"
...

If using Docker, just edit the environment variables on docker-compose.yml.

Activate your Python virtual environment and run:

poetry install

# or

pip install .

mypy pycommerce tests

ruff check .

black --check pycommerce tests

⚠️ If not using Docker, remember to run the init.sql in your local database before running the application.

# set the DB_URL env var to point to the dev database, and run
alembic upgrade head && poetry run app

# or
alembic upgrade head && python -m pycommerce

# with Docker (optionally, you can add pg-admin to the list of containers)
docker-compose up app pg-db -d

Then, open the browser on http://localhost:8080/docs to see the OpenAPI docs:

# to run all the tests
pytest

# to run only the unit tests
pytest tests/unit/

# to run only the integration tests
pytest tests/integration/

# with Docker
docker-compose up tests

By default, hot reload is configured independently of whether you're using Docker or not, so you can have faster development feedback like this:

Tests can also be triggered automatically whenever a test file is modified due to the use of pytest-watch, which leads to a nice and efficient TDD workflow:

For other options, you can use:

# to watch all project tests
docker-compose up watch

# to watch only the ingration tests
docker-compose up watch-integration

# without Docker
ptw -w -c tests/
ptw -w -c tests/unit/
ptw -w -c tests/integration/

This project is licensed under the MIT License - see the LICENSE file for details.