various modifications

Author: amirberenji1995

.gitignore

@@ -1,4 +1,5 @@
 __pycache__
 .pytest_cache
 .env
-core/__pycache__
+core/__pycache__
+src/pixy/__pycache__

docs/client.md

@@ -1,25 +1,17 @@
-# Pixy SDK Client API Reference
+# PixyClient API Reference
 
-The Pixy SDK Client is a Python library that provides a simple interface for interacting with the Pixy SDK. It allows you to generate images, videos, and subtitles using the Pixy API. Using the SDK, offers the following functionalities:
-
-1. Generating images, videos, and subtitles
-2. Getting previously generated resources
-3. Updating previously generated resources
-4. Deleting previously generated resources
-
-## Installation
-
-### <span style="color:red">To be added</span>
+The easiest approach to use the Pixy SDK is to initialize a new instance of the PixyClient class, using the API key obtained from the Pixy panel. In this page, we walk through the whole functionalities of the PixyClient class, step by step.
 
 ## Usage
 
-### ```PixyClient(api_key: str)```
+### 1. ```PixyClient(api_key: str, settings: Settings = Settings)```
 
 #### Description:
 Initializes a new instance of the PixyClient class, given the API key. The API key is verified automatically.
 
 #### Args:
 * api_key (str): The API key obtained from the Pixy panel.
+* settings (Settings): The settings to use; stick to the default value, unless you have a custom provider. Checkout the [settings documentation]() for a comprehensive instruction on how to declare custom settings.
 
 #### Example:
 ```python

docs/settings.md

@@ -0,0 +1,35 @@
+# `settings` class
+
+We use a the `settings` class from [settings.py](https://github.com/pixiee-ai/pixy-sdk/blob/main/src/pixy/settings.py) to store the settings that pixy SDK relies on; currently, these settings include:
+
+1. **url_mapping** (dict): The URL mapping to determine the endpoint, given the `generation_type`; stick to the default value, unless you have a custom provider.
+2. **properties_mapping** (dict): The properties mapping to determine the type of the `properties`, given the `generation_type`; stick to the default value, unless you have a custom provider.
+
+This class is initialized with the default values; therefore, unless you are using a custom provider, you don't need to worry about the values it contains. Moreover, as this class is a static class, its attributes are accessible without instantiating it.
+
+In case you are using a custom provider, you are supposed to instanciate from this class with custom endpoints, as below:
+
+```python
+
+from pixy.settings import Settings
+
+settings = Settings(
+    url_mapping = {"image": "https://example.com/image",
+                  "video": "https://example.com/video",
+                  "subtitle": "https://example.com/subtitle"},
+)
+
+```
+
+Don't forget to pass the custom settings to the `PixyClient` class, as well. You are supposed to this, once instanciating from the `PixyClient` class:
+
+```python
+from pixy.client import PixyClient
+
+# assuming that you have declared the custom settings above
+
+client = PixyClient(api_key, settings)
+
+```
+
+You also need to pass the attributes from the custom `settings` class to the functions from the `pixy.utils` module, as well; checkout the [utils documentation](https://github.com/pixiee-ai/pixy-sdk/blob/main/docs/utils.md) for more details.

docs/utils.md

@@ -2,20 +2,21 @@
 
 The Pixy SDK relys on a set of utility function, covering a wide range of tasks. In this section, each of them is discussed individually.
 
-## ```verify(api_key: str) -> bool```
+## ```verify(api_key: str, url: str = Settings.url_mapping.get("api_key_verification")) -> bool```
 
 ### Description:
 Verifies the given API key.
 
 ### Args:
 * api_key (str): The API key to verify.
+* url (str): The URL to call; stick to the default value, unless you have a custom provider.
 
 ### Returns:
 * bool: True if the API key is valid, False otherwise.
 
 ### Example:
 ```python
-from core.utils import verify
+from pixy.utils import verify
 
 api_key = "your_api_key"
 is_valid = verify(api_key)
@@ -24,7 +25,7 @@ print(is_valid)
 >>> True
 ```
 
-## ```generate(generation_type: str, properties: ImageGenProperties | VideoGenProperties | SubtitleGenProperties api_key: str,) -> dict```
+## ```generate(generation_type: str, properties: ImageGenProperties | VideoGenProperties | SubtitleGenProperties api_key: str, url_mapping: dict = Settings.url_mapping, properties_mapping: dict = Settings.properties_mapping,) -> dict```
 
 ### Description:
 Generates a resource (image, video, subtitle) based on the given properties.
@@ -33,14 +34,16 @@ Generates a resource (image, video, subtitle) based on the given properties.
 * generation_type (str): The type of resource to generate; current valid choices are "image", "video" and "subtitle".
 * properties (ImageGenProperties | VideoGenProperties | SubtitleGenProperties): The properties of the resource to generate; current valid choices are ImageGenProperties, VideoGenProperties and SubtitleGenProperties that correspond to "image", "video" and "subtitle", respectively.
 * api_key (str): The API key to use for the request.
+* url_mapping (dict): The URL mapping to determine the endpoint, given the `generation_type`; stick to the default value, unless you have a custom provider.
+* properties_mapping (dict): The properties mapping to determine the type of the `properties`, given the `generation_type`; stick to the default value, unless you have a custom provider.
 
 ### Returns:
 * dict: A JSON response containing the generated resource.
 
 ### Example:
 ```python
-from core.utils import generate
-from core.schemas import ImageGenProperties
+from pixy.utils import generate
+from pixy.schemas import ImageGenProperties
 
 api_key = "your_api_key"
 generation_type = "image"
@@ -94,7 +97,7 @@ print(resource)
 >>>}
 ```
 
-## ```get_by_uid(generation_type: str, uid: str, api_key: str) -> dict```
+## ```get_by_uid(generation_type: str, uid: str, api_key: str, url_mapping: dict = Settings.url_mapping) -> dict```
 
 ### Description:
 Retrieves a resource by its unique identifier (UID).
@@ -103,14 +106,15 @@ Retrieves a resource by its unique identifier (UID).
 * generation_type (str): The type of resource to retrieve; current valid choices are "image", "video" and "subtitle".
 * uid (str): The desired UID.
 * api_key (str): The API key to use for the request.
+* url_mapping (dict): The URL mapping to determine the endpoint, given the `generation_type`; stick to the default value, unless you have a custom provider.
 
 ### Returns:
 * dict: A JSON response inclding the desired resource.
 
 ### Example:
 
 ```python
-from core.utils import get_by_uid
+from pixy.utils import get_by_uid
 
 api_key = "your_api_key"
 generation_type = "image"
@@ -160,24 +164,26 @@ print(resource)
 >>>}
 ```
 
-## ```get_list(generation_type: str, params: GetListParameters | None, api_key: str) -> dict```
+## ```get_list(generation_type: str, api_key: str, params: GetListParameters | None = None, url_mapping: dict = Settings.url_mapping,
+) -> dict```
 
 ### Description:
 Retrieves a list of resources filtered by the given parameters.
 
 ### Args:
 * generation_type (str): The type of resource to retrieve.
-* params (GetListParameters | None): The parameters to filter the results by.
 * api_key (str): The API key to use for the request.
+* params (GetListParameters | None): The parameters to filter the results by; the default value is `None`.
+* url_mapping (dict): The URL mapping to determine the endpoint, given the `generation_type`; stick to the default value, unless you have a custom provider.
 
 ### Returns:
 * dict: A JSON response containing the retrieved resources.
 
 ### Example:
 
 ```python
-from core.schemas import GetListParameters
-from core.utils import get_list
+from pixy.schemas import GetListParameters
+from pixy.utils import get_list
 
 api_key = "your_api_key"
 generation_type = "image"
@@ -191,10 +197,10 @@ params = GetListParameters(
 
 resources = get_list(
     generation_type,
-    params,
     api_key
+    params,
 )
-print(lenresources)
+print(resources)
 
 {
   "items": [
@@ -279,7 +285,7 @@ print(lenresources)
 }
 ```
 
-## ```delete(generation_type: str, uid: str, api_key: str) -> dict```
+## ```delete(generation_type: str, uid: str, api_key: str, url_mapping: dict = Settings.url_mapping) -> dict```
 
 ### Description:
 Deletes a resource by its unique identifier.
@@ -288,14 +294,15 @@ Deletes a resource by its unique identifier.
 * generation_type (str): The type of resource to delete.
 * uid (str): The unique identifier of the resource.
 * api_key (str): The API key to use for the request.
+* url_mapping (dict): The URL mapping to determine the endpoint, given the `generation_type`; stick to the default value, unless you have a custom provider.
 
 ### Returns:
 * dict: A JSON response indicating the result of the deletion.
 
 ### Example:
 
 ```python
-from core.utils import delete
+from pixy.utils import delete
 
 api_key = "your_api_key"
 generation_type = "image"
@@ -343,7 +350,7 @@ response = delete(generation_type, uid, api_key)
 }
 ```
 
-## ```update(generation_type: str, uid: str, properties: dict, api_key: str) -> dict```
+## ```update(generation_type: str, uid: str, properties: dict, api_key: str, url_mapping: dict = Settings.url_mapping) -> dict```
 
 ### Description:
 Updates a resource by its unique identifier with the given properties.
@@ -353,13 +360,14 @@ Updates a resource by its unique identifier with the given properties.
 * uid (str): The unique identifier of the resource.
 * properties (dict): The properties to update the resource with. This is supposed to only include the key-values to update.
 * api_key (str): The API key to use for the request.
+* url_mapping (dict): The URL mapping to determine the endpoint, given the `generation_type`; stick to the default value, unless you have a custom provider.
 
 ### Returns:
 * dict: A JSON response containing the updated resource.
 
 ### Example:
 ```python
-from core.utils import update
+from pixy.utils import update
 
 api_key = "your_api_key"
 generation_type = "image"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pixy-sdk"
-version = "0.0.8"
+version = "0.0.9"
 description = "A python sdk for pixy."
 readme = "README.md"
 requires-python = ">=3.9"

src/pixy/client.py

@@ -16,7 +16,7 @@
 
 
 class PixyClient:
-    def __init__(self, api_key: str, settings: Settings = Settings()):
+    def __init__(self, api_key: str, settings: Settings = Settings):
         """
         Initialize the Pixy client.
 

src/pixy/settings.py

@@ -1,36 +1,21 @@
 from .schemas import ImageGenProperties, VideoGenProperties, SubtitleGenProperties
 
 
-class _Settings:
-
+class Settings:
     url_mapping = {
         "api_key_verification": "https://sso.pixy.ir/api_key/verify",
         "image": "https://media.pixy.ir/v1/apps/imagine/imagination/",
         "video": "https://media.pixy.ir/v1/apps/videogen/videos/",
         "subtitle": "https://media.pixy.ir/v1/apps/subtitle/subtitles/",
     }
-
     properties_mapping = {
         "image": ImageGenProperties,
         "video": VideoGenProperties,
         "subtitle": SubtitleGenProperties,
     }
 
-
-class Settings:
-    def __init__(
-        self,
-        url_mapping: dict = {
-            "api_key_verification": "https://sso.pixy.ir/api_key/verify",
-            "image": "https://media.pixy.ir/v1/apps/imagine/imagination/",
-            "video": "https://media.pixy.ir/v1/apps/videogen/videos/",
-            "subtitle": "https://media.pixy.ir/v1/apps/subtitle/subtitles/",
-        },
-        properties_mapping: dict = {
-            "image": ImageGenProperties,
-            "video": VideoGenProperties,
-            "subtitle": SubtitleGenProperties,
-        },
-    ):
-        self.url_mapping = url_mapping
-        self.properties_mapping = properties_mapping
+    def __init__(self, url_mapping: dict = None, properties_mapping: dict = None):
+        if url_mapping is not None:
+            self.url_mapping = url_mapping
+        if properties_mapping is not None:
+            self.properties_mapping = properties_mapping

src/pixy/utils.py

@@ -14,11 +14,10 @@
 logger.addHandler(console_handler)
 
 logger.setLevel(logging.INFO)
-settings = Settings()
 
 
 def verify(
-    api_key: str, url: str = settings.url_mapping.get("api_key_verification")
+    api_key: str, url: str = Settings.url_mapping.get("api_key_verification")
 ) -> bool:
     """
     Verifies the given API key.
@@ -58,8 +57,8 @@ def generate(
     generation_type: str,
     properties: ImageGenProperties | VideoGenProperties | SubtitleGenProperties,
     api_key: str,
-    url_mapping: dict = settings.url_mapping,
-    properties_mapping: dict = settings.properties_mapping,
+    url_mapping: dict = Settings.url_mapping,
+    properties_mapping: dict = Settings.properties_mapping,
 ) -> dict:
     """
     Generates a resource (image, video, subtitle) based on the given properties.
@@ -130,7 +129,7 @@ def get_by_uid(
     generation_type: str,
     uid: str,
     api_key: str,
-    url_mapping: dict = settings.url_mapping,
+    url_mapping: dict = Settings.url_mapping,
 ) -> dict:
     """
     Retrieves a resource by its unique identifier (UID).
@@ -166,8 +165,8 @@ def get_list(
     generation_type: str,
     api_key: str,
     params: GetListParameters | None = None,
-    url_mapping: dict = settings.url_mapping,
-):
+    url_mapping: dict = Settings.url_mapping,
+) -> dict:
     """
     Retrieves a list of resources filtered by the given parameters.
 
@@ -205,7 +204,7 @@ def delete(
     generation_type: str,
     uid: str,
     api_key: str,
-    url_mapping: dict = settings.url_mapping,
+    url_mapping: dict = Settings.url_mapping,
 ) -> dict:
     """
     Deletes a resource by its unique identifier.
@@ -243,7 +242,7 @@ def update(
     uid: str,
     properties: dict,
     api_key: str,
-    url_mapping: dict = settings.url_mapping,
+    url_mapping: dict = Settings.url_mapping,
 ) -> dict:
     """
     Updates a resource by its unique identifier with the given properties.

tests/test_schemas.py

@@ -1,4 +1,4 @@
-from pixy.schemas import (
+from src.pixy.schemas import (
     ImageGenEngine,
     ImageGenProperties,
     SubtitleGenProperties,

tests/test_utils.py

@@ -1,5 +1,5 @@
-from pixy.utils import verify, generate
-from core.schemas import ImageGenProperties, SubtitleGenProperties
+from src.pixy.utils import verify, generate
+from src.pixy.schemas import ImageGenProperties, SubtitleGenProperties
 import pytest
 from pydantic import BaseModel
 from typing import Literal