From fbe8c519e2b3a117699f6c8602d07985e0edd1f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20F=C3=A4hrmann?= Date: Fri, 23 Jun 2017 16:14:51 +0200 Subject: [PATCH] update README - mention and link to docs/configuration.rst - add OAuth section --- README.rst | 35 +++++++++++++++++++++++++++++++---- docs/configuration.rst | 37 +++++++++++++++++++++++++++++++------ docs/gallery-dl.conf | 5 ++++- 3 files changed, 66 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index ec1016ce..7db1ae14 100644 --- a/README.rst +++ b/README.rst @@ -130,7 +130,9 @@ Configuration ============= Configuration files for *gallery-dl* use a JSON-based file format. -For a (more or less) complete example, see gallery-dl.conf_. +For a (more or less) complete example of a configuration file, see +gallery-dl.conf_. A list of all available configuration options and their +descriptions can be found in configuration.rst_. *gallery-dl* searches for configuration files in the following paths: @@ -151,9 +153,13 @@ Values in later configuration files will override previous ones. Authentication ============== -Some extractors require you to provide valid login-credentials. -This currently includes ``pixiv``, ``exhentai``, ``nijie``, ``seiga`` -and ``batoto``. +Username & Password +------------------- + +Some extractors require you to provide valid login-credentials in the form of +a username & password pair. +This is necessary for ``pixiv``, ``nijie`` and ``seiga`` and optional +(but strongly recommended) for ``exhentai`` and ``batoto``. You can set the necessary information in your configuration file (cf. gallery-dl.conf_) @@ -180,8 +186,28 @@ or you can provide them directly via the $ gallery-dl -u -p URL $ gallery-dl -o username= -o password= URL +OAuth +----- + +*gallery-dl* supports user authentication via OAuth_ for ``flickr`` and +``reddit``. This is entirely optional, but grants *gallery-dl* the ability +to issue requests on your account's behalf and enables it to access resources +which would otherwise be unavailable to a public user. + +To link your account to *gallery-dl*, start by invoking it with +``oauth:`` as an argument. For example: + +.. code:: bash + + $ gallery-dl oauth:flickr + +You will be sent to the site's authorization page and asked to grant read +access to *gallery-dl*. Authorize it and you will he shown one or more +"tokens", which should be added to your configuration file. + .. _gallery-dl.conf: https://github.com/mikf/gallery-dl/blob/master/docs/gallery-dl.conf +.. _configuration.rst: https://github.com/mikf/gallery-dl/blob/master/docs/configuration.rst .. _Complete List: https://github.com/mikf/gallery-dl/blob/master/docs/supportedsites.rst .. _standalone executable: https://github.com/mikf/gallery-dl/releases/download/v0.8.4/gallery-dl.exe .. _Python: https://www.python.org/downloads/ @@ -190,6 +216,7 @@ or you can provide them directly via the .. _pip: https://pip.pypa.io/en/stable/ .. _stable: https://github.com/mikf/gallery-dl/archive/v0.8.4.zip .. _dev: https://github.com/mikf/gallery-dl/archive/master.zip +.. _OAuth: https://en.wikipedia.org/wiki/OAuth .. |pypi| image:: https://img.shields.io/pypi/v/gallery-dl.svg :target: https://pypi.python.org/pypi/gallery-dl diff --git a/docs/configuration.rst b/docs/configuration.rst index b4aba999..0ae614d1 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -27,9 +27,9 @@ cache.file ---------- =========== ===== Type ``string`` -Default ``tempfile.gettempdir() + ".gallery-dl.cache"`` +Default |tempfile.gettempdir()|_ + ``".gallery-dl.cache"`` Description Path of the SQLite3 database used to cache login sessions, - smaller cookies and API tokens. + cookies and API tokens. Set this value to an invalid path or simply ``null`` to disable this cache. @@ -101,7 +101,7 @@ Description Amount of time (in seconds) to wait for a successful connection and a response from a remote server. This value gets internally used as the ``timeout`` parameter for the - `requests.get()`_ method. + |requests.get()|_ method. =========== ===== @@ -177,7 +177,7 @@ Type ``bool`` Default ``true`` Description Enable mature content. - This option simply sets the ``mature_content`` parameter for API + This option simply sets the |mature_content|_ parameter for API calls to either ``"true"`` or ``"false"`` and does not do any other form of content filtering. =========== ===== @@ -294,7 +294,7 @@ Type ``bool`` Default ``true`` Description Controls how a user is directed to a OAuth authorization site. - * ``true``: Use Python's `webbrowser.open()`_ method to automatically + * ``true``: Use Python's |webbrowser.open()|_ method to automatically open the URL in the user's browser. * ``false``: Ask the user to copy & paste an URL from the terminal. =========== ===== @@ -330,6 +330,18 @@ Description The value of the ``limit`` parameter when loading =========== ===== +extractor.reddit.morecomments +------------------------- +=========== ===== +Type ``bool`` +Default ``false`` +Description Retrieve additional comments by resolving the ``more`` comment + stubs in the base commment tree. + + This requires 1 additional API call for every 100 extra comments. +=========== ===== + + extractor.reddit.date-min ------------------------- =========== ===== @@ -371,11 +383,24 @@ Type ``string`` Default ``null`` Description The ``refresh_token`` value you get from linking your Reddit account to ``gallery-dl``. + + Using the ``refresh_token`` allows you to access private or otherwise + not publicly available subreddits, given that your account is + authorized to do so, + but requests to the reddit API are going to be rate limited + at 600 requests every 10 minutes/600 seconds. =========== ===== -.. _requests.get(): http://docs.python-requests.org/en/latest/user/advanced/#timeouts +.. |tempfile.gettempdir()| replace:: ``tempfile.gettempdir()`` +.. |requests.get()| replace:: ``requests.get()`` +.. |mature_content| replace:: ``mature_content`` +.. |webbrowser.open()| replace:: ``webbrowser.open()`` + +.. _tempfile.gettempdir(): https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir +.. _requests.get(): https://docs.python-requests.org/en/latest/user/advanced/#timeouts .. _format string: https://docs.python.org/3/library/string.html#formatstrings .. _format strings: https://docs.python.org/3/library/string.html#formatstrings +.. _mature_content: https://www.deviantart.com/developers/http/v1/20160316/object/deviation .. _webbrowser.open(): https://docs.python.org/3/library/webbrowser.html .. _Authentication: https://github.com/mikf/gallery-dl#5authentication diff --git a/docs/gallery-dl.conf b/docs/gallery-dl.conf index 3f9aae23..14cf7be7 100644 --- a/docs/gallery-dl.conf +++ b/docs/gallery-dl.conf @@ -55,6 +55,7 @@ { "refresh-token": null, "comments": 500, + "morecomments": false, "date-min": 0, "date-max": 253402210800, "recursion": 0 @@ -62,7 +63,9 @@ "flickr": { "access-token": null, - "access-token-secret": null + "access-token-secret": null, + "metadata": false, + "size-max": null } }, "output":