{ "info": { "author": "Erick Daniszewski", "author_email": "edaniszewski@gmail.com", "bugtrack_url": null, "classifiers": [ "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Natural Language :: English", "Programming Language :: Python", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.7", "Topic :: Utilities" ], "description": "==========\r\ncolorutils\r\n==========\r\n\r\n.. image:: https://pypip.in/license/colorutils/badge.svg\r\n :target: https://pypi.python.org/pypi/colorutils/\r\n :alt: License\r\n \r\n.. image:: https://pypip.in/version/colorutils/badge.svg\r\n :target: https://pypi.python.org/pypi/colorutils/\r\n :alt: Latest Version\r\n \r\n.. image:: https://pypip.in/download/colorutils/badge.svg\r\n :target: https://pypi.python.org/pypi//colorutils/\r\n :alt: Downloads\r\n\r\nA library which provides utilities for working with colors in Python. Colors are modeled by the ``Color`` class and can be\r\nrepresented in ``RGB``, ``HEX``, ``WEB``, and ``YIQ`` formats.\r\n\r\n0. Installation\r\n===============\r\n\r\n``colorutils`` can be installed from pypi::\r\n\r\n pip install colorutils\r\n \r\nto update an existing installation from pypi to the latest version::\r\n\r\n pip install colorutils --upgrade\r\n\r\n\r\n1. Current Features\r\n===================\r\n\r\n**v0.2.1** (released 05/25/2015)\r\n\r\n- Bug fix for pip install on Windows for unfound packages\r\n\r\n**v0.2** (released 05/23/2015)\r\n\r\n- Add HSV color representation and conversions\r\n- Add YIQ color representation and conversions\r\n- Color objects can be treated as iterables\r\n- Implementation of color runs\r\n- Addition of pre-defined color palettes\r\n- Package restructuring\r\n\r\n**v0.1** (released 05/16/2015)\r\n\r\n- A versatile abstract color model which allows color addition and subtraction\r\n- Conversions between: ``RGB`` tuples, 6-character ``HEX`` strings, 3-character ``HEX`` strings, and ``WEB`` representations of color.\r\n- Random color generation\r\n\r\n\r\n2. Reporting Bugs / Requesting Features\r\n=======================================\r\n\r\nTo report a bug or request a feature for colorutils, please open a new issue_\r\n\r\n .. _issue: https://github.com/edaniszewski/colorutils/issues\r\n\r\n\r\n3. Usage\r\n========\r\n\r\n3.1 Instantiating a ``Color``\r\n-----------------------------\r\n\r\nThe basic way to instantiate a ``Color``::\r\n\r\n >>> from colorutils import Color\r\n >>> c = Color((255, 255, 255))\r\n >>> c\r\n \r\n\r\nBy default, the Color object expects an ``RGB`` 3-tuple, but there are multiple ways to instantiate a ``Color``. The possibilities for Cyan, for example::\r\n\r\n Color((0, 255, 255))\r\n Color(green=255, blue=255)\r\n Color(rgb=(0, 255, 255))\r\n Color(hex='#00FFFF')\r\n Color(hex='00ffff')\r\n Color(hex='#0ff')\r\n Color(hex='0ff')\r\n Color(web='cyan')\r\n Color(web='Cyan')\r\n Color(web='CYAN')\r\n Color(web='#00ffff')\r\n Color(web='#0ff')\r\n Color(yiq=(0.701, -0.596, -0.217))\r\n Color(hsv=(180, 1, 1))\r\n\r\n``Color`` objects can also take the color from other ``Color`` objects::\r\n\r\n >>> Color(Color((255, 255, 255)))\r\n \r\n\r\n >>> Color(Color(Color(Color((255, 255, 255)))))\r\n \r\n\r\n3.2 Color Conversion\r\n--------------------\r\nThe current color models supported by ``colorutils`` are: ``RGB``, ``HEX``, ``WEB``, ``YIQ``, and ``HSV``. Each instantiated ``Color`` object has properties which will automatically perform the required conversions::\r\n\r\n >>> c = Color((46, 139, 87))\r\n\r\n >>> c.red\r\n 46\r\n\r\n >>> c.green\r\n 139\r\n\r\n >>> c.blue\r\n 87\r\n\r\n >>> c.rgb\r\n (46, 139, 87)\r\n\r\n >>> c.hex\r\n '#2e8b57'\r\n\r\n >>> c.shorthex\r\n '#2e8b57'\r\n\r\n >>> c.web\r\n 'SeaGreen'\r\n\r\n >>> c.yiq\r\n (0.413, -0.152, -0.143)\r\n\r\n >>> c.hsv\r\n (146.452, 0.669, 0.545)\r\n\r\nIf the color were such that the ``HEX`` representation could be captured as a 3-char hex::\r\n\r\n >>> c = Color((0, 0, 0))\r\n\r\n >>> c.hex\r\n '#000000'\r\n\r\n >>> c.shorthex\r\n '#000'\r\n\r\nThe web representation will return the hex value if the color is not a well-known named web color::\r\n\r\n >>> c = Color((1, 243, 77))\r\n\r\n >>> c.hex\r\n '#01f34d'\r\n\r\n >>> c.web\r\n '#01f34d'\r\n\r\nThese same conversions can be done without instantiating a ``Color`` object by using the static methods:\r\n\r\n* ``rgb_to_hex()``\r\n* ``rgb_to_web()``\r\n* ``rgb_to_yiq()``\r\n* ``rgb_to_hsv()``\r\n* ``hex_to_rgb()``\r\n* ``hex_to_web()``\r\n* ``hex_to_yiq()``\r\n* ``hex_to_hsv()``\r\n* ``web_to_rbg()``\r\n* ``web_to_hex()``\r\n* ``web_to_yiq()``\r\n* ``web_to_hsv()``\r\n* ``yiq_to_rgb()``\r\n* ``yiq_to_hex()``\r\n* ``yiq_to_web()``\r\n* ``yiq_to_hsv()``\r\n* ``hsv_to_rgb()``\r\n* ``hsv_to_hex()``\r\n* ``hsv_to_web()``\r\n* ``hsv_to_yiq()``\r\n\r\nUsing these static conversion methods, one can chain conversions (due to the in-param and out-param of all multi-value color representations being a tuple), which you are unable to do using the Python default `colorsys`.::\r\n\r\n >>> rgb_to_hex(hex_to_rgb('#808080'))\r\n '#808080'\r\n\r\nOf course, be wary of chaining. Since approximation exists in the conversion algorithms, degradation will occur::\r\n\r\n >>> yiq_to_web(rgb_to_yiq(hex_to_rgb('808080')))\r\n '#7f807e'\r\n\r\nThough, the values will still be close::\r\n\r\n >>> hex(int('80', 16) - int('7f', 16)) # Red difference\r\n '0x1'\r\n\r\n >>> hex(int('80', 16) - int('80', 16)) # Green difference\r\n '0x0'\r\n\r\n >>> hex(int('80', 16) - int('7e', 16)) # Blue difference\r\n '0x2'\r\n\r\n3.3 ``Color`` Arithmetic\r\n------------------------\r\n\r\nAlthough the addition and subtraction of color does not always make sense, the ability to do so is supported. There are two additive models currently supported: ``LIGHT`` and ``BLEND``.\r\n\r\n3.3.1 Addition\r\n~~~~~~~~~~~~~~\r\n\r\n``LIGHT``\r\n the light model is an additive model, where the rgb components are added, but do not exceed the maximum value, 255. This model is the default model which every ``Color`` is initialized with, unless overridden.\r\n\r\nAn example of ``LIGHT`` addition::\r\n\r\n >>> Color((0, 100, 200)) + Color((100, 100, 100))\r\n \r\n\r\n``BLEND``\r\n the blend model is an averaging model, where each rgb component is averaged.\r\n\r\nAn example of ``BLEND`` addition::\r\n\r\n >>> Color((0, 100, 200), arithmetic=ArithmeticModel.BLEND) + Color((100, 100, 100))\r\n \r\n\r\nWhen assigning models, it is important to note that the arithmetic model for the first object in the operation, e.g. Object1 in 'Object1 + Object2', is the model which will be used when computing the addition.\r\n\r\n``Color`` addition can also operate on 3-tuples, which represent an ``RGB`` value::\r\n\r\n >>> Color((50, 50, 50)) + (20, 20, 20)\r\n \r\n\r\n3.3.2 Subtraction\r\n~~~~~~~~~~~~~~~~~\r\n\r\nThere is currently only one subtractive model, the equivalent to the inverse of the ``LIGHT`` additive model. There is no model representing the inverse of ``BLEND``, since the inverse average does not really make sense.::\r\n\r\n >>> Color((100, 100, 100)) - Color((0, 75, 200))\r\n \r\n\r\n\r\n``Color`` subtraction can also operate on 3-tuples, which represent an ``RGB`` value::\r\n\r\n >>> Color((50, 50, 50)) - (20, 20, 20)\r\n \r\n\r\n\r\n3.4 Color Equality\r\n------------------\r\n\r\nTesting for equality between colors defaults to testing between the equality of the ``RGB`` values::\r\n\r\n >>> c1 = Color((10, 20, 30))\r\n >>> c2 = Color((10, 20, 30))\r\n >>> c3 = Color((10, 20, 20))\r\n\r\n >>> c1 == c2\r\n True\r\n\r\n >>> c1 == c3\r\n False\r\n\r\nDifferent equality functions can be set, using either the predefined equalities in ``colorutils.equality``, or from a custom equality function::\r\n\r\n >>> from colorutils.equality import *\r\n >>> c = Color((10, 20, 30), equality_fn=RED_eq)\r\n >>> c2 = Color((10, 40, 60))\r\n\r\n >>> c == c2\r\n True\r\n\r\n >>> c2 == c\r\n False\r\n\r\nNotice that in the above example, when checking for red equality, when the color with the ``RED_eq`` equality comes first in the comparison, it\r\nevaluates to ``True``. If it comes second, it evaluates to ``False``. This is because the equality function of the first ``Color`` instance in\r\nthe comparison defines which equality function is used.\r\n\r\nThe predefined equalities are:\r\n\r\n* ``RGB_eq``\r\n* ``RED_eq``\r\n* ``GREEN_eq``\r\n* ``BLUE_eq``\r\n* ``HEX_eq``\r\n* ``WEB_eq``\r\n* ``YIQ_eq``\r\n* ``HSV_eq``\r\n\r\nDefining a custom equality would follow the pattern defined by the RGB_eq definition, below::\r\n\r\n RGB_eq = lambda c1, c2: c1.rgb == c2.rgb\r\n\r\n\r\n3.5 Color Palettes\r\n------------------\r\n\r\nA collection of pre-defined color palettes exists for convenience. The palettes which are currently implemented include:\r\n\r\n* grayscale\r\n* primary\r\n* rgb\r\n* roygbv\r\n* secondary\r\n\r\nIndividual named colors can be used from the palettes, or all colors can be retrieved::\r\n\r\n >>> import colorutils.palettes.primary as primary\r\n\r\n >>> primary.red\r\n \r\n\r\n >>> primary.yellow\r\n \r\n\r\n >>> primary.blue\r\n \r\n\r\n >>> primary.all\r\n [, , ]\r\n\r\n\r\n4. ``colorutils`` vs others\r\n===========================\r\n\r\nTo see how the ``colorutils`` conversion algorithms compare to other algorithms/provided values, see the comparisons_ wiki page.\r\n\r\n .. _comparisons: https://github.com/edaniszewski/colorutils/wiki/Comparing-Conversion-Algorithms", "description_content_type": null, "docs_url": null, "download_url": "https://github.com/edaniszewski/colorutils/releases/tag/0.2.1", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/edaniszewski/colorutils", "keywords": "color,color manipulation,color conversion,color tools", "license": "MIT", "maintainer": "", "maintainer_email": "", "name": "colorutils", "package_url": "https://pypi.org/project/colorutils/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/colorutils/", "project_urls": { "Download": "https://github.com/edaniszewski/colorutils/releases/tag/0.2.1", "Homepage": "https://github.com/edaniszewski/colorutils" }, "release_url": "https://pypi.org/project/colorutils/0.2.1/", "requires_dist": null, "requires_python": null, "summary": "A utility for working with colors in Python.", "version": "0.2.1" }, "last_serial": 1561433, "releases": { "0.1": [ { "comment_text": "", "digests": { "md5": "5ae4619dc1e730fc280667f62b6e4fcf", "sha256": "9dba05c9718b788ce64667c06ccb8e77223fdb7aaf26704518cd0837f7cbc66a" }, "downloads": -1, "filename": "colorutils-0.1.tar.gz", "has_sig": false, "md5_digest": "5ae4619dc1e730fc280667f62b6e4fcf", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 9302, "upload_time": "2015-05-16T11:08:30", "url": "https://files.pythonhosted.org/packages/b6/3d/837d27278efceb7d38778f9f4eb6d6eb42b3f623eb9e5830919d02d78661/colorutils-0.1.tar.gz" } ], "0.2": [ { "comment_text": "", "digests": { "md5": "e36a0b5e9394eeda100b92e329e76a21", "sha256": "5867d8eee44174d357d83d20bff0ca47db6ee9cea618ebd07f4065341aa9edd2" }, "downloads": -1, "filename": "colorutils-0.2.tar.gz", "has_sig": false, "md5_digest": "e36a0b5e9394eeda100b92e329e76a21", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13973, "upload_time": "2015-05-23T15:13:01", "url": "https://files.pythonhosted.org/packages/e8/f4/e2d6acbfec838f0670412b44ecb7843176e9c772590e24ce540bddd586d5/colorutils-0.2.tar.gz" } ], "0.2.1": [ { "comment_text": "", "digests": { "md5": "a859e4471b05999916420c44cea4c62e", "sha256": "c08d08411b11fa2a5e38f729a23f6ab84a6c92971d76443f575c66a4c308aba6" }, "downloads": -1, "filename": "colorutils-0.2.1.zip", "has_sig": false, "md5_digest": "a859e4471b05999916420c44cea4c62e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 24317, "upload_time": "2015-05-25T12:59:13", "url": "https://files.pythonhosted.org/packages/cb/f6/336aec4204176c5de680511b7a943c191502dc4fe819928921c7588f5f5e/colorutils-0.2.1.zip" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "a859e4471b05999916420c44cea4c62e", "sha256": "c08d08411b11fa2a5e38f729a23f6ab84a6c92971d76443f575c66a4c308aba6" }, "downloads": -1, "filename": "colorutils-0.2.1.zip", "has_sig": false, "md5_digest": "a859e4471b05999916420c44cea4c62e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 24317, "upload_time": "2015-05-25T12:59:13", "url": "https://files.pythonhosted.org/packages/cb/f6/336aec4204176c5de680511b7a943c191502dc4fe819928921c7588f5f5e/colorutils-0.2.1.zip" } ] }