README.md

To-do list using FastAPI

This project implements a to-do list using FastAPI.

Getting Started

Prerequisites

The following dependencies are expected to be installed:

• Python 3.12
• PostgreSQL
• pre-commit
• PDM

MacOS Users

MacOS users are recommended to use Homebrew, a package manager that simplifies the installation of software on MacOS and Linux systems, to easily install the required dependencies for this project. If Homebrew is not yet installed, follow the instructions on its homepage.

Once Homebrew is installed, the project dependencies can be installed by running the following command in the terminal:

brew install python3 postgresql pre-commit pdm

Database Setup

Before the project setup, follow these steps for database setup:

1. Start the PostgreSQL service. The command may vary depending on the operating system:

   • Windows
   • Linux

   MacOS

   brew services start postgresql

2. Connect to the default postgres database:

   psql postgres

3. If the postgres user does not exist, create a new user named postgres with password postgres:

   CREATE USER postgres WITH PASSWORD 'postgres';

   If the postgres user already exists, set the password for this user to 'postgres':

   ALTER USER postgres WITH PASSWORD 'postgres';

4. Create two databases named planner and planner_test owned by the postgres user:

   CREATE DATABASE planner OWNER postgres;
   CREATE DATABASE planner_test OWNER postgres;

   planner is used for the main application, while planner_test is used for running tests.

5. Set the timezone of the databases to UTC:

   ALTER DATABASE planner SET timezone TO 'UTC';
   ALTER DATABASE planner_test SET timezone TO 'UTC';

6. Exit the PostgreSQL shell:

   \q

Project Setup

After the database setup, the following steps are followed to set up the project:

1. Clone the repository:

   git clone https://github.com/lmiguelvargasf/planner.git

2. Navigate into the project directory:

   cd planner

3. Install the project dependencies using PDM:

   pdm install

4. Install the pre-commit hooks for the repository:

   pre-commit install

5. Copy the .env.example file to .env:

   cp .env.example .env

   Open the .env file and replace the placeholders in the DATABASE_URL with the appropriate values. The connection string should reflect the values used in the Database Setup section. For example:

   DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/planner
   

   In this example, postgres is the username and password, localhost is the host, 5432 is the port (default PostgreSQL port), and planner is the database.

6. Run the project:

   pdm run start

7. Access the application by clicking on the following link: localhost:8000. The following response should be seen:

   {"status": "up"}
   

Testing

pytest is used for testing.

Plugins

To enhance the testing capabilities, the following plugins are integrated with pytest:

• pytest-asyncio - to facilitate testing of code that uses the asyncio library.
• pytest-mock - to ease mocking.

Running Tests

Execute the following command to run the tests:

pdm run test

Jupyter Notebook Usage

It is encouraged the use of Jupyter notebooks for data analysis and exploration to facilitate interactive development and data visualization.

• Storage: Please place all notebooks in the ./notebooks directory.
• Naming Convention: Name the notebooks using the format YYYY-MM-DD_brief_description.ipynb. This convention organizes notebooks chronologically and provides a quick insight into their contents.

Pre-commit Hook: nbstripout

To maintain a clean repository, the nbstripout pre-commit hook is used to strip outputs from Jupyter notebooks, which can significantly reduce file sizes.

Launching JupyterLab

JupyterLab can be launched using the following command:

dotenv run jupyter lab --notebook-dir=./notebooks

It can also be initiated through pdm scripts:

pdm run lab

Executing either command starts the JupyterLab server, enabling access to notebooks via the web interface.