diff --git a/README.rst b/README.rst index f53a232..80a8736 100644 --- a/README.rst +++ b/README.rst @@ -1,39 +1,31 @@ Instaloader =========== -Installation ------------- - -.. installation-start - -Instaloader requires `Python `__, at least -version 3.5. If you have `pip `__ -installed, you may install Instaloader using - :: - pip3 install instaloader + $ pip3 install instaloader -Alternatively, to get the most current version of Instaloader from our -`Git repository `__: + $ instaloader profile [profile ...] -:: +**Instaloader** - pip3 install git+https://github.com/Thammus/instaloader +- downloads **public and private profiles, hashtags, user stories and + feeds**, -(pass ``--upgrade`` to upgrade if Instaloader is already installed) +- downloads **comments, geotags and captions** of each post, -Instaloader requires -`requests `__, which -will be installed automatically, if it is not already installed. +- automatically **detects profile name changes** and renames the target + directory accordingly, + +- allows **fine-grained customization** of filters and where to store + downloaded media. + +`Instaloader Documentation `__ -.. installation-end How to Automatically Download Pictures from Instagram ----------------------------------------------------- -.. basic-usage-start - To **download all pictures and videos of a profile**, as well as the **profile picture**, do @@ -52,8 +44,8 @@ To later **update your local copy** of that profiles, you may run If ``--fast-update`` is given, Instaloader stops when arriving at the first already-downloaded picture. When updating profiles, Instaloader -automatically **detects profile name changes** and renames the target -directory accordingly. +automatically **detects profile name changes** and renames the target directory +accordingly. Instaloader can also be used to **download private profiles**. To do so, invoke it with @@ -62,291 +54,13 @@ invoke it with instaloader --login=your_username profile [profile ...] -When logging in, Instaloader **stores the session cookies** in a file in -your temporary directory, which will be reused later the next time -``--login`` is given. So you can download private profiles -**non-interactively** when you already have a valid session cookie file. +When logging in, Instaloader **stores the session cookies** in a file in your +temporary directory, which will be reused later the next time ``--login`` +is given. So you can download private profiles **non-interactively** when you +already have a valid session cookie file. -What to Download -^^^^^^^^^^^^^^^^ +`Instaloader Documentation `__ -Instaloader does not only download media by-profile. More generally, you -may specify the following targets: - -- ``profile``: Public profile, or private profile with ``--login``, - -- ``"#hashtag"``: Posts with a certain **hashtag** (the quotes are - usually neccessary), - -- ``:stories``: The currently-visible **stories** of your followees - (requires ``--login``), - -- ``:feed``: Your **feed** (requires ``--login``), - -- ``@profile``: All profiles that are followed by ``profile``, i.e. the - *followees* of ``profile`` (requires ``--login``). - -Instaloader goes through all media matching the specified targets and -downloads the pictures and videos and their captions. You can specify -``--comments`` to also **download comments** of each post and -``--geotags`` to **download geotags** of each post and save them as -Google Maps link. For each profile you download, ``--stories`` -instructs Instaloader to **download the user's stories**. - -Filename Specification -^^^^^^^^^^^^^^^^^^^^^^ - -For each target, Instaloader creates a directory named after the target, -i.e. ``profile``, ``#hashtag``, ``:feed``, etc. and therein saves the -posts in files named after the post's timestamp. - -``--dirname-pattern`` allows to configure the directory name of each -target. The default is ``--dirname-pattern={target}``. In the dirname -pattern, the token ``{target}`` is replaced by the target name, and -``{profile}`` is replaced by the owner of the post which is downloaded. - -``--filename-pattern`` configures the path of the post's files relative -to the target directory. The default is ``--filename-pattern={date}``. -The tokens ``{target}`` and ``{profile}`` are replaced like in the -dirname pattern. Further, the tokens ``{date}`` and ``{shortcode}`` are -defined. - -For example, encode the poster's profile name in the filenames with: - -:: - - instaloader --filename-pattern={date}_{profile} "#hashtag" - -The pattern string is formatted with Python's string formatter. This -gives additional flexibilty for pattern specification. For example, -`strftime-style formatting options `__ -are supported for the post's -timestamp. The default for ``{date}`` is ``{date:%Y-%m-%d_%H-%M-%S}``. - -Filter Posts -^^^^^^^^^^^^ - -The ``--only-if`` option allows to specify criterias that posts have to -meet to be downloaded. If not given, all posts are downloaded. It must -be a boolean Python expression where the variables ``likes``, -``comments``, ``viewer_has_liked``, ``is_video``, and many -more are defined. - -A few examples: - -To **download the pictures from your feed that you have liked**: - -:: - - instaloader --login=your_username --only-if=viewer_has_liked :feed - -Or you might only want to download **posts that either you liked or were -liked by many others**: - -:: - - instaloader --login=your_username --only-if="likes>100 or viewer_has_liked" profile - -Or you may **skip videos**: - -:: - - instaloader --only-if="not is_video" target - -Or you may filter by hashtags that occur in the Post's caption. For -example, to download posts of kittens that are cute: :: - - instaloader --only-if="'cute' in caption_hashtags" "#kitten" - -.. basic-usage-end - -(For a more complete description of the ``-only-if`` option, refer to -the `Instaloader Documentation `__) - - -Advanced Options ----------------- - -.. cli-options-start - -The following flags can be given to Instaloader to specify how profiles should -be downloaded. - -To get a list of all flags, their abbreviations and their descriptions, you may -run ``instaloader --help``. - -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. - -Instead of a *profile* or a *#hashtag*, the special targets -``:feed`` (pictures from your feed) and -``:stories`` (stories of your followees) can be specified. - ---profile-pic-only Only download profile picture. ---no-videos Do not download videos. ---geotags **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. ---no-geotags Do not store geotags, even if they can be obtained - without any additional request. ---comments 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. ---no-captions Do not store media captions, although no additional - request is needed to obtain them. ---stories Also **download stories** of each profile that is - downloaded. Requires ``--login``. ---stories-only Rather than downloading regular posts of each - specified profile, only download stories. - Requires ``--login``. ---only-if filter 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: ``--only-if=viewer_has_liked``. - - -When to Stop Downloading -^^^^^^^^^^^^^^^^^^^^^^^^ - -If none of these options are given, Instaloader goes through all pictures -matching the specified targets. - ---fast-update 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. ---count COUNT Do not attempt to download more than COUNT posts. - Applies only to ``#hashtag``, ``:feed-all`` and ``:feed-liked``. - - -Login (Download Private Profiles) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Instaloader can **login to Instagram**. This allows downloading private -profiles. To login, pass the ``--login`` option. Your session cookie (not your -password!) will be saved to a local file to be reused next time you want -Instaloader to login. - ---login YOUR-USERNAME Login name (profile name) for your Instagram account. ---sessionfile SESSIONFILE Path for loading and storing session key file. - Defaults to a path - within your temporary directory, encoding your local - username and your Instagram profile name. ---password YOUR-PASSWORD Password for your Instagram account. Without this - option, you'll be prompted for your password - interactively if there is not yet a valid session - file. - -How to Download -^^^^^^^^^^^^^^^ - ---dirname-pattern DIRNAME_PATTERN - Name of directory where to store posts. ``{profile}`` - is replaced by the profile name, ``{target}`` is replaced - by the target you specified, i.e. either ``:feed``, - ``#hashtag`` or the profile name. Defaults to ``{target}``. ---filename-pattern FILENAME_PATTERN - Prefix of filenames. Posts are stored in the - directory whose pattern is given with ``--dirname-pattern``. - ``{profile}`` is replaced by the profile name, - ``{target}`` is replaced by the target you specified, i.e. - either ``:feed``, ``#hashtag`` or the profile name. Also, the - fields ``{date}`` and ``{shortcode}`` can be specified. - Defaults to ``{date:%Y-%m-%d_%H-%M-%S}``. ---user-agent USER_AGENT User Agent to use for HTTP requests. Per default, - Instaloader pretends being Chrome/51. - -Miscellaneous Options -^^^^^^^^^^^^^^^^^^^^^ - ---quiet Disable user interaction, i.e. do not print messages - (except errors) and fail if login credentials are - needed but not given. This makes Instaloader - **suitable as a cron job**. - -.. cli-options-end - -Usage as Python module ----------------------- - -.. as-module-intro-start - -You may also use parts of Instaloader as library to do other interesting -things. - -For example, to get a list of all followees and a list of all followers of a profile, do - -.. code:: python - - import instaloader - - # Get instance - loader = instaloader.Instaloader() - - # Login - loader.interactive_login(USERNAME) - - # Print followees - print(PROFILE + " follows these profiles:") - for f in loader.get_followees(PROFILE): - print("\t%s\t%s" % (f['username'], f['full_name'])) - - # Print followers - print("Followers of " + PROFILE + ":") - for f in loader.get_followers(PROFILE): - print("\t%s\t%s" % (f['username'], f['full_name'])) - -Then, you may download all pictures of all followees with - -.. code:: python - - for f in loader.get_followees(PROFILE): - loader.download_profile(f['username']) - -You could also download your last 20 liked pics with - -.. code:: python - - loader.download_feed_posts(max_count=20, fast_update=True, - filter_func=lambda post: post.viewer_has_liked) - -To download the last 20 pictures with hashtag #cat, do - -.. code:: python - - loader.download_hashtag('cat', max_count=20) - -Generally, Instaloader provides methods to iterate over the Posts from -a certain source. - -.. code:: python - - for post in loader.get_hashtag_posts('cat'): - # post is an instance of instaloader.Post - loader.download_post(post, target='#cat') - -Each Instagram profile has its own unique ID which stays unmodified even -if a user changes his/her username. To get said ID, given the profile's -name, you may call - -.. code:: python - - loader.get_id_by_username(PROFILE_NAME) - -.. as-module-intro-end - -Refer to the -`Instaloader Documentation `__ for -more information. Disclaimer ---------- diff --git a/docs/as-module.rst b/docs/as-module.rst index 6e190de..6cd831b 100644 --- a/docs/as-module.rst +++ b/docs/as-module.rst @@ -1,26 +1,114 @@ -Usage as Python Module ----------------------- +Python Module :mod:`instaloader` +-------------------------------- -Introduction -^^^^^^^^^^^^ +.. module:: instaloader -.. include:: ../README.rst - :start-after: as-module-intro-start - :end-before: as-module-intro-end +.. highlight:: python + +You may also use parts of Instaloader as library to do other interesting +things. + +For example, to get a list of all followees and a list of all followers of a profile, do + +.. code:: python + + import instaloader + + # Get instance + loader = instaloader.Instaloader() + + # Login + loader.interactive_login(USERNAME) + + # Print followees + print(PROFILE + " follows these profiles:") + for f in loader.get_followees(PROFILE): + print("\t%s\t%s" % (f['username'], f['full_name'])) + + # Print followers + print("Followers of " + PROFILE + ":") + for f in loader.get_followers(PROFILE): + print("\t%s\t%s" % (f['username'], f['full_name'])) + +Then, you may download all pictures of all followees with + +.. code:: python + + for f in loader.get_followees(PROFILE): + loader.download_profile(f['username']) + +You could also download your last 20 liked pics with + +.. code:: python + + loader.download_feed_posts(max_count=20, fast_update=True, + filter_func=lambda post: post.viewer_has_liked) + +To download the last 20 pictures with hashtag #cat, do + +.. code:: python + + loader.download_hashtag('cat', max_count=20) + +Generally, :class:`Instaloader` provides methods to iterate over the Posts from +a certain source. + +.. code:: python + + for post in loader.get_hashtag_posts('cat'): + # post is an instance of instaloader.Post + loader.download_post(post, target='#cat') + +Each Instagram profile has its own unique ID which stays unmodified even +if a user changes his/her username. To get said ID, given the profile's +name, you may call + +.. code:: python + + loader.get_id_by_username(PROFILE_NAME) ``Instaloader`` (Main Class) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. autoclass:: instaloader.Instaloader - :members: - :undoc-members: - -.. _post-class: +.. autoclass:: Instaloader + :no-show-inheritance: ``Post`` Class ^^^^^^^^^^^^^^ -.. autoclass:: instaloader.Post - :members: - :undoc-members: +.. autoclass:: Post + :no-show-inheritance: + +Miscellaneous Functions +^^^^^^^^^^^^^^^^^^^^^^^ + +.. autofunction:: shortcode_to_mediaid + +.. autofunction:: mediaid_to_shortcode + +.. autoclass:: Tristate + +Exceptions +^^^^^^^^^^ + +.. autoexception:: InstaloaderException + :no-show-inheritance: + +.. autoexception:: QueryReturnedNotFoundException + +.. autoexception:: ProfileNotExistsException + +.. autoexception:: ProfileHasNoPicsException + +.. autoexception:: PrivateProfileNotFollowedException + +.. autoexception:: LoginRequiredException + +.. autoexception:: InvalidArgumentException + +.. autoexception:: BadResponseException + +.. autoexception:: BadCredentialsException + +.. autoexception:: ConnectionException diff --git a/docs/basic-usage.rst b/docs/basic-usage.rst index 407f9e7..273fbba 100644 --- a/docs/basic-usage.rst +++ b/docs/basic-usage.rst @@ -1,15 +1,148 @@ Download Pictures from Instagram --------------------------------- +.. highlight:: none + +.. NOTE that Section "Basic Usage" is duplicated in README.rst. + Basic Usage ^^^^^^^^^^^ -.. include:: ../README.rst - :start-after: basic-usage-start - :end-before: basic-usage-end +To **download all pictures and videos of a profile**, as well as the +**profile picture**, do -.. (continuation of --only-if explanation) +:: + + instaloader profile [profile ...] + +where ``profile`` is the name of a profile you want to download. Instead +of only one profile, you may also specify a list of profiles. + +To later **update your local copy** of that profiles, you may run + +:: + + instaloader --fast-update profile [profile ...] + +If :option:`--fast-update` is given, Instaloader stops when arriving at the +first already-downloaded picture. When updating profiles, Instaloader +automatically **detects profile name changes** and renames the target directory +accordingly. + +Instaloader can also be used to **download private profiles**. To do so, +invoke it with + +:: + + instaloader --login=your_username profile [profile ...] + +When logging in, Instaloader **stores the session cookies** in a file in your +temporary directory, which will be reused later the next time :option:`--login` +is given. So you can download private profiles **non-interactively** when you +already have a valid session cookie file. + +.. _what-to-download: + +What to Download +^^^^^^^^^^^^^^^^ + +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**. + +``"#hashtag"`` + Posts with a certain **hashtag** (the quotes are usually neccessary), + +``:stories`` + The currently-visible **stories** of your followees (requires + :option:`--login`), + +``:feed`` + Your **feed** (requires :option:`--login`), + +``@profile`` + All profiles that are followed by ``profile``, i.e. the *followees* of + ``profile`` (requires :option:`--login`). + +Instaloader goes through all media matching the specified targets and +downloads the pictures and videos and their captions. You can specify + +- :option:`--comments`, to also **download comments** of each post and + +- :option:`--geotags`, to **download geotags** of each post and save them as + Google Maps link. + +.. _filename-specification: + +Filename Specification +^^^^^^^^^^^^^^^^^^^^^^ + +For each target, Instaloader creates a directory named after the target, +i.e. ``profile``, ``#hashtag``, ``:feed``, etc. and therein saves the +posts in files named after the post's timestamp. + +:option:`--dirname-pattern` allows to configure the directory name of each +target. The default is ``--dirname-pattern={target}``. In the dirname +pattern, the token ``{target}`` is replaced by the target name, and +``{profile}`` is replaced by the owner of the post which is downloaded. + +:option:`--filename-pattern` configures the path of the post's files relative +to the target directory. The default is ``--filename-pattern={date}``. +The tokens ``{target}`` and ``{profile}`` are replaced like in the +dirname pattern. Further, the tokens ``{date}`` and ``{shortcode}`` are +defined. + +For example, encode the poster's profile name in the filenames with: + +:: + + instaloader --filename-pattern={date}_{profile} "#hashtag" + +The pattern string is formatted with Python's string formatter. This +gives additional flexibilty for pattern specification. For example, +`strftime-style formatting options `__ +are supported for the post's +timestamp. The default for ``{date}`` is ``{date:%Y-%m-%d_%H-%M-%S}``. + +.. _filter-posts: + +Filter Posts +^^^^^^^^^^^^ + +The :option:`--only-if` option allows to specify criterias that posts have to +meet to be downloaded. If not given, all posts are downloaded. It must be a +boolean Python expression where the variables :attr:`.likes`, :attr:`.comments`, +:attr:`.viewer_has_liked`, :attr:`.is_video`, and many more are defined. + +A few examples: + +To **download the pictures from your feed that you have liked**: + +:: + + instaloader --login=your_username --only-if=viewer_has_liked :feed + +Or you might only want to download **posts that either you liked or were +liked by many others**: + +:: + + instaloader --login=your_username --only-if="likes>100 or viewer_has_liked" profile + +Or you may **skip videos**: + +:: + + instaloader --only-if="not is_video" target + +Or you may filter by hashtags that occur in the Post's caption. For +example, to download posts of kittens that are cute: :: + + instaloader --only-if="'cute' in caption_hashtags" "#kitten" The given string is evaluated as a `Python boolean expression `__, -where all occuring variables are properties of the :ref:`post-class`. +where all occuring variables are attributes of the :class:`.Post` class. diff --git a/docs/cli-options.rst b/docs/cli-options.rst index d06a982..a9e10ab 100644 --- a/docs/cli-options.rst +++ b/docs/cli-options.rst @@ -1,6 +1,145 @@ Command Line Options ==================== -.. include:: ../README.rst - :start-after: cli-options-start - :end-before: cli-options-end +The following flags can be given to Instaloader to specify how profiles should +be downloaded. + +To get a list of all flags, their abbreviations and their descriptions, +run ``instaloader --help``. + +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. + +Instead of a *profile* or a *#hashtag*, the special targets +``:feed`` (pictures from your feed) and +``:stories`` (stories of your followees) can be specified. + +.. option:: --profile-pic-only + + Only download profile picture. + +.. option:: --no-videos + + Do not download videos. + +.. option:: --geotags + + **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. + +.. option:: --no-geotags + + Do not store geotags, even if they can be obtained without any additional + request. + +.. option:: --comments + + 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. + +.. option:: --no-captions + + Do not store media captions, although no additional request is needed to + obtain them. + +.. option:: --stories + + Also **download stories** of each profile that is downloaded. Requires + :option:`--login`. + +.. option:: --stories-only + + Rather than downloading regular posts of each specified profile, only + download stories. Requires :option:`--login`. + +.. option:: --only-if filter + + 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 :class:`instaloader.Post` attributes. Example: + ``--only-if=viewer_has_liked``. 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 + + 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 + + Do not attempt to download more than COUNT posts. Applies only to + ``#hashtag``, ``:feed-all`` and ``:feed-liked``. + + +Login (Download Private Profiles) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Instaloader can **login to Instagram**. This allows downloading private +profiles. To login, pass the :option:`--login` option. Your session cookie (not your +password!) will be saved to a local file to be reused next time you want +Instaloader to login. + +.. option:: --login YOUR-USERNAME + + Login name (profile name) for your Instagram account. + +.. option:: --sessionfile SESSIONFILE + + Path for loading and storing session key file. Defaults to a path within + your temporary directory, encoding your local username and your Instagram + profile name. + +.. option:: --password YOUR-PASSWORD + + Password for your Instagram account. Without this option, you'll be prompted + for your password interactively if there is not yet a valid session file. + +How to Download +^^^^^^^^^^^^^^^ + +.. option:: --dirname-pattern DIRNAME_PATTERN + + Name of directory where to store posts. ``{profile}`` is replaced by the + profile name, ``{target}`` is replaced by the target you specified, i.e. + either ``:feed``, ``#hashtag`` or the profile name. Defaults to ``{target}``. + See :ref:`filename-specification`. + +.. option:: --filename-pattern FILENAME_PATTERN + + Prefix of filenames. Posts are stored in the directory whose pattern is given + with ``--dirname-pattern``. ``{profile}`` is replaced by the profile name, + ``{target}`` is replaced by the target you specified, i.e. either ``:feed``, + ``#hashtag`` or the profile name. Also, the fields ``{date}`` and + ``{shortcode}`` can be specified. Defaults to ``{date:%Y-%m-%d_%H-%M-%S}``. + See :ref:`filename-specification`. + +.. option:: --user-agent USER_AGENT + + User Agent to use for HTTP requests. Per default, Instaloader pretends being + Chrome/51. + +Miscellaneous Options +^^^^^^^^^^^^^^^^^^^^^ + +.. option:: --quiet + + Disable user interaction, i.e. do not print messages (except errors) and fail + if login credentials are needed but not given. This makes Instaloader + **suitable as a cron job**. diff --git a/docs/conf.py b/docs/conf.py index c9656c9..ed3ca46 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,8 +34,16 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx_autodoc_typehints', 'sphinx.ext.githubpages', + 'sphinx.ext.intersphinx' ] +autodoc_default_flags = ['show-inheritance', 'members', 'undoc-members'] + +autodoc_member_order = 'bysource' + +intersphinx_mapping = {'python': ('https://docs.python.org/3', None), + 'requests': ('http://docs.python-requests.org/en/master', None)} + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/index.rst b/docs/index.rst index 3e5114e..dbbc4b7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,9 +4,7 @@ Instaloader **Instaloader** is a tool to download pictures (or videos) along with their captions and other metadata from Instagram. -With `Python `__ installed, do: - -:: +With `Python `__ installed, do:: $ pip3 install instaloader @@ -16,16 +14,16 @@ With `Python `__ installed, do: - downloads **public and private profiles, hashtags, user stories and feeds**, - + - downloads **comments, geotags and captions** of each post, - automatically **detects profile name changes** and renames the target directory accordingly, - + - allows **fine-grained customization** of filters and where to store downloaded media, -- is free `Open Source `__ +- is free `open source `__ software written in Python. diff --git a/docs/installation.rst b/docs/installation.rst index 532d836..bba309d 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,9 +1,28 @@ Installation ============ -.. include:: ../README.rst - :start-after: installation-start - :end-before: installation-end +.. highlight:: none + +Instaloader requires `Python `__, at least +version 3.5. If you have `pip `__ +installed, you may install Instaloader using + +:: + + pip3 install instaloader + +Alternatively, to get the most current version of Instaloader from our +`Git repository `__: + +:: + + pip3 install git+https://github.com/Thammus/instaloader + +(pass ``--upgrade`` to upgrade if Instaloader is already installed) + +Instaloader requires +`requests `__, which +will be installed automatically, if it is not already installed. If you do not want to use pip, even though it is highly recommended, and prefer installing Instaloader manually, diff --git a/instaloader.py b/instaloader.py index ce25a46..d5f6fb9 100755 --- a/instaloader.py +++ b/instaloader.py @@ -43,7 +43,9 @@ else: class InstaloaderException(Exception): - """Base exception for this script""" + """Base exception for this script. + + :note: This exception should not be raised directly.""" pass @@ -163,9 +165,13 @@ class Post: """ Structure containing information about an Instagram post. - Created by Instaloader methods get_profile_posts(), get_hashtag_posts(), get_feed_posts(). Posts are linked to - an Instaloader instance which is used for error logging and obtaining of additional metadata, if required. - This class unifies access to the properties associated with a post. It implements == and is hashable. + Created by Instaloader methods :meth:`.get_profile_posts`, :meth:`.get_hashtag_posts`, :meth:`.get_feed_posts`. + Posts are linked to an :class:`Instaloader` instance which is used for error logging and obtaining of additional + metadata, if required. This class unifies access to the properties associated with a post. It implements == and is + hashable. + + The properties defined here are accessable by the filter expressions specified with the :option:`--only-if` + parameter. """ LOGIN_REQUIRING_PROPERTIES = ["viewer_has_liked"] @@ -173,7 +179,7 @@ class Post: def __init__(self, instaloader: 'Instaloader', node: Dict[str, Any], profile: Optional[str] = None): """Create a Post instance from a node structure as returned by Instagram. - :param instaloader: Instaloader instance used for additional queries if neccessary. + :param instaloader: :class:`Instaloader` instance used for additional queries if neccessary. :param node: Node structure. :param profile: The name of the owner, if already known at creation. """ @@ -340,9 +346,14 @@ class Post: class Tristate(Enum): """Tri-state to encode whether we should save certain information, i.e. videos, captions, comments or geotags. - never: Do not save, even if the information is available without any additional request, - no_extra_query: Save if and only if available without doing additional queries, - always: Save (and query, if neccessary). + :attr:`never` + Do not save, even if the information is available without any additional request, + + :attr:`no_extra_query` + Save if and only if available without doing additional queries, + + :attr:`always` + Save (and query, if neccessary). """ never = 0 no_extra_query = 1 @@ -753,7 +764,7 @@ class Instaloader: self._log('') # log output of _get_and_write_raw() does not produce \n def save_session_to_file(self, filename: Optional[str] = None) -> None: - """Saves requests.Session object.""" + """Saves internally stored :class:`requests.Session` object.""" if filename is None: filename = get_default_session_filename(self.username) dirname = os.path.dirname(filename) @@ -766,7 +777,7 @@ class Instaloader: self._log("Saved session to %s." % filename) def load_session_from_file(self, username: str, filename: Optional[str] = None) -> None: - """Internally stores requests.Session object loaded from file. + """Internally stores :class:`requests.Session` object loaded from file. If filename is None, the file with the default session path is loaded. @@ -784,7 +795,7 @@ class Instaloader: self.username = username def test_login(self, session: Optional[requests.Session]) -> Optional[str]: - """Returns the Instagram username to which given requests.Session object belongs, or None.""" + """Returns the Instagram username to which given :class:`requests.Session` object belongs, or None.""" if session: data = self.get_json('', params={'__a': 1}, session=session) return data['graphql']['user']['username'] if 'graphql' in data else None @@ -1011,7 +1022,7 @@ class Instaloader: """ Download pictures from the user's feed. - Example to download up to the 20 pics the user last liked: :: + Example to download up to the 20 pics the user last liked:: loader = Instaloader() loader.load_session_from_file('USER') @@ -1050,7 +1061,7 @@ class Instaloader: fast_update: bool = False) -> None: """Download pictures of one hashtag. - To download the last 30 pictures with hashtag #cat, do :: + To download the last 30 pictures with hashtag #cat, do:: loader = Instaloader() loader.download_hashtag('cat', max_count=30) @@ -1081,7 +1092,8 @@ class Instaloader: has changed and return current name of the profile, and store ID of profile. :param profile: Profile name - :param profile_metadata: The profile's metadata (get_profile_metadata()), or None if the profile was not found + :param profile_metadata: + The profile's metadata (:meth:`get_profile_metadata`), or None if the profile was not found :return: current profile name, profile id """ profile_exists = profile_metadata is not None @@ -1126,7 +1138,7 @@ class Instaloader: raise ProfileNotExistsException("Profile {0} does not exist.".format(profile)) def get_profile_metadata(self, profile_name: str) -> Dict[str, Any]: - """Retrieves a profile's metadata, for use with e.g. get_profile_posts() and check_profile_id().""" + """Retrieves a profile's metadata, for use with e.g. :meth:`get_profile_posts` and :meth:`check_profile_id`.""" try: return self.get_json('{}/'.format(profile_name), params={'__a': 1}) except QueryReturnedNotFoundException: