Merge pull request #1158 from Ayobamidele/chore/readme_update

chore: Removed outdated setup instructions to follow current standards

Author: joboy-dev

README.md

@@ -1,115 +1,257 @@
-# FASTAPI
-FastAPI boilerplate
+# **FASTAPI Boilerplate**  
+A FastAPI boilerplate for efficient project setup.  
 
-## Setup
+## **Cloning the Repository**  
 
-1. Create a virtual environment.
- ```sh
-    python3 -m venv .venv
- ```
-2. Activate virtual environment.
-```sh
-    source /path/to/venv/bin/activate`
-```
-3. Install project dependencies `pip install -r requirements.txt`
-4. Create a .env file by copying the .env.sample file
-`cp .env.sample .env`
+1. **Fork the repository** and clone it:  
+   ```sh
+   git clone https://github.com/<username>/hng_boilerplate_python_fastapi_web.git
+   ```
+2. **Navigate into the project directory**:  
+   ```sh
+   cd hng_boilerplate_python_fastapi_web
+   ```
+3. **Switch to the development branch** (if not already on `dev`):  
+   ```sh
+   git checkout dev
+   ```
 
-5. Start server.
- ```sh
- python main.py
-```
 
-## **DATABASE TEST SETUP**
+## **Setup Instructions**  
+
+1. **Create a virtual environment**:  
+   ```sh
+   python3 -m venv .venv
+   ```
+2. **Activate the virtual environment**:  
+   - On macOS/Linux:  
+     ```sh
+     source .venv/bin/activate
+     ```
+   - On Windows (PowerShell):  
+     ```sh
+     .venv\Scripts\Activate
+     ```
+3. **Install project dependencies**:  
+   ```sh
+   pip install -r requirements.txt
+   ```
+4. **Create a `.env` file** from `.env.sample`:  
+   ```sh
+   cp .env.sample .env
+   ```
+5. **Start the server**:  
+   ```sh
+   python main.py
+   ```
 
-To set up the database, follow the following steps:
+---
 
-**Cloning**
-- clone the repository using `git clone https://github.com/hngprojects/hng_boilerplate_python_fastapi_web`
-- `cd` into the directory hng_boilerplate_python_fastapi_web
-- switch branch using `git checkout backend`
+## **Database Setup**  
 
-**Environment Setup**
-- run `pip install -r requrements.txt` to install dependencies
-- create a `.env` file in the root directory and copy the content of `.env.sample` and update it accordingly
+### **Replacing Placeholders in Database Setup**  
 
-**Create your local database**
-```bash
-sudo -u root psql
+When setting up the database, you need to replace **placeholders** with your actual values. Below is a breakdown of where to replace them:
+
+---
+
+## **Step 1: Create a Database User**
+```sql
+CREATE USER user WITH PASSWORD 'your_password';
 ```
+🔹 **Replace:**  
+- `user` → Your **preferred database username** (e.g., `fastapi_user`).  
+- `'your_password'` → A **secure password** for the user (e.g., `'StrongP@ssw0rd'`).  
+
+✅ **Example:**  
+```sql
+CREATE USER fastapi_user WITH PASSWORD 'StrongP@ssw0rd';
+```
+
+---
+
+## **Step 2: Create the Database**
 ```sql
-CREATE USER user WITH PASSWORD 'your desired password'; 
 CREATE DATABASE hng_fast_api;
+```
+🔹 **Replace:**  
+- `hng_fast_api` → Your **preferred database name** (e.g., `fastapi_db`).  
+
+✅ **Example:**  
+```sql
+CREATE DATABASE fastapi_db;
+```
+
+---
+
+## **Step 3: Grant Permissions**
+```sql
 GRANT ALL PRIVILEGES ON DATABASE hng_fast_api TO user;
 ```
+🔹 **Replace:**  
+- `hng_fast_api` → The **database name you used** in Step 2.  
+- `user` → The **username you created** in Step 1.  
 
-**Starting the database**
-after cloning the database, dont run 
-`alembic revision --autogenerate -m 'initial migration'`
-but run
-`alembic upgrade head`
+✅ **Example:**  
+```sql
+GRANT ALL PRIVILEGES ON DATABASE fastapi_db TO fastapi_user;
+```
 
-if you make changes to any table locally, then run the below command.
-```bash
-alembic revision --autogenerate -m 'initial migration'
-alembic upgrade head
+---
+
+## **Step 4: Update `.env` File**
+Edit the `.env` file to match your setup.
+
+```env
+DATABASE_URL=postgresql://user:your_password@localhost/hng_fast_api
 ```
+🔹 **Replace:**  
+- `user` → Your **database username**.  
+- `your_password` → Your **database password**.  
+- `hng_fast_api` → Your **database name**.  
 
-**create dummy data**
-```bash
-python3 seed.py
+✅ **Example:**  
+```env
+DATABASE_URL=postgresql://fastapi_user:StrongP@ssw0rd@localhost/fastapi_db
 ```
 
+---
 
-**Adding tables and columns to models**
+## **Step 5: Verify Connection**
+After setting up the database, test the connection:
 
-After creating new tables, or adding new models. Make sure to run alembic revision --autogenerate -m "Migration messge"
+```sh
+psql -U user -d hng_fast_api -h localhost
+```
+🔹 **Replace:**  
+- `user` → Your **database username**.  
+- `hng_fast_api` → Your **database name**.  
 
-After creating new tables, or adding new models. Make sure you import the new model properly in th 'api/v1/models/__init__.py file
+✅ **Example:**  
+```sh
+psql -U fastapi_user -d fastapi_db -h localhost
+```
 
-After importing it in the init file, you need not import it in the /alembic/env.py file anymore
+## **Step 6: Run database migrations**  
+   ```sh
+   alembic upgrade head
+   ```
+   _Do NOT run `alembic revision --autogenerate -m 'initial migration'` initially!_
 
+## **Step 7: If making changes to database models, update migrations**  
+```sh
+   alembic revision --autogenerate -m 'your migration message'
+   alembic upgrade head
+   ```
+## **Step 8: Seed dummy data**  
+   ```sh
+   python3 seed.py
+   ```
 
-**Adding new routes**
+---
 
-To add a new route, confirm if a file relating to that route is not already created. If it is add the route in that file using the already declared router
+## **Adding Tables and Columns**  
 
-If the there is no file relating to the route in the 'api/v1/routes/' directory create a new one following the naming convention
+1. **After creating new tables or modifying models**:  
+   - Run Alembic migrations:  
+     ```sh
+     alembic revision --autogenerate -m "Migration message"
+     alembic upgrade head
+     ```
+   - Ensure you **import new models** into `api/v1/models/__init__.py`.  
+   - You do NOT need to manually import them in `alembic/env.py`.
 
-After creating the new route file, declare the router and add the prefix as well as the tag
+---
 
-The prefix should not include the base prefix ('/api/v1') as it is already includedin the base `api_version_one` router
+## **Adding New Routes**  
 
-After creating the router, import it in the 'api/v1/routes/__init__.py' file and include the router in the `api_version_one` router using
-```python
-api_version_one.include_router(<router_name>)
+1. **Check if a related route file already exists** in `api/v1/routes/`.  
+   - If yes, add your route inside the existing file.  
+   - If no, create a new file following the naming convention.  
+2. **Define the router** inside the new route file:  
+   - Include the prefix (without `/api/v1` since it's already handled).  
+3. **Register the router in `api/v1/routes/__init__.py`**:  
+   ```python
+   from .new_route import router as new_router
+   api_version_one.include_router(new_router)
+   ```
+
+---
+
+## **Running Tests with Pytest**  
+
+### **Install Pytest**  
+Ensure `pytest` is installed in your virtual environment:  
+```sh
+pip install pytest
+```
+
+### **Run all tests in the project**  
+From the **project root directory**, run:  
+```sh
+pytest
+```
+This will automatically discover and execute all test files in the `tests/` directory.
+
+### **Run tests in a specific directory**  
+To run tests in a specific model directory (e.g., `tests/v1/user/`):  
+```sh
+pytest tests/v1/user/
+```
+
+### **Run a specific test file**  
+To run tests from a specific test file (e.g., `test_signup.py` inside `tests/v1/auth/`):  
+```sh
+pytest tests/v1/auth/test_signup.py
+```
+
+### **Run a specific test function**  
+If you want to run a specific test inside a file, use:  
+```sh
+pytest tests/v1/auth/test_signup.py::test_user_signup
 ```
 
-## TEST THE ENDPOINT
-- run the following code
+### **Run tests with detailed output**  
+For verbose output, add the `-v` flag:  
+```sh
+pytest -v
 ```
-python -m unittest tests/v1/test_login.py
-python -m unittest tests/v1/test_signup.py
+
+### **Run tests and generate coverage report**  
+To check test coverage, install `pytest-cov`:  
+```sh
+pip install pytest-cov
+```
+Then run:  
+```sh
+pytest --cov=api
 ```
 
-## Issues
-if you encounter the following Error, when you run the code below
+---
 
-**alembic revision --autogenerate -m 'your migration message'**
+## **Common Migration Issues & Solutions**  
 
+### **Error: "Target database is not up to date."**  
+If you encounter this issue when running:  
+```sh
+alembic revision --autogenerate -m 'your migration message'
 ```
-INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
-INFO  [alembic.runtime.migration] Will assume transactional DDL.
-ERROR [alembic.util.messaging] Target database is not up to date.
-  FAILED: Target database is not up to date.
+#### **Solution**:  
+Run the following command first:  
+```sh
+alembic upgrade head
 ```
+Then retry:  
+```sh
+alembic revision --autogenerate -m 'your migration message'
+```
+
+---
+
+## **Contribution Guidelines**  
 
-## Solutions
-Run the following code below first to update the datebase
-**alembic upgrade head**
-then, run this again.
-**alembic revision --autogenerate -m 'your migration message'**
+- **Test your endpoints and models** before pushing changes.  
+- **Push Alembic migrations** if database models are modified.  
+- Ensure your code **follows project standards** and **passes tests** before submitting a pull request.  
 
-## update 
-please make sure to test your endpoint or model before pushing.
-push your alembic migrations.
+💯 Happy coding!

api/utils/logger.py

@@ -1,6 +1,5 @@
 import logging
 
-# Configure the logging
 logging.basicConfig(
     level=logging.ERROR,
     format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",