colourlovers 0.2.0

Import the wrapper

1. Download the wrapper via pip: pip install colourlovers. Alternatively, clone the repository by typing in a terminal: git clone https://github.com/juangallostra/Colourlovers-API-wrapper.git

2. Start a Python terminal session in the directory where you cloned the repository

3. Import the wrapper by:

   >>> from colourlovers import clapi
   >>> cl = clapi.ColourLovers()

Queries

Once we have created the API wrapper object (cl in the present case) we are ready to query the API. Note that a query, even if it is for a single object, always returns a list. The ColourLovers API queries are structured in three levels:

1. Object of the query. The possible query objects are: Color/s, Pattern/s, Palette/s, Lover/s or stats. Note that most of the objects can be queried in plural or in singular. The wrapper offers a different method for each object, all of them being:

   >>> cl.search_palette()  # Query for a single palette
   >>> cl.search_pattern()  # Query for a single pattern
   >>> cl.search_color()  # Query for a single color
   >>> cl.search_lover()  # Query for a single user
   >>> cl.search_palettes()  # Query for multiple palettes
   >>> cl.search_patterns()  # Query for multiple patterns
   >>> cl.search_colors()  # Query for multiple colors
   >>> cl.search_lovers()  # Query for multiple users
   >>> cl.search_stats()  # Query for a single pattern

   Each of these methods only accepts keyword arguments. Optionally, a first boolean positional argument can be passed specifying whether the response of the query should be returned as raw data or as a Python object. By default the response of a query will be returned as a Python object. Hence, the general form of a query to the API is:

   >>> cl.search_patterns(True, kwargs)  # Response will be returned as raw data
   >>> cl.search_patterns(kwargs)  # Response will be returned as a Python object

   We will get back to this later.

2. Type of the query. These are general, normally non-object dependent types. However, not all the types are supported by all the objects. The possible query types and the keyword used to specify them for each type of object are:

   Object	Keyword	Value
   Palettes	request	new, top, random
   Patterns	request	new, top, random
   Colors	request	new, top, random
   Lovers	request	new, top
   Palette	id	valid id as int or str
   Pattern	id	valid id as int or str
   Color	hexvalue	valid hex color value as str
   Lover	username	valid username str
   Stats	request	colors, palettes, patterns, lovers

   The random query type is exclusive. When using it, no other parameters can be specified. Some examples of valid queries are:

   >>> cl.search_patterns(request='new')
   >>> cl.search_colors(request='top')
   >>> cl.search_stats(request='patterns')
   >>> cl.search_palettes(request='random')
   >>> cl.search_pattern(id=1145)
   >>> cl.search_lover(username='whatever')
   >>> cl.search_color(hexvalue='C6C5AC')

3. Object specific query parameters. These depend on the object of the query and are also specified as keyword arguments. To see which are the parameters supported by each object follow the links to the official API page in the following table. Note the differences in the available parameters when querying for multiple objects or for a single object.

   Object	Supported Types
   Palette/s	Parameters
   Pattern/s	Parameters
   Color/s	Parameters
   Lover/s	Parameters
   Stats	Parameters

   Examples of valid queries are:

   >>> cl.search_palettes(request='top', keywords='river', numResults=15)
   >>> cl.search_lovers(request='new', orderCol='numVotes')

   Note that the parameters are case-sensitive and that some of them expect predefined values. This edge cases are all listed at the official API documentation.

Response data

The data from a query can be returned in three different formats: XML, JSON or as a Python object.

To get the data in XML format a first positional argument (raw_data) has to be set to True. This is so because the default raw data response format is XML.

>>> resp = cl.search_palette(True, id=2323)
>>> resp
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<palettes numResults="1" totalResults="4567661">\n\t<palette>\n\t\t<id>2323</id>\n\t\t<title><![CDATA[On the lake]]></title>\n\t\t<userName><![CDATA[viatora]]></userName>\n\t\t<numViews>529</numViews>\n\t\t<numVotes>12</numVotes>\n\t\t<numComments>3</numComments>\n\t\t<numHearts>0</numHearts>\n\t\t<rank>0</rank>\n\t\t<dateCreated>2005-08-24 10:44:11</dateCreated>\n\t\t<colors>\n\t\t\t<hex>E6F0F7</hex>\n\t\t\t<hex>97A4B2</hex>\n\t\t\t<hex>5F0609</hex>\n\t\t\t<hex>766F59</hex>\n\t\t\t<hex>989383</hex>\n\t\t</colors>\n\t\t<description><![CDATA[I-MOO\r\n<div style="width: 300px; text-align: center;"><a href="http://www.colourlovers.com/contests/moo/minicard/2291466" target="_blank" style="display: block; margin-bottom: 5px; width: 300px; height: 120px; -moz-box-shadow: 0 1px 4px #d1d1d1; -webkit-box-shadow: 0 1px 4px #d1d1d1; box-shadow: 0 1px 4px #d1d1d1; filter: progid:DXImageTransform.Microsoft.Shadow(Strength=1, Direction=180, Color=]]></description>\n\t\t<url><![CDATA[http://www.colourlovers.com/palette/2323/On_the_lake]]></url>\n\t\t<imageUrl><![CDATA[http://www.colourlovers.com/paletteImg/E6F0F7/97A4B2/5F0609/766F59/989383/On_the_lake.png]]></imageUrl>\n\t\t<badgeUrl><![CDATA[http://www.colourlovers.com/images/badges/p/2/2323_On_the_lake.png]]></badgeUrl>\n\t\t<apiUrl>http://www.colourlovers.com/api/palette/2323</apiUrl>\n\t</palette>\n</palettes>'

To get the data in JSON format, a part from specifying that the response should be returned as raw data by setting the first positional argument to True, it is necessary to include another keyword parameter in the query specifying that the format of the response should be JSON (format='json').

>>> resp = cl.search_palette(True, id=2323, format='json')
>>> resp
'[
  {
   "id":2323,
   "title":"On the lake",
   "userName":"viatora",
   "numViews":529,
   "numVotes":12,
   "numComments":3,
   "numHearts":0,
   "rank":0,
   "dateCreated":"2005-08-24 10:44:11",
   "colors":["E6F0F7","97A4B2","5F0609","766F59","989383"],
   "description":"I-MOO\\r\\n<div style=\\"width: 300px; text-align: center;\\"><a href=\\"http:\\/\\/www.colourlovers.com\\/contests\\/moo\\/minicard\\/2291466\\" target=\\"_blank\\" style=\\"display: block; margin-bottom: 5px; width: 300px; height: 120px; -moz-box-shadow: 0 1px 4px #d1d1d1; -webkit-box-shadow: 0 1px 4px #d1d1d1; box-shadow: 0 1px 4px #d1d1d1; filter: progid:DXImageTransform.Microsoft.Shadow(Strength=1, Direction=180, Color=",
   "url":"http:\\/\\/www.colourlovers.com\\/palette\\/2323\\/On_the_lake",
   "imageUrl":"http:\\/\\/www.colourlovers.com\\/paletteImg\\/E6F0F7\\/97A4B2\\/5F0609\\/766F59\\/989383\\/On_the_lake.png",
   "badgeUrl":"http:\\/\\/www.colourlovers.com\\/images\\/badges\\/p\\/2\\/2323_On_the_lake.png",
   "apiUrl":"http:\\/\\/www.colourlovers.com\\/api\\/palette\\/2323"
  }
 ]'

Finally, if the parameter raw data is not set or set to False then the data will be obtained as a Python object (which is the recommended way). If the response of a query contains more than one object - for example, when querying for palettes - then each object in the response will be mapped to a Python object. Finally, when the response data is obtained as Python objects it will always come inside of a list for consistency reasons among methods, even if the response contains a single object.

>>> resp = cl.search_palette(id=2323)
>>> resp
[<colourlovers.data_containers.Palette object at 0x7fc64a87f0f0>]
>>> resp =  cl.search_palettes(request='top', keywords='river')
>>> resp
[<colourlovers.data_containers.Palette object at 0x7fc64a569ef0>,
 <colourlovers.data_containers.Palette object at 0x7fc64a569f28>,
 <colourlovers.data_containers.Palette object at 0x7fc64a569f60>,
 <colourlovers.data_containers.Palette object at 0x7fc64a569f98>,
 <colourlovers.data_containers.Palette object at 0x7fc64a569fd0>,
 <colourlovers.data_containers.Palette object at 0x7fc64a562048>,
 <colourlovers.data_containers.Palette object at 0x7fc64a562080>,
 <colourlovers.data_containers.Palette object at 0x7fc64a5620b8>,
 <colourlovers.data_containers.Palette object at 0x7fc64a5620f0>,
 <colourlovers.data_containers.Palette object at 0x7fc64a562128>,
 <colourlovers.data_containers.Palette object at 0x7fc64a562160>,
 <colourlovers.data_containers.Palette object at 0x7fc64a562198>,
 <colourlovers.data_containers.Palette object at 0x7fc64a5621d0>,
 <colourlovers.data_containers.Palette object at 0x7fc64a562208>,
 <colourlovers.data_containers.Palette object at 0x7fc64a562240>,
 <colourlovers.data_containers.Palette object at 0x7fc64a562278>,
 <colourlovers.data_containers.Palette object at 0x7fc64a5622b0>,
 <colourlovers.data_containers.Palette object at 0x7fc64a5622e8>,
 <colourlovers.data_containers.Palette object at 0x7fc64a562320>,
 <colourlovers.data_containers.Palette object at 0x7fc64a562358>]

Each of this objects (Lover, Palette, Pattern, Color, Stats) provides an attribute - named following PEP8 style guidelines - for each of the fields present in the response. Refer to the official API documentation to see which fields (Example Result sections) are present for each object. As an example:

>>> p = cl.search_pattern(id=2323)
>>> p
[<colourlovers.data_containers.Pattern object at 0x7fcf64ae4a20>]
>>> vars(p[0])
{
    'id': 2323,
    'title': 'inspiration',
    'username': 'daisyjean911',
    'num_views': 328,
    'num_votes': 0,
    'num_comments': 0,
    'num_hearts': 0,
    'rank': 0,
    'date_created': '2007-12-10 12:19:14',
    'description': '<a href="http://www.colourlovers.com/palette/2285499/Nestled" target="_blank"><img src="http://www.colourlovers.com/images/badges/pw/2285/2285499_Nestled.png" style="width: 240px; height: 120px; border: 0 none;" alt="Nestled" /></a>\r\n<div style="width: 300px; text-align: center;"><a href="http://www.colourlovers.com/contests/moo/minicard/2285499" target="_blank" style="display: block; margin-bottom: 5px; width: 300px; height: 120px; -moz-box-shadow: 0 1px 4px #d1d1d1; -webkit-box-shadow: 0 1px 4px #d1d1d1; box-shadow: 0 1px 4px #d1d1d1; filter: progid:DXImageTransform.Microsoft.Shadow(Strength=1, Direction=180, Color=',
    'url': 'http://www.colourlovers.com/pattern/2323/inspiration',
    'image_url': 'http://colourlovers.com.s3.amazonaws.com/images/patterns/2/2323.png',
    'badge_url': 'http://www.colourlovers.com/images/badges/n/2/2323_inspiration.png',
    'api_url': 'http://www.colourlovers.com/api/pattern/2323',
    'colors': ['97BEC9', 'AB2B91', '76A379', 'ABD66B'],
    'rgb_colors': [(151, 190, 201), (171, 43, 145), (118, 163, 121), (171, 214, 107)],
    'num_colors': 4
}
>>> pattern = p[0]
>>> pattern.username
'daisyjean911'
>>> pattern.colors
['97BEC9', 'AB2B91', '76A379', 'ABD66B']
>>> pattern.num_views
328
>>> pattern.id
2323