Metadata-Version: 2.1
Name: librecaptcha
Version: 0.5.1
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+)
Description: librecaptcha
        ============
        
        Version 0.5.1
        
        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/
        
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
Provides-Extra: gtk
