added updated docstrings and tox for tests

README.md

@@ -7,7 +7,7 @@
 Have you ever wanted a simple and intuitive way to work with colors in python? Then this library is for you! `acrylic` is a python package that you can use to manage colors, convert between different color formats, and work with color schemes and palettes.
 
 Currently supported color formats are:  
-`rgb`, `hsl`, `hsv`, `ryb` and `hex` strings.
+`rgb`, `hsl`, `hsv`, `ryb`, `hex`, `name`
 
 Small example:  
 ```python
@@ -55,17 +55,17 @@ cyan = Color(rgb=[83, 237, 229])
 
 The same syntax can be used to give input in any of the supported color formats. Currently supported formats are `rgb`, `hsv`, `hsl`, `hex` and `ryb`. Example:
 ```python
-cyan = Color(rgb=[83, 237, 229])
-cyan = Color(hsl=[176.8, 81, 62.75])
-cyan = Color(hsv=[176.8, 65, 92.94])
-cyan = Color(hex='#53EDE5')
-cyan = Color(ryb=[18, 97, 172])
+color = Color(rgb=[127, 255, 212])
+color = Color(hsl=[160, 100, 75])
+color = Color(hsv=[160, 50, 100])
+color = Color(hex='#7fffd4')
+color = Color(name='aquamarine')
+color = Color(ryb=[0, 77, 128])
 ```
-- All values for `rgb` and `ryb` should be between `0` - `255` and `int`  
-- The value of hue for `hsv` and `hsl` should be between `0.0` - `360.0` and the other
-  two components should be between `0.0` - `100.0`. All 3 of them can be either `int` or
-`float`
-- Values for `hex` should be strings representing 6-digit hex number
+- All values for `rgb` and `ryb` should be between `0` - `255`  
+- The value of hue for `hsv` and `hsl` should be between `0.0` - `360.0` and the other two components should be between `0.0` - `100.0`.  
+- Values for `hex` should be a string representing 6-digit hex number  
+- Values for `name` should be a string representing a valid CSS3 color name  
 
 ### Converting between color formats
 
@@ -77,6 +77,7 @@ print(cyan.rgb)
 print(cyan.hsv)
 print(cyan.hsl)
 print(cyan.hex)
+print(cyan.name)
 print(cyan.ryb)
 ```
 
@@ -138,6 +139,13 @@ random_cyan = Color(hsv=[176, (30, RANDOM), 95])
   new_color = Color(hsv=[230, old_color.hsv.s, old_color.hsv.v])
   ```
 - All instances of colors are also hashable. They can be safely used as keys for `dict()`s and can be added to `set()` to efficiently find unique colors or to test membership.
+  ```python
+  >>> colors = {Color(hex='#7fffd4'): 'Can be used in dict() keys!'}
+  >>> Color(name='aquamarine') in colors
+  True
+  >>> colors[Color(rgb=[127, 255, 212])]
+  'Can be used in dict() keys!'
+  ```
 - As a result of colors being immutable and hashable, colors that represent the same `RGB` values will always be unambiguously equal to each other. This prevents a lot of bugs that can randomly appear when working with float `hsv`/`hsl` values and removes the inconsistencies in the conversion algorithm that converts between `rgb` and `hsv`/`hsl`. An example that demonstrates this:
   ```python
   >>> Color(hsl=[236.94, 9.29, 84.54]) == Color(hsl=[240.0, 8.86, 84.51])
@@ -204,23 +212,13 @@ For a list of all the available color schemes and their explanations, check **[t
     ```
     This example also illustrates how easy it is to integrate `acrylic` with other libraries and seamlessly switch between `rgb` and `hsl`
 
-## TODO
-- Support for Color Blindness
-- Functions that can generate a wide range of color palettes
-- `cmy`/`cmyk` color format
-- `HSLuv` color format
-- `rgba` color format
-
-## Contributions 
+## Contributions
 All contributions to `acrylic` are welcome and appreciated! Ways in which you can contribute are:
 - Report an issue ([here](https://github.com/prdx23/acrylic/issues))
 - Raise a pull request ([here](https://github.com/prdx23/acrylic/pulls))
 - Request new features
 - Spread the word about `acrylic`!
 
-## Credit
-`acrylic` was developed by [Arsh](https://prdx.me)
-
 ## License
 **MIT License**: Copyright (c) 2020 Arsh  
 [License.txt](https://github.com/prdx23/acrylic/blob/master/LICENSE.txt)

acrylic/Color.py

@@ -48,8 +48,82 @@ def setter(instance, *args, **kwargs):
 
 
 class Color(metaclass=ColorMeta):
+    '''
+    class to represent colors
+
+    Supported color formats: rgb, hsl, hsv, hex, name, ryb
+    check `help(acrylic.Color)` for creating a new Color instance
+
+    '''
 
     def __init__(self, **kwargs):
+        '''
+        Create an instance of `Color`
+
+        Supported formats:
+        rgb, hsl, hsv, ryb, hex, name
+
+        Examples:
+            >>> from acrylic import Color, RANDOM
+
+            Create a color using rgb
+            >>> Color(rgb=[83, 237, 229])
+            Color(rgb=(83, 237, 229))
+
+            Create a color using hsl with a range of saturation values
+            >>> Color(hsl=[176.5, (20, 70), 62])
+            Color(hsl=(176.5, 51.58, 62))
+
+            Note: Since saturation is picked from the range (20, 70),
+            it can differ from 51.58
+
+            Create a color with random hue
+            >>> Color(hsv=[RANDOM, 75, 98])
+            Color(hsv=(167.23, 75, 98))
+
+            Note: Since hue is random it can differ from 167.23
+
+            Create a color using hex
+            >>> Color(hex='#80ffd4')
+            Color(hex='#80ffd4')
+
+            Create a color using a valid CSS3 name
+            >>> Color(name='aquamarine')
+            Color(name='aquamarine')
+
+        Args:
+            rgb (optional):
+                Iterable with 3 values
+                0 <= {r, g, b} <= 255
+            ryb (optional):
+                Iterable with 3 values
+                0 <= {r, y, b} <= 255
+            hsv (optional):
+                Iterable with 3 values
+                0.0 <= {h} <= 360.0
+                0.0 <= {s, v} <= 100.0
+            hsl (optional):
+                Iterable with 3 values
+                0.0 <= {h} <= 360.0
+                0.0 <= {s, l} <= 100.0
+            hex (optional):
+                String representing 6-digit hex number
+            name (optional):
+                String representing a valid CSS3 color name
+
+        Note:
+            Each value of the Iterable can be:
+                - a single value
+                - a list of 2 values, a random value will be picked from
+                  between these 2 values
+                - `Color.RANDOM` or -1, a random value from that component's
+                  range will be picked
+
+        Raises:
+            TypeError: if datatypes dont match
+            ValueError: values are not within valid ranges
+        '''
+
         if len(kwargs) > 1:
             raise TypeError('Color() got multiple keyword arguments')
 

acrylic/__init__.py

@@ -1,3 +1,19 @@
+'''
+acrylic is a simple and intutive library to work with color in python. 
+It can be used to handle color data, easily convert between different 
+color spaces and work with colorschemes. acrylic currently supports the 
+following color formats:
+rgb, hsl, hsv, hex, name, ryb
+
+Try this for more details on how to use acrylic:
+>>> from acrylic import Color
+>>> help(Color)
+'''
+
+
+__version__ = '0.3.0'
+
+
 from .Color import Color
 from .Defaults import RANDOM
 from . import Schemes

changelog

@@ -6,6 +6,7 @@ v0.3.0
 - added more detailed tests for validation and conversion
 - changed conversion to lazily evaluate when needed
 - rewrote most of Color() class to reduce complexity
+- added tox with docker to automate tests across different python versions
 
 
 v0.2.4 & older

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
     name="acrylic",
-    version="0.2.2",
+    version="0.3.0",
     author="Arsh",
     author_email="[email protected]",
     description="A simple and intuitive library to work with colors in python",
@@ -18,6 +18,7 @@
         'Programming Language :: Python :: 3.6',
         'Programming Language :: Python :: 3.7',
         'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
         "Development Status :: 4 - Beta",

tests/Dockerfile

@@ -0,0 +1,13 @@
+FROM ubuntu:20.04
+
+RUN apt update && \
+    DEBIAN_FRONTEND=noninteractive apt install -y \
+        software-properties-common python3-pip && \
+    add-apt-repository -y ppa:deadsnakes/ppa && \
+    python3 -m pip install pytest tox
+
+RUN apt install -y python3.6 python3.7 python3.9
+
+WORKDIR /tests
+
+CMD ["tox"]

tox.ini

@@ -0,0 +1,6 @@
+[tox]
+envlist = py36,py37,py38,py39
+
+[testenv]
+deps = pytest
+commands = pytest