From 538cc4ae2e39070be386ab062ed855faaed17db6 Mon Sep 17 00:00:00 2001 From: Adam Dobrawy Date: Sat, 7 Mar 2026 14:19:17 +0100 Subject: [PATCH] Switch README from RST to Markdown Markdown is the dominant format on GitHub, renders natively, and is easier for contributors to edit. Inline the previously-included content into the Sphinx docs since they remain RST-based. Co-Authored-By: Claude Opus 4.6 --- README.md | 187 ++++++++++++++++++++++++++++++++++++++ README.rst | 237 ------------------------------------------------- docs/index.rst | 14 ++- docs/usage.rst | 161 ++++++++++++++++++++++++++++++++- pyproject.toml | 2 +- 5 files changed, 357 insertions(+), 244 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 0000000..d664fb3 --- /dev/null +++ b/README.md @@ -0,0 +1,187 @@ +# python-anticaptcha + +[![Build Status](https://github.com/ad-m/python-anticaptcha/workflows/Python%20package/badge.svg)](https://github.com/ad-m/python-anticaptcha/actions?workflow=Python+package) +[![PyPI](https://img.shields.io/pypi/v/python-anticaptcha.svg)](https://pypi.org/project/python-anticaptcha/) +[![Chat](https://badges.gitter.im/python-anticaptcha/Lobby.svg)](https://gitter.im/python-anticaptcha/Lobby?utm_source=share-link&utm_medium=link&utm_campaign=share-link) +[![Python compatibility](https://img.shields.io/pypi/pyversions/python-anticaptcha.svg)](https://github.com/ad-m/python-anticaptcha/blob/master/setup.py) + +Client library for solve captchas with [Anticaptcha.com support](http://getcaptchasolution.com/i1hvnzdymd). +The library requires Python >= 3.9. + +The library is cyclically and automatically tested for proper operation. We are constantly making the best efforts for its effective operation. + +In case of any problems with integration - [read the documentation](http://python-anticaptcha.readthedocs.io/en/latest/), [create an issue](https://github.com/ad-m/python-anticaptcha/issues/new), use [Gitter](https://gitter.im/python-anticaptcha/Lobby) or contact privately. + +## Getting Started + +Install as standard Python package using: + +``` +pip install python-anticaptcha +``` + +## Usage + +To use this library do you need [Anticaptcha.com](http://getcaptchasolution.com/p9bwplkicx) API key. + +You can pass the key explicitly or set the `ANTICAPTCHA_API_KEY` environment variable: + +```python +# Explicit key +client = AnticaptchaClient("my-api-key") + +# Or set ANTICAPTCHA_API_KEY environment variable +client = AnticaptchaClient() +``` + +### Solve recaptcha + +Example snippet for Recaptcha: + +```python +from python_anticaptcha import AnticaptchaClient, NoCaptchaTaskProxylessTask + +api_key = '174faff8fbc769e94a5862391ecfd010' +site_key = '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-' # grab from site +url = 'https://www.google.com/recaptcha/api2/demo' + +client = AnticaptchaClient(api_key) +task = NoCaptchaTaskProxylessTask(url, site_key) +job = client.create_task(task) +job.join() +print(job.get_solution_response()) +``` + +The full integration example is available in file `examples/recaptcha.py`. + +If you only process few page many times to increase reliability, you can specify +whether the captcha is visible or not. This parameter is not required, as is the +system detects invisible sitekeys automatically, and needs several recursive +measures for automated training and analysis. For provide that pass +`is_invisible` parameter to `NoCaptchaTaskProxylessTask` or `NoCaptchaTask` eg.: + +```python +from python_anticaptcha import AnticaptchaClient, NoCaptchaTaskProxylessTask + +api_key = '174faff8fbc769e94a5862391ecfd010' +site_key = '6Lc-0DYUAAAAAOPM3RGobCfKjIE5STmzvZfHbbNx' # grab from site +url = 'https://losangeles.craigslist.org/lac/kid/d/housekeeper-sitting-pet-care/6720136191.html' + +client = AnticaptchaClient(api_key) +task = NoCaptchaTaskProxylessTask(url, site_key, is_invisible=True) +job = client.create_task(task) +job.join() +print(job.get_solution_response()) +``` + +### Solve text captcha + +Example snippet for text captcha: + +```python +from python_anticaptcha import AnticaptchaClient, ImageToTextTask + +api_key = '174faff8fbc769e94a5862391ecfd010' +captcha_fp = open('examples/captcha_ms.jpeg', 'rb') +client = AnticaptchaClient(api_key) +task = ImageToTextTask(captcha_fp) +job = client.create_task(task) +job.join() +print(job.get_captcha_text()) +``` + +### Solve funcaptcha + +Example snippet for funcaptcha: + +```python +from python_anticaptcha import AnticaptchaClient, FunCaptchaTask, Proxy +UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1) AppleWebKit/537.36 ' \ + '(KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36' + +api_key = '174faff8fbc769e94a5862391ecfd010' +site_key = 'DE0B0BB7-1EE4-4D70-1853-31B835D4506B' # grab from site +url = 'https://www.google.com/recaptcha/api2/demo' +proxy = Proxy.parse_url("socks5://login:password@123.123.123.123:1080") + +client = AnticaptchaClient(api_key) +task = FunCaptchaTask(url, site_key, user_agent=UA, **proxy.to_kwargs()) +job = client.create_task(task) +job.join() +print(job.get_token_response()) +``` + +### Report incorrect image + +Example snippet for reporting an incorrect image task: + +```python +from python_anticaptcha import AnticaptchaClient, ImageToTextTask + +api_key = '174faff8fbc769e94a5862391ecfd010' +captcha_fp = open('examples/captcha_ms.jpeg', 'rb') +client = AnticaptchaClient(api_key) +task = ImageToTextTask(captcha_fp) +job = client.create_task(task) +job.join() +print(job.get_captcha_text()) +job.report_incorrect_image() +``` + +### Setup proxy + +The library is not responsible for managing the proxy server. However, we point to +the possibility of simply launching such a server by: + +``` +pip install mitmproxy +mitmweb -p 9190 -b 0.0.0.0 --ignore '.' --socks +``` + +Next to in your application use something like: + +```python +proxy = Proxy.parse_url("socks5://123.123.123.123:9190") +``` + +We recommend entering IP-based access control for incoming addresses to proxy. IP address required by +[Anticaptcha.com](http://getcaptchasolution.com/p9bwplkicx) is: + +``` +69.65.41.21 +209.212.146.168 +``` + +### Error handling + +In the event of an application error, the `AnticaptchaException` exception is thrown. To handle the exception, do the following: + +```python +from python_anticaptcha import AnticaptchaException, ImageToTextTask + +try: + # any actions +except AnticaptchaException as e: + if e.error_code == 'ERROR_ZERO_BALANCE': + notify_about_no_funds(e.error_id, e.error_code, e.error_description) + else: + raise +``` + +> **Note:** The legacy misspelled `AnticatpchaException` alias is still available for backward compatibility. + +## Versioning + +We use [SemVer](http://semver.org/) for versioning. For the versions available, see the +[tags on this repository](https://github.com/ad-m/python-anticaptcha/tags). + +## Authors + +- **Adam Dobrawy** - *Initial work* - [ad-m](https://github.com/ad-m) + +See also the list of [contributors](https://github.com/ad-m/python-anticaptcha/contributors) who participated in this project. + +## License + +This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) +file for details diff --git a/README.rst b/README.rst deleted file mode 100644 index 1846064..0000000 --- a/README.rst +++ /dev/null @@ -1,237 +0,0 @@ -python-anticaptcha -================== - -.. image:: https://github.com/ad-m/python-anticaptcha/workflows/Python%20package/badge.svg - :target: https://github.com/ad-m/python-anticaptcha/actions?workflow=Python+package - -.. image:: https://img.shields.io/pypi/v/python-anticaptcha.svg - :target: https://pypi.org/project/python-anticaptcha/ - :alt: Python package - -.. image:: https://badges.gitter.im/python-anticaptcha/Lobby.svg - :target: https://gitter.im/python-anticaptcha/Lobby?utm_source=share-link&utm_medium=link&utm_campaign=share-link - :alt: Join the chat at https://gitter.im/python-anticaptcha/Lobby - -.. image:: https://img.shields.io/pypi/pyversions/python-anticaptcha.svg - :target: https://github.com/ad-m/python-anticaptcha/blob/master/setup.py - :alt: Python compatibility - -.. introduction-start - -Client library for solve captchas with `Anticaptcha.com support`_. -The library requires Python >= 3.9. - -The library is cyclically and automatically tested for proper operation. We are constantly making the best efforts for its effective operation. - -In case of any problems with integration - `read the documentation`_, `create an issue`_, use `Gitter`_ or contact privately. - -.. _read the documentation: http://python-anticaptcha.readthedocs.io/en/latest/ -.. _Anticaptcha.com support: http://getcaptchasolution.com/i1hvnzdymd -.. _create an issue: https://github.com/ad-m/python-anticaptcha/issues/new -.. _Gitter: https://gitter.im/python-anticaptcha/Lobby - -.. introduction-end - - -Getting Started ---------------- - -.. getting-started-start - -Install as standard Python package using:: - - pip install python-anticaptcha - -.. getting-started-end - - -Usage ------ - -.. usage-start - -To use this library do you need `Anticaptcha.com`_ API key. - -You can pass the key explicitly or set the ``ANTICAPTCHA_API_KEY`` environment variable: - -.. code:: python - - # Explicit key - client = AnticaptchaClient("my-api-key") - - # Or set ANTICAPTCHA_API_KEY environment variable - client = AnticaptchaClient() - -Solve recaptcha -############### - -Example snippet for Recaptcha: - -.. code:: python - - from python_anticaptcha import AnticaptchaClient, NoCaptchaTaskProxylessTask - - api_key = '174faff8fbc769e94a5862391ecfd010' - site_key = '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-' # grab from site - url = 'https://www.google.com/recaptcha/api2/demo' - - client = AnticaptchaClient(api_key) - task = NoCaptchaTaskProxylessTask(url, site_key) - job = client.create_task(task) - job.join() - print(job.get_solution_response()) - -The full integration example is available in file ``examples/recaptcha.py``. - -If you only process few page many times to increase reliability, you can specify -whether the captcha is visible or not. This parameter is not required, as is the -system detects invisible sitekeys automatically, and needs several recursive -measures for automated training and analysis. For provide that pass -``is_invisible`` parameter to ``NoCaptchaTaskProxylessTask`` or ``NoCaptchaTask`` eg.: - -.. code:: python - - from python_anticaptcha import AnticaptchaClient, NoCaptchaTaskProxylessTask - - api_key = '174faff8fbc769e94a5862391ecfd010' - site_key = '6Lc-0DYUAAAAAOPM3RGobCfKjIE5STmzvZfHbbNx' # grab from site - url = 'https://losangeles.craigslist.org/lac/kid/d/housekeeper-sitting-pet-care/6720136191.html' - - client = AnticaptchaClient(api_key) - task = NoCaptchaTaskProxylessTask(url, site_key, is_invisible=True) - job = client.create_task(task) - job.join() - print(job.get_solution_response()) - - -Solve text captcha -################## - -Example snippet for text captcha: - -.. code:: python - - from python_anticaptcha import AnticaptchaClient, ImageToTextTask - - api_key = '174faff8fbc769e94a5862391ecfd010' - captcha_fp = open('examples/captcha_ms.jpeg', 'rb') - client = AnticaptchaClient(api_key) - task = ImageToTextTask(captcha_fp) - job = client.create_task(task) - job.join() - print(job.get_captcha_text()) - -Solve funcaptcha -################ - -Example snippet for funcaptcha: - -.. code:: python - - from python_anticaptcha import AnticaptchaClient, FunCaptchaTask, Proxy - UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1) AppleWebKit/537.36 ' \ - '(KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36' - - api_key = '174faff8fbc769e94a5862391ecfd010' - site_key = 'DE0B0BB7-1EE4-4D70-1853-31B835D4506B' # grab from site - url = 'https://www.google.com/recaptcha/api2/demo' - proxy = Proxy.parse_url("socks5://login:password@123.123.123.123:1080") - - client = AnticaptchaClient(api_key) - task = FunCaptchaTask(url, site_key, user_agent=UA, **proxy.to_kwargs()) - job = client.create_task(task) - job.join() - print(job.get_token_response()) - -Report incorrect image -###################### - -Example snippet for reporting an incorrect image task: - -.. code:: python - - from python_anticaptcha import AnticaptchaClient, ImageToTextTask - - api_key = '174faff8fbc769e94a5862391ecfd010' - captcha_fp = open('examples/captcha_ms.jpeg', 'rb') - client = AnticaptchaClient(api_key) - task = ImageToTextTask(captcha_fp) - job = client.create_task(task) - job.join() - print(job.get_captcha_text()) - job.report_incorrect_image() - -Setup proxy -########### - -The library is not responsible for managing the proxy server. However, we point to -the possibility of simply launching such a server by: - -.. code:: - - pip install mitmproxy - mitmweb -p 9190 -b 0.0.0.0 --ignore '.' --socks - -Next to in your application use something like: - -.. code:: python - - proxy = Proxy.parse_url("socks5://123.123.123.123:9190") - -We recommend entering IP-based access control for incoming addresses to proxy. IP address required by -`Anticaptcha.com`_ is: - -.. code:: - - 69.65.41.21 - 209.212.146.168 - -.. _Anticaptcha.com: http://getcaptchasolution.com/p9bwplkicx - -Error handling -############## - -In the event of an application error, the ``AnticaptchaException`` exception is thrown. To handle the exception, do the following: - -.. code:: python - - from python_anticaptcha import AnticaptchaException, ImageToTextTask - - try: - # any actions - except AnticaptchaException as e: - if e.error_code == 'ERROR_ZERO_BALANCE': - notify_about_no_funds(e.error_id, e.error_code, e.error_description) - else: - raise - -.. note:: - - The legacy misspelled ``AnticatpchaException`` alias is still available for backward compatibility. - -.. usage-end - -Versioning ----------- - -We use `SemVer`_ for versioning. For the versions available, see the -`tags on this repository`_. - -Authors -------- - -- **Adam Dobrawy** - *Initial work* - `ad-m`_ - -See also the list of `contributors`_ who participated in this project. - -License -------- - -This project is licensed under the MIT License - see the `LICENSE.md`_ -file for details - -.. _SemVer: http://semver.org/ -.. _tags on this repository: https://github.com/ad-m/python-anticaptcha/tags -.. _ad-m: https://github.com/ad-m -.. _contributors: https://github.com/ad-m/python-anticaptcha/contributors -.. _LICENSE.md: LICENSE.md diff --git a/docs/index.rst b/docs/index.rst index dfa5a1a..422a2e1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,9 +6,17 @@ Welcome to python-anticaptcha's documentation! ============================================== -.. include:: ../README.rst - :start-after: introduction-start - :end-before: introduction-end +Client library for solve captchas with `Anticaptcha.com support`_. +The library requires Python >= 3.9. + +The library is cyclically and automatically tested for proper operation. We are constantly making the best efforts for its effective operation. + +In case of any problems with integration - `read the documentation`_, `create an issue`_, use `Gitter`_ or contact privately. + +.. _read the documentation: http://python-anticaptcha.readthedocs.io/en/latest/ +.. _Anticaptcha.com support: http://getcaptchasolution.com/i1hvnzdymd +.. _create an issue: https://github.com/ad-m/python-anticaptcha/issues/new +.. _Gitter: https://gitter.im/python-anticaptcha/Lobby .. toctree:: :maxdepth: 2 diff --git a/docs/usage.rst b/docs/usage.rst index e83d252..664ed88 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,6 +1,161 @@ Usage ===== -.. include:: ../README.rst - :start-after: usage-start - :end-before: usage-end +To use this library do you need `Anticaptcha.com`_ API key. + +You can pass the key explicitly or set the ``ANTICAPTCHA_API_KEY`` environment variable: + +.. code:: python + + # Explicit key + client = AnticaptchaClient("my-api-key") + + # Or set ANTICAPTCHA_API_KEY environment variable + client = AnticaptchaClient() + +Solve recaptcha +############### + +Example snippet for Recaptcha: + +.. code:: python + + from python_anticaptcha import AnticaptchaClient, NoCaptchaTaskProxylessTask + + api_key = '174faff8fbc769e94a5862391ecfd010' + site_key = '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-' # grab from site + url = 'https://www.google.com/recaptcha/api2/demo' + + client = AnticaptchaClient(api_key) + task = NoCaptchaTaskProxylessTask(url, site_key) + job = client.create_task(task) + job.join() + print(job.get_solution_response()) + +The full integration example is available in file ``examples/recaptcha.py``. + +If you only process few page many times to increase reliability, you can specify +whether the captcha is visible or not. This parameter is not required, as is the +system detects invisible sitekeys automatically, and needs several recursive +measures for automated training and analysis. For provide that pass +``is_invisible`` parameter to ``NoCaptchaTaskProxylessTask`` or ``NoCaptchaTask`` eg.: + +.. code:: python + + from python_anticaptcha import AnticaptchaClient, NoCaptchaTaskProxylessTask + + api_key = '174faff8fbc769e94a5862391ecfd010' + site_key = '6Lc-0DYUAAAAAOPM3RGobCfKjIE5STmzvZfHbbNx' # grab from site + url = 'https://losangeles.craigslist.org/lac/kid/d/housekeeper-sitting-pet-care/6720136191.html' + + client = AnticaptchaClient(api_key) + task = NoCaptchaTaskProxylessTask(url, site_key, is_invisible=True) + job = client.create_task(task) + job.join() + print(job.get_solution_response()) + + +Solve text captcha +################## + +Example snippet for text captcha: + +.. code:: python + + from python_anticaptcha import AnticaptchaClient, ImageToTextTask + + api_key = '174faff8fbc769e94a5862391ecfd010' + captcha_fp = open('examples/captcha_ms.jpeg', 'rb') + client = AnticaptchaClient(api_key) + task = ImageToTextTask(captcha_fp) + job = client.create_task(task) + job.join() + print(job.get_captcha_text()) + +Solve funcaptcha +################ + +Example snippet for funcaptcha: + +.. code:: python + + from python_anticaptcha import AnticaptchaClient, FunCaptchaTask, Proxy + UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1) AppleWebKit/537.36 ' \ + '(KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36' + + api_key = '174faff8fbc769e94a5862391ecfd010' + site_key = 'DE0B0BB7-1EE4-4D70-1853-31B835D4506B' # grab from site + url = 'https://www.google.com/recaptcha/api2/demo' + proxy = Proxy.parse_url("socks5://login:password@123.123.123.123:1080") + + client = AnticaptchaClient(api_key) + task = FunCaptchaTask(url, site_key, user_agent=UA, **proxy.to_kwargs()) + job = client.create_task(task) + job.join() + print(job.get_token_response()) + +Report incorrect image +###################### + +Example snippet for reporting an incorrect image task: + +.. code:: python + + from python_anticaptcha import AnticaptchaClient, ImageToTextTask + + api_key = '174faff8fbc769e94a5862391ecfd010' + captcha_fp = open('examples/captcha_ms.jpeg', 'rb') + client = AnticaptchaClient(api_key) + task = ImageToTextTask(captcha_fp) + job = client.create_task(task) + job.join() + print(job.get_captcha_text()) + job.report_incorrect_image() + +Setup proxy +########### + +The library is not responsible for managing the proxy server. However, we point to +the possibility of simply launching such a server by: + +.. code:: + + pip install mitmproxy + mitmweb -p 9190 -b 0.0.0.0 --ignore '.' --socks + +Next to in your application use something like: + +.. code:: python + + proxy = Proxy.parse_url("socks5://123.123.123.123:9190") + +We recommend entering IP-based access control for incoming addresses to proxy. IP address required by +`Anticaptcha.com`_ is: + +.. code:: + + 69.65.41.21 + 209.212.146.168 + +.. _Anticaptcha.com: http://getcaptchasolution.com/p9bwplkicx + +Error handling +############## + +In the event of an application error, the ``AnticaptchaException`` exception is thrown. To handle the exception, do the following: + +.. code:: python + + from python_anticaptcha import AnticaptchaException, ImageToTextTask + + try: + # any actions + except AnticaptchaException as e: + if e.error_code == 'ERROR_ZERO_BALANCE': + notify_about_no_funds(e.error_id, e.error_code, e.error_description) + else: + raise + +.. note:: + + The legacy misspelled ``AnticatpchaException`` alias is still available for backward compatibility. diff --git a/pyproject.toml b/pyproject.toml index 67d0624..ac79d94 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta" [project] name = "python-anticaptcha" description = "Client library for solve captchas with Anticaptcha.com support." -readme = "README.rst" +readme = "README.md" license = "MIT" requires-python = ">=3.9" dependencies = ["requests"]