InstaloaderContext (Low-level functions)

InstaloaderContext

class instaloader.InstaloaderContext(sleep: bool = True, quiet: bool = False, user_agent: str | None = None, max_connection_attempts: int = 3, request_timeout: float = 300.0, rate_controller: Callable[[InstaloaderContext], RateController] | None = None, fatal_status_codes: List[int] | None = None, iphone_support: bool = True)

Class providing methods for (error) logging and low-level communication with Instagram.

It is not thought to be instantiated directly, rather Instaloader instances maintain a context object.

For logging, it provides log(), error(), error_catcher().

It provides low-level communication routines get_json(), graphql_query(), graphql_node_list(), get_and_write_raw() and implements mechanisms for rate controlling and error handling.

Further, it provides methods for logging in and general session handles, which are used by that routines in class Instaloader.

anonymous_copy()
close()

Print error log and close session

do_sleep()

Sleep a short time if self.sleep is set. Called before each request to instagram.com.

doc_id_graphql_query(doc_id: str, variables: Dict[str, Any], referer: str | None = None) → Dict[str, Any]

Do a doc_id-based GraphQL Query using method POST.

Added in version 4.13.

Parameters:

  • doc_id – doc_id for the query.

  • variables – Variables for the Query.

  • referer – HTTP Referer, or None.

Returns:

The server’s response dictionary.

error(msg, repeat_at_end=True)

Log a non-fatal error message to stderr, which is repeated at program termination.

Parameters:

  • msg – Message to be printed.

  • repeat_at_end – Set to false if the message should be printed, but not repeated at program termination.

error_catcher(extra_info: str | None = None)

Context manager to catch, print and record InstaloaderExceptions.

Parameters:

extra_info – String to prefix error message with.

get_and_write_raw(url: str, filename: str) → None

Downloads and writes anonymously-requested raw data into a file.

Raises:
get_anonymous_session() → Session

Returns our default anonymous requests.Session object.

get_iphone_json(path: str, params: Dict[str, Any]) → Dict[str, Any]

JSON request to i.instagram.com.

Parameters:

  • path – URL, relative to i.instagram.com/

  • params – GET parameters

Returns:

Decoded response dictionary

Raises:

Added in version 4.2.1.

get_json(path: str, params: Dict[str, Any], host: str = 'www.instagram.com', session: Session | None = None, _attempt=1, response_headers: Dict[str, Any] | None = None, use_post: bool = False) → Dict[str, Any]

JSON request to Instagram.

Parameters:

  • path – URL, relative to the given domain which defaults to www.instagram.com/

  • params – request parameters

  • host – Domain part of the URL from where to download the requested JSON; defaults to www.instagram.com

  • session – Session to use, or None to use self.session

  • use_post – Use POST instead of GET to make the request

Returns:

Decoded response dictionary

Raises:

Changed in version 4.13: Added use_post parameter.

get_page_data(path: str) → List[Dict[str, Any]]

Load a page of www.instagram.com as a logged-out visitor and return the data it embeds.

Instagram renders public profile and post pages with the results of their GraphQL queries embedded in the HTML, even when it refuses anonymous API requests for the same data.

Parameters:

path – URL, relative to www.instagram.com/

Returns:

The data object of each query result that the page embeds, in page order.

Raises:
get_raw(url: str, _attempt=1) → Response

Downloads a file anonymously.

Raises:

Added in version 4.2.1.

graphql_node_list(query_hash: str, query_variables: Dict[str, Any], query_referer: str | None, edge_extractor: Callable[[Dict[str, Any]], Dict[str, Any]], _rhx_gis: str | None = None, first_data: Dict[str, Any] | None = None) → Iterator[Dict[str, Any]]

Retrieve a list of GraphQL nodes.

Deprecated since version 4.5: Use NodeIterator instead, which provides more functionality.

graphql_query(query_hash: str, variables: Dict[str, Any], referer: str | None = None) → Dict[str, Any]

Do a GraphQL Query.

Parameters:

  • query_hash – Query identifying hash.

  • variables – Variables for the Query.

  • referer – HTTP Referer, or None.

Returns:

The server’s response dictionary.

Changed in version 4.13.1: Removed the rhx_gis parameter.

property has_stored_errors: bool

Returns whether any error has been reported and stored to be repeated at program termination.

head(url: str, allow_redirects: bool = False) → Response

HEAD a URL anonymously.

Raises:

Added in version 4.7.6.

property is_logged_in: bool

True, if this Instaloader instance is logged in.

load_session(username, sessiondata)

Not meant to be used directly, use Instaloader.load_session().

load_session_from_file(username, sessionfile)

Not meant to be used directly, use Instaloader.load_session_from_file().

log(*msg, sep='', end='\n', flush=False)

Log a message to stdout that can be suppressed with –quiet.

login(user, passwd)

Not meant to be used directly, use Instaloader.login().

Raises:

Changed in version 4.12: Raises LoginException instead of ConnectionException when an error happens. Raises LoginException instead of InvalidArgumentException when the username does not exist.

save_session()

Not meant to be used directly, use Instaloader.save_session().

save_session_to_file(sessionfile)

Not meant to be used directly, use Instaloader.save_session_to_file().

test_login() → str | None

Not meant to be used directly, use Instaloader.test_login().

two_factor_login(two_factor_code)

Second step of login if 2FA is enabled. Not meant to be used directly, use Instaloader.two_factor_login().

Raises:

Added in version 4.2.

update_cookies(cookie)

Added in version 4.11.

write_raw(resp: bytes | Response, filename: str) → None

Write raw response data into a file.

Added in version 4.2.1.

RateController

class instaloader.RateController(context: InstaloaderContext)

Class providing request tracking and rate controlling to stay within rate limits.

It can be overridden to change Instaloader’s behavior regarding rate limits, for example to raise a custom exception when the rate limit is hit:

import instaloader

class MyRateController(instaloader.RateController):
    def sleep(self, secs):
        raise MyCustomException()

L = instaloader.Instaloader(rate_controller=lambda ctx: MyRateController(ctx))

Added in version 4.5.

count_per_sliding_window(query_type: str) → int

Return how many requests of the given type can be done within a sliding window of 11 minutes.

This is called by RateController.query_waittime() and allows to simply customize wait times before queries at query_type granularity. Consider overriding RateController.query_waittime() directly if you need more control.

handle_429(query_type: str) → None

This method is called to handle a 429 Too Many Requests response.

It calls RateController.query_waittime() to determine the time needed to wait and then calls RateController.sleep() to wait until we can repeat the same request.

query_waittime(query_type: str, current_time: float, untracked_queries: bool = False) → float

Calculate time needed to wait before query can be executed.

sleep(secs: float)

Wait given number of seconds.

wait_before_query(query_type: str) → None

This method is called before a query to Instagram.

It calls RateController.query_waittime() to determine the time needed to wait and then calls RateController.sleep() to wait until the request can be made.

Next Section

Exceptions