{"id":34086717,"url":"https://github.com/max-derner/colour_fx","last_synced_at":"2026-04-06T02:01:46.891Z","repository":{"id":263282388,"uuid":"889884344","full_name":"Max-Derner/colour_fx","owner":"Max-Derner","description":"Colour handling through 4 bit and 8 bit ANSI escape sequences. Powerful effects like gradients for blocks of text such as figlet banners.","archived":false,"fork":false,"pushed_at":"2024-12-22T09:56:15.000Z","size":1452,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-06T05:34:28.425Z","etag":null,"topics":["ansi-colors","ansi-colours","ansi-escape-codes","colored-text-python","colors","coloured-text-python","colours","pypi-package","python","select-graphic-rendition"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Max-Derner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-17T13:46:35.000Z","updated_at":"2025-08-25T09:49:36.000Z","dependencies_parsed_at":"2024-11-30T15:51:39.665Z","dependency_job_id":null,"html_url":"https://github.com/Max-Derner/colour_fx","commit_stats":null,"previous_names":["max-derner/pyglet","max-derner/colour_effects","max-derner/colour_fx"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Max-Derner/colour_fx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Max-Derner%2Fcolour_fx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Max-Derner%2Fcolour_fx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Max-Derner%2Fcolour_fx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Max-Derner%2Fcolour_fx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Max-Derner","download_url":"https://codeload.github.com/Max-Derner/colour_fx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Max-Derner%2Fcolour_fx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31456664,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansi-colors","ansi-colours","ansi-escape-codes","colored-text-python","colors","coloured-text-python","colours","pypi-package","python","select-graphic-rendition"],"created_at":"2025-12-14T13:32:19.199Z","updated_at":"2026-04-06T02:01:46.885Z","avatar_url":"https://github.com/Max-Derner.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Testing and linting](https://github.com/Max-Derner/colour_effects/actions/workflows/python-testing.yml/badge.svg?branch=main)](https://github.com/Max-Derner/colour_effects/actions/workflows/python-testing.yml)\n\n\n![promo image](https://github.com/Max-Derner/colour_fx/blob/main/README_IMGS/promo_img.png?raw=true)\n\nThis a project to develop a Python PyPI package that not just handles colour text output but can also apply colour effects such as gradients to your text.\n\n\n# Introduction\n\nThis package uses ANSI escape sequence select graphics renditions in order to apply colour and style to text and backgrounds.\nHow is this package any different to the others?\n* 8 bit codes as well as 4 bit codes\n* there is an ever expanding library of effects that can be applied to larger blocks of texts.\n* super slick and simple interface\n\n\n#### N.B.\nDifferent terminals render colours differently, some terminals don't even render ANSI escape sequences at all, leading to a big mess of text. Playing around with ANSI escape codes is just that, it is playing.\n\nSome basic colours used sparingly to highlight different logging levels is fine but you can't get carried away with colours in serious projects.\n\n# Getting started\n\nFirst, there 4 bit and 8 bit codes available, import from `colour_fx.four_bit` and `colour_fx.eight_bit` respectively. However, both 8 bit and 4 bit codes can be used together without issue.  \n\n#### N.B.\nThe objects in these modules only provide the the value to be used inside an ANSI escape sequence. They will need to be compiled into an ANSI escape sequence using `compile_ansi_code` which can be imported with `from colour_fx import compile_ansi_code`.  \n\n## 4 bit example\n```python\nfrom colour_fx import compile_ansi_code\nfrom colour_fx.four_bit import Colour, Style\n\nblinking_red_on_yellow = compile_ansi_code(\n    # add as many ANSI values as you like and receive a single ANSI\n    # escape sequence to handle all effects\n    Colour.RED,\n    Colour.YELLOW.bright_background,\n    Style.BLINK\n)\n\n# an empty call to compile_ansi_code() gives the reset ANSI escape\n# sequence which resets the way text is rendered\nRESET = compile_ansi_code()\n\nprint(F\"HELLO, {blinking_red_on_yellow}WORLD{RESET}!\")\n```\n![Colour example output](https://github.com/Max-Derner/colour_fx/blob/main/README_IMGS/Colour-example-output.gif?raw=true)\n\n## 8 bit examples\n\n##### N.B.\n8 bit colours are much more unpredictable in appearance between different terminals than 4 bit colours are.\n\n### `SimpleColour`\n```python\nfrom colour_fx import compile_ansi_code\nfrom colour_fx.eight_bit import SimpleColour\n\nred_on_yellow = compile_ansi_code(\n    # add as many ANSI values as you like and receive a single ANSI\n    # escape sequence to handle all effects\n    SimpleColour.RED,\n    SimpleColour.YELLOW.bright_background,\n)\n\n# an empty call to compile_ansi_code() gives the reset ANSI escape\n# sequence which resets the way text is rendered\nRESET = compile_ansi_code()\n\nprint(F\"HELLO, {red_on_yellow}WORLD{RESET}!\")\n```\n#### output\n![SipleColour example output](https://github.com/Max-Derner/colour_fx/blob/main//README_IMGS/SimpleColour-example-output.png?raw=true)\n\n### `Grey`\n```python\nfrom colour_fx import compile_ansi_code\nfrom colour_fx.eight_bit import Grey\n\n# Grey has 24 different shades available, here we use 12 to apply a\n# gradient to the text \"HELLO, WORLD!\"\ngrey_array = [\n    Grey.AA,\n    Grey.AC,\n    Grey.AE,\n    Grey.BB,\n    Grey.BD,\n    Grey.BF,\n    Grey.CA,\n    Grey.CC,\n    Grey.CE,\n    Grey.DB,\n    Grey.DD,\n    Grey.DF,\n]\n\n# converting shades in grey_array to background colours and\n# reversing order\ngrey_back = [grey.background for grey in reversed(grey_array)]\n\n# Compiling the values in grey_array and grey_back into codes\ng = [\n    compile_ansi_code(\n        grey_array[idx],\n        grey_back[idx],\n    )\n    for idx in range(len(grey_array))\n]\n\n# an empty call to compile_ansi_code() gives the reset ANSI escape\n# sequence which resets the way text is rendered\nRESET = compile_ansi_code()\n\n# Accessing the individual ANSI escape codes in the list of codes to\n# create a gradient\nprint(\n    F\"{g[0]}H{g[1]}E{g[2]}L{g[3]}L{g[4]}O{g[5]},\"\n    F\"{g[6]} W{g[7]}O{g[8]}R{g[9]}L{g[10]}D{g[11]}!{RESET}\"\n)\n```\n#### output\n![Grey example output](https://github.com/Max-Derner/colour_fx/blob/main/README_IMGS/Grey-example-output.png?raw=true)\n\n### `RGB`\n```python\nfrom colour_fx import compile_ansi_code\nfrom colour_fx.eight_bit import RGB\n\n\n# RGB is different to the rest in that you need to pass values in and\n# initialise the object rather than treating as an Enum\n# RGB values should be an integer between 0 and 5 inclusive\nspectrum = [\n    RGB(5, 0, 0).foreground,\n    RGB(3, 2, 0).foreground,\n    RGB(1, 4, 0).foreground,\n    RGB(0, 4, 1).foreground,\n    RGB(0, 2, 3).foreground,\n    RGB(0, 0, 5).foreground,\n]\n\n# compiling spectrum into ANSI escape sequences while adding a\n# white background\ns = [\n    compile_ansi_code(spec, RGB(5, 5, 5).background)\n    for spec in spectrum\n]\n\n# an empty call to compile_ansi_code() gives the reset ANSI escape\n# sequence which resets the way text is rendered\nRESET = compile_ansi_code()\n\n# Accessing individual elements of s allows a gradient\nprint(F\"{s[0]}HE{s[1]}LL{s[2]}O,{s[3]} WO{s[4]}RL{s[5]}D!{RESET}\")\n```\n\n#### output\n![RGB output](https://github.com/Max-Derner/colour_fx/blob/main/README_IMGS/RGB-example-output.png?raw=true)\n\n\n# Getting advanced\nNow this is what inspired the creation of this package, being able to apply gradients to large blocks of text.\n\n## gradients\n```python\nfrom colour_fx.four_bit import Colour\nfrom colour_fx.effects.gradients import create_vertical_gradient_field\nfrom colour_fx.effects import apply_ansi_field\n\nrainbow_vals = [\n    [Colour.RED],\n    [Colour.RED.bright],\n    [Colour.YELLOW.bright],\n    [Colour.GREEN],\n    [Colour.BLUE],\n    [Colour.BLUE.bright],\n    [Colour.MAGENTA],\n]\n\ntext_to_render = (\n    \"       :::    ::: :::::::::: :::        :::        ::::::::  ::: \\n\"\n    \"      :+:    :+: :+:        :+:        :+:       :+:    :+: :+:  \\n\"\n    \"     +:+    +:+ +:+        +:+        +:+       +:+    +:+ +:+   \\n\"\n    \"    +#++:++#++ +#++:++#   +#+        +#+       +#+    +:+ +#+    \\n\"\n    \"   +#+    +#+ +#+        +#+        +#+       +#+    +#+ +#+     \\n\"\n    \"  #+#    #+# #+#        #+#        #+#       #+#    #+#          \\n\"\n    \" ###    ### ########## ########## ########## ########  ###       \\n\"\n)\n\noutput_field = create_vertical_gradient_field(\n    template=text_to_render,\n    ansi_vals=rainbow_vals,\n    indent=3,\n    step=1,\n)\n\noutput_text = apply_ansi_field(\n    text=text_to_render,\n    field=output_field\n)\n\nprint(output_text)\n```\n#### output\n![vertical gradient example output](https://github.com/Max-Derner/colour_fx/blob/main/README_IMGS/vertical-gradient-example-output.png?raw=true)\n\n\n# Working on this?\nDon't use Windows, install Python 3.9, then use `source ./tooling \u0026\u0026 venv-setup` to get yourself a venv set up with Python 3.9 (our lowest supported Python version)\n\nUse command `lint-cfx` to lint work, and command `test-cfx` to test work.\n\nUse a branch in your name to do feature work, then submit a pull request.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmax-derner%2Fcolour_fx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmax-derner%2Fcolour_fx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmax-derner%2Fcolour_fx/lists"}