Module Documentation

class DesktopprApi.DesktopprAPI

This class allows you to create an object that allows you to query the Desktoppr site using their public API.

authorize_API(apikey)

Authorizes using a users api key. This does not require the user’s password or username.

Parameters:apikey (str) – The api key for your user account. Successfully authorizing will store this key in the field self.apikey.
Returns:
  • True – if the authorization worked with the given apikey.
  • False – if the authorization did not work with the given apikey.
authorize_user_pass(username, password)

Gets a users api key by authorizing to the site with a username/ password. Stores the users API key in the field self.apikey for further privileged access in this object’s session.

Parameters:
  • username (str) – Username to login with.
  • password (str) – User’s password. You should take steps to secure the entry of this argument.
Returns:

  • True – if the authorization worked with the given username/password. The API key of the user is now cached.
  • False – if the authorization did not work with the given username/password.
check_if_liked(username, wallpaper_id)

Checks if a user has liked a wallpaper.

Parameters:
  • username (str) – Username to check for liking a wallpaper
  • wallpaper_id (int) – Wallpaper to check if the user likes it
Returns:

  • None – if an error occurs (user doesn’t exist, etc).
  • True – if the user has liked the wallpaper.
  • False – if the user hasn’t liked the wallpaper.
check_if_synced(username, wallpaper_id)

Checks if a user has a wallpaper currently synced to their personal DropBox.

Parameters:
  • username (str) – Username to check for wallpaper sync status on
  • wallpaper_id (int) – Wallpaper to check if it is synced
Returns:

  • True – if the wallpaper exists in the user’s DropBox since their last relink to DropBox. If a DropBox account is unlinked and relinked, all previous synced wallpapers are ignored, even if they still reside in their DropBox folder.
  • False – If the wallpaper is not synced, or if an error occurs.
flag_wallpaper(wallpaper_id, flag)

Flags a wallpaper for filtering on the site.

Warning

This is a privileged method. You must authorize with authorize_user_pass() or authorize_API() before you can use it.

Parameters:
  • wallpaper_id (int) – id of the wallpaper.
  • flag (str) – Flag to place on a wallpaper. Valid options are flag_safe, flag_not_safe, and flag_deletion
Returns:

  • None – if the you haven’t authorized against the server yet or if the flag is invalid.
  • True – if the Wallpaper was successfully flagged.
  • False – if the Wallpaper was not successfully flagged.
follow_user(username)

Attempts to follow a user.

Warning

This is a privileged method. You must authorize with authorize_user_pass() or authorize_API() before you can use it.

Parameters:username (str) – Username to follow
Returns:
  • None – if the you haven’t authorized against the server yet.
  • True – if the follow attempt succeeded.
  • False – if the follow attempt failed.
get_followed_users(username, page=1)

Gets a page containg a list of User objects who the specified user follows.

Parameters:username (str) – Username to query.
Returns:
  • None – if the user follows noone, the user cannot be found, or an error occurs.
  • Page object – if the command succeeds. The page object’s username attribute is populated with the list of users.
get_random_wallpaper(safefilter='safe')

Retrieves a random wallpaper.

The safefilter can return different levels of images:

safe = Safe for work
include_pending = Images not yet marked as safe or not safe for work (NSFW)
all = All images, including NSFW images
Parameters:safefilter (str) – Optional, Safety filter for returned images. Valid strings are safe, include_pending, and all. Defaults to safe.
Returns:
  • None – if a bad safefilter is passed (if any) or there was an error getting a wallpaper.
  • Wallpaper object – if successful.
get_user_collection(username, page=1)

Gets a page of wallpapers defining ones in a users collection.

Parameters:
  • username (str) – User to query for information
  • page (int) – Optional, the page number to return. The number of results per page is limited by the server. The default is page 1.
Returns:

  • None – if an error occurs (no wallpapers, invalid user...)
  • Page object – if the command succeeds. The page object’s wallpapers attribute is populated with the list of wallpapers the user has in their collection.
get_user_followers(username, page=1)

Gets a Page contains a list of of User objects representing users who follow this user. The pages can be iterated over to find all followers.

Parameters:
  • username (str) – Username to query.
  • page (int) – Page of results to return
Returns:

  • None – if the user has no followers, cannot be found, or an error occurs.
  • Page object – if the command succeeds. The page object’s users attribute is populated with the list of users.
get_user_info(username)

Get information about a user.

Parameters:username (str) – User to query for information
Returns:
  • None if the request did not return user information.
  • User object – if the command succeeds. The user object’s attributes can be parsed for desired information.
get_user_randomwallpaper(username)

Fetches a random wallpaper a user has in their collection.

Parameters:username (str) – Username to get random wallpaper from
Returns:
  • None – if a failure occurred trying to get a wallpaper
  • Wallpaper object – If successful.
get_userlikes(username, page=1)

Gets a list of wallpapers that a user likes.

Parameters:
  • username (str) – Username to get list of liked wallpapers for
  • page (int) – Optional, return different list of pages. Defaults to page 1.
Returns:

  • None – if an error occurs (not a user, etc).
  • Page object – if successful. Wallpapers the user likes can be accessed via the .wallpapers attribute.
get_wallpaper_urls(page=1, safefilter='safe')

This is a subset of get_wallpapers(), which returns a page of wallpaper URLs. The API does not document sorting options. It uses the same interface as get_wallpapers.

Parameters:
  • page (int) – Optional, page number to return. The server limits how many results are returned by query, so pages allow you to sift through results.
  • safefilter (str) – Optional, safety filter for returned images. Valid strings are safe, include_pending, and all. Defaults to safe.
Returns:

  • Page object – if the command succeeds. The page object’s wallpapers attribute is populated with the list of wallpapers.
  • None – If an error occurs trying to get wallpapers.
get_wallpapers(page=1, safefilter='safe')

Retrieves a list of wallpapers. The page parameter can query different pages of results.

The safefilter can return different levels of images:

safe = Safe for work
include_pending = Images not yet marked as safe or not safe for work (NSFW)
all = All images, including NSFW images
Parameters:
  • page (int) – Optional, page of results to retrieve. Defaults to page 1.
  • safefilter (str) – Optional, Safety filter for returned images. Valid strings are safe, include_pending, and all. Defaults to safe.
Returns:

  • None if a bad safefilter is passed (if any) or there was an error getting wallpapers.
  • Page object – if the command succeeds. The page object’s wallpapers attribute is populated with the list of wallpapers the returned by the server.
like_wallpaper(wallpaper_id)

Warning

This is a privileged method. You must authorize with authorize_user_pass() or authorize_API() before you can use it.

Likes a wallpaper.

Parameters:wallpaper_id (int) – Wallpaper to like
Returns:
  • None – if the you haven’t authorized against the server yet.
  • True – if the like succeeded.
  • False – if the like attempt failed.
sync_wallpaper(wallpaper_id)

Informs the server that it should start a sync of a wallpaper to a user’s DropBox. This checks against the server for wallpapers.

Warning

This is a privileged method. You must authorize with authorize_user_pass() or authorize_API() before you can use it.

Parameters:wallpaper_id (int) – The wallpaper id to sync to the authorized user’s DropBox
Returns:
  • None – if the you haven’t authorized against the server yet.
  • True – if a wallpaper was set to sync (or was already synced).
  • False – if the HTTP response is not 200 or 422 (already synced)
unfollow_user(username)

Attempts to unfollow a user.

Parameters:username (str) – User to unfollow
Returns:
  • None – if the you haven’t authorized against the server yet.
  • True – if the unfollow attempt succeeded.
  • False – if the unfollow attempt failed.
unlike_wallpaper(wallpaper_id)

Unlikes a wallpaper.

Warning

This is a privileged method. You must authorize with authorize_user_pass() or authorize_API() before you can use it.

Parameters:wallpaper_id (int) – Wallpaper to unlike
Returns:
  • None – if the you haven’t authorized against the server yet.
  • True – if the unlike succeeded.
  • ** False** – if the unlike attempt failed.
unsync_wallpaper(wallpaper_id)

Informs the server that it should remove a wallpaper from a user’s DropBox. This checks against the user’s DropBox for wallpapers, so if it doesn’t exist there, it will still return True.

Warning

This is a privileged method. You must authorize with authorize_user_pass() or authorize_API() before you can use it.

Parameters:wallpaper_id (int) – The wallpaper id to unsync from the authorized user’s DropBox
Returns:
  • None – if the you haven’t authorized against the server yet.
  • True – if a wallpaper was set to unsync (or did not exist).
  • False – if the HTTP response is not 200 or 404 (Not in user’s DropBox)
class DesktopprApi.Image(info=None)

Represents an image object (a part of a wallpaper object). All values are initialized to none, but are set if an image dict is passed.

An image object can contain another image object. There are only two different setups of an image object:

  • Contains thumb, preview, and url = Full Resolution Image
  • Contains width, height, and url = Thumbnail or Preview Image
class DesktopprApi.Page(infotype, info)

A page object represents a ‘page’ of information returned by the API when it involves paginated information. It contains either a list of Wallpaper objects or a list of User objects.

class DesktopprApi.User(info=None)

Defines a user on the site.

class DesktopprApi.Wallpaper(info=None)

Defines a Wallpaper on the Desktoppr server. Contains many attributes about the image.