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_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