Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] update OAuth guide in README.rst #3496

Merged
merged 2 commits into from
Jan 6, 2023
Merged

[docs] update OAuth guide in README.rst #3496

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0e8657e
[docs] update OAuth guide in README.rst
ClosedPort22 Jan 5, 2023
c94692f
[docs] document 'access-token' for Mastodon instances
ClosedPort22 Jan 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -328,20 +328,23 @@ For example:
OAuth
-----

*gallery-dl* supports user authentication via OAuth_ for
*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.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One could argue that it is not entirely optional for Mastodon instances, since it is required to map user name to ID, but I have no idea how to accurately describe that here without being too verbose.

.../users/username requires an access token
.../users/id:12345 works without
(for instances that are not supported by default)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the current description is okay, since it's not entirely non-functional without the token, unlike Pixiv. Maybe a more detailed description could be added to configuration.rst (although extractor.mastodon.access-token is currently undocumented).


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.
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 link your account to *gallery-dl*, start by invoking it with
``oauth:<sitename>`` as an argument. For example:
To do so, start by invoking it with ``oauth:<sitename>`` as an argument.
For example:

.. code:: bash

Expand Down
28 changes: 22 additions & 6 deletions docs/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1845,8 +1845,24 @@ Description
List of acceptable content ratings for returned chapters.


extractor.mastodon.reblogs
--------------------------
extractor.[mastodon].access-token
---------------------------------
Type
``string``
Default
``null``
Description
The ``access-token`` value you get from `linking your account to
gallery-dl <OAuth_>`__.

Note: gallery-dl comes with built-in tokens for ``mastodon.social``,
``pawoo`` and ``baraag``. For other instances, you need to obtain an
``access-token`` in order to use usernames in place of numerical
user IDs.


extractor.[mastodon].reblogs
----------------------------
Type
``bool``
Default
Expand All @@ -1855,8 +1871,8 @@ Description
Fetch media from reblogged posts.


extractor.mastodon.replies
--------------------------
extractor.[mastodon].replies
----------------------------
Type
``bool``
Default
Expand All @@ -1865,8 +1881,8 @@ Description
Fetch media from replies to other posts.


extractor.mastodon.text-posts
-----------------------------
extractor.[mastodon].text-posts
-------------------------------
Type
``bool``
Default
Expand Down