API

class TheNounProjectAPI.api.API(key=None, secret=None, testing=False, timeout=5.0)

Bases: TheNounProjectAPI.collections.Collections, TheNounProjectAPI.icons.Icons, TheNounProjectAPI.usage.Usage, TheNounProjectAPI.enterprise.Enterprise

API is a class allowing convenient access to the TheNounProject API.

Construct a new object for making API requests.

Parameters

  • key (str) – The API key from the TheNounProject API. (defaults to None)

  • secret (str) – The secret key from the TheNounProject API. (defaults to None)

  • testing (bool) – Whether the methods should return a PreparedRequest, instead of data from the API. Should not be used except for testing this wrapper. (defaults to False)

  • timeout (Union[float, Tuple[float, float], None]) – Float timeout in seconds, 2-tuples for seperate connect and read timeouts, and None for no timeout. (defaults to 5.0)

get_collection(identifier)

Fetches a single Collection, either by id or by slug.

Parameters

identifier (Union[int, str]) – Collection identifier (id or slug).

Raises

  • NonPositive – Raises exception when identifier is a nonpositive integer.

  • IllegalSlug – Raises exception when identifier is a string that’s empty, non-ascii or with multiple words.

Returns

CollectionModel object identified by the identifier.

Return type

CollectionModel

get_collection_by_id(_id)

Fetches a single Collection by id.

Parameters

_id (int) – Collection ID.

Raises

NonPositive – Raises exception when id is nonpositive.

Returns

CollectionModel object identified by the _id.

Return type

CollectionModel

get_collection_by_slug(slug)

Fetches a single Collection by slug.

Parameters

slug (str) – Collection slug.

Raises

IllegalSlug – Raises exception when slug is an empty string, contains non ascii characters or contains multiple words.

Returns

CollectionModel object identified by the slug.

Return type

CollectionModel

get_collection_icons(identifier, limit=None, offset=None, page=None)

Fetches collection Icons, either by id or by slug.

Parameters

  • identifier (Union[int, str]) – Collection identifier (id or slug).

  • limit (int) – Maximum number of results. (defaults to None)

  • offset (int) – Number of results to displace or skip over. (defaults to None)

  • page (int) – Number of results of limit length to displace or skip over. (defaults to None)

Raises

  • NonPositive – Raises exception when identifier is a nonpositive integer.

  • IllegalSlug – Raises exception when identifier is a string that’s empty, non-ascii or with multiple words.

Returns

List of IconModel objects from the collection identified by the identifier.

Return type

List[IconModel]

get_collection_icons_by_id(_id, limit=None, offset=None, page=None)

Fetches collection Icons by id from the API.

Parameters

  • _id (int) – Collection id.

  • limit (int) – Maximum number of results. (defaults to None)

  • offset (int) – Number of results to displace or skip over. (defaults to None)

  • page (int) – Number of results of limit length to displace or skip over. (defaults to None)

Raises

NonPositive – Raises exception when _id is nonpositive.

Returns

List of IconModel objects from the collection identified by the _id.

Return type

List[IconModel]

get_collection_icons_by_slug(slug, limit=None, offset=None, page=None)

Fetches collection Icons by slug from the API.

Parameters

  • slug (str) – Collection slug.

  • limit (int) – Maximum number of results. (defaults to None)

  • offset (int) – Number of results to displace or skip over. (defaults to None)

  • page (int) – Number of results of limit length to displace or skip over. (defaults to None)

Raises

IllegalSlug – Raises exception when slug is an empty string, contains non ascii characters or contains multiple words.

Returns

List of IconModel objects from the collection identified by the slug.

Return type

List[IconModel]

get_collections(limit=None, offset=None, page=None)

Fetches a list of all Collections.

Parameters

  • limit (int) – Maximum number of results. (defaults to None)

  • offset (int) – Number of results to displace or skip over. (defaults to None)

  • page (int) – Number of results of limit length to displace or skip over. (defaults to None)

Returns

List of CollectionModel objects.

Return type

List[CollectionModel]

get_icon(identifier)

Fetches single Icon, either by id or by term.

Parameters

identifier (Union[int, str]) – Collection identifier (id or term).

Raises

  • NonPositive – Raises exception when identifier is a nonpositive integer.

  • IllegalTerm – Raises exception when identifier is an empty string.

Returns

IconModel object identified by the identifier.

Return type

IconModel

get_icon_by_id(_id)

Fetches a single Icon by id.

Parameters

_id (int) – Icon id.

Raises

NonPositive – Raises exception when id is nonpositive.

Returns

IconModel object identified by the _id.

Return type

IconModel

get_icon_by_term(term)

Fetches a single Icon by term.

Parameters

term (str) – Icon term.

Raises

IllegalTerm – Raises exception when term is an empty string.

Returns

IconModel object identified by the term.

Return type

IconModel

get_icons_by_term(term, public_domain_only=False, limit=None, offset=None, page=None)

Fetches a list of Icons by term.

Parameters

  • term (str) – Collection term.

  • public_domain_only (Union[bool, int]) – Limit results to public domain icons only (defaults to False)

  • limit (int) – Maximum number of results. (defaults to None)

  • offset (int) – Number of results to displace or skip over. (defaults to None)

  • page (int) – Number of results of limit length to displace or skip over. (defaults to None)

Raises

IllegalTerm – Raises exception when term is an empty string.

Returns

List of IconModel objects identified by the term.

Return type

List[IconModel]

get_recent_icons(limit=None, offset=None, page=None)

Fetches recent Icons.

Parameters

  • limit (int) – Maximum number of results. (defaults to None)

  • offset (int) – Number of results to displace or skip over. (defaults to None)

  • page (int) – Number of results of limit length to displace or skip over. (defaults to None)

Returns

List of IconModel objects.

Return type

List[IconModel]

get_usage()

Fetches current oauth Usage and limits.

Returns

UsageModel object.

Return type

UsageModel

get_user_collection(user_id, slug)

Fetches a single Collection associated with a user.

Parameters

  • user_id (int) – User id.

  • slug (str) – Collection slug.

Raises

  • NonPositive – Raises exception when user_id is not positive.

  • IllegalSlug – Raises exception when slug is an empty string, contains non ascii characters or contains multiple words.

Returns

CollectionModel object identified by the slug, from the user identified by the user_id.

Return type

CollectionModel

get_user_collections(user_id)

Fetches a list of Collections associated with a user.

Parameters

user_id (int) – User id.

Raises

NonPositive – Raises exception when user_id is not positive.

Returns

List of CollectionModel objects associated with a user identified by the user_id.

Return type

List[CollectionModel]

get_user_uploads(username, limit=None, offset=None, page=None)

Fetches a list of uploads (Icons) associated with a user.

Parameters

  • username (str) – Username.

  • public_domain_only – Limit results to public domain icons only (defaults to False)

  • limit (int) – Maximum number of results. (defaults to None)

  • offset (int) – Number of results to displace or skip over. (defaults to None)

  • page (int) – Number of results of limit length to displace or skip over. (defaults to None)

Raises

IllegalTerm – Raises exception when username is an empty string.

Returns

List of IconModel objects uploaded by user identified with the user_id.

Return type

List[IconModel]

report_usage(icons, test=False)

Accepts icon ids for reporting icon usage.

Parameters

  • icons (Union[list, set, str, int]) – Icon ids.

  • test (bool) – True to test endpoint without reporting data.

Returns

EnterpriseModel object based on the icon ids.

Return type

EnterpriseModel

set_api_key(key)

Sets API key.

Parameters

key (str) – The API key from the TheNounProject API.

Return type

None

set_secret_key(secret)

Sets API secret.

Parameters

secret (str) – The secret key from the TheNounProject API

Return type

None