crud_base addition, better readme, script to generate initial super user

Author: igorbenav

LICENSE renamed to LICENSE.md

@@ -1,13 +1,106 @@
 # FastAPI-boilerplate
-A boilerplate for Fastapi
+>A template to speed your FastAPI development up.
 
+## About
+**FastAPI boilerplate** creates an extendable async API using FastAPI, Pydantic V2, SQLAlchemy 2.0 and PostgreSQL:
+- [`FastAPI`](https://fastapi.tiangolo.com): modern Python web framework for building APIs
+- [`Pydantic V2`](https://docs.pydantic.dev/2.4/): the most widely used data validation library for Python now rewritten in Rust [`(5x to 50x speed improvement)`](https://docs.pydantic.dev/latest/blog/pydantic-v2-alpha/)
+- [`SQLAlchemy 2.0`](https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html): Python SQL toolkit and Object Relational Mapper
+- [`PostgreSQL`](https://www.postgresql.org): The World's Most Advanced Open Source Relational Database
+
+## Features
+  - Fully async
+  - Pydantic V2 and SQLAlchemy 2.0
+  - User authentication with JWT
+  - Easily extendable
+  - Flexible
+
+
+# Usage
+___
+## Start by cloning the repository
+```sh
+git clone https://github.com/igormagalhaesr/FastAPI-boilerplate
+```
+___
+## Requirements
+### Packages
+Then install poetry:
+```sh
+pip install poetry
+```
+
+In the **src** directory, run to install required packages:
+```sh
+poetry install
+```
+
+### Environment Variables
+Then create a .env file:
+```sh
+touch .env
+```
+
+Inside of .env, create the following app settings variables:
+```
+# ------------- app settings ------------- 
+APP_NAME="Your app name here"
+APP_DESCRIPTION="Your app description here"
+APP_VERSION="0.1"
+CONTACT_NAME="Your name"
+CONTACT_EMAIL="Your email"
+LICENSE_NAME="The license you picked"
+```
+
+For the database ([`if you don't have a database yet, click here`](#running-postgresql-with-docker)), create: 
+```
+# ------------- database ------------- 
+POSTGRES_USER="your_postgres_user"
+POSTGRES_PASSWORD="your_password"
+POSTGRES_SERVER="your_server" # default localhost
+POSTGRES_PORT=5432 
+POSTGRES_DB="your_db"
+```
+
+For crypt:
+Start by running
+```sh
+openssl rand -hex 32
+```
+
+And then create in .env:
+```
+# ------------- crypt -------------
+SECRET_KEY= # result of openssl rand -hex 32
+ALGORITHM= # pick an algorithm, default HS256
+ACCESS_TOKEN_EXPIRE_MINUTES= # minutes until token expires, default 30
+```
+
+For tests, create:
+```
+# ------------- test -------------
+TEST_EMAIL="[email protected]"
+TEST_USERNAME="testeruser"
+TEST_PASSWORD="Str1ng$t"
+```
+
+And finally for the first admin user:
+```
+# ------------- admin -------------
+ADMIN_NAME="your_name"
+ADMIN_EMAIL="your_email"
+ADMIN_USERNAME="your_username"
+ADMIN_PASSWORD="your_password"
+```
+
+___
 ## Running PostgreSQL with docker:
-After installing docker, run:
+Install docker if you don't have it yet, then run:
 ```sh
 docker pull postgres
 ```
 
-Then pick the port, name, user and password and replace them:
+And pick the port, name, user and password, replacing the fields:
 ```sh
 docker run -d \
     -p {PORT}:{PORT} \
@@ -27,11 +120,56 @@ docker run -d \
     postgres
 ```
 
-And create the variables in a .env file in the src folder:
+[`If you didn't create the .env variables yet, click here.`](#environment-variables)
+
+___
+## Running the api
+While in the **src** folder, run to start the application with uvicorn server:
+```sh
+poetry run uvicorn app.main:app --reload
+```
+
+___
+## Creating the first superuser:
+While in the **src** folder, run (after you started the application at least once to create the tables):
+```sh
+poetry run python -m scripts.create_first_superuser
+```
+
+___
+## Database Migrations
+Migrations done via [Alembic](https://alembic.sqlalchemy.org/en/latest/):
+
+Whenever you change somethin in the database, in the **src** directory, run to create the script:
+```sh
+poetry run alembic revision --autogenerate
 ```
-POSTGRES_USER="postgres"
-POSTGRES_PASSWORD=1234
-POSTGRES_SERVER="localhost"
-POSTGRES_PORT=5432
-POSTGRES_DB="postgres"
+
+And to actually migrate:
+```sh
+poetry run alembic upgrade head
 ```
+
+___
+## Testing
+TODO
+
+___
+# Other stuff
+## Contributing
+1. Fork it (https://github.com/igormagalhaesr/FastAPI-boilerplate)
+2. Create your feature branch (`git checkout -b feature/fooBar`)
+3. Test your changes while in the src folder `poetry run python -m pytest`
+4. Commit your changes (`git commit -am 'Add some fooBar'`)
+5. Push to the branch (`git push origin feature/fooBar`)
+6. Create a new Pull Request
+
+## References
+TODO
+
+## License
+[`MIT`](LICENSE.md)
+
+## Contact
+Igor Magalhaes – [@igormagalhaesr](https://twitter.com/igormagalhaesr) – [email protected]
+[github.com/igormagalhaesr](https://github.com/igormagalhaesr/)

README.md

@@ -4,45 +4,39 @@
 
 from sqlalchemy.ext.asyncio import AsyncSession
 from jose import JWTError, jwt
-from fastapi import Depends, HTTPException, status
+from fastapi import Depends, HTTPException
 
 from app.core.database import async_get_db
-from app.crud.crud_users import get_user_by_email, get_user_by_username
 from app.core.models import TokenData
 from app.models.user import User
+from app.crud.crud_users import crud_users
+from app.api.exceptions import credentials_exception, privileges_exception
 
 async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)], db: Annotated[AsyncSession, Depends(async_get_db)]):
-    credentials_exception = HTTPException(
-        status_code=status.HTTP_401_UNAUTHORIZED,
-        detail="Could not validate credentials",
-        headers={"WWW-Authenticate": "Bearer"},
-    )
     try:
         payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
         username_or_email: str = payload.get("sub")
         if username_or_email is None:
             raise credentials_exception
         token_data = TokenData(username_or_email=username_or_email)
-    
     except JWTError:
         raise credentials_exception
 
     if "@" in username_or_email:
-        user = await get_user_by_email(db=db, email=token_data.username_or_email)
+        user = await crud_users.get(db=db, email=token_data.username_or_email)
     else: 
-        user = await get_user_by_username(db=db, username=token_data.username_or_email)
+        user = await crud_users.get(db=db, username=token_data.username_or_email)
 
     if user is None:
         raise credentials_exception
 
     if user.is_deleted:
-        raise HTTPException(status_code=400, detai="User deleted")
+        raise HTTPException(status_code=400, detail="User deleted")
 
     return user
 
 def get_current_superuser(current_user: Annotated[User, Depends(get_current_user)]) -> User:
     if not current_user.is_superuser:
-        raise HTTPException(
-            status_code=403, detail="The user doesn't have enough privileges"
-        )
+        raise privileges_exception
+    
     return current_user

src/app/api/dependencies.py

@@ -0,0 +1,12 @@
+from fastapi import HTTPException, status
+
+credentials_exception = HTTPException(
+    status_code=status.HTTP_401_UNAUTHORIZED,
+    detail="Incorrect email, username or password",
+    headers={"WWW-Authenticate": "Bearer"},
+)
+
+privileges_exception = HTTPException(
+    status_code=403, 
+    detail="The user doesn't have enough privileges"
+)

src/app/api/exceptions.py

@@ -1,13 +1,15 @@
 from typing import Annotated
 from datetime import timedelta
 
-from fastapi import Depends, HTTPException, status
+from fastapi import Depends
 from fastapi.security import OAuth2PasswordRequestForm
 from sqlalchemy.ext.asyncio import AsyncSession
 import fastapi
+
 from app.core.database import async_get_db
 from app.core.models import Token
-from app.core.security import create_access_token, authenticate_user_by_username, authenticate_user_by_email, ACCESS_TOKEN_EXPIRE_MINUTES
+from app.core.security import ACCESS_TOKEN_EXPIRE_MINUTES, create_access_token, authenticate_user
+from app.api.exceptions import credentials_exception
 
 router = fastapi.APIRouter(tags=["login"])
 
@@ -16,19 +18,18 @@ async def login_for_access_token(
     form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
     db: AsyncSession = Depends(async_get_db)
 ):
-    if "@" in form_data.username:
-        user = await authenticate_user_by_email(form_data.username, form_data.password, db=db)
-    else:
-        user = await authenticate_user_by_username(form_data.username, form_data.password, db=db)
 
+    user = await authenticate_user(
+        username_or_email=form_data.username, 
+        password=form_data.password, 
+        db=db
+    )
     if not user:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Incorrect email, username or password",
-            headers={"WWW-Authenticate": "Bearer"},
-        )
+        raise credentials_exception
+    
     access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
     access_token = await create_access_token(
         data={"sub": user.username}, expires_delta=access_token_expires
     )
+    
     return {"access_token": access_token, "token_type": "bearer"}