Package: colourlovers
Colourlovers-API-wrapperPython wrapper for theAPIprovided by www.colourlovers.comRequirementsPython 3 (Checkelbaschid’s
wrapperif
using Python 2)PillowHow to use itImport the wrapperDownload the wrapper viapip:pip install colourlovers.
Alternatively, clone the repository by typing in a terminal:git clonehttps://github.com/juangallostra/Colourlovers-API-wrapper.gitStart a Python terminal session in the directory where you cloned the
repositoryImport the wrapper by:>>>fromcolourloversimportclapi>>>cl=clapi.ColourLovers()QueriesOnce we have created the API wrapper object (clin 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: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 patternEach 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 objectWe will get back to this later.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:ObjectKeywordValuePalettesrequestnew,top,randomPatternsrequestnew,top,randomColorsrequestnew,top,randomLoversrequestnew,topPaletteidvalid id asintorstrPatternidvalid id asintorstrColorhexvaluevalid hex color value asstrLoverusernamevalid usernamestrStatsrequestcolors,palettes,patterns,loversTherandomquery 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')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.ObjectSupported TypesPalette/sParametersPattern/sParametersColor/sParametersLover/sParametersStatsParametersExamples 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 theofficial API documentation.Response dataThe 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 toTrue. 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 toTrue, 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:01px4px#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 toFalsethen 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.Paletteobjectat0x7fc64a87f0f0>]>>>resp=cl.search_palettes(request='top',keywords='river')>>>resp[<colourlovers.data_containers.Paletteobjectat0x7fc64a569ef0>,<colourlovers.data_containers.Paletteobjectat0x7fc64a569f28>,<colourlovers.data_containers.Paletteobjectat0x7fc64a569f60>,<colourlovers.data_containers.Paletteobjectat0x7fc64a569f98>,<colourlovers.data_containers.Paletteobjectat0x7fc64a569fd0>,<colourlovers.data_containers.Paletteobjectat0x7fc64a562048>,<colourlovers.data_containers.Paletteobjectat0x7fc64a562080>,<colourlovers.data_containers.Paletteobjectat0x7fc64a5620b8>,<colourlovers.data_containers.Paletteobjectat0x7fc64a5620f0>,<colourlovers.data_containers.Paletteobjectat0x7fc64a562128>,<colourlovers.data_containers.Paletteobjectat0x7fc64a562160>,<colourlovers.data_containers.Paletteobjectat0x7fc64a562198>,<colourlovers.data_containers.Paletteobjectat0x7fc64a5621d0>,<colourlovers.data_containers.Paletteobjectat0x7fc64a562208>,<colourlovers.data_containers.Paletteobjectat0x7fc64a562240>,<colourlovers.data_containers.Paletteobjectat0x7fc64a562278>,<colourlovers.data_containers.Paletteobjectat0x7fc64a5622b0>,<colourlovers.data_containers.Paletteobjectat0x7fc64a5622e8>,<colourlovers.data_containers.Paletteobjectat0x7fc64a562320>,<colourlovers.data_containers.Paletteobjectat0x7fc64a562358>]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 theofficial API documentationto see which fields (Example Result sections) are present for each object. As an example:>>>p=cl.search_pattern(id=2323)>>>p[<colourlovers.data_containers.Patternobjectat0x7fcf64ae4a20>]>>>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_views328>>>pattern.id2323Other possible sources for color paletteshttps://www.colr.org/api.html- (https://www.colr.org/)https://www.pictaculous.com/api/- (https://www.pictaculous.com/)It is also worth mentioninghttps://github.com/elbaschid/python-colourloversColourLovers API wrapper CHANGELOG0.2.0AddedDeletedChangedFixed#27 Random search for palettes doesn’t workAlpha version (unreleased)Added#13 Issue and Pull Request templates#22 Documentation: Wrapper usage in README#22 Support search by id when searching for one palette or pattern#22 Support search by username one searching for one user (Lover)#22 Support search by hexvalue when searching for one color#24 Improve usage explanation in the READMEDeletedChanged#15 Reduce amount of duplicated code amongst data-holder classes#19 Change names of files and foldersFixed#14 When making a query the type of raw-data is checked. In case it is not a boolean value an exception is raised#23 Fix data loss when creating Python container objects