docs upd

docs/modules/captcha-instrument/info.rst

@@ -0,0 +1,12 @@
+FileInstrument
+==============
+
+To import this module:
+
+.. code-block:: python
+
+    from python3_capsolver.core import captcha_instrument
+
+
+.. autoclass:: python3_capsolver.core.captcha_instrument.FileInstrument
+    :members:

docs/modules/enum/info.rst

@@ -23,3 +23,7 @@ To import this module:
 .. autoclass:: python3_capsolver.core.enum.CaptchaTypeEnm
     :members:
     :undoc-members:
+
+.. autoclass:: python3_capsolver.core.enum.SaveFormatsEnm
+    :members:
+    :undoc-members:

src/python3_capsolver/core/aio_captcha_instrument.py

@@ -9,12 +9,12 @@
 from .const import REQUEST_URL, VALID_STATUS_CODES, GET_BALANCE_POSTFIX
 from .utils import attempts_generator
 from .serializer import CaptchaResponseSer
-from .captcha_instrument import CaptchaInstrument
+from .captcha_instrument import CaptchaInstrumentBase
 
 __all__ = ("AIOCaptchaInstrument",)
 
 
-class AIOCaptchaInstrument(CaptchaInstrument):
+class AIOCaptchaInstrument(CaptchaInstrumentBase):
     """
     Instrument for working with async captcha
     """
@@ -84,12 +84,12 @@ async def __get_result(self, url_postfix: str = EndpointPostfixEnm.GET_TASK_RESU
                 # if captcha just created or in processing now - wait
                 await asyncio.sleep(self.captcha_params.sleep_time)
 
-            # default response if server is silent
-            self.result.errorId = 1
-            self.result.errorCode = self.CAPTCHA_UNSOLVABLE
-            self.result.errorDescription = "Captcha not recognized"
-            self.result.taskId = self.created_task_data.taskId
-            self.result.status = ResponseStatusEnm.Failed
+        # default response if server is silent
+        self.result.errorId = 1
+        self.result.errorCode = self.CAPTCHA_UNSOLVABLE
+        self.result.errorDescription = self.CAPTCHA_UNSOLVABLE_DESCRIPTION
+        self.result.taskId = self.created_task_data.taskId
+        self.result.status = ResponseStatusEnm.Failed
 
     @staticmethod
     async def send_post_request(payload: Optional[dict] = None, url_postfix: str = GET_BALANCE_POSTFIX) -> dict:

src/python3_capsolver/core/base.py

@@ -6,7 +6,7 @@
 from .const import REQUEST_URL
 from .serializer import RequestCreateTaskSer, RequestGetTaskResultSer
 from .context_instr import AIOContextManager, SIOContextManager
-from .captcha_instrument import CaptchaInstrument
+from .captcha_instrument import CaptchaInstrumentBase
 from .aio_captcha_instrument import AIOCaptchaInstrument
 from .sio_captcha_instrument import SIOCaptchaInstrument
 
@@ -38,7 +38,7 @@ def __init__(
         # prepare `get task result` payload
         self.get_result_params = RequestGetTaskResultSer(clientKey=api_key)
         self.request_url = request_url
-        self._captcha_handling_instrument = CaptchaInstrument()
+        self._captcha_handling_instrument = CaptchaInstrumentBase()
         self.sleep_time = sleep_time
 
     def captcha_handler(self, task_payload: Dict) -> Dict[str, Any]:

src/python3_capsolver/core/captcha_instrument.py

@@ -13,10 +13,26 @@
 from .const import RETRIES, ASYNC_RETRIES
 from .serializer import CaptchaResponseSer
 
-__all__ = ("CaptchaInstrument", "FileInstrument")
+__all__ = ("CaptchaInstrumentBase", "FileInstrument")
 
 
 class FileInstrument:
+    """
+    This class contains usefull methods for async and async files processing to prepare them for solving
+
+    Examples:
+        >>> from python3_capsolver.core.captcha_instrument import FileInstrument
+        >>> body = FileInstrument().file_processing(captcha_file="captcha_example.jpeg")
+        /9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAoHCBUVxxxxx
+
+        >>> from python3_capsolver.core.captcha_instrument import FileInstrument
+        >>> body = FileInstrument().file_processing(captcha_link="https://some-url/file.jpeg")
+        /9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAoHCBUVxxxxx
+
+    Returns:
+        String with decoded file data
+    """
+
     @staticmethod
     def _local_file_captcha(captcha_file: str):
         """
@@ -80,6 +96,33 @@ def file_processing(
         file_extension: str = "png",
         **kwargs,
     ) -> str:
+        """
+        Synchronous method for captcha image processing.
+         - Method can read local file and return it's as base64 string.
+         - Method can read file URL and return it's as base64 string.
+         - Method can decode base64 bytes and return it's as base64 string.
+
+        Args:
+            captcha_link: URL link to file. Instrument will send GET request to it and read content
+            captcha_file: Local file path. Instrument will read it
+            captcha_base64: Readed file base64 data. Instrument will decode it in ``utf-8``
+            save_format: This arg works only with ``captcha_link`` arg
+                            If ``SaveFormatsEnm.CONST`` is set - file will be loaded and saved locally.
+            img_clearing: This arg works only with ``captcha_link`` arg
+                            If ``False`` - file wil not be removed downloading and saving locally
+            file_path: This arg works only with ``captcha_link`` and ``SaveFormatsEnm.CONST`` args
+                        In this param u can set locally path for downloaded file saving
+            file_extension: This arg works only with ``file_path`` args
+                        In this param u MUST set file format for saving
+
+        Examples:
+            >>> from python3_capsolver.core.captcha_instrument import FileInstrument
+            >>> body = FileInstrument().file_processing(captcha_file="captcha_example.jpeg")
+            /9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAoHCBUVxxxxx
+
+        Returns:
+            String with decoded file data
+        """
         # if a local file link is passed
         if captcha_file:
             return base64.b64encode(self._local_file_captcha(captcha_file=captcha_file)).decode("utf-8")
@@ -109,6 +152,35 @@ async def aio_file_processing(
         file_extension: str = "png",
         **kwargs,
     ) -> str:
+        """
+        Asynchronous method for captcha image processing.
+         - Method can read local file and return it's as base64 string.
+         - Method can read file URL and return it's as base64 string.
+         - Method can decode base64 bytes and return it's as base64 string.
+
+        Args:
+            captcha_link: URL link to file. Instrument will send GET request to it and read content
+            captcha_file: Local file path. Instrument will read it
+            captcha_base64: Readed file base64 data. Instrument will decode it in ``utf-8``
+            save_format: This arg works only with ``captcha_link`` arg
+                            If ``SaveFormatsEnm.CONST`` is set - file will be loaded and saved locally.
+            img_clearing: This arg works only with ``captcha_link`` arg
+                            If ``False`` - file wil not be removed downloading and saving locally
+            file_path: This arg works only with ``captcha_link`` and ``SaveFormatsEnm.CONST`` args
+                        In this param u can set locally path for downloaded file saving
+            file_extension: This arg works only with ``file_path`` args
+                        In this param u MUST set file format for saving
+
+        Examples:
+            >>> import asyncio
+            >>> from python3_capsolver.core.captcha_instrument import FileInstrument
+            >>> body = asyncio.run(FileInstrument()
+            ...                     .aio_file_processing(captcha_file="captcha_example.jpeg"))
+            /9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAoHCBUVxxxxx
+
+        Returns:
+            String with decoded file data
+        """
         # if a local file link is passed
         if captcha_file:
             return base64.b64encode(self._local_file_captcha(captcha_file=captcha_file)).decode("utf-8")
@@ -129,8 +201,9 @@ async def aio_file_processing(
             raise ValueError("No valid captcha variant is set.")
 
 
-class CaptchaInstrument(FileInstrument):
+class CaptchaInstrumentBase:
     CAPTCHA_UNSOLVABLE = "ERROR_CAPTCHA_UNSOLVABLE"
+    CAPTCHA_UNSOLVABLE_DESCRIPTION = "Captcha not recognized"
     """
     Basic Captcha solving class
 

src/python3_capsolver/core/sio_captcha_instrument.py

@@ -10,12 +10,12 @@
 from .const import RETRIES, REQUEST_URL, VALID_STATUS_CODES, GET_BALANCE_POSTFIX
 from .utils import attempts_generator
 from .serializer import CaptchaResponseSer
-from .captcha_instrument import CaptchaInstrument
+from .captcha_instrument import CaptchaInstrumentBase
 
 __all__ = ("SIOCaptchaInstrument",)
 
 
-class SIOCaptchaInstrument(CaptchaInstrument):
+class SIOCaptchaInstrument(CaptchaInstrumentBase):
     """
     Instrument for working with sync captcha
     """
@@ -92,7 +92,7 @@ def __get_result(self, url_postfix: str = EndpointPostfixEnm.GET_TASK_RESULT.val
         # default response if server is silent
         self.result.errorId = 1
         self.result.errorCode = self.CAPTCHA_UNSOLVABLE
-        self.result.errorDescription = "Captcha not recognized"
+        self.result.errorDescription = self.CAPTCHA_UNSOLVABLE_DESCRIPTION
         self.result.taskId = self.created_task_data.taskId
         self.result.status = ResponseStatusEnm.Failed
 

src/python3_capsolver/image_to_text.py

@@ -21,7 +21,6 @@ class ImageToText(CaptchaParams):
     Examples:
         >>> from python3_capsolver.image_to_text import ImageToText
         >>> from python3_capsolver.core.captcha_instrument import FileInstrument
-
         >>> body = FileInstrument().file_processing(captcha_file="captcha_example.jpeg")
         >>> ImageToText(api_key="CAI-12345....").captcha_handler(
         ...                     task_payload={"body": body, "module": "common"}
@@ -41,7 +40,6 @@ class ImageToText(CaptchaParams):
         >>> import asyncio
         >>> from python3_capsolver.image_to_text import ImageToText
         >>> from python3_capsolver.core.captcha_instrument import FileInstrument
-
         >>> body = FileInstrument().file_processing(captcha_file="captcha_example.jpeg")
         >>> asyncio.run(ImageToText(api_key="CAI-12345....").aio_captcha_handler(
         ...                     task_payload={"body": body, "module": "common"}
@@ -61,7 +59,6 @@ class ImageToText(CaptchaParams):
 
         >>> from python3_capsolver.image_to_text import ImageToText
         >>> from python3_capsolver.core.captcha_instrument import FileInstrument
-
         >>> body = FileInstrument().file_processing(captcha_file="captcha_example.jpeg")
         >>> ImageToText(api_key="CAI-12345....").captcha_handler(
         ...                     task_payload={"body": body,