Welcome to python-colourlovers’s documentation!

This module provides access to the ColourLovers API, a web service that allows users to publish colour themes and rate them. The API of this webservice allows to search for users (Lovers) and their posted contents (Colours, Patterns, Palettes).

Accessing the API requires an instance of ColourLovers which provides the methods to access the different content types: Colour, Palette, Pattern, Lover. Sending a request to ColourLovers is as easy as calling the corresponding method such as ColourLovers.palettes() to search for palettes. Additionally, the following arguments can be specified new, top, random with additional parameters. Please refer to the ColourLovers API documentation to find out more about the specific parameters and their restrictions at http://www.colourlovers.com/api.

You find the ColourLovers website at: http://www.colourlovers.com

Usage example:

>>> from colourlovers import ColourLovers
>>> cl = ColourLovers()
>>> cl.color('#37cbff')
[<Colour id='4767129' title='i feel pretty' rgb=(55, 203, 255)>]
>>> cl.palettes('new', keywords='funky', numResults=3)
[<Palette id='1940972' title='"Funky President"'>,
 <Palette id='1936394' title='Barbie Doll Blonde'>,
 <Palette id='1936247' title='Lily's Rainbow'>]

Another example:

>>> cl.patterns('random')
[<Pattern id='391644' title='acanalado'>]
>>> cl.colors('top', numResults=3)
[<Colour id='14' title='Black' rgb=(0, 0, 0)>,
 <Colour id='16' title='white' rgb=(255, 255, 255)>,
 <Colour id='1086335' title='dutch teal' rgb=(22, 147, 165)>]

ColourLovers

class colourlovers.ColourLovers
color(argument, **kwargs)
colors(argument=None, **kwargs)
lover Restrict results to specific COLOURlover by providing their user name.
hue_range Hue range of the colour: 12,68. Values must be in range [0,359] and the left value must be less than the right value.
bri_range Brightness range of the colours: 2,88. Values must be in range [0, 99] and the left value must be less than the right value.
keywords String of keywords to search for in patterns.
keyword_exact Perform an exact search for the keywords passed if set to 1. Default: 0.
order_col dateCreated, score, name`, ``numVotes or numViews
sort_by Sorting in asceding (ASC) or descending (DESC) order. Defaults to (ASC)
num_results Number of results to be returned. Maximum: 100. Default: 20.
result_offset Result offset, for paging. Default: 0.
palette(argument, **kwargs)
palettes(argument=None, **kwargs)
lover Restrict results to specific COLOURlover by providing their user name.
hue_option yellow, orange, red or green, violet or blue
hex Restrict results to patterns with a specific colour given as any valid 6-char hex value without preceeding #.
keywords String of keywords to search for in patterns.
keyword_exact Perform an exact search for the keywords passed if set to 1. Default: 0.
order_col dateCreated, score, name`, ``numVotes or numViews
sort_by Sorting in asceding (ASC) or descending (DESC) order. Defaults to (ASC)
num_results Number of results to be returned. Maximum: 100. Default: 20.
result_offset Result offset, for paging. Default: 0.
show_palette_widths Shows palette’s colour’s widths if set to 1. Default: 0
pattern(argument, **kwargs)
patterns(argument=None, **kwargs)
lover Restrict results to specific COLOURlover by providing their user name.
hue_option yellow, orange, red or green, violet or blue
hex Restrict results to patterns with a specific colour given as any valid 6-char hex value without preceeding #.
keywords String of keywords to search for in patterns.
keyword_exact Perform an exact search for the keywords passed if set to 1. Default: 0.
order_col dateCreated, score, name`, ``numVotes or numViews
sort_by Sorting in asceding (ASC) or descending (DESC) order. Defaults to (ASC)
num_results Number of results to be returned. Maximum: 100. Default: 20.
result_offset Result offset, for paging. Default: 0.
lover(argument, **kwargs)
comments 0 or 1: if 1, will show last 10 comments for given Lover
lovers(argument=None, **kwargs)
order_col Order in which the colours will be shown. Possible values are: dateCreated, score, name`, ``numVotes or numViews.
sort_by Sorting in asceding (ASC) or descending (DESC) order. Defaults to (ASC)
num_results Number of results to be returned. Maximum: 100. Default: 20.
result_offset Result offset, for paging. Default: 0.
stats(stats_type)

Return the stats for stat_type. stat_type refers to one of the content types on ColourLovers and can be colors, lovers, patterns, palettes. A ColourLoversError is raised when an invalid type is requested.

Args:
stat_type (str): content type to request stats for.
Returns:
The requested stats as Stat object.

Request the statistical value (total number) for stats_type. stats_type is a string that can be either of the following: colors, patterns, palettes, lovers.

Args:
stats_type (str): Content type to retrieve statistics for.
Returns:
Total number of the requested content type on ColourLovers.com.

Colour

class colourlovers.Colour(**kwargs)

This class defines a ColourLovers colour in the RGB and HSV colour spaces. The colour values can be accessed through the rgb and hsv respectively and are of type RGB and HSV.

id

Unique id for this Color as int.

title

Title / Name of the Color.

user_name

Username of the Color’s creator.

num_views

Number of views this Color has received as int.

num_votes

Number of votes this Color has received as int.

num_comments

Number of comments this Color has received as int.

num_hearts

Number of hearts this Color has in the range of [0,5] as float.

rank

This Color’s rank on COLOURlovers.com as int.

date_created

Date this Color was created as a datetime object.

description

This Color’s description.

url

This Color’s COLOURlovers.com URL.

image_url

Link to a PNG version of this Color.

badge_url

Link to a COLOURlovers.com badge for this Color.

api_url

This Color’s COLOURlovers.com API URL.

classmethod from_xml(xml)

Create a new colour instance from xml. xml is a DOM element with the root element name color.

Args:
xml (Element): color DOM element.
Returns:
New instance of Colour.
classmethod tag()

Returns the name of the XML tag for a colour object.

Palette

class colourlovers.Palette(**kwargs)
id

Unique id for this Palette as int.

title

Title / Name of the Palette.

user_name

Username of the Palette’s creator.

num_views

Number of views this Palette has received as int.

num_votes

Number of votes this Palette has received as int.

num_comments

Number of comments this Palette has received as int.

num_hearts

Number of hearts this Palette has in the range [0,5] as float.

rank

This Palette’s rank on COLOURlovers.com as int.

date_created

Date this Palette was created as datetime object.

colors

List of Colors within this Palette as hex values

color_widths

This Palette’s Color’s widths in the range [0.0, 1.0] as float.

Note: this attribute is optional and might not be present if not returned by the API response.

description

This Palette’s description

url

This Palette’s COLOURlovers.com URL.

image_url

Link to a png version of this Palette.

badge_url

Link to a COLOURlovers.com badge for this Palette.

api_url

This Palette’s COLOURlovers.com API URL.

classmethod from_xml(xml)

Parse xml and generate class attributes for each immediate child of the root element without children of their own.

Args:
xml (``Element``): xml element of content type.
Returns:
Instance of calling class.
classmethod tag()

Abstract method to be overwritten in subclasses. Should return the tag used in the XML response to identify the corresponding content type.

Pattern

class colourlovers.Pattern(**kwargs)
id

Unique id for this Pattern as int.

title

Title / Name of the Pattern.

user_name

Username of the Pattern’s creator.

num_views

Number of views this Pattern has received as int.

num_votes

Number of votes this Pattern has received as int.

num_comments

Number of comments this Pattern has received as int.

num_hearts

Number of Hearts this Pattern has in the range [0,5] as float.

rank

This Pattern’s rank on COLOURlovers.com as int.

date_created

Date this Pattern was created as datetime object.

colors

List of colors within this Pattern as hex code.

description

This Pattern’s description.

url

This Pattern’s COLOURlovers.com URL

image_url

Link to a PNG version of this Pattern.

badge_url

Link to a COLOURlovers.com badge for this Pattern.

api_url

This Pattern’s COLOURlovers.com API URL.

classmethod from_xml(xml)

Parse xml and generate class attributes for each immediate child of the root element without children of their own.

Args:
xml (``Element``): xml element of content type.
Returns:
Instance of calling class.
classmethod tag()

Abstract method to be overwritten in subclasses. Should return the tag used in the XML response to identify the corresponding content type.

Lover

class colourlovers.Lover(**kwargs)
id

Unique id for this Lover as int.

user_name

This Lover’s Username.

date_registered

Date this Lover registered with COLOURlovers.com as datetime object.

date_last_active

Date this Lover was last active on COLOURlovers.com as datetime object.

rating

This Lover’s rating

location

This Lover’s location.

num_colors

Number of Colors this Lover has made as int.

num_palettes

Number of Palettes this Lover has made as int.

num_patterns

Number of Patterns this Lover has made as int.

num_comments_made

Number of comments this Lover has made as int.

num_lovers

Number of Lovers [friends] this Lover has as int.

num_comments_on_profile

Number of comments this Lover has on their profile as int.

comments

Last 10 comments made on this Lover’s profile as list of Comment instances.

Note: this attribute is optional. It is only returned when sending the parameter comments=1 in the request.

url

This Lover’s COLOURlovers.com URL.

api_url

This Lover’s COLOURlovers.com API URL.

classmethod from_xml(xml)

Parse xml and generate class attributes for each immediate child of the root element without children of their own.

Args:
xml (``Element``): xml element of content type.
Returns:
Instance of calling class.
classmethod tag()

Abstract method to be overwritten in subclasses. Should return the tag used in the XML response to identify the corresponding content type.

Stat

class colourlovers.Stat(total, **kwargs)
total

Total number of colors, palettes, patterns or lovers in the COLOURlovers system.

classmethod from_xml(xml)

Parse xml and generate class attributes for each immediate child of the root element without children of their own.

Args:
xml (``Element``): xml element of content type.
Returns:
Instance of calling class.

The RGB and HSV colour classes

class colourlovers.RGB(red, green, blue)

Define a RGB colour as a triple of integers in the range from 0 to 255. The colour channels are stored in attributes red, green, blue.

classmethod from_xml(xml)

Create an instance of RGB from xml.

Args:
xml (Element): rgb element from API response.
Returns:
Instance of RGB.
red

Red colour channel in range [0, 255]

green

Green colour channel in range [0, 255]

blue

Blue colour channel in range [0, 255]

hex

Return hex colour code corresponding to the RGB value.

class colourlovers.HSV(hue, saturation, value)

Define a HSV colour instance from hue, saturation and value. The three values have to be integer values with hue in range [0, 360] and saturation, value in range [0, 255].

classmethod from_xml(xml)

Create an instance of HSV from xml.

Args:
xml (Element): hsv element from API response.
Returns:
Instance of HSV.
hue

HSV hue channel in range [0, 360]

saturation

HSV saturation channel in range [0, 255]

value

HSV value channel in range [0, 255]

Indices and tables