From 8211c9daf17605b68872ff9729b0764003cc4736 Mon Sep 17 00:00:00 2001 From: Alexander Graf Date: Sun, 17 Jun 2018 18:10:19 +0200 Subject: [PATCH] Documentation Improvements - Fix Spelling - codesnippets: Improve introduction texts; Write subsection about metadata JSON files --- docs/basic-usage.rst | 4 +-- docs/codesnippets.rst | 65 +++++++++++++++++++++++++++++-------------- docs/contributing.rst | 4 +-- 3 files changed, 48 insertions(+), 25 deletions(-) diff --git a/docs/basic-usage.rst b/docs/basic-usage.rst index c10018f..e45fd68 100644 --- a/docs/basic-usage.rst +++ b/docs/basic-usage.rst @@ -68,7 +68,7 @@ Instaloader supports the following targets: **download the user's stories**. - ``"#hashtag"`` - Posts with a certain **hashtag** (the quotes are usually neccessary), + Posts with a certain **hashtag** (the quotes are usually necessary), - ``:stories`` The currently-visible **stories** of your followees (requires @@ -158,7 +158,7 @@ Filter Posts .. py:currentmodule:: instaloader The options :option:`--post-filter` and :option:`--storyitem-filter` -allows to specify criterias that posts or story items have to +allows to specify criteria that posts or story items have to meet to be downloaded. If not given, all posts are downloaded. The filter string must be a diff --git a/docs/codesnippets.rst b/docs/codesnippets.rst index ef533b8..047d757 100644 --- a/docs/codesnippets.rst +++ b/docs/codesnippets.rst @@ -11,8 +11,8 @@ Advanced Instaloader Examples :backlinks: none Here we present code examples that use the :ref:`python-module-instaloader` for -more advanced tasks than what is possible with the Instaloader command line -interface. +more advanced Instagram downloading or metadata mining than what is possible +with the Instaloader command line interface. .. For each code snippet: - title @@ -21,12 +21,12 @@ interface. - link to discussion issue - link used methods -Download Posts in a specific period +Download Posts in a Specific Period ----------------------------------- -To collect pictures (and metadata) only from a specific period, you can play -around with :func:`~itertools.dropwhile` and :func:`~itertools.takewhile` from -:mod:`itertools` like in this snippet. +To only download Instagram pictures (and metadata) that are within a specific +period, you can play around with :func:`~itertools.dropwhile` and +:func:`~itertools.takewhile` from :mod:`itertools` like in this snippet. .. literalinclude:: codesnippets/121_since_until.py @@ -37,8 +37,8 @@ Discussed in :issue:`121`. Likes of a Profile / Ghost Followers ------------------------------------ -To store inactive followers, i.e. followers that did not like any of your -pictures, into a file you can use this approach. +To obtain a list of your inactive followers, i.e. followers that did not like +any of your pictures, into a file you can use this approach. .. literalinclude:: codesnippets/120_ghost_followers.py @@ -51,10 +51,10 @@ Discussed in :issue:`120`. Track Deleted Posts ------------------- -This script uses Instaloader to obtain a list of currently-online posts, and -generates the matching filename of each post. It outputs a list of posts which -are online but not offline (i.e. not yet downloaded) and a list of posts which -are offline but not online (i.e. deleted in the profile). +This script uses Instaloader to obtain a list of currently-online Instagram and +compares it with the set of posts that you already have downloaded. It outputs +a list of posts which are online but not offline (i.e. not yet downloaded) and a +list of posts which are offline but not online (i.e. deleted in the profile). .. literalinclude:: codesnippets/56_track_deleted.py @@ -68,9 +68,9 @@ Only one Post per User To download only the one most recent post from each user, this snippet creates a :class:`set` that contains the users of which a post has already been -downloaded. When iterating the posts, check whether the post's owner already is -in the set. If so, skip the post. Otherwise, download it and add the user to -that set. +downloaded. While iterating the posts, it checks whether the post's owner +already is in the set. If not, the post is downloaded from Instagram and the +user is added to that set. .. literalinclude:: codesnippets/113_only_one_per_user.py @@ -79,23 +79,23 @@ See also :class:`Post`, :meth:`Instaloader.download_post`, Discussed in :issue:`113`. -Upgrade Images by local Copies +Upgrade Images by Local Copies ------------------------------ The following script finds local versions of images fetched by Instaloader, in -order to ugprade the downloaded images by locally-found versions with better +order to upgrade the downloaded images by locally-found versions with better quality. It uses image hashing to identify similar images. `updgrade-instaloader-images.py `__ (external link to GitHub Gist) Discussed in :issue:`46`. -Render Captions to downloaded Images ------------------------------------- +Add Captions to Images +---------------------- Instaloader does not modify the downloaded JPEG file. However, one could combine -it with an imaging library such as Pillow or PIL to render the -:attr:`Post.caption` on pictures. The following shows an approach. +it with an imaging library such as Pillow or PIL to render the caption on +Instagram pictures. The following shows an approach. .. literalinclude:: codesnippets/110_pil_captions.py @@ -103,3 +103,26 @@ See also :attr:`Post.caption`, :attr:`Post.url`, :meth:`Post.from_shortcode`, :func:`load_structure_from_file`. Discussed in :issue:`110`. + +Metadata JSON Files +------------------- + +The JSON files Instaloader saves along with each Post contain all the metadata +that has been retrieved from Instagram while downloading the picture and +associated required information. + +With `jq `__, a command-line JSON processor, the +metadata can be easily post-processed. For example, Instaloader's JSON files can +be pretty-formatted with: + +.. code-block:: none + + xzcat 2018-05-13_11-18-45_UTC.json.xz | jq .node + +However, Instaloader tries to do as few metadata requests as possible, so, +depending on how Instaloader has been invoked, it may occur that these files do +not contain the complete available metadata structure. Nevertheless, the file +can be loaded into Instaloader with :func:`load_structure_from_file` and the +required metadata then be accessed via the :class:`Post` or :class:`Profile` +attributes, which trigger an Instagram request if that particular information is +not present in the JSON file. diff --git a/docs/contributing.rst b/docs/contributing.rst index a1a73eb..024d246 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -28,7 +28,7 @@ following in mind: opening a new issue. However, if unsure, please create a new issue. - State **how the bug can be reproduced**, i.e. how Instaloader was invoked - when the problem occured (of course, you may anonymize profile names etc.). + when the problem occurred (of course, you may anonymize profile names etc.). - Include all **error messages and tracebacks** in the report. @@ -54,7 +54,7 @@ few things to consider: warning rather than adapting the code to Pylint's desires. - The documentation source is located in the ``docs`` folder. The file - ``cli-options.rst`` is merely an RST-formatted copy of ``ìnstaloader --help`` + ``cli-options.rst`` is merely an RST-formatted copy of ``instaloader --help`` output, of which the source is in ``instaloader/__main__.py``. - Feel free to contact us, even if you "only" have Proof-of-Concepts or