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
ornumViews
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
orgreen
,violet
orblue
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
ornumViews
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
orgreen
,violet
orblue
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
ornumViews
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
ornumViews
.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
. AColourLoversError
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
andhsv
respectively and are of typeRGB
andHSV
.-
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.
-
classmethod
-
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]
-
classmethod