diff --git a/docs/index.rst b/docs/index.rst index c0c1ec26..0f3649c1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -38,5 +38,6 @@ Check our other projects here - `RedPandaDev group dict: diff --git a/src/python3_capsolver/core/base.py b/src/python3_capsolver/core/base.py index 31773433..8ca1b28c 100644 --- a/src/python3_capsolver/core/base.py +++ b/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]: diff --git a/src/python3_capsolver/core/captcha_instrument.py b/src/python3_capsolver/core/captcha_instrument.py index 44079874..f37ffb5d 100644 --- a/src/python3_capsolver/core/captcha_instrument.py +++ b/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 diff --git a/src/python3_capsolver/core/sio_captcha_instrument.py b/src/python3_capsolver/core/sio_captcha_instrument.py index d1f06ab9..d3f198dd 100644 --- a/src/python3_capsolver/core/sio_captcha_instrument.py +++ b/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 diff --git a/src/python3_capsolver/image_to_text.py b/src/python3_capsolver/image_to_text.py index 2f0b4cda..f520335e 100644 --- a/src/python3_capsolver/image_to_text.py +++ b/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,