API Documentation

This section describes the API routes provided by the Vocabulary Builder application. It includes details on request and response formats, authentication, and error handling.

Authentication and Authorization

This module handles user authentication and JWT token management.

This module provides functions and classes for user authentication, including password hashing, user verification, and JWT token management.

vocabulary_builder.utils.auth.authenticate_user(username: str, password: str, db: Session = Depends(get_db)) → UserBase | bool

Authenticate a user by username and password.

Parameters:

  • username – Username.

  • password – Password.

  • db – Database session dependency.

Returns:

User representation if authentication is successful, False otherwise.

vocabulary_builder.utils.auth.create_access_token(data: dict, expires_delta: timedelta) → str

Create a JWT access token.

Parameters:

  • data – Data to encode in the token.

  • expires_delta – Token expiration time.

Returns:

Encoded JWT token.

async vocabulary_builder.utils.auth.get_current_user(token: str = Depends(OAuth2PasswordBearerWithCookie), db: Session = Depends(get_db)) → UserBase

Get the current user based on the JWT token.

Parameters:

  • token – JWT token.

  • db – Database session dependency.

Returns:

Current user.

vocabulary_builder.utils.auth.get_hashed_password(password: str) → str

Hash a plain text password using bcrypt.

Parameters:

password – Plain text password.

Returns:

Hashed password.

vocabulary_builder.utils.auth.verify_password(plain_password: str, hashed_password: str) → bool

Verify a plain text password against a hashed password.

Parameters:

  • plain_password – Plain text password.

  • hashed_password – Hashed password.

Returns:

True if the passwords match, False otherwise.

Translation Handling

This module provides translation functionalities across different languages.

This module provides functions and classes for handling translations across different languages using gettext.

class vocabulary_builder.utils.translations.LanguageModel(value)

Enumeration of supported languages.

vocabulary_builder.utils.translations._(language: str) → Callable[[str], str]

Retrieve the gettext translation function for the specified language.

Parameters:

language – Language code (e.g., ‘ru’, ‘fr’).

Returns:

The translation function for the specified language.

Routes for Pages

These routes render HTML pages for different parts of the application.

Routes for rendering HTML pages

async vocabulary_builder.routes.pages.get_favorite_words(request: Request, language: LanguageModel = LanguageModel.ru, current_user: UserBase = Depends(get_current_user)) → HTMLResponse

Retrieve favorite words for the current user.

Parameters:

  • request – HTTP request.

  • language – Language code.

  • current_user – Current user dependency.

Returns:

HTML response with the favorite words.

vocabulary_builder.routes.pages.get_learn_page_in_language(request: Request, language: LanguageModel = LanguageModel.ru, current_user: UserBase = Depends(get_current_user)) → HTMLResponse

Endpoint to learn a new word for the current user.

Parameters:

  • request – HTTP request.

  • language – Language code.

  • current_user – Current user dependency.

Returns:

HTML response with the learn page content for logged-in user.

vocabulary_builder.routes.pages.get_main_page_in_language(request: Request, language: LanguageModel = LanguageModel.ru, db: Session = Depends(get_db)) → HTMLResponse

Serve the main page in the specified language.

Parameters:

  • request – HTTP request.

  • language – Language code (e.g., ‘ru’, ‘fr’).

  • db – Database session dependency.

Returns:

HTML response with the main page content in the specified language.

async vocabulary_builder.routes.pages.get_tests_page(request: Request, language: LanguageModel = LanguageModel.ru, current_user: UserBase = Depends(get_current_user)) → HTMLResponse

Serve the tests page.

Parameters:

  • request – HTTP request.

  • language – Language code.

  • current_user – Current user dependency.

Returns:

HTML response with the tests page.

vocabulary_builder.routes.pages.login_page(request: Request, language: LanguageModel = LanguageModel.ru) → HTMLResponse

Serve the login page.

Parameters:

  • request – HTTP request.

  • language – Language code.

Returns:

HTML response with the login page.

async vocabulary_builder.routes.pages.page_not_found(request: Request, language: LanguageModel = LanguageModel.ru) → HTMLResponse

Serve the error page with a custom image based on the status code and language.

Parameters:

  • request – HTTP request.

  • language – Language code.

Returns:

HTML response with the error page.

vocabulary_builder.routes.pages.register_page(request: Request, language: LanguageModel = LanguageModel.ru) → HTMLResponse

Serve the registration page.

Parameters:

  • request – HTTP request.

  • language – Language code.

Returns:

HTML response with the registration page.

API Endpoints

This section covers the API routes for interacting with words and user data.

Module providing an API route to fetch a new random word

vocabulary_builder.routes.words.get_new_word(db: Session = Depends(get_db)) → dict

Fetch a new random word and return it as a JSON response.

Parameters:

db – Database session dependency.

Returns:

JSON response with the new word data, or a message if no word is found.

API routes for managing user saved words

async vocabulary_builder.routes.users.get_saved_words(user_id: Annotated[UUID, UuidVersion(uuid_version=4)], db: Session = Depends(get_db)) → list[dict]

Retrieve saved words for the user.

Parameters:

  • user_id – User ID.

  • db – Database session dependency.

Returns:

List of dictionaries containing saved words information.

async vocabulary_builder.routes.users.remove_word(user_id: Annotated[UUID, UuidVersion(uuid_version=4)], word: WordBase, db: Session = Depends(get_db)) → dict

Remove a word for the user.

Parameters:

  • user_id – User ID.

  • word – Word data to be removed.

  • db – Database session dependency.

Returns:

JSON response with a success message.

async vocabulary_builder.routes.users.save_word(user_id: Annotated[UUID, UuidVersion(uuid_version=4)], word: WordBase, db: Session = Depends(get_db)) → dict

Save a word for the user.

Parameters:

  • user_id – User ID.

  • word – Word data to be saved.

  • db – Database session dependency.

Returns:

JSON response with a success message.

User authentication and registration routes

async vocabulary_builder.routes.auth.login_for_access_token(username: str = Form(PydanticUndefined), password: str = Form(PydanticUndefined), language: str = Form(ru), db: Session = Depends(get_db)) → RedirectResponse

Endpoint to log in and get an access token.

Parameters:

  • username – Username from form data.

  • password – Password from form data.

  • language – Language from form data (default is ‘ru’).

  • db – Database session dependency.

Returns:

Redirect response to learn page with JWT access token cookie.

async vocabulary_builder.routes.auth.logout(language: LanguageModel = LanguageModel.ru) → RedirectResponse

Endpoint to log out and remove the access token cookie.

Parameters:

  • request – HTTP request.

  • response – HTTP response.

  • language – Language parameter (default is ‘ru’).

Returns:

Redirect to the home page or login page.

async vocabulary_builder.routes.auth.register_user(username: str = Form(PydanticUndefined), password: str = Form(PydanticUndefined), language: str = Form(ru), db: Session = Depends(get_db)) → RedirectResponse

Endpoint to register a new user.

Parameters:

  • username – Username from form data.

  • password – Password from form data.

  • language – Language from form data (default is ‘ru’).

  • db – Database session dependency.

Returns:

Redirect response to login page with language parameter.

Custom Exceptions

The following exceptions are used in the API to handle errors gracefully.

Custom exceptions for the application.

exception vocabulary_builder.exceptions.BadIdentifier

Exception raised for a bad identifier.

exception vocabulary_builder.exceptions.CredentialsException

Exception raised for invalid credentials.

exception vocabulary_builder.exceptions.IncorrectUsernamePasswordException

Exception raised for incorrect username or password.

exception vocabulary_builder.exceptions.UserNotFound

Exception raised when a user is not found.

exception vocabulary_builder.exceptions.WordNotFound

Exception raised when a word is not found.