# ansiplus
A Python package designed to enhance code readability and CLI experience.
## Usage
> [!WARNING]
> Not all terminals work perfectly with ANSI codes.
> Ideally you should use xterm-256color.
> [!NOTE]
> Terminal themes can change colors, e.g. magenta might show up as yellow, but it is still using the magenta ANSI code.
### Prerequisites
- Python version >=3.10
- A terminal emulator that accepts ANSI codes
- A terminal emulator that uses xterm-256color
> [!NOTE]
> ANSi codes are not limited to xterm-256color, but they may still be limited to all features this package provides.
#### Tested Terminals on Linux
Terminal ($TERM)
- Konsole (xterm-256color) - no missing features
- Xterm (xterm) - no missing features
- Alacritty (alacritty) - blinking text does not work
- Kitty (xterm-kitty) - blinking text does not work
### Colors
This package introduces the ability to print colors via name, id, rgb, and hex codes with a single function:
```python
>>> from ansiplus import print_color
>>> print_color("my colored text", color=(100, 200, 255), bgcolor=198)
'my colored text'
>>> print_color("red text", color="red")
>>> print("hex color 'f06'", color="#f06")
```
Colors may also be manually printed:
```python
>>> from ansiplus.ansi.colors import Fore
>>> print(f"{Fore.GREEN}green text{Fore.RESET}")
```
#### Rainbow & Random Colors
Text can be colored to resemble a rainbow:
```python
>>> from ansiplus import print_color
>>> print_color("this text is rainbow colored", "rainbow")
'this text is rainbow colored'
>>> print_color("each character will be a random color", "random")
'each character will be a random color'
```
> [!WARNING]
> Using rainbow or random color option uses a lot of ANSI codes.
### User Input
Along with colors, users can be prompted for input which can be colored:
```python
>>> from ansiplus import input_color
>>> txt = input_color("example: ", color="blue")
>>> print(txt)
'my input'
```
Prompting input can also store history if you assign it to a variable:
```python
>>> from ansiplus import NewPrompt
>>> ui = NewPrompt()
>>> ui.set_color("red")
>>> ui.set_prompt_color("green")
>>> ui.prompt("prompt class example: ")
>>> ui.history
['my text']
>>> ui.latest
'my text'
>>> ui.prompt("prompt class example 2: ", "yellow")
>>> ui.latest
'this text is yellow, but default is red'
```
#### Rainbow & Random Colors
Prompt foreground text can also be colored rainbow:
```python
>>> from ansiplus import input_color
>>> input_color("this text is rainbow: ", prompt_color="rainbow")
```
#### Clearing Prompt Lines
After receiving user input, the line can be cleared:
```python
from ansiplus import input_color
while True:
input_color("forever input: ", clearline=True)
```
The above code sample will ask for input forever, after every input, the line will clear and the input will be prompted again on the same line.
### Text Styles
This package includes several several styles that can be used:
```python
>>> from ansiplus import print_style
>>> print_style("underline text", "underline")
'underline text'
```
Like colors, styles may also be used manually:
```python
>>> from ansiplus.ansi.styles import BOLD, BOLD_RESET
>>> print(f"{BOLD}bold text{BOLD_RESET}")
'bold text'
>>>
```
### More Functions
There are more ANSI codes featured beyond colors and styles, these could be viewed by using `help(ansiplus)` inside the python interpreter.
## Developers
When building the package for testing, it is recommended to use `python3 -m build`.
### Wheels
When building the package for testing, it is recommended to use `python3 -m build`.
### PIP Virtual Environments
Virtual environments should be named ".venv" or ".env", as this is used in the ".gitignore" file.
### Contributing
Contributions must not include:
- breaking code
- major changes
- changes to the version number
- wheel files or egg-info files
- spaghetti code
Raw data
{
"_id": null,
"home_page": "https://github.com/xyzpw/ansiplus/",
"name": "ansiplus",
"maintainer": "xyzpw",
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "ansi, cursor, style, color",
"author": "xyzpw",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/3f/26/1785fe065b58c7e6349044a02228ad8cf718d318415713df68738703db84/ansiplus-3.1.tar.gz",
"platform": null,
"description": "# ansiplus\n\n\n\n\n\n\nA Python package designed to enhance code readability and CLI experience.\n\n\n\n\n## Usage\n> [!WARNING]\n> Not all terminals work perfectly with ANSI codes.\n> Ideally you should use xterm-256color.\n\n> [!NOTE]\n> Terminal themes can change colors, e.g. magenta might show up as yellow, but it is still using the magenta ANSI code.\n\n### Prerequisites\n- Python version >=3.10\n- A terminal emulator that accepts ANSI codes\n- A terminal emulator that uses xterm-256color\n\n> [!NOTE]\n> ANSi codes are not limited to xterm-256color, but they may still be limited to all features this package provides.\n\n#### Tested Terminals on Linux\nTerminal ($TERM)\n- Konsole (xterm-256color) - no missing features\n- Xterm (xterm) - no missing features\n- Alacritty (alacritty) - blinking text does not work\n- Kitty (xterm-kitty) - blinking text does not work\n\n### Colors\nThis package introduces the ability to print colors via name, id, rgb, and hex codes with a single function:\n```python\n>>> from ansiplus import print_color\n>>> print_color(\"my colored text\", color=(100, 200, 255), bgcolor=198)\n'my colored text'\n>>> print_color(\"red text\", color=\"red\")\n>>> print(\"hex color 'f06'\", color=\"#f06\")\n```\n\nColors may also be manually printed:\n```python\n>>> from ansiplus.ansi.colors import Fore\n>>> print(f\"{Fore.GREEN}green text{Fore.RESET}\")\n```\n\n#### Rainbow & Random Colors\nText can be colored to resemble a rainbow:\n```python\n>>> from ansiplus import print_color\n>>> print_color(\"this text is rainbow colored\", \"rainbow\")\n'this text is rainbow colored'\n>>> print_color(\"each character will be a random color\", \"random\")\n'each character will be a random color'\n```\n\n> [!WARNING]\n> Using rainbow or random color option uses a lot of ANSI codes.\n\n### User Input\nAlong with colors, users can be prompted for input which can be colored:\n```python\n>>> from ansiplus import input_color\n>>> txt = input_color(\"example: \", color=\"blue\")\n>>> print(txt)\n'my input'\n```\n\nPrompting input can also store history if you assign it to a variable:\n```python\n>>> from ansiplus import NewPrompt\n>>> ui = NewPrompt()\n>>> ui.set_color(\"red\")\n>>> ui.set_prompt_color(\"green\")\n>>> ui.prompt(\"prompt class example: \")\n>>> ui.history\n['my text']\n>>> ui.latest\n'my text'\n>>> ui.prompt(\"prompt class example 2: \", \"yellow\")\n>>> ui.latest\n'this text is yellow, but default is red'\n```\n\n#### Rainbow & Random Colors\nPrompt foreground text can also be colored rainbow:\n```python\n>>> from ansiplus import input_color\n>>> input_color(\"this text is rainbow: \", prompt_color=\"rainbow\")\n```\n\n#### Clearing Prompt Lines\nAfter receiving user input, the line can be cleared:\n```python\nfrom ansiplus import input_color\nwhile True:\n input_color(\"forever input: \", clearline=True)\n```\nThe above code sample will ask for input forever, after every input, the line will clear and the input will be prompted again on the same line.\n\n### Text Styles\nThis package includes several several styles that can be used:\n```python\n>>> from ansiplus import print_style\n>>> print_style(\"underline text\", \"underline\")\n'underline text'\n```\n\nLike colors, styles may also be used manually:\n```python\n>>> from ansiplus.ansi.styles import BOLD, BOLD_RESET\n>>> print(f\"{BOLD}bold text{BOLD_RESET}\")\n'bold text'\n>>>\n```\n\n### More Functions\nThere are more ANSI codes featured beyond colors and styles, these could be viewed by using `help(ansiplus)` inside the python interpreter.\n\n## Developers\nWhen building the package for testing, it is recommended to use `python3 -m build`.\n### Wheels\nWhen building the package for testing, it is recommended to use `python3 -m build`.\n### PIP Virtual Environments\nVirtual environments should be named \".venv\" or \".env\", as this is used in the \".gitignore\" file.\n\n### Contributing\nContributions must not include:\n- breaking code\n- major changes\n- changes to the version number\n- wheel files or egg-info files\n- spaghetti code\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package designed to enhance code readability and CLI experience.",
"version": "3.1",
"project_urls": {
"Homepage": "https://github.com/xyzpw/ansiplus/"
},
"split_keywords": [
"ansi",
" cursor",
" style",
" color"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9de729dc5d708d1c0edbaa802b3f3a4a9d2c53474cd26b33bafe0e80be9cb51e",
"md5": "96813cf20564ef8d13d5c811b50cdb2f",
"sha256": "33af5af41a2a18c16376a817afc257725ab25d802015536af35e7cf117378b60"
},
"downloads": -1,
"filename": "ansiplus-3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "96813cf20564ef8d13d5c811b50cdb2f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 13855,
"upload_time": "2024-08-10T22:32:03",
"upload_time_iso_8601": "2024-08-10T22:32:03.715297Z",
"url": "https://files.pythonhosted.org/packages/9d/e7/29dc5d708d1c0edbaa802b3f3a4a9d2c53474cd26b33bafe0e80be9cb51e/ansiplus-3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3f261785fe065b58c7e6349044a02228ad8cf718d318415713df68738703db84",
"md5": "37816249b7201f5df4e34c2cc6b4edee",
"sha256": "1810a9c57f1bd05575ab51691cadf7e77d04386a427975254f192731150b4262"
},
"downloads": -1,
"filename": "ansiplus-3.1.tar.gz",
"has_sig": false,
"md5_digest": "37816249b7201f5df4e34c2cc6b4edee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12106,
"upload_time": "2024-08-10T22:32:04",
"upload_time_iso_8601": "2024-08-10T22:32:04.719453Z",
"url": "https://files.pythonhosted.org/packages/3f/26/1785fe065b58c7e6349044a02228ad8cf718d318415713df68738703db84/ansiplus-3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-10 22:32:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xyzpw",
"github_project": "ansiplus",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ansiplus"
}
JSON
