色彩爱好者 0.2.0

导入包装器

1. 通过pip下载包装器： pip install colourlovers。或者，在终端中克隆存储库： git clone https://github.com/juangallostra/Colourlovers-API-wrapper.git

2. 在克隆存储库的目录中启动Python终端会话

3. 通过以下方式导入包装器

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

查询

一旦我们创建了API包装器对象（当前情况下为cl），我们就可以查询API。请注意，即使查询的对象只有一个，查询结果总是返回一个列表。ColorLovers API查询分为三个级别

1. 查询的对象。可能的查询对象有：Color/s、Pattern/s、Palette/s、Lover/s或stats。请注意，大多数对象都可以以复数或单数形式查询。包装器为每个对象提供了不同的方法，所有方法都是

   >>> 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

   这些方法都只接受关键字参数。可选地，可以传递一个布尔值位置参数，以指定查询的响应应以原始数据还是以Python对象的形式返回。默认情况下，查询的响应将以Python对象的形式返回。因此，调用API的查询的一般形式是

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

   我们稍后会回到这个问题。

2. 查询类型。这些是通用的，通常与非对象依赖的类型。然而，并非所有类型都受所有对象支持。可能的查询类型以及指定它们的每个类型的关键字如下

   对象	关键字	值
   调色板	请求	new、top、random
   图案	请求	new、top、random
   颜色	请求	new、top、random
   恋人	请求	new、top
   调色板	id	有效的id，可以是整数或字符串
   图案	id	有效的id，可以是整数或字符串
   颜色	十六进制值	有效的十六进制颜色值，作为字符串
   恋人	用户名	有效的用户名，作为字符串
   统计信息	请求	colors、palettes、patterns、lovers

   随机查询类型是唯一的。在它被使用时，不能指定其他参数。一些有效的查询示例是

   >>> 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. 对象特定查询参数。这些取决于查询的对象，也被指定为关键字参数。要查看每个对象支持的参数，请遵循以下表格中指向官方API页面的链接。注意，当查询多个对象或单个对象时，可用参数之间的差异。

   对象	支持的类型
   调色板	参数
   图案	参数
   颜色	参数
   恋人	参数
   统计信息	参数

   有效的查询示例

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

   请注意，参数是区分大小写的，并且其中一些期望预定义的值。这些边缘情况都在官方API文档中列出。

响应数据

查询的数据可以以三种不同的格式返回：XML、JSON或作为Python对象。

要获取XML格式的数据，必须将第一个位置参数（raw_data）设置为True。这是因为默认的原始数据响应格式是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>'

要获取JSON格式的数据，除了指定响应应以原始数据返回并设置第一个位置参数为True之外，还需要在查询中包含另一个关键字参数，指定响应格式应为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"
  }
 ]'

最后，如果没有设置参数raw_data或将其设置为False，则数据将作为Python对象获得（这是推荐的方式）。如果查询的响应包含多个对象 - 例如，查询调色板时 - 则响应中的每个对象都将映射到Python对象。最后，当响应数据作为Python对象获得时，出于方法之间的一致性原因，它将始终在列表中，即使响应只包含单个对象。

>>> 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>]

这些对象（恋人、调色板、图案、颜色、统计信息）都为响应中存在的每个字段提供了一个属性 - 按照PEP8样式指南命名 -。有关每个对象中存在的字段（示例结果部分）的信息，请参阅官方API文档。例如

>>> 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