Skip to content

Commit baf32b3

Browse files
AndreiDrangAndreiDrang
committed
docs upd
1 parent f8495a6 commit baf32b3

7 files changed

Lines changed: 104 additions & 18 deletions

File tree

‎docs/modules/captcha-instrument/info.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
FileInstrument
2+
==============
3+
4+
To import this module:
5+
6+
.. code-block:: python
7+
8+
from python3_capsolver.core import captcha_instrument
9+
10+
11+
.. autoclass:: python3_capsolver.core.captcha_instrument.FileInstrument
12+
:members:

‎docs/modules/enum/info.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,7 @@ To import this module:
2323
.. autoclass:: python3_capsolver.core.enum.CaptchaTypeEnm
2424
:members:
2525
:undoc-members:
26+
27+
.. autoclass:: python3_capsolver.core.enum.SaveFormatsEnm
28+
:members:
29+
:undoc-members:

‎src/python3_capsolver/core/aio_captcha_instrument.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,12 @@
99
from .const import REQUEST_URL, VALID_STATUS_CODES, GET_BALANCE_POSTFIX
1010
from .utils import attempts_generator
1111
from .serializer import CaptchaResponseSer
12-
from .captcha_instrument import CaptchaInstrument
12+
from .captcha_instrument import CaptchaInstrumentBase
1313

1414
__all__ = ("AIOCaptchaInstrument",)
1515

1616

17-
class AIOCaptchaInstrument(CaptchaInstrument):
17+
class AIOCaptchaInstrument(CaptchaInstrumentBase):
1818
"""
1919
Instrument for working with async captcha
2020
"""
@@ -84,12 +84,12 @@ async def __get_result(self, url_postfix: str = EndpointPostfixEnm.GET_TASK_RESU
8484
# if captcha just created or in processing now - wait
8585
await asyncio.sleep(self.captcha_params.sleep_time)
8686

87-
# default response if server is silent
88-
self.result.errorId = 1
89-
self.result.errorCode = self.CAPTCHA_UNSOLVABLE
90-
self.result.errorDescription = "Captcha not recognized"
91-
self.result.taskId = self.created_task_data.taskId
92-
self.result.status = ResponseStatusEnm.Failed
87+
# default response if server is silent
88+
self.result.errorId = 1
89+
self.result.errorCode = self.CAPTCHA_UNSOLVABLE
90+
self.result.errorDescription = self.CAPTCHA_UNSOLVABLE_DESCRIPTION
91+
self.result.taskId = self.created_task_data.taskId
92+
self.result.status = ResponseStatusEnm.Failed
9393

9494
@staticmethod
9595
async def send_post_request(payload: Optional[dict] = None, url_postfix: str = GET_BALANCE_POSTFIX) -> dict:

‎src/python3_capsolver/core/base.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
from .const import REQUEST_URL
77
from .serializer import RequestCreateTaskSer, RequestGetTaskResultSer
88
from .context_instr import AIOContextManager, SIOContextManager
9-
from .captcha_instrument import CaptchaInstrument
9+
from .captcha_instrument import CaptchaInstrumentBase
1010
from .aio_captcha_instrument import AIOCaptchaInstrument
1111
from .sio_captcha_instrument import SIOCaptchaInstrument
1212

@@ -38,7 +38,7 @@ def __init__(
3838
# prepare `get task result` payload
3939
self.get_result_params = RequestGetTaskResultSer(clientKey=api_key)
4040
self.request_url = request_url
41-
self._captcha_handling_instrument = CaptchaInstrument()
41+
self._captcha_handling_instrument = CaptchaInstrumentBase()
4242
self.sleep_time = sleep_time
4343

4444
def captcha_handler(self, task_payload: Dict) -> Dict[str, Any]:

‎src/python3_capsolver/core/captcha_instrument.py‎

Lines changed: 75 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,26 @@
1313
from .const import RETRIES, ASYNC_RETRIES
1414
from .serializer import CaptchaResponseSer
1515

16-
__all__ = ("CaptchaInstrument", "FileInstrument")
16+
__all__ = ("CaptchaInstrumentBase", "FileInstrument")
1717

1818

1919
class FileInstrument:
20+
"""
21+
This class contains usefull methods for async and async files processing to prepare them for solving
22+
23+
Examples:
24+
>>> from python3_capsolver.core.captcha_instrument import FileInstrument
25+
>>> body = FileInstrument().file_processing(captcha_file="captcha_example.jpeg")
26+
/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAoHCBUVxxxxx
27+
28+
>>> from python3_capsolver.core.captcha_instrument import FileInstrument
29+
>>> body = FileInstrument().file_processing(captcha_link="https://some-url/file.jpeg")
30+
/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAoHCBUVxxxxx
31+
32+
Returns:
33+
String with decoded file data
34+
"""
35+
2036
@staticmethod
2137
def _local_file_captcha(captcha_file: str):
2238
"""
@@ -80,6 +96,33 @@ def file_processing(
8096
file_extension: str = "png",
8197
**kwargs,
8298
) -> str:
99+
"""
100+
Synchronous method for captcha image processing.
101+
- Method can read local file and return it's as base64 string.
102+
- Method can read file URL and return it's as base64 string.
103+
- Method can decode base64 bytes and return it's as base64 string.
104+
105+
Args:
106+
captcha_link: URL link to file. Instrument will send GET request to it and read content
107+
captcha_file: Local file path. Instrument will read it
108+
captcha_base64: Readed file base64 data. Instrument will decode it in ``utf-8``
109+
save_format: This arg works only with ``captcha_link`` arg
110+
If ``SaveFormatsEnm.CONST`` is set - file will be loaded and saved locally.
111+
img_clearing: This arg works only with ``captcha_link`` arg
112+
If ``False`` - file wil not be removed downloading and saving locally
113+
file_path: This arg works only with ``captcha_link`` and ``SaveFormatsEnm.CONST`` args
114+
In this param u can set locally path for downloaded file saving
115+
file_extension: This arg works only with ``file_path`` args
116+
In this param u MUST set file format for saving
117+
118+
Examples:
119+
>>> from python3_capsolver.core.captcha_instrument import FileInstrument
120+
>>> body = FileInstrument().file_processing(captcha_file="captcha_example.jpeg")
121+
/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAoHCBUVxxxxx
122+
123+
Returns:
124+
String with decoded file data
125+
"""
83126
# if a local file link is passed
84127
if captcha_file:
85128
return base64.b64encode(self._local_file_captcha(captcha_file=captcha_file)).decode("utf-8")
@@ -109,6 +152,35 @@ async def aio_file_processing(
109152
file_extension: str = "png",
110153
**kwargs,
111154
) -> str:
155+
"""
156+
Asynchronous method for captcha image processing.
157+
- Method can read local file and return it's as base64 string.
158+
- Method can read file URL and return it's as base64 string.
159+
- Method can decode base64 bytes and return it's as base64 string.
160+
161+
Args:
162+
captcha_link: URL link to file. Instrument will send GET request to it and read content
163+
captcha_file: Local file path. Instrument will read it
164+
captcha_base64: Readed file base64 data. Instrument will decode it in ``utf-8``
165+
save_format: This arg works only with ``captcha_link`` arg
166+
If ``SaveFormatsEnm.CONST`` is set - file will be loaded and saved locally.
167+
img_clearing: This arg works only with ``captcha_link`` arg
168+
If ``False`` - file wil not be removed downloading and saving locally
169+
file_path: This arg works only with ``captcha_link`` and ``SaveFormatsEnm.CONST`` args
170+
In this param u can set locally path for downloaded file saving
171+
file_extension: This arg works only with ``file_path`` args
172+
In this param u MUST set file format for saving
173+
174+
Examples:
175+
>>> import asyncio
176+
>>> from python3_capsolver.core.captcha_instrument import FileInstrument
177+
>>> body = asyncio.run(FileInstrument()
178+
... .aio_file_processing(captcha_file="captcha_example.jpeg"))
179+
/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAoHCBUVxxxxx
180+
181+
Returns:
182+
String with decoded file data
183+
"""
112184
# if a local file link is passed
113185
if captcha_file:
114186
return base64.b64encode(self._local_file_captcha(captcha_file=captcha_file)).decode("utf-8")
@@ -129,8 +201,9 @@ async def aio_file_processing(
129201
raise ValueError("No valid captcha variant is set.")
130202

131203

132-
class CaptchaInstrument(FileInstrument):
204+
class CaptchaInstrumentBase:
133205
CAPTCHA_UNSOLVABLE = "ERROR_CAPTCHA_UNSOLVABLE"
206+
CAPTCHA_UNSOLVABLE_DESCRIPTION = "Captcha not recognized"
134207
"""
135208
Basic Captcha solving class
136209

‎src/python3_capsolver/core/sio_captcha_instrument.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,12 @@
1010
from .const import RETRIES, REQUEST_URL, VALID_STATUS_CODES, GET_BALANCE_POSTFIX
1111
from .utils import attempts_generator
1212
from .serializer import CaptchaResponseSer
13-
from .captcha_instrument import CaptchaInstrument
13+
from .captcha_instrument import CaptchaInstrumentBase
1414

1515
__all__ = ("SIOCaptchaInstrument",)
1616

1717

18-
class SIOCaptchaInstrument(CaptchaInstrument):
18+
class SIOCaptchaInstrument(CaptchaInstrumentBase):
1919
"""
2020
Instrument for working with sync captcha
2121
"""
@@ -92,7 +92,7 @@ def __get_result(self, url_postfix: str = EndpointPostfixEnm.GET_TASK_RESULT.val
9292
# default response if server is silent
9393
self.result.errorId = 1
9494
self.result.errorCode = self.CAPTCHA_UNSOLVABLE
95-
self.result.errorDescription = "Captcha not recognized"
95+
self.result.errorDescription = self.CAPTCHA_UNSOLVABLE_DESCRIPTION
9696
self.result.taskId = self.created_task_data.taskId
9797
self.result.status = ResponseStatusEnm.Failed
9898

‎src/python3_capsolver/image_to_text.py‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@ class ImageToText(CaptchaParams):
2121
Examples:
2222
>>> from python3_capsolver.image_to_text import ImageToText
2323
>>> from python3_capsolver.core.captcha_instrument import FileInstrument
24-
2524
>>> body = FileInstrument().file_processing(captcha_file="captcha_example.jpeg")
2625
>>> ImageToText(api_key="CAI-12345....").captcha_handler(
2726
... task_payload={"body": body, "module": "common"}
@@ -41,7 +40,6 @@ class ImageToText(CaptchaParams):
4140
>>> import asyncio
4241
>>> from python3_capsolver.image_to_text import ImageToText
4342
>>> from python3_capsolver.core.captcha_instrument import FileInstrument
44-
4543
>>> body = FileInstrument().file_processing(captcha_file="captcha_example.jpeg")
4644
>>> asyncio.run(ImageToText(api_key="CAI-12345....").aio_captcha_handler(
4745
... task_payload={"body": body, "module": "common"}
@@ -61,7 +59,6 @@ class ImageToText(CaptchaParams):
6159
6260
>>> from python3_capsolver.image_to_text import ImageToText
6361
>>> from python3_capsolver.core.captcha_instrument import FileInstrument
64-
6562
>>> body = FileInstrument().file_processing(captcha_file="captcha_example.jpeg")
6663
>>> ImageToText(api_key="CAI-12345....").captcha_handler(
6764
... task_payload={"body": body,

0 commit comments

Comments
 (0)