Mirrors/instaloader
1
0
Fork 0
mirror of https://github.com/instaloader/instaloader.git synced 2024-11-23 10:42:30 +01:00
Code Issues Releases Activity

Documentation Enhancements

Browse Source
This commit is contained in:
Alexander Graf 2017-09-08 10:35:38 +02:00
parent 9ae7b23939
commit 9a72f85a0e
8 changed files with 464 additions and 353 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

326
README.rst
View File

@ -1,39 +1,31 @@
Instaloader Instaloader
=========== ===========
Installation
------------
.. installation-start
Instaloader requires `Python <https://www.python.org/>`__, at least
version 3.5. If you have `pip <https://pypi.python.org/pypi/pip>`__
installed, you may install Instaloader using
:: ::
pip3 install instaloader $ pip3 install instaloader
Alternatively, to get the most current version of Instaloader from our $ instaloader profile [profile ...]
`Git repository <https://github.com/Thammus/instaloader>`__:
:: **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 - automatically **detects profile name changes** and renames the target
`requests <http://python-requests.org/>`__, which directory accordingly,
will be installed automatically, if it is not already installed.
- allows **fine-grained customization** of filters and where to store
downloaded media.
`Instaloader Documentation <https://instaloader.readthedocs.io/>`__
.. installation-end
How to Automatically Download Pictures from Instagram How to Automatically Download Pictures from Instagram
----------------------------------------------------- -----------------------------------------------------
.. basic-usage-start
To **download all pictures and videos of a profile**, as well as the To **download all pictures and videos of a profile**, as well as the
**profile picture**, do **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 If ``--fast-update`` is given, Instaloader stops when arriving at the
first already-downloaded picture. When updating profiles, Instaloader first already-downloaded picture. When updating profiles, Instaloader
automatically **detects profile name changes** and renames the target automatically **detects profile name changes** and renames the target directory
directory accordingly. accordingly.
Instaloader can also be used to **download private profiles**. To do so, Instaloader can also be used to **download private profiles**. To do so,
invoke it with invoke it with
@ -62,291 +54,13 @@ invoke it with
instaloader --login=your_username profile [profile ...] instaloader --login=your_username profile [profile ...]
When logging in, Instaloader **stores the session cookies** in a file in When logging in, Instaloader **stores the session cookies** in a file in your
your temporary directory, which will be reused later the next time temporary directory, which will be reused later the next time ``--login``
``--login`` is given. So you can download private profiles is given. So you can download private profiles **non-interactively** when you
**non-interactively** when you already have a valid session cookie file. already have a valid session cookie file.
What to Download `Instaloader Documentation <https://instaloader.readthedocs.io/basic-usage.html>`__
^^^^^^^^^^^^^^^^
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 <https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior>`__
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 <https://instaloader.readthedocs.io/basic-usage.html#filter-posts>`__)
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 <https://instaloader.readthedocs.io/as-module.html>`__ for
more information.
Disclaimer Disclaimer
---------- ----------

118
docs/as-module.rst
View File

@ -1,26 +1,114 @@
Usage as Python Module Python Module :mod:`instaloader`
---------------------- --------------------------------
Introduction .. module:: instaloader
^^^^^^^^^^^^
.. include:: ../README.rst .. highlight:: python
:start-after: as-module-intro-start
:end-before: as-module-intro-end 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) ``Instaloader`` (Main Class)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: instaloader.Instaloader .. autoclass:: Instaloader
:members: :no-show-inheritance:
:undoc-members:
.. _post-class:
``Post`` Class ``Post`` Class
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
.. autoclass:: instaloader.Post .. autoclass:: Post
:members: :no-show-inheritance:
:undoc-members:
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

143
docs/basic-usage.rst
View File

@ -1,15 +1,148 @@
Download Pictures from Instagram Download Pictures from Instagram
--------------------------------- ---------------------------------
.. highlight:: none
.. NOTE that Section "Basic Usage" is duplicated in README.rst.
Basic Usage Basic Usage
^^^^^^^^^^^ ^^^^^^^^^^^
.. include:: ../README.rst To **download all pictures and videos of a profile**, as well as the
:start-after: basic-usage-start **profile picture**, do
:end-before: basic-usage-end
.. (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 <https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior>`__
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 The given string is evaluated as a
`Python boolean expression <https://docs.python.org/3/reference/expressions.html#boolean-operations>`__, `Python boolean expression <https://docs.python.org/3/reference/expressions.html#boolean-operations>`__,
where all occuring variables are properties of the :ref:`post-class`. where all occuring variables are attributes of the :class:`.Post` class.

145
docs/cli-options.rst
View File

@ -1,6 +1,145 @@
Command Line Options Command Line Options
==================== ====================
.. include:: ../README.rst The following flags can be given to Instaloader to specify how profiles should
:start-after: cli-options-start be downloaded.
:end-before: cli-options-end
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**.

8
docs/conf.py
View File

@ -34,8 +34,16 @@ extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
'sphinx_autodoc_typehints', 'sphinx_autodoc_typehints',
'sphinx.ext.githubpages', '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. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']

10
docs/index.rst
View File

@ -4,9 +4,7 @@ Instaloader
**Instaloader** is a tool to download pictures (or videos) along with **Instaloader** is a tool to download pictures (or videos) along with
their captions and other metadata from Instagram. their captions and other metadata from Instagram.
With `Python <https://www.python.org/>`__ installed, do: With `Python <https://www.python.org/>`__ installed, do::
::
$ pip3 install instaloader $ pip3 install instaloader
@ -16,16 +14,16 @@ With `Python <https://www.python.org/>`__ installed, do:
- downloads **public and private profiles, hashtags, user stories and - downloads **public and private profiles, hashtags, user stories and
feeds**, feeds**,
- downloads **comments, geotags and captions** of each post, - downloads **comments, geotags and captions** of each post,
- automatically **detects profile name changes** and renames the target - automatically **detects profile name changes** and renames the target
directory accordingly, directory accordingly,
- allows **fine-grained customization** of filters and where to store - allows **fine-grained customization** of filters and where to store
downloaded media, downloaded media,
- is free `Open Source <https://github.com/Thammus/instaloader>`__ - is free `open source <https://github.com/Thammus/instaloader>`__
software written in Python. software written in Python.

25
docs/installation.rst
View File

@ -1,9 +1,28 @@
Installation Installation
============ ============
.. include:: ../README.rst .. highlight:: none
:start-after: installation-start
:end-before: installation-end Instaloader requires `Python <https://www.python.org/>`__, at least
version 3.5. If you have `pip <https://pypi.python.org/pypi/pip>`__
installed, you may install Instaloader using
::
pip3 install instaloader
Alternatively, to get the most current version of Instaloader from our
`Git repository <https://github.com/Thammus/instaloader>`__:
::
pip3 install git+https://github.com/Thammus/instaloader
(pass ``--upgrade`` to upgrade if Instaloader is already installed)
Instaloader requires
`requests <http://python-requests.org/>`__, 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, If you do not want to use pip, even though it is highly recommended,
and prefer installing Instaloader manually, and prefer installing Instaloader manually,

42
instaloader.py
View File

@ -43,7 +43,9 @@ else:
class InstaloaderException(Exception): class InstaloaderException(Exception):
"""Base exception for this script""" """Base exception for this script.
:note: This exception should not be raised directly."""
pass pass
@ -163,9 +165,13 @@ class Post:
""" """
Structure containing information about an Instagram 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 Created by Instaloader methods :meth:`.get_profile_posts`, :meth:`.get_hashtag_posts`, :meth:`.get_feed_posts`.
an Instaloader instance which is used for error logging and obtaining of additional metadata, if required. Posts are linked to an :class:`Instaloader` instance which is used for error logging and obtaining of additional
This class unifies access to the properties associated with a post. It implements == and is hashable. 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"] 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): 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. """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 node: Node structure.
:param profile: The name of the owner, if already known at creation. :param profile: The name of the owner, if already known at creation.
""" """
@ -340,9 +346,14 @@ class Post:
class Tristate(Enum): class Tristate(Enum):
"""Tri-state to encode whether we should save certain information, i.e. videos, captions, comments or geotags. """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, :attr:`never`
no_extra_query: Save if and only if available without doing additional queries, Do not save, even if the information is available without any additional request,
always: Save (and query, if neccessary).
:attr:`no_extra_query`
Save if and only if available without doing additional queries,
:attr:`always`
Save (and query, if neccessary).
""" """
never = 0 never = 0
no_extra_query = 1 no_extra_query = 1
@ -753,7 +764,7 @@ class Instaloader:
self._log('') # log output of _get_and_write_raw() does not produce \n self._log('') # log output of _get_and_write_raw() does not produce \n
def save_session_to_file(self, filename: Optional[str] = None) -> None: 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: if filename is None:
filename = get_default_session_filename(self.username) filename = get_default_session_filename(self.username)
dirname = os.path.dirname(filename) dirname = os.path.dirname(filename)
@ -766,7 +777,7 @@ class Instaloader:
self._log("Saved session to %s." % filename) self._log("Saved session to %s." % filename)
def load_session_from_file(self, username: str, filename: Optional[str] = None) -> None: 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. If filename is None, the file with the default session path is loaded.
@ -784,7 +795,7 @@ class Instaloader:
self.username = username self.username = username
def test_login(self, session: Optional[requests.Session]) -> Optional[str]: 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: if session:
data = self.get_json('', params={'__a': 1}, session=session) data = self.get_json('', params={'__a': 1}, session=session)
return data['graphql']['user']['username'] if 'graphql' in data else None return data['graphql']['user']['username'] if 'graphql' in data else None
@ -1011,7 +1022,7 @@ class Instaloader:
""" """
Download pictures from the user's feed. 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 = Instaloader()
loader.load_session_from_file('USER') loader.load_session_from_file('USER')
@ -1050,7 +1061,7 @@ class Instaloader:
fast_update: bool = False) -> None: fast_update: bool = False) -> None:
"""Download pictures of one hashtag. """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 = Instaloader()
loader.download_hashtag('cat', max_count=30) 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. has changed and return current name of the profile, and store ID of profile.
:param profile: Profile name :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 :return: current profile name, profile id
""" """
profile_exists = profile_metadata is not None profile_exists = profile_metadata is not None
@ -1126,7 +1138,7 @@ class Instaloader:
raise ProfileNotExistsException("Profile {0} does not exist.".format(profile)) raise ProfileNotExistsException("Profile {0} does not exist.".format(profile))
def get_profile_metadata(self, profile_name: str) -> Dict[str, Any]: 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: try:
return self.get_json('{}/'.format(profile_name), params={'__a': 1}) return self.get_json('{}/'.format(profile_name), params={'__a': 1})
except QueryReturnedNotFoundException: except QueryReturnedNotFoundException: