New upstream version 1.24.3.upstream/1.24.3

1 files changed, 83 insertions, 47 deletions

diff --git a/PKG-INFO b/PKG-INFO
index 68af9dd..508ba02 100644
--- a/PKG-INFO
+++ b/PKG-INFO
@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: gallery_dl
-Version: 1.24.2
+Version: 1.24.3
 Summary: Command-line program to download image galleries and collections from several image hosting sites
 Home-page: https://github.com/mikf/gallery-dl
 Download-URL: https://github.com/mikf/gallery-dl/releases/latest
@@ -39,13 +39,16 @@ License-File: LICENSE
 gallery-dl
 ==========
 
-*gallery-dl* is a command-line program to download image galleries and
-collections from several image hosting sites (see `Supported Sites`_).
-It is a cross-platform tool with many configuration options
-and powerful `filenaming capabilities <Formatting_>`_.
+*gallery-dl* is a command-line program
+to download image galleries and collections
+from several image hosting sites
+(see `Supported Sites <docs/supportedsites.md>`__).
+It is a cross-platform tool
+with many `configuration options <docs/configuration.rst>`__
+and powerful `filenaming capabilities <docs/formatting.md>`__.
 
 
-|pypi| |build| |gitter|
+|pypi| |build|
 
 .. contents::
 
@@ -59,7 +62,7 @@ Dependencies
 Optional
 --------
 
-- FFmpeg_: Pixiv Ugoira to WebM conversion
+- FFmpeg_: Pixiv Ugoira conversion
 - yt-dlp_ or youtube-dl_: Video downloads
 - PySocks_: SOCKS proxy support
 - brotli_ or brotlicffi_: Brotli compression support
@@ -103,9 +106,13 @@ Standalone Executable
 Prebuilt executable files with a Python interpreter and
 required Python packages included are available for
 
-- `Windows <https://github.com/mikf/gallery-dl/releases/download/v1.24.2/gallery-dl.exe>`__
+- `Windows <https://github.com/mikf/gallery-dl/releases/download/v1.24.3/gallery-dl.exe>`__
   (Requires `Microsoft Visual C++ Redistributable Package (x86) <https://aka.ms/vs/17/release/vc_redist.x86.exe>`__)
-- `Linux   <https://github.com/mikf/gallery-dl/releases/download/v1.24.2/gallery-dl.bin>`__
+- `Linux   <https://github.com/mikf/gallery-dl/releases/download/v1.24.3/gallery-dl.bin>`__
+
+
+Nightly Builds
+--------------
 
 | Executables build from the latest commit can be found at
 | https://github.com/mikf/gallery-dl/actions/workflows/executables.yml
@@ -141,6 +148,16 @@ Scoop
     scoop install gallery-dl
 
 
+Homebrew
+--------
+
+For macOS or Linux users using Homebrew:
+
+.. code:: bash
+
+    brew install gallery-dl
+
+
 Usage
 =====
 
@@ -149,9 +166,10 @@ from:
 
 .. code:: bash
 
-    gallery-dl [OPTION]... URL...
+    gallery-dl [OPTIONS]... URLS...
 
-See also :code:`gallery-dl --help`.
+Use :code:`gallery-dl --help` or see `<docs/options.md>`__
+for a full list of all command-line options.
 
 
 Examples
@@ -199,13 +217,22 @@ Configuration
 
 Configuration files for *gallery-dl* use a JSON-based file format.
 
-| For a (more or less) complete example with options set to their default values,
-  see gallery-dl.conf_.
-| For a configuration file example with more involved settings and options,
-  see gallery-dl-example.conf_.
-| A list of all available configuration options and their
-  descriptions can be found in configuration.rst_.
-|
+
+Documentation
+-------------
+
+A list of all available configuration options and their descriptions
+can be found in `<docs/configuration.rst>`__.
+
+| For a default configuration file with available options set to their
+  default values, see `<docs/gallery-dl.conf>`__.
+
+| For a commented example with more involved settings and option usage,
+  see `<docs/gallery-dl-example.conf>`__.
+
+
+Locations
+---------
 
 *gallery-dl* searches for configuration files in the following places:
 
@@ -214,7 +241,7 @@ Windows:
     * ``%USERPROFILE%\gallery-dl\config.json``
     * ``%USERPROFILE%\gallery-dl.conf``
 
-    (``%USERPROFILE%`` usually refers to the user's home directory,
+    (``%USERPROFILE%`` usually refers to a user's home directory,
     i.e. ``C:\Users\<username>\``)
 
 Linux, macOS, etc.:
@@ -223,12 +250,13 @@ Linux, macOS, etc.:
     * ``${HOME}/.config/gallery-dl/config.json``
     * ``${HOME}/.gallery-dl.conf``
 
-Values in later configuration files will override previous ones.
+When run as `executable <Standalone Executable_>`__,
+*gallery-dl* will also look for a ``gallery-dl.conf`` file
+in the same directory as said executable.
 
-Command line options will override all related settings in the configuration file(s),
-e.g. using ``--write-metadata`` will enable writing metadata using the default values
-for all ``postprocessors.metadata.*`` settings, overriding any specific settings in
-configuration files.
+It is possible to use more than one configuration file at a time.
+In this case, any values from files after the first will get merged
+into the already loaded settings and potentially override previous ones.
 
 
 Authentication
@@ -258,8 +286,8 @@ and optional for
 ``twitter``,
 and ``zerochan``.
 
-You can set the necessary information in your configuration file
-(cf. gallery-dl.conf_)
+You can set the necessary information in your
+`configuration file <Configuration_>`__
 
 .. code:: json
 
@@ -278,8 +306,8 @@ or you can provide them directly via the
 
 .. code:: bash
 
-    gallery-dl -u <username> -p <password> URL
-    gallery-dl -o username=<username> -o password=<password> URL
+    gallery-dl -u "<username>" -p "<password>" "URL"
+    gallery-dl -o "username=<username>" -o "password=<password>" "URL"
 
 
 Cookies
@@ -290,7 +318,7 @@ CAPTCHA or similar, or has not been implemented yet, you can use the
 cookies from a browser login session and input them into *gallery-dl*.
 
 This can be done via the
-`cookies <https://github.com/mikf/gallery-dl/blob/master/docs/configuration.rst#extractorcookies>`__
+`cookies <docs/configuration.rst#extractorcookies>`__
 option in your configuration file by specifying
 
 - | the path to a Mozilla/Netscape format cookies.txt file exported by a browser addon
@@ -301,6 +329,9 @@ option in your configuration file by specifying
   | (in `Chrome <https://developers.google.com/web/tools/chrome-devtools/storage/cookies>`__,
      in `Firefox <https://developer.mozilla.org/en-US/docs/Tools/Storage_Inspector>`__)
 
+- | the name of a browser to extract cookies from
+  | (supported browsers are Chromium-based ones, Firefox, and Safari)
+
 For example:
 
 .. code:: json
@@ -314,30 +345,43 @@ For example:
                 "cookies": {
                     "session_id": "K1T57EKu19TR49C51CDjOJoXNQLF7VbdVOiBrC9ye0a"
                 }
+            },
+            "twitter": {
+                "cookies": ["firefox"]
             }
         }
     }
 
-You can also specify a cookies.txt file with
-the :code:`--cookies` command-line option:
+| You can also specify a cookies.txt file with
+  the :code:`--cookies` command-line option
+| or a browser to extract cookies from with :code:`--cookies-from-browser`:
 
 .. code:: bash
 
-    gallery-dl --cookies "$HOME/path/to/cookies.txt" URL
+    gallery-dl --cookies "$HOME/path/to/cookies.txt" "URL"
+    gallery-dl --cookies-from-browser firefox "URL"
 
 
 OAuth
 -----
 
-*gallery-dl* supports user authentication via OAuth_ for
-``deviantart``, ``flickr``, ``reddit``, ``smugmug``, ``tumblr``,
+*gallery-dl* supports user authentication via OAuth_ for some extractors.
+This is necessary for
+``pixiv``
+and optional for
+``deviantart``,
+``flickr``,
+``reddit``,
+``smugmug``,
+``tumblr``,
 and ``mastodon`` instances.
-This is mostly 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:<sitename>`` as an argument. For example:
+Linking your account to *gallery-dl* grants it 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 do so, start by invoking it with ``oauth:<sitename>`` as an argument.
+For example:
 
 .. code:: bash
 
@@ -356,13 +400,6 @@ To authenticate with a ``mastodon`` instance, run *gallery-dl* with
     gallery-dl oauth:mastodon:https://mastodon.social/
 
 
-
-.. _gallery-dl.conf:         https://github.com/mikf/gallery-dl/blob/master/docs/gallery-dl.conf
-.. _gallery-dl-example.conf: https://github.com/mikf/gallery-dl/blob/master/docs/gallery-dl-example.conf
-.. _configuration.rst:       https://github.com/mikf/gallery-dl/blob/master/docs/configuration.rst
-.. _Supported Sites:         https://github.com/mikf/gallery-dl/blob/master/docs/supportedsites.md
-.. _Formatting:              https://github.com/mikf/gallery-dl/blob/master/docs/formatting.md
-
 .. _Python:     https://www.python.org/downloads/
 .. _PyPI:       https://pypi.org/
 .. _pip:        https://pip.pypa.io/en/stable/
@@ -373,7 +410,6 @@ To authenticate with a ``mastodon`` instance, run *gallery-dl* with
 .. _PySocks:    https://pypi.org/project/PySocks/
 .. _brotli:     https://github.com/google/brotli
 .. _brotlicffi: https://github.com/python-hyper/brotlicffi
-.. _pyOpenSSL:  https://pyopenssl.org/
 .. _Snapd:      https://docs.snapcraft.io/installing-snapd
 .. _OAuth:      https://en.wikipedia.org/wiki/OAuth
 .. _Chocolatey: https://chocolatey.org/install