Merge pull request #2 from birddevelper/docs

Docs

Author: birddevelper

docs/source/API parameters.rst

@@ -0,0 +1,64 @@
+API Parameters
+===================
+
+dequest provides `PathParameter`, `QueryParameter`, `FormParameter` and `JsonBody` to handle API parameters. 
+
+Path Parameters
+---------------
+
+Use `PathParameter` to include values in the URL:
+
+.. code-block:: python
+
+   from dequest import sync_client, PathParameter
+
+   @sync_client(url="https://api.example.com/users/{user_id}")
+   def get_user(user_id: PathParameter[int]):
+       pass
+
+   user = get_user(user_id=42)
+   print(user)
+
+Query Parameters
+----------------
+
+Use `QueryParameter` to pass values as query parameters:
+
+.. code-block:: python
+
+   from dequest import sync_client, QueryParameter
+
+   @sync_client(url="https://api.example.com/search")
+   def search(keyword: QueryParameter[str, "q"]):
+       pass
+
+   results = search(keyword="python")
+   print(results)
+
+
+In endpoint function definitions, `QueryParameter`, `PathParameter`, `FormParameter`, and `JsonBody` parameters support two optional arguments:
+
+1. **Type Hint (First Argument)**  
+   
+   You can provide a type hint (e.g., `str`, `int`, `bool`, etc.) as the first argument. This enables automatic type checking and validation before making the API call.
+
+   **Example:**
+
+.. code-block:: python
+
+   keyword: QueryParameter[str]
+
+This ensures that `keyword` must be a string when passed to the function.
+
+2. **Mapping Name (Second Argument)**  
+   The second argument is an optional string that lets you map the Python parameter name to the actual API parameter name.
+
+   **Example:**
+
+.. code-block:: python
+
+   keyword: QueryParameter[str, "q"]
+
+This maps the `keyword` parameter in your function to the `q` query parameter in the API request.
+
+These features help keep your code type-safe and aligned with external API schemas. Note that each of these arguments can be used alone.

docs/source/API_parameters.rst

@@ -9,4 +9,7 @@ To improve performance, `dequest` can cache responses.
    def get_popular():
        pass
 
-The response will be stored for 60 seconds, reducing API calls. It generates a cache_key by combining the URL, including the values of path parameters, with query parameters, ensuring that an API request with different query parameters is cached separately for each paramter set.
+The response will be stored for 60 seconds, reducing API calls. It generates a cache_key by combining the URL, including the values of path parameters, with query parameters, ensuring that an API request with different query parameters is cached separately for each paramter set.
+
+
+The cache featues supports `in_memory`, `redis`, and `django` cache that can be configured using `DequestConfig`.

docs/source/caching.rst

@@ -7,8 +7,8 @@ To use a circuit breaker with `dequest`, create an instance of `CircuitBreaker`
 
 .. code-block:: python
 
-   from dequest.clients import sync_client
-   from dequest.circuit_breaker import CircuitBreaker
+   from dequest import sync_client
+   from dequest import CircuitBreaker
 
    # Define a Circuit Breaker with failure threshold of 3 and recovery timeout of 10 seconds
    breaker = CircuitBreaker(failure_threshold=3, recovery_timeout=10)
@@ -22,8 +22,8 @@ Note The retry logic wraps the entire operation so that only if all attempts fai
 
 .. code-block:: python
 
-   from dequest.clients import sync_client
-   from dequest.circuit_breaker import CircuitBreaker
+   from dequest import sync_client
+   from dequest import CircuitBreaker
 
    breaker = CircuitBreaker(failure_threshold=3, recovery_timeout=10)
 
@@ -40,7 +40,7 @@ When the circuit breaker is open, calling the function will raise a `CircuitBrea
 
 .. code-block:: python
 
-   from dequest.circuit_breaker import CircuitBreakerOpenError
+   from dequest import CircuitBreakerOpenError
 
    try:
        response = fetch_data()
@@ -57,7 +57,7 @@ For example, if the main API fails, we can return a cached response or default d
 .. code-block:: python
 
    from dequest import sync_client
-   from dequest.circuit_breaker import CircuitBreaker
+   from dequest import CircuitBreaker
 
    # Define a fallback function
    def fallback_response():

docs/source/circuit_breaker.rst

@@ -2,12 +2,12 @@
 
 # -- Project information
 
-project = 'Lumache'
-copyright = '2021, Graziella'
-author = 'Graziella'
+project = 'Dequest'
+copyright = '2025, M.Shaeri'
+author = 'M.Shaeri'
 
-release = '0.1'
-version = '0.1.0'
+release = '0.2.0'
+version = '0.2.0'
 
 # -- General configuration
 

docs/source/conf.py

@@ -8,16 +8,25 @@ Cache Provider
 
 .. code-block:: python
 
-   from dequest.config import DequestConfig
+   from dequest import DequestConfig
 
    DequestConfig.CACHE_PROVIDER = "redis"  # Options: "in_memory", "redis" and "django"
 
 Redis Configuration
 -------------------
 If you set "redis" as cache provider, you should set the redis server configuration also.
+
 .. code-block:: python
 
-   DequestConfig.REDIS_HOST = "localhost"
-   DequestConfig.REDIS_PORT = 6379
-   DequestConfig.REDIS_PASSWORD = None
-   DequestConfig.REDIS_SSL = False
+   from dequest import DequestConfig
+
+   DequestConfig.config(
+      cache_provider="redis", # defaults to "in_memory"
+      redis_host="my-redis-server.com",
+      redis_port=6380,
+      redis_db=1,
+      redis_password="securepassword",
+      redis_ssl=True,
+   )
+
+Calling the `.config()` method is optional. You can use it during application initialization if you need to specify custom configurations instead of the defaults.

docs/source/config.rst

@@ -1,4 +1,4 @@
-.. Dequest Documentation
+Dequest Documentation
 ========================
 
 Welcome to the documentation for `dequest`, a Python library for declarative HTTP requests. `dequest` provides powerful decorators for synchronous and asynchronous API calls, with built-in support for retries, caching, circuit breakers, and more.
@@ -7,12 +7,12 @@ Welcome to the documentation for `dequest`, a Python library for declarative HTT
    :caption: Contents:
 
    installation
+   config
    sync_client
    async_client
    retry
-   config
    caching
    circuit_breaker
-   API parameters
+   API_parameters
 
 

docs/source/index.rst

@@ -1,4 +1,4 @@
-Automatic Retries
+Retry
 =================
 
 If an API request fails due to network issues or server errors, `dequest` can automatically retry the request.