Documentation Enhancements
This commit is contained in:
Alexander Graf
@@ -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
|
||||
|
||||
@@ -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 <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
|
||||
`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.
|
||||
|
||||
@@ -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**.
|
||||
|
||||
@@ -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']
|
||||
|
||||
|
||||
@@ -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 <https://www.python.org/>`__ installed, do:
|
||||
|
||||
::
|
||||
With `Python <https://www.python.org/>`__ installed, do::
|
||||
|
||||
$ pip3 install instaloader
|
||||
|
||||
@@ -16,16 +14,16 @@ With `Python <https://www.python.org/>`__ 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 <https://github.com/Thammus/instaloader>`__
|
||||
- is free `open source <https://github.com/Thammus/instaloader>`__
|
||||
software written in Python.
|
||||
|
||||
|
||||
|
||||
@@ -1,9 +1,28 @@
|
||||
Installation
|
||||
============
|
||||
|
||||
.. include:: ../README.rst
|
||||
:start-after: installation-start
|
||||
:end-before: installation-end
|
||||
.. highlight:: none
|
||||
|
||||
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,
|
||||
and prefer installing Instaloader manually,
|
||||
|
||||
Reference in New Issue
Block a user