Metadata-Version: 2.1
Name: librecaptcha
Version: 0.5.0
Summary: A free/libre interface for solving reCAPTCHA challenges.
Home-page: https://github.com/nickolas360/librecaptcha
Author: nickolas360
Author-email: contact@nickolas360.com
License: GNU General Public License v3 or later (GPLv3+)
Keywords: captcha recaptcha
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Internet
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Dist: Pillow (>=4.1.1)
Requires-Dist: requests (>=2.18.1)
Requires-Dist: slimit (>=0.8.1)
Provides-Extra: gtk
Requires-Dist: PyGObject (>=3.30.0) ; extra == 'gtk'

librecaptcha
============

Version 0.5.0

librecaptcha is a free/libre program and library that allows you to solve
`reCAPTCHA`_ challenges.

*librecaptcha does not automatically solve challenges and is not designed to
make it easier to do so---it provides an interface through which a human can
solve the challenges without proprietary software.*

.. _reCAPTCHA: https://en.wikipedia.org/wiki/ReCAPTCHA


Installation
------------

From PyPI
~~~~~~~~~

Install with `pip`_::

    sudo pip3 install librecaptcha[gtk]

To install locally, run without ``sudo`` and add the ``--user`` option.
You can omit ``[gtk]`` if you don’t want to install the GTK 3 GUI.


From the Git repository
~~~~~~~~~~~~~~~~~~~~~~~

Clone the repository with the following commands (you’ll need to have `Git`_
installed)::

    git clone https://github.com/nickolas360/librecaptcha
    cd librecaptcha

Then install with `pip`_::

    sudo pip3 install .[gtk]

To install locally, run without ``sudo`` and add the ``--user`` option.
You can omit ``[gtk]`` if you don’t want to install the GTK 3 GUI.


Run without installing
~~~~~~~~~~~~~~~~~~~~~~

Run the first set of commands in the previous section to clone the repository.
Then, install the required dependencies by running::

    sudo pip3 install -r requirements.txt

To install the dependencies locally, run without ``sudo`` and add ``--user``.

.. _pip: https://pip.pypa.io
.. _Git: https://git-scm.com


Usage
-----

If you installed librecaptcha, you can simply run ``librecaptcha``.
Otherwise, run ``./librecaptcha.py``. Pass the ``--help`` option to show usage
information. If you’d like to use the GUI, be sure to pass the ``--gui``
option.

To use librecaptcha programmatically, import it::

    import librecaptcha

and then call ``librecaptcha.get_token()``. Its signature is::

    get_token(
        api_key: str,
        site_url: str,
        user_agent: str, *,
        gui=False,
        debug=False,
    ) -> str

Parameters:

* ``api_key``:
  The reCAPTCHA API key to use. This is usually the value of the
  ``data-sitekey`` HTML attribute.

* ``site_url``:
  The base URL of the site that contains the reCAPTCHA challenge. This should
  start with ``http://`` or ``https://`` and include the hostname. Everything
  after the hostname is optional. For example: ``https://example.com``

* ``user_agent``:
  The user-agent string to use. This should match the user-agent used when
  sending the request that requires a reCAPTCHA token. You can generate a
  random user-agent string with ``librecaptcha.random_user_agent()``.

* ``gui``:
  Whether to use the GTK 3 GUI (as opposed to the CLI). The CLI writes to
  standard output and reads from standard input.

* ``debug``:
  Whether to print debug information.

Returns: A reCAPTCHA token. This should usually be submitted with the form as
the value of the ``g-recaptcha-response`` field. These tokens usually expire
after a couple of minutes.


Notes
-----

librecaptcha currently supports two types of challenges: *dynamic* and
*multicaptcha*.

*dynamic* challenges present you with a grid of different images and ask you to
select the images that match the given description. Each time you click an
image, a new one takes its place. Usually, three images from the initial
set match the description, and at least one of the replacement images does as
well.

*multicaptcha* challenges present you with one large image split into a grid
of tiles and ask you to select the tiles that contain a given object. It is
possible to select no tiles; however, it appears that this is rarely the
correct answer.

**Note:** Even when all challenges are completed and a token is obtained, the
token may still be rejected when used. If this happens, simply try again.
Waiting a while may also help.


What’s new
----------

Version 0.5.0:

* Added a GTK 3 GUI (thanks, cyclopsian!).
* ``get_token()`` now has an optional ``gui`` parameter.
* ``get_token()`` now requires a user-agent string.
* ``librecaptcha.py`` now has a ``--gui`` option.
* ``librecaptcha.py`` now accepts an optional ``<user-agent>`` argument.
  If not provided, a random user-agent string is chosen and shown.

Version 0.4.0:

* Image windows are now automatically closed when questions are answered.

Version 0.3.x:

* Fixed possible encoding issue in ``setup.py``.
* librecaptcha can now be installed from PyPI, or from the Git repository with
  pip or ``setup.py``.

Version 0.2.x:

* Updated user-agent list.
* The current reCAPTCHA version is now fetched during initialization and no
  longer needs to be manually updated.


Dependencies
------------

* `Python`_ ≥ 3.5
* The following Python packages (the installation instructions above handle
  installing these):

  - `Pillow`_ ≥ 4.1.1
  - `requests`_ ≥ 2.18.1
  - `slimit`_ ≥ 0.8.1
  - `PyGObject`_ ≥ 3.30.0 (only for GUI)

.. _Python: https://www.python.org/
.. _Pillow: https://pypi.org/project/Pillow/
.. _requests: https://pypi.org/project/requests/
.. _slimit: https://pypi.org/project/slimit/
.. _PyGObject: https://pypi.org/project/PyGObject/


License
-------

librecaptcha is licensed under the GNU General Public License, version 3 or
any later version. See `LICENSE`_.

This README file has been released to the public domain using `CC0`_.

.. _LICENSE: https://github.com/nickolas360/librecaptcha/blob/master/LICENSE
.. _CC0: https://creativecommons.org/publicdomain/zero/1.0/


