diff --git a/README.rst b/README.rst index 3e03d4c..cdebeb5 100644 --- a/README.rst +++ b/README.rst @@ -21,7 +21,7 @@ :: - instaloader [--comments] [--geotags] [--stories] + instaloader [--comments] [--geotags] [--stories] [--tagged] [--login YOUR-USERNAME] [--fast-update] profile | "#hashtag" | :stories | :feed | :saved diff --git a/docs/basic-usage.rst b/docs/basic-usage.rst index 18d97f3..f60cd09 100644 --- a/docs/basic-usage.rst +++ b/docs/basic-usage.rst @@ -60,12 +60,20 @@ already have a valid session cookie file. What to Download ^^^^^^^^^^^^^^^^ +.. targets-start + Instaloader supports the following targets: - ``profile`` - Public profile, or private profile with :option:`--login`. For each profile - you download, :option:`--stories` instructs Instaloader to also - **download the user's stories**. + Public profile, or private profile with :option:`--login`. + + If an already-downloaded profile has been renamed, Instaloader automatically + finds it by its unique ID and renames the folder accordingly. + + Besides the profile's posts, its current profile picture is downloaded. For + each profile you download, :option:`--stories` instructs Instaloader to also + **download the user's stories**, and :option:`--tagged` to **download posts + where the user is tagged**. - ``"#hashtag"`` Posts with a certain **hashtag** (the quotes are usually necessary), @@ -88,6 +96,8 @@ Instaloader supports the following targets: The single **post** with the given shortcode. Must be preceeded by ``--`` in the argument list to not be mistaken as an option flag. +.. targets-end + Instaloader goes through all media matching the specified targets and downloads the pictures and videos and their captions. You can specify diff --git a/docs/cli-options.rst b/docs/cli-options.rst index 537bd18..2a090d2 100644 --- a/docs/cli-options.rst +++ b/docs/cli-options.rst @@ -13,27 +13,33 @@ feed), ``:stories`` (stories of your followees) or ``:saved`` (collection of posts marked as saved). Here we explain the additional options that can be given to Instaloader to -customize its behavior. To get a list of all flags, their abbreviations and -their descriptions, you may also run ``instaloader --help``. For an +customize its behavior. For an introduction on how to use Instaloader, see :ref:`download-pictures-from-instagram`. -What to Download -^^^^^^^^^^^^^^^^ +To get a list of all flags, their abbreviations and +their descriptions, you may also run:: -Specify a list of targets (profiles, #hashtags, ``:feed``, ``:stories`` or -``:saved``). For each of these, Instaloader creates a folder and stores all -posts along with the pictures's captions and the current **profile picture** -there. If an already-downloaded profile has been renamed, Instaloader -automatically **finds it by its unique ID** and renames the folder likewise. + instaloader --help -.. option:: --profile-pic-only, -P +Targets +^^^^^^^ - Only download profile picture. +Specify a list of targets. For each of these, Instaloader creates a folder and +stores all posts along with the pictures's captions there. -.. option:: --no-profile-pic +.. include:: basic-usage.rst + :start-after: targets-start + :end-before: targets-end - Do not download profile picture. +- ``filename.json[.xz]`` + Re-Download the given object + +- ``+args.txt`` + Read targets (and options) from given textfile. See :option:`+args.txt`. + +What to Download of each Post +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. option:: --no-pictures @@ -75,6 +81,26 @@ automatically **finds it by its unique ID** and renames the folder likewise. Template to write in txt file for each StoryItem. See :ref:`metadata-text-files`. +.. option:: --no-metadata-json + + Do not create a JSON file containing the metadata of each post. + +.. option:: --no-compress-json + + Do not xz compress JSON files, rather create pretty formatted JSONs. + + +What to Download of each Profile +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. option:: --profile-pic-only, -P + + Only download profile picture. + +.. option:: --no-profile-pic + + Do not download profile picture. + .. option:: --stories, -s Also **download stories** of each profile that is downloaded. Requires @@ -84,14 +110,6 @@ automatically **finds it by its unique ID** and renames the folder likewise. Also download posts where each profile is tagged. -.. option:: --no-metadata-json - - Do not create a JSON file containing the metadata of each post. - -.. option:: --no-compress-json - - Do not xz compress JSON files, rather create pretty formatted JSONs. - .. option:: --stories-only Rather than downloading regular posts of each specified profile, only @@ -107,6 +125,15 @@ automatically **finds it by its unique ID** and renames the folder likewise. Download only post where each profile is tagged, not their regular posts. +Which Posts to Download +^^^^^^^^^^^^^^^^^^^^^^^ + +.. option:: --fast-update, -F + + For each target, stop when encountering the first already-downloaded picture. + This flag is recommended when you use Instaloader to update your personal + Instagram archive. + .. option:: --post-filter filter, --only-if filter Expression that, if given, must evaluate to True for each post to be @@ -122,20 +149,6 @@ automatically **finds it by its unique ID** and renames the folder likewise. evaluated to :class:`instaloader.StoryItem` attributes. See :ref:`filter-posts` for more examples. - - -When to Stop Downloading -^^^^^^^^^^^^^^^^^^^^^^^^ - -If none of these options are given, Instaloader goes through all pictures -matching the specified targets. - -.. option:: --fast-update, -F - - For each target, stop when encountering the first already-downloaded picture. - This flag is recommended when you use Instaloader to update your personal - Instagram archive. - .. option:: --count COUNT, -c Do not attempt to download more than COUNT posts. Applies only to diff --git a/docs/index.rst b/docs/index.rst index 5f0987f..d55e7c8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -41,7 +41,7 @@ See :ref:`install` for more options on how to install Instaloader. :: - instaloader [--comments] [--geotags] [--stories] + instaloader [--comments] [--geotags] [--stories] [--tagged] [--login YOUR-USERNAME] [--fast-update] profile | "#hashtag" | :stories | :feed | :saved diff --git a/instaloader/__main__.py b/instaloader/__main__.py index ffd6d3d..85c1cde 100644 --- a/instaloader/__main__.py +++ b/instaloader/__main__.py @@ -18,7 +18,7 @@ def usage_string(): argv0 = os.path.basename(sys.argv[0]) argv0 = "instaloader" if argv0 == "__main__.py" else argv0 return """ -{0} [--comments] [--geotags] [--stories] +{0} [--comments] [--geotags] [--stories] [--tagged] {2:{1}} [--login YOUR-USERNAME] [--fast-update] {2:{1}} profile | "#hashtag" | :stories | :feed | :saved {0} --help""".format(argv0, len(argv0), '') @@ -212,77 +212,91 @@ def main(): "https://instaloader.github.io/.", fromfile_prefix_chars='+') - g_what = parser.add_argument_group('What to Download', - 'Specify a list of profiles or #hashtags. For each of these, Instaloader ' - 'creates a folder and ' - 'downloads all posts along with the pictures\'s ' - 'captions and the current profile picture. ' - 'If an already-downloaded profile has been renamed, Instaloader automatically ' - 'finds it by its unique ID and renames the folder likewise.') - g_what.add_argument('profile', nargs='*', metavar='profile|#hashtag', - help='Name of profile or #hashtag to download. ' - 'Alternatively, if --login is given: @ to download all followees of ' - '; the special targets ' - ':feed to download pictures from your feed; ' - ':stories to download the stories of your followees; or ' - ':saved to download the posts marked as saved.') - g_what.add_argument('-P', '--profile-pic-only', action='store_true', + g_targets = parser.add_argument_group("What to Download", + "Specify a list of targets. For each of these, Instaloader creates a folder " + "and downloads all posts. The following targets are supported:") + g_targets.add_argument('profile', nargs='*', + help="Download profile. If an already-downloaded profile has been renamed, Instaloader " + "automatically finds it by its unique ID and renames the folder likewise.") + g_targets.add_argument('_at_profile', nargs='*', metavar="@profile", + help="Download all followees of profile. Requires --login. " + "Consider using :feed rather than @yourself.") + g_targets.add_argument('_hashtag', nargs='*', metavar='"#hashtag"', help="Download #hashtag.") + g_targets.add_argument('_feed', nargs='*', metavar=":feed", + help="Download pictures from your feed. Requires --login.") + g_targets.add_argument('_stories', nargs='*', metavar=":stories", + help="Download the stories of your followees. Requires --login.") + g_targets.add_argument('_saved', nargs='*', metavar=":saved", + help="Download the posts that you marked as saved. Requires --login.") + g_targets.add_argument('_singlepost', nargs='*', metavar="-- -shortcode", + help="Download the post with the given shortcode") + g_targets.add_argument('_json', nargs='*', metavar="filename.json[.xz]", + help="Re-Download the given object.") + g_targets.add_argument('_fromfile', nargs='*', metavar="+args.txt", + help="Read targets (and options) from given textfile.") + + g_post = parser.add_argument_group("What to Download of each Post") + + g_prof = parser.add_argument_group("What to Download of each Profile") + + g_prof.add_argument('-P', '--profile-pic-only', action='store_true', help='Only download profile picture.') - g_what.add_argument('--no-profile-pic', action='store_true', + g_prof.add_argument('--no-profile-pic', action='store_true', help='Do not download profile picture.') - g_what.add_argument('--no-pictures', action='store_true', + g_post.add_argument('--no-pictures', action='store_true', help='Do not download post pictures. Cannot be used together with --fast-update. ' 'Implies --no-video-thumbnails, does not imply --no-videos.') - g_what.add_argument('-V', '--no-videos', action='store_true', + g_post.add_argument('-V', '--no-videos', action='store_true', help='Do not download videos.') - g_what.add_argument('--no-video-thumbnails', action='store_true', + g_post.add_argument('--no-video-thumbnails', action='store_true', help='Do not download thumbnails of videos.') - g_what.add_argument('-G', '--geotags', action='store_true', + g_post.add_argument('-G', '--geotags', action='store_true', help='Download geotags when available. Geotags are stored as a ' 'text file with the location\'s name and a Google Maps link. ' 'This requires an additional request to the Instagram ' 'server for each picture, which is why it is disabled by default.') - g_what.add_argument('-C', '--comments', action='store_true', + g_post.add_argument('-C', '--comments', action='store_true', help='Download and update comments for each post. ' 'This requires an additional request to the Instagram ' 'server for each post, which is why it is disabled by default.') - g_what.add_argument('--no-captions', action='store_true', + g_post.add_argument('--no-captions', action='store_true', help='Do not create txt files.') - g_what.add_argument('--post-metadata-txt', action='append', + g_post.add_argument('--post-metadata-txt', action='append', help='Template to write in txt file for each Post.') - g_what.add_argument('--storyitem-metadata-txt', action='append', + g_post.add_argument('--storyitem-metadata-txt', action='append', help='Template to write in txt file for each StoryItem.') - g_what.add_argument('--no-metadata-json', action='store_true', + g_post.add_argument('--no-metadata-json', action='store_true', help='Do not create a JSON file containing the metadata of each post.') - g_what.add_argument('--metadata-json', action='store_true', + g_post.add_argument('--metadata-json', action='store_true', help=SUPPRESS) - g_what.add_argument('--no-compress-json', action='store_true', + g_post.add_argument('--no-compress-json', action='store_true', help='Do not xz compress JSON files, rather create pretty formatted JSONs.') - g_what.add_argument('-s', '--stories', action='store_true', + g_prof.add_argument('-s', '--stories', action='store_true', help='Also download stories of each profile that is downloaded. Requires --login.') - g_what.add_argument('--stories-only', action='store_true', + g_prof.add_argument('--stories-only', action='store_true', help='Rather than downloading regular posts of each specified profile, only download ' 'stories. Requires --login. Does not imply --no-profile-pic.') - g_what.add_argument('--tagged', action='store_true', + g_prof.add_argument('--tagged', action='store_true', help='Also download posts where each profile is tagged.') - g_what.add_argument('--tagged-only', action='store_true', + g_prof.add_argument('--tagged-only', action='store_true', help='Download only post where each profile is tagged, not their regular posts.') - g_what.add_argument('--post-filter', '--only-if', metavar='filter', + + g_cond = parser.add_argument_group("Which Posts to Download") + + g_cond.add_argument('-F', '--fast-update', action='store_true', + help='For each target, stop when encountering the first already-downloaded picture. This ' + 'flag is recommended when you use Instaloader to update your personal Instagram archive.') + + g_cond.add_argument('--post-filter', '--only-if', metavar='filter', help='Expression that, if given, must evaluate to True for each post to be downloaded. Must be ' 'a syntactically valid python expression. Variables are evaluated to ' 'instaloader.Post attributes. Example: --post-filter=viewer_has_liked.') - g_what.add_argument('--storyitem-filter', metavar='filter', + g_cond.add_argument('--storyitem-filter', metavar='filter', help='Expression that, if given, must evaluate to True for each storyitem to be downloaded. ' 'Must be a syntactically valid python expression. Variables are evaluated to ' 'instaloader.StoryItem attributes.') - g_stop = parser.add_argument_group('When to Stop Downloading', - 'If none of these options are given, Instaloader goes through all pictures ' - 'matching the specified targets.') - g_stop.add_argument('-F', '--fast-update', action='store_true', - help='For each target, stop when encountering the first already-downloaded picture. This ' - 'flag is recommended when you use Instaloader to update your personal Instagram archive.') - g_stop.add_argument('-c', '--count', + g_cond.add_argument('-c', '--count', help='Do not attempt to download more than COUNT posts. ' 'Applies only to #hashtag and :feed.')