Merge pull request #42 from piercefreeman/feature/mountaineer-docs

Add docstrings for dependency injection helpers

iceaxe/mountaineer/config.py

@@ -2,8 +2,37 @@
 
 
 class DatabaseConfig(BaseSettings):
+    """
+    Configuration settings for PostgreSQL database connection.
+    This class uses Pydantic's BaseSettings to manage environment-based configuration.
+    """
+
     POSTGRES_HOST: str
+    """
+    The hostname where the PostgreSQL server is running.
+    This can be a domain name or IP address (e.g., 'localhost' or '127.0.0.1').
+    """
+
     POSTGRES_USER: str
+    """
+    The username to authenticate with the PostgreSQL server.
+    This user should have appropriate permissions for the database operations.
+    """
+
     POSTGRES_PASSWORD: str
+    """
+    The password for authenticating the PostgreSQL user.
+    This should be kept secure and not exposed in code or version control.
+    """
+
     POSTGRES_DB: str
+    """
+    The name of the PostgreSQL database to connect to.
+    This database should exist on the server before attempting connection.
+    """
+
     POSTGRES_PORT: int = 5432
+    """
+    The port number where PostgreSQL server is listening.
+    Defaults to the standard PostgreSQL port 5432 if not specified.
+    """

iceaxe/mountaineer/dependencies/core.py

@@ -17,6 +17,35 @@ async def get_db_connection(
         CoreDependencies.get_config_with_type(DatabaseConfig)
     ),
 ) -> AsyncGenerator[DBConnection, None]:
+    """
+    A dependency that provides a database connection for use in FastAPI endpoints or other
+    dependency-injected contexts. The connection is automatically closed when the endpoint
+    finishes processing.
+
+    This dependency:
+    - Creates a new PostgreSQL connection using the provided configuration
+    - Wraps it in a DBConnection for ORM functionality
+    - Automatically closes the connection when done
+    - Integrates with Mountaineer's dependency injection system
+
+    :param config: DatabaseConfig instance containing connection parameters.
+                  Automatically injected by Mountaineer if not provided.
+    :return: An async generator yielding a DBConnection instance
+
+    ```python
+    from fastapi import FastAPI, Depends
+    from iceaxe.mountaineer.dependencies import get_db_connection
+    from iceaxe.session import DBConnection
+
+    app = FastAPI()
+
+    # Basic usage in a FastAPI endpoint
+    @app.get("/users")
+    async def get_users(db: DBConnection = Depends(get_db_connection)):
+        users = await db.exec(select(User))
+        return users
+    ```
+    """
     conn = await asyncpg.connect(
         host=config.POSTGRES_HOST,
         port=config.POSTGRES_PORT,