instagram-archiver 0.3.3__py3-none-any.whl

instagram_archiver/__init__.py

@@ -0,0 +1,10 @@
+"""Instagram archiver."""
+
+from __future__ import annotations
+
+from .client import InstagramClient
+from .profile_scraper import ProfileScraper
+from .saved_scraper import SavedScraper
+
+__all__ = ('InstagramClient', 'ProfileScraper', 'SavedScraper')
+__version__ = 'v0.3.3'

instagram_archiver/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for ``python -m`` invocation."""
+
+from __future__ import annotations
+
+from .main import main
+
+main()

instagram_archiver/client.py

@@ -0,0 +1,290 @@
+"""Generic client."""
+
+from __future__ import annotations
+
+from http import HTTPStatus
+from os import utime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Self, TypeVar, cast
+import json
+import logging
+
+from requests import HTTPError
+from yt_dlp_utils import setup_session
+import requests
+
+from .constants import API_HEADERS, SHARED_HEADERS
+from .typing import (
+    CarouselMedia,
+    Comments,
+    Edge,
+    HighlightsTray,
+    MediaInfo,
+    MediaInfoItem,
+    MediaInfoItemImageVersions2Candidate,
+)
+from .utils import get_extension, json_dumps_formatted, write_if_new
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+    from types import TracebackType
+
+    from .typing import BrowserName
+
+__all__ = ('CSRFTokenNotFound', 'InstagramClient', 'UnexpectedRedirect')
+
+T = TypeVar('T')
+log = logging.getLogger(__name__)
+
+
+class CSRFTokenNotFound(RuntimeError):
+    """CSRF token not found in cookies."""
+
+
+class UnexpectedRedirect(RuntimeError):
+    """Unexpected redirect in a request."""
+
+
+class InstagramClient:
+    """Generic client for Instagram."""
+
+    def __init__(self, browser: BrowserName = 'chrome', browser_profile: str = 'Default') -> None:
+        """
+        Initialise the client.
+
+        Parameters
+        ----------
+        browser : str
+            The browser to use.
+
+        browser_profile : str
+            The browser profile to use.
+        """
+        self.session = setup_session(
+            browser,
+            browser_profile,
+            SHARED_HEADERS,
+            domains={'instagram.com'},
+            status_forcelist=(413, 429, 500, 502, 503, 504),
+        )
+        self.failed_urls: set[str] = set()
+        """Set of failed URLs."""
+        self.video_urls: list[str] = []
+        """List of video URLs to download."""
+
+    def add_video_url(self, url: str) -> None:
+        """Add a video URL to the list of video URLs."""
+        log.info('Added video URL: %s', url)
+        self.video_urls.append(url)
+
+    def add_csrf_token_header(self) -> None:
+        """
+        Add CSRF token header to the session.
+
+        Raises
+        ------
+        CSRFTokenNotFound
+            If the CSRF token is not found in the cookies.
+        """
+        token = self.session.cookies.get('csrftoken')
+        if not token:
+            raise CSRFTokenNotFound
+        self.session.headers.update({'x-csrftoken': token})
+
+    def graphql_query(
+        self,
+        variables: Mapping[str, Any],
+        *,
+        cast_to: type[T],  # noqa: ARG002
+        doc_id: str = '9806959572732215',
+    ) -> T | None:
+        """Make a GraphQL query."""
+        with self.session.post(
+            'https://www.instagram.com/graphql/query',
+            headers={
+                'content-type': 'application/x-www-form-urlencoded',
+            }
+            | API_HEADERS,
+            data={'doc_id': doc_id, 'variables': json.dumps(variables, separators=(',', ':'))},
+        ) as r:
+            if r.status_code != HTTPStatus.OK:
+                return None
+            data = r.json()
+            assert isinstance(data, dict)
+            if (status := data.get('status')) != 'ok':
+                log.error('GraphQL status not "ok": %s', status)
+                return None
+            if data.get('errors'):
+                log.warning('Response has errors.')
+                log.debug('Response: %s', json.dumps(data, indent=2))
+            if not data.get('data'):
+                log.error('No data in response.')
+            return cast('T', data['data'])
+
+    def get_text(self, url: str, *, params: Mapping[str, str] | None = None) -> str:
+        """Get text from a URL."""
+        with self.session.get(url, params=params, headers=API_HEADERS) as r:
+            r.raise_for_status()
+            return r.text
+
+    def highlights_tray(self, user_id: int | str) -> HighlightsTray:
+        """Get the highlights tray data for a user."""
+        return self.get_json(
+            f'https://i.instagram.com/api/v1/highlights/{user_id}/highlights_tray/',
+            cast_to=HighlightsTray,
+        )
+
+    def __enter__(self) -> Self:  # pragma: no cover
+        """Recommended way to initialise the client."""
+        return self
+
+    def __exit__(
+        self, _: type[BaseException] | None, __: BaseException | None, ___: TracebackType | None
+    ) -> None:
+        """Clean up."""
+
+    def is_saved(self, url: str) -> bool:  # pragma: no cover  # noqa: ARG002, PLR6301
+        """Check if a URL is already saved."""
+        return False
+
+    def save_to_log(self, url: str) -> None:
+        """Save a URL to the log."""
+
+    def save_image_versions2(self, sub_item: CarouselMedia | MediaInfoItem, timestamp: int) -> None:
+        """Save images in the image_versions2 dictionary."""
+
+        def key(x: MediaInfoItemImageVersions2Candidate) -> int:
+            return x['width'] * x['height']
+
+        best = max(sub_item['image_versions2']['candidates'], key=key)
+        if self.is_saved(best['url']):
+            return
+        r = self.session.head(best['url'])
+        if r.status_code != HTTPStatus.OK:
+            log.warning('HEAD request failed with status code %s.', r.status_code)
+            return
+        ext = get_extension(r.headers['content-type'])
+        name = f'{sub_item["id"]}.{ext}'
+        with Path(name).open('wb') as f:
+            f.writelines(self.session.get(best['url'], stream=True).iter_content(chunk_size=512))
+        utime(name, (timestamp, timestamp))
+        self.save_to_log(r.url)
+
+    def save_comments(self, edge: Edge) -> None:
+        """Save comments for an edge node."""
+        comment_url = f'https://www.instagram.com/api/v1/media/{edge["node"]["id"]}/comments/'
+        shared_params = {'can_support_threading': 'true'}
+        try:
+            comment_data = self.get_json(
+                comment_url,
+                params={**shared_params, 'permalink_enabled': 'false'},
+                cast_to=Comments,
+            )
+        except HTTPError:
+            log.exception('Failed to get comments.')
+            return
+        top_comment_data: Any = comment_data
+        while comment_data['can_view_more_preview_comments'] and comment_data['next_min_id']:
+            try:
+                comment_data = self.get_json(
+                    comment_url,
+                    params={
+                        **shared_params,
+                        'min_id': comment_data['next_min_id'],
+                    },
+                    cast_to=Comments,
+                )
+            except HTTPError:
+                log.exception('Failed to get comments.')
+                break
+            top_comment_data['comments'] = list(top_comment_data['comments']) + list(
+                comment_data['comments']
+            )
+        comments_json = f'{edge["node"]["id"]}-comments.json'
+        with Path(comments_json).open('w+', encoding='utf-8') as f:
+            json.dump(top_comment_data, f, sort_keys=True, indent=2)
+
+    def save_media(self, edge: Edge) -> None:
+        """
+        Save media for an edge node.
+
+        Raises
+        ------
+        UnexpectedRedirect
+            If a redirect occurs unexpectedly.
+        """
+        media_info_url = f'https://www.instagram.com/api/v1/media/{edge["node"]["pk"]}/info/'
+        log.info('Saving media at URL: %s', media_info_url)
+        if self.is_saved(media_info_url):
+            return
+        r = self.session.get(media_info_url, headers=API_HEADERS, allow_redirects=False)
+        if r.status_code != HTTPStatus.OK:
+            if r.status_code in {HTTPStatus.MOVED_PERMANENTLY, HTTPStatus.FOUND}:
+                raise UnexpectedRedirect
+            log.warning('GET request failed with status code %s.', r.status_code)
+            log.debug('Content: %s', r.text)
+            return
+        if 'image_versions2' not in r.text or 'taken_at' not in r.text:
+            log.warning('Invalid response. image_versions2 dict not found.')
+            return
+        media_info: MediaInfo = r.json()
+        timestamp = media_info['items'][0]['taken_at']
+        id_json_file = f'{edge["node"]["id"]}.json'
+        media_info_json_file = f'{edge["node"]["id"]}-media-info-0000.json'
+        write_if_new(id_json_file, str(json_dumps_formatted(edge['node'])))
+        write_if_new(media_info_json_file, str(json_dumps_formatted(media_info)))
+        for file in (id_json_file, media_info_json_file):
+            utime(file, (timestamp, timestamp))
+        self.save_to_log(media_info_url)
+        for item in media_info['items']:
+            timestamp = item['taken_at']
+            if carousel_media := item.get('carousel_media'):
+                for sub_item in carousel_media:
+                    self.save_image_versions2(sub_item, timestamp)
+            elif 'image_versions2' in item:
+                self.save_image_versions2(item, timestamp)
+
+    def save_edges(self, edges: Iterable[Edge], parent_edge: Edge | None = None) -> None:
+        """Save edge node media."""
+        for edge in edges:
+            if edge['node']['__typename'] == 'XDTMediaDict':
+                try:
+                    shortcode = edge['node']['code']
+                except KeyError:
+                    if parent_edge:
+                        try:
+                            shortcode = parent_edge['node']['code']
+                        except KeyError:
+                            log.exception('Unknown shortcode.')
+                            return
+                    else:
+                        log.exception('Unknown shortcode.')
+                if edge['node'].get('video_dash_manifest'):
+                    self.add_video_url(f'https://www.instagram.com/p/{shortcode}/')
+                else:
+                    try:
+                        self.save_comments(edge)
+                        self.save_media(edge)
+                    except requests.exceptions.RetryError:
+                        log.exception('Retries exhausted.')
+                        return
+            else:
+                log.warning(  # type: ignore[unreachable]
+                    'Unknown type: `%s`. Item %s will not be processed.',
+                    edge['node']['__typename'],
+                    edge['node']['id'],
+                )
+                shortcode = edge['node']['code']
+                self.failed_urls.add(f'https://www.instagram.com/p/{shortcode}/')
+
+    def get_json(
+        self,
+        url: str,
+        *,
+        cast_to: type[T],  # noqa: ARG002
+        params: Mapping[str, str] | None = None,
+    ) -> T:
+        """Get JSON data from a URL."""
+        with self.session.get(url, params=params, headers=API_HEADERS) as r:
+            r.raise_for_status()
+            return cast('T', r.json())

instagram_archiver/constants.py

@@ -0,0 +1,66 @@
+"""Constants."""
+
+from __future__ import annotations
+
+__all__ = ('API_HEADERS', 'BROWSER_CHOICES', 'PAGE_FETCH_HEADERS', 'SHARED_HEADERS', 'USER_AGENT')
+
+USER_AGENT = (
+    'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) '
+    'Chrome/137.0.0.0 Safari/537.36'
+)
+"""
+User agent.
+
+:meta hide-value:
+"""
+SHARED_HEADERS = {
+    'accept': '*/*',
+    'authority': 'www.instagram.com',
+    'cache-control': 'no-cache',
+    'dnt': '1',
+    'pragma': 'no-cache',
+    'user-agent': USER_AGENT,
+    # 'x-asbd-id': '359341',
+    # 'x-ig-app-id': '936619743392459',
+}
+"""
+Headers to use for requests.
+
+:meta hide-value:
+"""
+API_HEADERS = {
+    'x-asbd-id': '359341',
+    'x-ig-app-id': '936619743392459',
+}
+"""
+Headers to use for API requests.
+
+:meta hide-value:
+"""
+PAGE_FETCH_HEADERS = {
+    'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,'
+    'image/apng,*/*;q=0.8',
+    'dpr': '1.5',
+    'sec-fetch-mode': 'navigate',  # Definitely required.
+    'viewport-width': '3840',
+}
+"""
+Headers to use for fetching HTML pages.
+
+:meta hide-value:
+"""
+LOG_SCHEMA = """CREATE TABLE log (
+    url TEXT PRIMARY KEY NOT NULL,
+    date TEXT DEFAULT CURRENT_TIMESTAMP NOT NULL
+);"""
+"""
+Schema for log database.
+
+:meta hide-value:
+"""
+BROWSER_CHOICES = ('brave', 'chrome', 'chromium', 'edge', 'opera', 'vivaldi', 'firefox', 'safari')
+"""
+Possible browser choices to get cookies from.
+
+:meta hide-value:
+"""

instagram_archiver/main.py

@@ -0,0 +1,131 @@
+"""Main application."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from bascom import setup_logging
+import click
+
+from .client import UnexpectedRedirect
+from .constants import BROWSER_CHOICES
+from .profile_scraper import ProfileScraper
+from .saved_scraper import SavedScraper
+
+if TYPE_CHECKING:
+    from .typing import BrowserName
+
+__all__ = ('main',)
+
+
+@click.command(context_settings={'help_option_names': ('-h', '--help')})
+@click.option(
+    '-o',
+    '--output-dir',
+    default='%(username)s',
+    help='Output directory.',
+    type=click.Path(file_okay=False, writable=True),
+)
+@click.option(
+    '-b',
+    '--browser',
+    default='chrome',
+    type=click.Choice(BROWSER_CHOICES),
+    help='Browser to read cookies from.',
+)
+@click.option('-p', '--profile', default='Default', help='Browser profile.')
+@click.option('-d', '--debug', is_flag=True, help='Enable debug output.')
+@click.option('--no-log', is_flag=True, help='Ignore log (re-fetch everything).')
+@click.option(
+    '-C',
+    '--include-comments',
+    is_flag=True,
+    help='Also download all comments (extends download time significantly).',
+)
+@click.argument('username')
+def main(
+    output_dir: str,
+    username: str,
+    browser: BrowserName = 'chrome',
+    profile: str = 'Default',
+    *,
+    debug: bool = False,
+    include_comments: bool = False,
+    no_log: bool = False,
+) -> None:
+    """Archive a profile's posts."""  # noqa: DOC501
+    setup_logging(
+        debug=debug, loggers={'instagram_archiver': {'handlers': ('console',), 'propagate': False}}
+    )
+    try:
+        with ProfileScraper(
+            browser=browser,
+            browser_profile=profile,
+            comments=include_comments,
+            disable_log=no_log,
+            output_dir=(
+                Path(output_dir % {'username': username})
+                if '%(username)s' in output_dir
+                else Path(output_dir)
+            ),
+            username=username,
+        ) as client:
+            client.process()
+    except UnexpectedRedirect as e:
+        click.echo('Unexpected redirect. Assuming request limit has been reached.', err=True)
+        raise click.Abort from e
+    except Exception as e:
+        if isinstance(e, KeyboardInterrupt) or debug:
+            raise
+        click.echo('Run with --debug for more information.', err=True)
+        raise click.Abort from e
+
+
+@click.command(context_settings={'help_option_names': ('-h', '--help')})
+@click.option(
+    '-o',
+    '--output-dir',
+    default='.',
+    help='Output directory.',
+    type=click.Path(file_okay=False, writable=True),
+)
+@click.option(
+    '-b',
+    '--browser',
+    default='chrome',
+    type=click.Choice(BROWSER_CHOICES),
+    help='Browser to read cookies from.',
+)
+@click.option('-p', '--profile', default='Default', help='Browser profile.')
+@click.option('-d', '--debug', is_flag=True, help='Enable debug output.')
+@click.option(
+    '-C',
+    '--include-comments',
+    is_flag=True,
+    help='Also download all comments (extends download time significantly).',
+)
+@click.option('-u', '--unsave', is_flag=True, help='Unsave posts after successful archive.')
+def save_saved_main(
+    output_dir: str,
+    browser: BrowserName = 'chrome',
+    profile: str = 'Default',
+    *,
+    debug: bool = False,
+    include_comments: bool = False,
+    unsave: bool = False,
+) -> None:
+    """Archive your saved posts."""  # noqa: DOC501
+    setup_logging(
+        debug=debug, loggers={'instagram_archiver': {'handlers': ('console',), 'propagate': False}}
+    )
+    try:
+        SavedScraper(browser, profile, output_dir, comments=include_comments).process(unsave=unsave)
+    except UnexpectedRedirect as e:
+        click.echo('Unexpected redirect. Assuming request limit has been reached.', err=True)
+        raise click.Abort from e
+    except Exception as e:
+        if isinstance(e, KeyboardInterrupt) or debug:
+            raise
+        click.echo('Run with --debug for more information.', err=True)
+        raise click.Abort from e

instagram_archiver/profile_scraper.py

@@ -0,0 +1,214 @@
+"""Instagram client."""
+
+from __future__ import annotations
+
+from contextlib import chdir
+from pathlib import Path
+from typing import TYPE_CHECKING, TypeVar, override
+from urllib.parse import urlparse
+import json
+import logging
+import sqlite3
+
+from requests import HTTPError
+from yt_dlp_utils import get_configured_yt_dlp
+
+from .client import InstagramClient
+from .constants import LOG_SCHEMA
+from .typing import (
+    BrowserName,
+    WebProfileInfo,
+    XDTAPIV1FeedUserTimelineGraphQLConnectionContainer,
+)
+from .utils import SaveCommentsCheckDisabledMixin
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+__all__ = ('ProfileScraper',)
+
+T = TypeVar('T')
+log = logging.getLogger(__name__)
+
+
+def _clean_url(url: str) -> str:
+    parsed = urlparse(url)
+    return f'https://{parsed.netloc}{parsed.path}'
+
+
+class ProfileScraper(SaveCommentsCheckDisabledMixin, InstagramClient):
+    """The scraper."""
+
+    def __init__(
+        self,
+        username: str,
+        *,
+        log_file: str | Path | None = None,
+        output_dir: str | Path | None = None,
+        disable_log: bool = False,
+        browser: BrowserName = 'chrome',
+        browser_profile: str = 'Default',
+        comments: bool = False,
+    ) -> None:
+        """
+        Initialise ``ProfileScraper``.
+
+        Parameters
+        ----------
+        username : str
+            The username to scrape.
+        log_file : str | Path | None
+            The log file to use.
+        output_dir : str | Path | None
+            The output directory to save the posts to.
+        disable_log : bool
+            Whether to disable logging or not.
+        browser : BrowserName
+            The browser to use.
+        browser_profile : str
+            The browser profile to use.
+        comments : bool
+            Whether to save comments or not.
+        """
+        super().__init__(browser, browser_profile)
+        self._no_log = disable_log
+        self._output_dir = Path(output_dir or Path.cwd() / username)
+        self._output_dir.mkdir(parents=True, exist_ok=True)
+        self._log_db = Path(log_file or self._output_dir / '.log.db')
+        self._connection = sqlite3.connect(self._log_db)
+        self._cursor = self._connection.cursor()
+        self._setup_db()
+        self._username = username
+        self.should_save_comments = comments
+
+    def _setup_db(self) -> None:
+        if self._no_log:
+            return
+        existed = self._log_db.exists()
+        if not existed or (existed and self._log_db.stat().st_size == 0):
+            log.debug('Creating schema.')
+            self._cursor.execute(LOG_SCHEMA)
+
+    @override
+    def save_to_log(self, url: str) -> None:
+        if self._no_log:
+            return
+        self._cursor.execute('INSERT INTO log (url) VALUES (?)', (_clean_url(url),))
+        self._connection.commit()
+
+    @override
+    def is_saved(self, url: str) -> bool:
+        if self._no_log:
+            return False
+        self._cursor.execute('SELECT COUNT(url) FROM log WHERE url = ?', (_clean_url(url),))
+        count: int
+        (count,) = self._cursor.fetchone()
+        return count == 1
+
+    @override
+    def __exit__(
+        self, _: type[BaseException] | None, __: BaseException | None, ___: TracebackType | None
+    ) -> None:
+        """Clean up."""
+        self._cursor.close()
+        self._connection.close()
+
+    def process(self) -> None:
+        """Process posts."""
+        with chdir(self._output_dir):
+            self.get_text(f'https://www.instagram.com/{self._username}/')
+            self.add_csrf_token_header()
+            r = self.get_json(
+                'https://i.instagram.com/api/v1/users/web_profile_info/',
+                params={'username': self._username},
+                cast_to=WebProfileInfo,
+            )
+            if 'data' in r:
+                with Path('web_profile_info.json').open('w', encoding='utf-8') as f:
+                    json.dump(r, f, indent=2, sort_keys=True)
+                user_info = r['data']['user']
+                if not self.is_saved(user_info['profile_pic_url_hd']):
+                    with Path('profile_pic.jpg').open('wb') as f:
+                        f.writelines(
+                            self.session.get(
+                                user_info['profile_pic_url_hd'], stream=True
+                            ).iter_content(chunk_size=512)
+                        )
+                    self.save_to_log(user_info['profile_pic_url_hd'])
+                try:
+                    for item in self.highlights_tray(user_info['id'])['tray']:
+                        self.add_video_url(
+                            'https://www.instagram.com/stories/highlights/'
+                            f'{item["id"].split(":")[-1]}/'
+                        )
+                except HTTPError:
+                    log.exception('Failed to get highlights data.')
+                self.save_edges(user_info['edge_owner_to_timeline_media']['edges'])
+            else:
+                log.warning(
+                    'Failed to get user info. Profile information and image will not be saved.'
+                )
+            d = self.graphql_query(
+                {
+                    'data': {
+                        'count': 12,
+                        'include_reel_media_seen_timestamp': True,
+                        'include_relationship_info': True,
+                        'latest_besties_reel_media': True,
+                        'latest_reel_media': True,
+                    },
+                    'username': self._username,
+                    '__relay_internal__pv__PolarisIsLoggedInrelayprovider': True,
+                    '__relay_internal__pv__PolarisShareSheetV3relayprovider': True,
+                },
+                cast_to=XDTAPIV1FeedUserTimelineGraphQLConnectionContainer,
+            )
+            if not d:
+                log.error('First GraphQL query failed.')
+            else:
+                self.save_edges(d['xdt_api__v1__feed__user_timeline_graphql_connection']['edges'])
+                page_info = d['xdt_api__v1__feed__user_timeline_graphql_connection']['page_info']
+                while page_info['has_next_page']:
+                    d = self.graphql_query(
+                        {
+                            'after': page_info['end_cursor'],
+                            'before': None,
+                            'data': {
+                                'count': 12,
+                                'include_reel_media_seen_timestamp': True,
+                                'include_relationship_info': True,
+                                'latest_besties_reel_media': True,
+                                'latest_reel_media': True,
+                            },
+                            'first': 12,
+                            'last': None,
+                            'username': self._username,
+                            '__relay_internal__pv__PolarisIsLoggedInrelayprovider': True,
+                            '__relay_internal__pv__PolarisShareSheetV3relayprovider': True,
+                        },
+                        cast_to=XDTAPIV1FeedUserTimelineGraphQLConnectionContainer,
+                    )
+                    if not d:
+                        break
+                    page_info = d['xdt_api__v1__feed__user_timeline_graphql_connection'][
+                        'page_info'
+                    ]
+                    self.save_edges(
+                        d['xdt_api__v1__feed__user_timeline_graphql_connection']['edges']
+                    )
+            if self.video_urls:
+                with get_configured_yt_dlp() as ydl:
+                    while self.video_urls and (url := self.video_urls.pop()):
+                        if self.is_saved(url):
+                            log.info('%s is already saved.', url)
+                            continue
+                        if ydl.extract_info(url):
+                            log.info('Downloading video: %s', url)
+                            self.save_to_log(url)
+                        else:
+                            self.failed_urls.add(url)
+            if self.failed_urls:
+                log.warning('Some URIs failed. Check failed.txt.')
+                with Path('failed.txt').open('w', encoding='utf-8') as f:
+                    for url in self.failed_urls:
+                        f.write(f'{url}\n')

instagram_archiver/saved_scraper.py

@@ -0,0 +1,85 @@
+"""Saved posts scraper."""
+
+from __future__ import annotations
+
+from contextlib import chdir
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+import logging
+
+from .client import InstagramClient
+from .constants import API_HEADERS, PAGE_FETCH_HEADERS
+from .utils import SaveCommentsCheckDisabledMixin
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from .typing import BrowserName
+
+__all__ = ('SavedScraper',)
+log = logging.getLogger(__name__)
+
+
+class SavedScraper(SaveCommentsCheckDisabledMixin, InstagramClient):
+    """Scrape saved posts."""
+
+    def __init__(
+        self,
+        browser: BrowserName = 'chrome',
+        browser_profile: str = 'Default',
+        output_dir: str | Path | None = None,
+        *,
+        comments: bool = False,
+    ) -> None:
+        """
+        Initialise ``SavedScraper``.
+
+        Parameters
+        ----------
+        browser : BrowserName
+            The browser to use.
+        browser_profile : str
+            The browser profile to use.
+        output_dir : str | Path | None
+            The output directory to save the posts to.
+        comments : bool
+            Whether to save comments or not.
+        """
+        super().__init__(browser, browser_profile)
+        self._output_dir = Path(output_dir or Path.cwd() / '@@saved-posts@@')
+        Path(self._output_dir).mkdir(parents=True, exist_ok=True)
+        self.should_save_comments = comments
+
+    def unsave(self, items: Iterable[str]) -> None:
+        """Unsave saved posts."""
+        for item in items:
+            log.info('Unsaving %s.', item)
+            self.session.post(
+                f'https://www.instagram.com/web/save/{item}/unsave/', headers=API_HEADERS
+            )
+
+    def process(self, *, unsave: bool = False) -> None:
+        """Process the saved posts."""
+        with chdir(self._output_dir):
+            self.add_csrf_token_header()
+            self.session.get('https://www.instagram.com/', headers=PAGE_FETCH_HEADERS)
+            feed = self.get_json(
+                'https://www.instagram.com/api/v1/feed/saved/posts/', cast_to=dict[str, Any]
+            )
+            self.save_edges(
+                {
+                    'node': {
+                        '__typename': 'XDTMediaDict',
+                        'id': item['media']['id'],
+                        'code': item['media']['code'],
+                        'owner': item['media']['owner'],
+                        'pk': item['media']['pk'],
+                        'video_dash_manifest': item['media'].get('video_dash_manifest'),
+                    }
+                }
+                for item in feed['items']
+            )
+            if unsave:
+                self.unsave(item['media']['code'] for item in feed['items'])
+            if feed.get('more_available'):
+                log.warning('Unhandled pagination.')

instagram_archiver/typing.py

@@ -0,0 +1,195 @@
+"""Typing helpers."""
+
+# ruff: noqa: D101
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal, NotRequired, TypedDict
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = (
+    'BrowserName',
+    'CarouselMedia',
+    'Comments',
+    'Edge',
+    'HasID',
+    'HighlightsTray',
+    'MediaInfo',
+    'MediaInfoItem',
+    'MediaInfoItemImageVersions2Candidate',
+    'UserInfo',
+    'WebProfileInfo',
+    'WebProfileInfoData',
+    'XDTAPIV1FeedUserTimelineGraphQLConnection',
+    'XDTAPIV1FeedUserTimelineGraphQLConnectionContainer',
+    'XDTMediaDict',
+)
+
+
+class MediaInfoItemVideoVersion(TypedDict):
+    height: int
+    url: str
+    width: int
+
+
+class MediaInfoItemImageVersions2Candidate(TypedDict):
+    height: int
+    """Height of the image."""
+    url: str
+    """URL of the image."""
+    width: int
+    """Width of the image."""
+
+
+class HighlightItem(TypedDict):
+    id: str
+    """Identifier."""
+
+
+class HighlightsTray(TypedDict):
+    tray: Sequence[HighlightItem]
+    """Highlights tray items."""
+
+
+class PageInfo(TypedDict):
+    end_cursor: str
+    """End cursor for pagination."""
+    has_next_page: bool
+    """Whether there are more pages."""
+
+
+class EdgeOwnerToTimelineMedia(TypedDict):
+    edges: Sequence[Edge]
+    page_info: PageInfo
+    """Pagination information."""
+
+
+class UserInfo(TypedDict):
+    """User information."""
+
+    edge_owner_to_timeline_media: EdgeOwnerToTimelineMedia
+    """Timeline media edge."""
+    id: str
+    """User ID."""
+    profile_pic_url_hd: str
+    """Profile picture URL."""
+
+
+class MediaInfoItemImageVersions2(TypedDict):
+    candidates: Sequence[MediaInfoItemImageVersions2Candidate]
+    """Image versions."""
+
+
+class CarouselMedia(TypedDict):
+    image_versions2: MediaInfoItemImageVersions2
+    """Image versions."""
+    id: str
+    """Identifier."""
+
+
+class HasID(TypedDict):
+    """Dictionary with an ``id`` field."""
+
+    id: str
+    """Identifier."""
+
+
+class MediaInfoItem(TypedDict):
+    """Media information item."""
+
+    carousel_media: NotRequired[Sequence[CarouselMedia] | None]
+    """Carousel media items."""
+    image_versions2: MediaInfoItemImageVersions2
+    """Image versions."""
+    id: str
+    """Identifier."""
+    taken_at: int
+    """Timestamp when the media was taken"""
+    user: HasID
+    """User who posted the media."""
+    video_dash_manifest: NotRequired[str | None]
+    """URL of the video dash manifest."""
+    video_duration: float
+    """Duration of the video in seconds."""
+    video_versions: Sequence[MediaInfoItemVideoVersion]
+    """Video versions."""
+
+
+class Comments(TypedDict):
+    """Comments container."""
+
+    can_view_more_preview_comments: bool
+    """Whether more preview comments can be viewed."""
+    comments: Sequence[HasID]
+    """List of comments."""
+    next_min_id: str
+    """Next minimum ID for pagination."""
+
+
+class MediaInfo(TypedDict):
+    """Media information."""
+
+    items: Sequence[MediaInfoItem]
+    """List of media items."""
+
+
+class Owner(TypedDict):
+    id: str
+    """Owner ID."""
+    username: str
+    """Owner username."""
+
+
+class XDTMediaDict(TypedDict):
+    __typename: Literal['XDTMediaDict']
+    """Type name."""
+    code: str
+    """Short code."""
+    id: str
+    """Media ID."""
+    owner: Owner
+    """Owner information."""
+    pk: str
+    """Primary key. Also carousel ID."""
+    video_dash_manifest: NotRequired[str | None]
+    """Video dash manifest URL, if available."""
+
+
+class Edge(TypedDict):
+    """Edge of a graph."""
+
+    node: XDTMediaDict
+    """Node at this edge."""
+
+
+class XDTAPIV1FeedUserTimelineGraphQLConnection(TypedDict):
+    edges: Sequence[Edge]
+    """Edges of the graph."""
+    page_info: PageInfo
+    """Pagination information."""
+
+
+class XDTAPIV1FeedUserTimelineGraphQLConnectionContainer(TypedDict):
+    """Container for :py:class:`XDTAPIV1FeedUserTimelineGraphQLConnection`."""
+
+    xdt_api__v1__feed__user_timeline_graphql_connection: XDTAPIV1FeedUserTimelineGraphQLConnection
+    """User timeline data."""
+
+
+class WebProfileInfoData(TypedDict):
+    user: UserInfo
+    """User information."""
+
+
+class WebProfileInfo(TypedDict):
+    """Profile information container."""
+
+    data: NotRequired[WebProfileInfoData]
+    """Profile data."""
+
+
+BrowserName = Literal[
+    'brave', 'chrome', 'chromium', 'edge', 'firefox', 'opera', 'safari', 'vivaldi'
+]
+"""Possible browser choices to get cookies from."""

instagram_archiver/utils.py

@@ -0,0 +1,96 @@
+"""Utility functions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, Protocol, TypeVar, override
+import json
+
+import click
+
+if TYPE_CHECKING:
+    from .typing import Edge
+
+__all__ = (
+    'JSONFormattedString',
+    'UnknownMimetypeError',
+    'get_extension',
+    'json_dumps_formatted',
+    'write_if_new',
+)
+
+T = TypeVar('T')
+
+
+class JSONFormattedString:
+    """Contains a formatted version of the JSON str and the original value."""
+
+    def __init__(self, formatted: str, original: Any) -> None:
+        self.formatted = formatted
+        """Formatted JSON string."""
+        self.original_value = original
+        """Original value."""
+
+    @override
+    def __str__(self) -> str:
+        return self.formatted
+
+
+def json_dumps_formatted(obj: Any) -> JSONFormattedString:
+    """
+    Return a special object with the formatted version of the JSON str and the original.
+
+    Parameters
+    ----------
+    obj : Any
+        The object to be formatted.
+    """
+    return JSONFormattedString(json.dumps(obj, sort_keys=True, indent=2), obj)
+
+
+def write_if_new(target: Path | str, content: str | bytes, mode: str = 'w') -> None:
+    """Write a file only if it will be a new file."""
+    if not Path(target).is_file():
+        with click.open_file(str(target), mode) as f:
+            f.write(content)
+
+
+class UnknownMimetypeError(Exception):
+    """Raised when an unknown mimetype is encountered in :py:func:`~get_extension`."""
+
+
+def get_extension(mimetype: str) -> Literal['png', 'jpg']:
+    """
+    Get the appropriate three-letter extension for a mimetype.
+
+    Raises
+    ------
+    UnknownMimetypeError
+        If the mimetype is not recognised.
+    """
+    if mimetype == 'image/jpeg':
+        return 'jpg'
+    if mimetype == 'image/png':
+        return 'png'
+    raise UnknownMimetypeError(mimetype)
+
+
+if TYPE_CHECKING:
+
+    class InstagramClientInterface(Protocol):
+        should_save_comments: bool
+
+        def save_comments(self, edge: Edge) -> None: ...
+
+else:
+    InstagramClientInterface = object
+
+
+class SaveCommentsCheckDisabledMixin(InstagramClientInterface):
+    """Mixin to control saving comments."""
+
+    @override
+    def save_comments(self, edge: Edge) -> None:
+        if not self.should_save_comments:
+            return
+        super().save_comments(edge)  # type: ignore[safe-super]

instagram_archiver-0.3.3.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: instagram-archiver
+Version: 0.3.3
+Summary: Save Instagram content you have access to.
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: command line,instagram
+Author: Andrew Udvare
+Author-email: audvare@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: bascom (>=0.0.4,<0.0.5)
+Requires-Dist: click (>=8.3.0,<9.0.0)
+Requires-Dist: requests (>=2.32.5,<3.0.0)
+Requires-Dist: typing-extensions (>=4.15.0,<5.0.0)
+Requires-Dist: yt-dlp-utils (>=0.0.6,<0.0.7)
+Project-URL: Documentation, https://instagram-archiver.readthedocs.org
+Project-URL: Homepage, https://tatsh.github.io/instagram-archiver/
+Project-URL: Issues, https://github.com/Tatsh/instagram-archiver/issues
+Project-URL: Repository, https://github.com/Tatsh/instagram-archiver
+Description-Content-Type: text/markdown
+
+# instagram-archiver
+
+[![Python versions](https://img.shields.io/pypi/pyversions/instagram-archiver.svg?color=blue&logo=python&logoColor=white)](https://www.python.org/)
+[![PyPI - Version](https://img.shields.io/pypi/v/instagram-archiver)](https://pypi.org/project/instagram-archiver/)
+[![GitHub tag (with filter)](https://img.shields.io/github/v/tag/Tatsh/instagram-archiver)](https://github.com/Tatsh/instagram-archiver/tags)
+[![License](https://img.shields.io/github/license/Tatsh/instagram-archiver)](https://github.com/Tatsh/instagram-archiver/blob/master/LICENSE.txt)
+[![GitHub commits since latest release (by SemVer including pre-releases)](https://img.shields.io/github/commits-since/Tatsh/instagram-archiver/v0.3.3/master)](https://github.com/Tatsh/instagram-archiver/compare/v0.3.3...master)
+[![CodeQL](https://github.com/Tatsh/instagram-archiver/actions/workflows/codeql.yml/badge.svg)](https://github.com/Tatsh/instagram-archiver/actions/workflows/codeql.yml)
+[![QA](https://github.com/Tatsh/instagram-archiver/actions/workflows/qa.yml/badge.svg)](https://github.com/Tatsh/instagram-archiver/actions/workflows/qa.yml)
+[![Tests](https://github.com/Tatsh/instagram-archiver/actions/workflows/tests.yml/badge.svg)](https://github.com/Tatsh/instagram-archiver/actions/workflows/tests.yml)
+[![Coverage Status](https://coveralls.io/repos/github/Tatsh/instagram-archiver/badge.svg?branch=master)](https://coveralls.io/github/Tatsh/instagram-archiver?branch=master)
+[![Documentation Status](https://readthedocs.org/projects/instagram-archiver/badge/?version=latest)](https://instagram-archiver.readthedocs.org/?badge=latest)
+[![mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![pydocstyle](https://img.shields.io/badge/pydocstyle-enabled-AD4CD3)](http://www.pydocstyle.org/en/stable/)
+[![pytest](https://img.shields.io/badge/pytest-zz?logo=Pytest&labelColor=black&color=black)](https://docs.pytest.org/en/stable/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Downloads](https://static.pepy.tech/badge/instagram-archiver/month)](https://pepy.tech/project/instagram-archiver)
+[![Stargazers](https://img.shields.io/github/stars/Tatsh/instagram-archiver?logo=github&style=flat)](https://github.com/Tatsh/instagram-archiver/stargazers)
+
+[![@Tatsh](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpublic.api.bsky.app%2Fxrpc%2Fapp.bsky.actor.getProfile%2F%3Factor%3Ddid%3Aplc%3Auq42idtvuccnmtl57nsucz72%26query%3D%24.followersCount%26style%3Dsocial%26logo%3Dbluesky%26label%3DFollow%2520%40Tatsh&query=%24.followersCount&style=social&logo=bluesky&label=Follow%20%40Tatsh)](https://bsky.app/profile/Tatsh.bsky.social)
+[![Mastodon Follow](https://img.shields.io/mastodon/follow/109370961877277568?domain=hostux.social&style=social)](https://hostux.social/@Tatsh)
+
+Save Instagram content you have access to.
+
+## Installation
+
+### Poetry
+
+```shell
+poetry add instagram-archiver
+```
+
+### Pip
+
+```shell
+pip install instagram-archiver
+```
+
+## Usage
+
+```plain
+Usage: instagram-archiver [OPTIONS] USERNAME
+
+  Archive a profile's posts.
+
+Options:
+  -o, --output-dir DIRECTORY      Output directory.
+  -b, --browser [brave|chrome|chromium|edge|opera|vivaldi|firefox|safari]
+                                  Browser to read cookies from.
+  -p, --profile TEXT              Browser profile.
+  -d, --debug                     Enable debug output.
+  --no-log                        Ignore log (re-fetch everything).
+  -C, --include-comments          Also download all comments (extends download
+                                  time significantly).
+  -h, --help                      Show this message and exit.
+```
+
+Typical use:
+
+```shell
+instagram-archiver -o ~/instagram-backups/username username
+```
+
+### `instagram-save-saved`
+
+This tool saves your saved posts (at `www.instagram.com/username/saved/all-posts`).
+
+```plain
+Usage: instagram-save-saved [OPTIONS]
+
+  Archive your saved posts.
+
+Options:
+  -o, --output-dir DIRECTORY      Output directory.
+  -b, --browser [brave|chrome|chromium|edge|opera|vivaldi|firefox|safari]
+                                  Browser to read cookies from.
+  -p, --profile TEXT              Browser profile.
+  -d, --debug                     Enable debug output.
+  -C, --include-comments          Also download all comments (extends download
+                                  time significantly).
+  -u, --unsave                    Unsave posts after successful archive.
+  -h, --help                      Show this message and exit.
+```
+
+## Notes
+
+The default output path is the username under the current working directory.
+
+Videos are saved using yt-dlp and its respective configuration.
+

instagram_archiver-0.3.3.dist-info/RECORD

@@ -0,0 +1,15 @@
+instagram_archiver/__init__.py,sha256=d74_Lpwy4wMo0DjrJEFfFqI37yBeM_fso7n-a6IJVwY,271
+instagram_archiver/__main__.py,sha256=oQb8YAn5SGNM15OuCcOYPqBDgQtNFZ7FZJvVdLRsckE,116
+instagram_archiver/client.py,sha256=AnTFq7NivYfEBUIGHn-teh2Gw_vsgUT2XscOoe3wyC4,10689
+instagram_archiver/constants.py,sha256=eN33N_nd3Nuo6fnlXZzhYl0QfGBjVwdtq9dZwRys8_M,1446
+instagram_archiver/main.py,sha256=LYnJcnRZATrGkuXh_oE7X8Xd_Li7NXzXIFfpnSh2AfY,4032
+instagram_archiver/profile_scraper.py,sha256=uRcVA39h3X59LFXbBST2aWyyxgcemyhM2qd8BBibeT8,8345
+instagram_archiver/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+instagram_archiver/saved_scraper.py,sha256=9x9UVspraq1H3zyG8gn7Q_2GPu7iCPG7zZpnsARZLd8,2850
+instagram_archiver/typing.py,sha256=1vOr3qIiOZhvzSSBpUc3iFKgEZE5ryd_oCysF_ZGpls,4395
+instagram_archiver/utils.py,sha256=4wePufLtJZjiSRucMz5kD-_mM1SJyOynusZONqvyonE,2378
+instagram_archiver-0.3.3.dist-info/METADATA,sha256=MzIVF7R_Vm3kOXnb646fwS8DuoHylBfV2ydwoQbgLuk,5996
+instagram_archiver-0.3.3.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+instagram_archiver-0.3.3.dist-info/entry_points.txt,sha256=kNXd0Sy6896DEBRcx2mVYiaE-OR9-XR56MpWuaNa49g,128
+instagram_archiver-0.3.3.dist-info/licenses/LICENSE.txt,sha256=cDLmbhzFwEUz5FL_OnA6Jp9zdz80330J6YyEq-00yNQ,1093
+instagram_archiver-0.3.3.dist-info/RECORD,,

instagram_archiver-0.3.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

instagram_archiver-0.3.3.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+instagram-archiver=instagram_archiver.main:main
+instagram-save-saved=instagram_archiver.main:save_saved_main
+

instagram_archiver-0.3.3.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,18 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 instagram-archiver authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
+OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.