<!-- markdownlint-disable -->
<p align="center">
<a href="https://github.com/DevelopersToolbox/">
<img src="https://cdn.wolfsoftware.com/assets/images/github/organisations/developerstoolbox/black-and-white-circle-256.png" alt="DevelopersToolbox logo" />
</a>
<br />
<a href="https://github.com/DevelopersToolbox/draw-lines-package/actions/workflows/cicd.yml">
<img src="https://img.shields.io/github/actions/workflow/status/DevelopersToolbox/draw-lines-package/cicd.yml?branch=master&label=build%20status&style=for-the-badge" alt="Github Build Status" />
</a>
<a href="https://github.com/DevelopersToolbox/draw-lines-package/blob/master/LICENSE.md">
<img src="https://img.shields.io/github/license/DevelopersToolbox/draw-lines-package?color=blue&label=License&style=for-the-badge" alt="License">
</a>
<a href="https://github.com/DevelopersToolbox/draw-lines-package">
<img src="https://img.shields.io/github/created-at/DevelopersToolbox/draw-lines-package?color=blue&label=Created&style=for-the-badge" alt="Created">
</a>
<br />
<a href="https://github.com/DevelopersToolbox/draw-lines-package/releases/latest">
<img src="https://img.shields.io/github/v/release/DevelopersToolbox/draw-lines-package?color=blue&label=Latest%20Release&style=for-the-badge" alt="Release">
</a>
<a href="https://github.com/DevelopersToolbox/draw-lines-package/releases/latest">
<img src="https://img.shields.io/github/release-date/DevelopersToolbox/draw-lines-package?color=blue&label=Released&style=for-the-badge" alt="Released">
</a>
<a href="https://github.com/DevelopersToolbox/draw-lines-package/releases/latest">
<img src="https://img.shields.io/github/commits-since/DevelopersToolbox/draw-lines-package/latest.svg?color=blue&style=for-the-badge" alt="Commits since release">
</a>
<br />
<a href="https://github.com/DevelopersToolbox/draw-lines-package/blob/master/.github/CODE_OF_CONDUCT.md">
<img src="https://img.shields.io/badge/Code%20of%20Conduct-blue?style=for-the-badge" />
</a>
<a href="https://github.com/DevelopersToolbox/draw-lines-package/blob/master/.github/CONTRIBUTING.md">
<img src="https://img.shields.io/badge/Contributing-blue?style=for-the-badge" />
</a>
<a href="https://github.com/DevelopersToolbox/draw-lines-package/blob/master/.github/SECURITY.md">
<img src="https://img.shields.io/badge/Report%20Security%20Concern-blue?style=for-the-badge" />
</a>
<a href="https://github.com/DevelopersToolbox/draw-lines-package/issues">
<img src="https://img.shields.io/badge/Get%20Support-blue?style=for-the-badge" />
</a>
</p>
## Overview
A Python module for drawing styled and colored lines in the terminal. This utility allows for the customization of line styles, colors, and text positioning, making it a versatile tool for enhancing the output of CLI applications.
## Features
- Customizable text positions: left, right, or center.
- Support for various text colors and styles including bold.
- Adjustable line width and padding.
- Uses `colorama` for color and style handling, ensuring compatibility across different operating systems.
## Installation
```shell
pip install wolfsoftware.drawlines
```
## Usage
The main functionality is provided by the `draw_line` function, which can be used to create lines in the terminal with or without text.
### Function Signature
```python
def draw_line(text='', position='center', fill_char='-', pad=2, width=-1, color=''):
"""
Draw a line across the terminal with optional text.
Args:
text (str): Text to include in the line. Defaults to '' (no text).
position (str): Position of the text ('left', 'right', 'center'). Defaults to 'center'.
fill_char (str): Character used to fill the line. Defaults to '-'.
pad (int): Padding characters around the text. Defaults to 2.
width (int): Total width of the line; defaults to the terminal width if set to -1.
color (str): Color and style of the text, e.g., 'red', 'blue+bold'. Defaults to no color.
"""
```
### Examples
#### 1. Simple line with default settings
```python
from your_module import draw_line
# Draw a simple dashed line
print(draw_line())
```
#### Output
```shell
------------------------------------------------------------------------------------------
```
#### 2. Line with centered text and custom color
```python
# Draw a line with centered text
print(draw_line(text="Hello, World!", position='center'))
```
#### Output
```shell
------------------------------------- Hello, World! --------------------------------------
```
> If you set the `fill_char=' '` you will simply get centered text with no line.
#### 3. Line with left-aligned text and custom fill character
```python
# Draw a line with left-aligned text and asterisk fill character
print(draw_line(text="Left aligned text", position='left', fill_char='*'))
```
#### Output
```shell
** Left aligned text *********************************************************************
```
## Customization
This section provides details on how you can customize the `draw_line` function parameters. Below is a table listing each parameter, its default value, purpose, and allowed values:
| Name | Default Value | Purpose | Allowed Values |
| :-------- | :-----------: | :--------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| text | '' | Any string you want to display within the line. | Any string |
| position | 'center' | Where to place the text. | 'left', 'center', 'right' |
| fill_char | '-' | The character to use when drawing the line. If more than one is given, only the first is used. | Any single character |
| left_pad | 2 | How many fill_chars to use as a prefix when aligning the text left. | Any positive integer |
| right_pad | 2 | How many fill_chars to use as a postfix when aligning the text right. | Any positive integer |
| width | -1 | How wide to draw the line. Defaults to the terminal's width minus one if not specified. | Any integer; -1 for terminal width minus 1 |
| color | '' | What color to make the text. | 'bold', 'black', 'blue', 'cyan', 'green', 'grey', 'magenta', 'red', 'white', 'yellow', 'black+bold', 'blue+bold', 'cyan+bold', 'green+bold', 'grey+bold', 'magenta+bold', 'red+bold', 'white+bold', 'yellow+bold' |
| bold | False | Should the text be bold. This can be used with or without a defined color. | True, False |
> If you are adding bold to a color it **must** come after the color name. E.b. cyan+bold **NOT** bold+cyan as this will cause an exception to be thrown.
<br />
<p align="right"><a href="https://wolfsoftware.com/"><img src="https://img.shields.io/badge/Created%20by%20Wolf%20on%20behalf%20of%20Wolf%20Software-blue?style=for-the-badge" /></a></p>
Raw data
{
"_id": null,
"home_page": "https://github.com/DevelopersToolbox/draw-lines-package",
"name": "wolfsoftware.drawlines",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "python, convert_size",
"author": "Wolf Software",
"author_email": "pypi@wolfsoftware.com",
"download_url": "https://files.pythonhosted.org/packages/94/f3/5a605239d3f77c14fca3d12eced123f2e0f53131dd79fe39dc3f2ad135f0/wolfsoftware_drawlines-0.1.3.tar.gz",
"platform": null,
"description": "<!-- markdownlint-disable -->\n<p align=\"center\">\n <a href=\"https://github.com/DevelopersToolbox/\">\n <img src=\"https://cdn.wolfsoftware.com/assets/images/github/organisations/developerstoolbox/black-and-white-circle-256.png\" alt=\"DevelopersToolbox logo\" />\n </a>\n <br />\n <a href=\"https://github.com/DevelopersToolbox/draw-lines-package/actions/workflows/cicd.yml\">\n <img src=\"https://img.shields.io/github/actions/workflow/status/DevelopersToolbox/draw-lines-package/cicd.yml?branch=master&label=build%20status&style=for-the-badge\" alt=\"Github Build Status\" />\n </a>\n <a href=\"https://github.com/DevelopersToolbox/draw-lines-package/blob/master/LICENSE.md\">\n <img src=\"https://img.shields.io/github/license/DevelopersToolbox/draw-lines-package?color=blue&label=License&style=for-the-badge\" alt=\"License\">\n </a>\n <a href=\"https://github.com/DevelopersToolbox/draw-lines-package\">\n <img src=\"https://img.shields.io/github/created-at/DevelopersToolbox/draw-lines-package?color=blue&label=Created&style=for-the-badge\" alt=\"Created\">\n </a>\n <br />\n <a href=\"https://github.com/DevelopersToolbox/draw-lines-package/releases/latest\">\n <img src=\"https://img.shields.io/github/v/release/DevelopersToolbox/draw-lines-package?color=blue&label=Latest%20Release&style=for-the-badge\" alt=\"Release\">\n </a>\n <a href=\"https://github.com/DevelopersToolbox/draw-lines-package/releases/latest\">\n <img src=\"https://img.shields.io/github/release-date/DevelopersToolbox/draw-lines-package?color=blue&label=Released&style=for-the-badge\" alt=\"Released\">\n </a>\n <a href=\"https://github.com/DevelopersToolbox/draw-lines-package/releases/latest\">\n <img src=\"https://img.shields.io/github/commits-since/DevelopersToolbox/draw-lines-package/latest.svg?color=blue&style=for-the-badge\" alt=\"Commits since release\">\n </a>\n <br />\n <a href=\"https://github.com/DevelopersToolbox/draw-lines-package/blob/master/.github/CODE_OF_CONDUCT.md\">\n <img src=\"https://img.shields.io/badge/Code%20of%20Conduct-blue?style=for-the-badge\" />\n </a>\n <a href=\"https://github.com/DevelopersToolbox/draw-lines-package/blob/master/.github/CONTRIBUTING.md\">\n <img src=\"https://img.shields.io/badge/Contributing-blue?style=for-the-badge\" />\n </a>\n <a href=\"https://github.com/DevelopersToolbox/draw-lines-package/blob/master/.github/SECURITY.md\">\n <img src=\"https://img.shields.io/badge/Report%20Security%20Concern-blue?style=for-the-badge\" />\n </a>\n <a href=\"https://github.com/DevelopersToolbox/draw-lines-package/issues\">\n <img src=\"https://img.shields.io/badge/Get%20Support-blue?style=for-the-badge\" />\n </a>\n</p>\n\n## Overview\n\nA Python module for drawing styled and colored lines in the terminal. This utility allows for the customization of line styles, colors, and text positioning, making it a versatile tool for enhancing the output of CLI applications.\n\n## Features\n\n- Customizable text positions: left, right, or center.\n- Support for various text colors and styles including bold.\n- Adjustable line width and padding.\n- Uses `colorama` for color and style handling, ensuring compatibility across different operating systems.\n\n## Installation\n\n```shell\npip install wolfsoftware.drawlines\n```\n\n## Usage\n\nThe main functionality is provided by the `draw_line` function, which can be used to create lines in the terminal with or without text.\n\n### Function Signature\n\n```python\ndef draw_line(text='', position='center', fill_char='-', pad=2, width=-1, color=''):\n \"\"\"\n Draw a line across the terminal with optional text.\n\n Args:\n text (str): Text to include in the line. Defaults to '' (no text).\n position (str): Position of the text ('left', 'right', 'center'). Defaults to 'center'.\n fill_char (str): Character used to fill the line. Defaults to '-'.\n pad (int): Padding characters around the text. Defaults to 2.\n width (int): Total width of the line; defaults to the terminal width if set to -1.\n color (str): Color and style of the text, e.g., 'red', 'blue+bold'. Defaults to no color.\n \"\"\"\n```\n\n### Examples\n\n#### 1. Simple line with default settings\n\n```python\nfrom your_module import draw_line\n\n# Draw a simple dashed line\nprint(draw_line())\n```\n\n#### Output\n\n```shell\n------------------------------------------------------------------------------------------\n```\n\n#### 2. Line with centered text and custom color\n\n```python\n# Draw a line with centered text\nprint(draw_line(text=\"Hello, World!\", position='center'))\n```\n\n#### Output\n\n```shell\n------------------------------------- Hello, World! --------------------------------------\n```\n> If you set the `fill_char=' '` you will simply get centered text with no line.\n\n#### 3. Line with left-aligned text and custom fill character\n\n```python\n# Draw a line with left-aligned text and asterisk fill character\nprint(draw_line(text=\"Left aligned text\", position='left', fill_char='*'))\n```\n\n#### Output\n\n```shell\n** Left aligned text *********************************************************************\n```\n\n## Customization\n\nThis section provides details on how you can customize the `draw_line` function parameters. Below is a table listing each parameter, its default value, purpose, and allowed values:\n\n| Name | Default Value | Purpose | Allowed Values |\n| :-------- | :-----------: | :--------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| text | '' | Any string you want to display within the line. | Any string |\n| position | 'center' | Where to place the text. | 'left', 'center', 'right' |\n| fill_char | '-' | The character to use when drawing the line. If more than one is given, only the first is used. | Any single character |\n| left_pad | 2 | How many fill_chars to use as a prefix when aligning the text left. | Any positive integer |\n| right_pad | 2 | How many fill_chars to use as a postfix when aligning the text right. | Any positive integer |\n| width | -1 | How wide to draw the line. Defaults to the terminal's width minus one if not specified. | Any integer; -1 for terminal width minus 1 |\n| color | '' | What color to make the text. | 'bold', 'black', 'blue', 'cyan', 'green', 'grey', 'magenta', 'red', 'white', 'yellow', 'black+bold', 'blue+bold', 'cyan+bold', 'green+bold', 'grey+bold', 'magenta+bold', 'red+bold', 'white+bold', 'yellow+bold' |\n| bold | False | Should the text be bold. This can be used with or without a defined color. | True, False |\n\n> If you are adding bold to a color it **must** come after the color name. E.b. cyan+bold **NOT** bold+cyan as this will cause an exception to be thrown.\n\n<br />\n<p align=\"right\"><a href=\"https://wolfsoftware.com/\"><img src=\"https://img.shields.io/badge/Created%20by%20Wolf%20on%20behalf%20of%20Wolf%20Software-blue?style=for-the-badge\" /></a></p>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Draw lines on the console with optional text.",
"version": "0.1.3",
"project_urls": {
"Documentation": "https://github.com/DevelopersToolbox/draw-lines-package",
"Homepage": "https://github.com/DevelopersToolbox/draw-lines-package",
"Source": "https://github.com/DevelopersToolbox/draw-lines-package",
"Sponsor": "https://github.com/sponsors/WolfSoftware",
"Tracker": "https://github.com/DevelopersToolbox/draw-lines-package/issues/"
},
"split_keywords": [
"python",
" convert_size"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d92b58d3b4bee741cba471ca7603106762e3dd480f4a29939fed6aac0221285d",
"md5": "843bda99a8718791bf94bdcc065eba81",
"sha256": "8cec821923878d5b5bce18dceb47308e5bf21cff57ae7d64b48431e56a5dba85"
},
"downloads": -1,
"filename": "wolfsoftware.drawlines-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "843bda99a8718791bf94bdcc065eba81",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7466,
"upload_time": "2024-06-26T16:50:06",
"upload_time_iso_8601": "2024-06-26T16:50:06.821577Z",
"url": "https://files.pythonhosted.org/packages/d9/2b/58d3b4bee741cba471ca7603106762e3dd480f4a29939fed6aac0221285d/wolfsoftware.drawlines-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "94f35a605239d3f77c14fca3d12eced123f2e0f53131dd79fe39dc3f2ad135f0",
"md5": "8c39d6a148dfb1cb8c373cea7febf00f",
"sha256": "c3bcd700d42071dd12ce5192ced291be3025766117480d6cbb1050c065df6832"
},
"downloads": -1,
"filename": "wolfsoftware_drawlines-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "8c39d6a148dfb1cb8c373cea7febf00f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 10118,
"upload_time": "2024-06-26T16:50:09",
"upload_time_iso_8601": "2024-06-26T16:50:09.334948Z",
"url": "https://files.pythonhosted.org/packages/94/f3/5a605239d3f77c14fca3d12eced123f2e0f53131dd79fe39dc3f2ad135f0/wolfsoftware_drawlines-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-26 16:50:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DevelopersToolbox",
"github_project": "draw-lines-package",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "wolfsoftware.drawlines"
}
JSON
