Module ipernity.api

Ipernity API Class

All funcionality in PyIpernity is available through the IpernityAPI class.

class ipernity.api.IpernityAPI(api_key: str, api_secret: str, token: str | Mapping | None = None, auth: str | AuthHandler = 'desktop', url: str = 'https://api.ipernity.com/api/', auth_url_base: str = 'https://www.ipernity.com/apps/authorize')[source]

Bases: object

Encapsulates Ipernity functionality.

See Calling API methods for access to the individual API methods.

Parameters:

  • api_key – The API key obtained from Ipernity.

  • api_secret – The secret belonging to the API key.

  • token – API token. Can be given as a string or as a mapping. When given as a mapping, the actual token is extracted as token['token'], token['user'] is stored as user information (see user_info), and token['permissions'] is stored as permissions. The format of the mapping should be like the return data of [auth.getToken].

  • auth – Authentication methop, can be desktop, web or a subclass of AuthHandler (not an instance thereof!). The authentication handler is set accordingly.

  • url – API URL, should normally be left alone.

  • auth_url_base – Base for Authentication URLs, should normally be left alone.

See also

Changed in version 0.3.1: * New argument auth_url_base * URLs default to HTTPS

Changed in version 0.3.0: auth can be a subclass of AuthHandler.

property auth: AuthHandler

The authentication handler

property api_key: str

The API key generated by Ipernity

Assigning a new value will set token to None.

Added in version 0.3.0.

property api_secret: str

The API secret generated by Ipernity

Assigning a new value will set token to None.

Added in version 0.3.0.

property token: str

The authentication token

When setting, the new value can be given as a string or as dict. If given as a dict, the actual token is extracted as token['token'].

property user_info: dict | None

Information about the current user

property permissions: dict | None

Information about the current permissions

Added in version 0.1.5.

has_permissions(permissions: Mapping[str, str] | None) → bool[source]

Checks if the API has at least the given permissions.

Returns False if the token is None.

Added in version 0.1.5.

call(method_name: str, **kwargs: api_arg) → dict[source]

Makes an API call.

Parameters:

  • method_name – API method to call

  • kwargs – API arguments

Raises:

Changed in version 0.2.0: An HTTP error raises APIRequestError instead of HTTPError.

upload_file(filename: str, **kwargs: api_arg) → str[source]

Simplified interface to uploading a file

Parameters:

  • filename – The file to be uploaded. Can be relative or absolute.

  • kwargs – Additional attributes for [upload.file].

Returns:

The doc_id of the uploaded file.

Raises:

UploadError – The ticket gets invalid.

walk_data(method_name: str, elem_name: str | None = None, **kwargs: api_arg) → Iterable[dict][source]

Iterates over an arbitrary API search/list.

walk_data guesses the structure of the returned JSON object from the API method used. If this does not work, the elem_name argument can be given to specify the object keys:

  • If elem_name contains dots, the last part is taken to be the innermost key that points to the list of elements to iterate over, while the preceding parts specify the outer keys.

  • If elem_name does not contain dots, the returned JSON is assumed to contain a key “elem_name``+s" pointing to an object that contains a key "``elem_name” that contains the list of results.

Parameters:

  • method_name – Search method to call. The method must accept the page argument.

  • elem_name – Name of list elements.

  • kwargs – Argument for the search method. Use per_page to set the number of returned elements per method call.

Yields:

dict containing the element data.

walk_albums(**kwargs: api_arg) → Iterable[dict][source]

Iterates over a user’s albums.

See the album.getList documentation for possible arguments.

walk_album_docs(album_id: int, **kwargs: api_arg) → Iterable[dict][source]

Iterates over the documents of an album.

See the album.docs.getList documentation for optional arguments.

Parameters:

Iterates over a search result.

See the doc.search documentation for possible arguments.

walk_docs(**kwargs: api_arg) → Iterable[dict][source]

Iterates over a user’s documents.

See the doc.getList documentation for possible arguments.

walk_folders(**kwargs: api_arg) → Iterable[dict][source]

Iterates over a user’s folders.

See the folder.getList documentation for possible arguments.

walk_folder_albums(folder_id: int, **kwargs: api_arg) → Iterable[dict][source]

Iterates over the albums of a folder.

See the folder.albums.getList documentation for optional arguments.

Parameters: