<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241106_012559_output.jpg" />
</p>
`pinsy` (pronounced **pin-si**) _formerly `pins`_, is a powerful lightweight python package that helps speed up the workflow of creating visually apealing command-line applications.
## Table of contents
- [Features](#features)
- [Dependencies](#dependencies)
- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [how to color text](#how-to-color-text)
- [how to color a regex match](#how-to-color-a-regex-match)
- [how to print status messages](#how-to-print-status-messages)
- [how to align text](#how-to-align-text)
- [how to indent text](#how-to-indent-text)
- [how to wrap text](#how-to-wrap-text)
- [how to create lists](#how-to-create-lists)
- [how to take inputs of various types](#how-to-take-inputs-of-various-types)
- [how to create hrs (horizontal rules)](#how-to-create-hrs-horizontal-rules)
- [how to create box around text](#how-to-create-box-around-text)
- [how to create a calendar](#how-to-create-a-calendar)
- [how to pretty-print json](#how-to-pretty-print-json)
- [how to print lengthy text for user to read easily](#how-to-print-lengthy-text-for-user-to-read-easily)
- [how to print multiline text as pages](#how-to-print-multiline-text-as-pages)
- [how to print info about your program](#how-to-print-info-about-your-program)
- [how to print text with typewriter effect](#how-to-print-text-with-typewriter-effect)
- [how to print text with reveal effect](#how-to-print-text-with-reveal-effect)
- [Pinsy CLI](#pinsy-cli)
## Features
- Ability to create a **box** around text
- Ability to print colorful calendars
- Ability **align**, **indent** and **wrap** text
- Ability to create nested **ordered** and **unordered** lists
- Ability to create dynamic **HRs** (_Horizontal Rules_)
- Syntax Highlight for **Json**
- Text effects like _typewriter_ and _reveal text_ effect.
- Text coloring and styling
- Supports 3 color modes (`4-bit`, `8-bit`, `24-bit`)
- Prompting and validation
- Basic cursor manipulation functions using `ansi sequences`
- Highly optimized
- And much more!
- And pretty lightweight\* too (under `160kb`)
## Dependencies
`pinsy` has three small dependencies.
- `colorama` (_to fix windows console for color output_)
- `cursor` (to show/hide cursor in terminal)
- `ansy` (_which i wrote specifically for `pinsy` for color support)_
## Installation
Open terminal and run below command:
```python
pip install pinsy
```
## Basic Usage
There is a `class` in _pinsy_ which is the heart of it, called `Pins`. Most of the time, you'll be using this class for all sorts of stuff. Rest of the package is just built around it or to extend it.
```py
from pinsy import Pins
# Create an instance of Pins and pins is ready to be used or abused.
pins = Pins()
```
### How to color text
Use `pins.colorize()` method to color text using any of the three color modes.
```py
text = "Color this text"
red_text = pins.colorize(text, fgcolor="red")
yellow_text = pins.colorize(text, fgcolor="yellow")
blue_text = pins.colorize(text, fgcolor="blue")
print(red_text)
print(yellow_text)
print(blue_text)
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172244_colored_text.png" />
</p>
### How to color a regex match
You can color only specific parts of text that match a regular expression, using `pins.colorize_regex()`.
```py
text = "Thi5 t3xt c0ntain5 a l0t 0f number5."
highlights = pins.colorize_regex(text, pattern="\d", fgcolor="red")
print(highlights)
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172238_highlights.png" />
</p>
`pattern` can also be a `re` compiled pattern.
```py
pattern = re.compile(r"\d")
pins.colorize_regex(text, pattern=pattern, fgcolor="red")
```
### How to print status messages
Status messages include **info**, **warning**, **success**, and **error** messages. There are four built-in methods for printing these messages.
```py
pins.print_info("This is an info message.")
pins.print_warning("This is a warning message.")
pins.print_success("This is a success message.")
pins.print_error("This is an error message.")
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172215_status_messages.png" />
</p>
Colors are set by default for these built-in messages. But you can also create custom status messages for more control, using `pins.create_status()`.
```py
message = "This is a hint message"
hint = pins.create_status("Hint", message, label_fg="green", text_fg="blue")
print(hint)
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172159_hint.png" />
</p>
### How to align text
You can easily align text in the terminal using `pins.textalign_x()` (_for horizontal alignment_) or `pins.textalign_y` (_for vertical alignment_).
```py
# Horizontal Alignment
text = "Align this text"
print(pins.textalign_x(text, align="left"))
print(pins.textalign_x(text, align="center"))
print(pins.textalign_x(text, align="right"))
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172028_align_x.png" />
</p>
### How to indent text
Use `pins.indent_text()` to indent text, **Duh!**
```py
text = "Indent this 4 spaces"
print("|", pins.indent_text(text, indent=4))
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172019_indent.png" />
</p>
### How to wrap text
You can wrap text using `pins.wrap_text()`. This method is merely a wrapper around the `fill()` method from `textwrap` module.
```py
text = "Wrap this text if it exceeds 15 characters."
print(pins.wrap_text(text, 15))
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172013_wrap.png" />
</p>
### How to create lists
There are two types of lists that you can create, **ordered** and **unordered**, using `pins.create_list_ordered()` and `pins.create_list_unordered()` respectively.
```py
# Ordered List
items = ["Assembly", "C", "Python", ["CPython", "PyPy"], "Javascript"]
ordered_list = pins.create_list_ordered(items, num_color="green", item_color="blue")
print(ordered_list)
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172003_ordered.png" />
</p>
```py
# Unordered List
items = ["Assembly", "C", "Python", ["CPython", "PyPy"], "Javascript"]
unordered_list = pins.create_list_unordered(items, bullet_color="green", item_color="blue")
print(unordered_list)
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_171953_unordered.png" />
</p>
You can further tweak these lists using other arguments of both of these methods.
### How to take inputs of various types
There are 13 input methods that can be used take all sorts of inputs from users. almost all of them support colors.
```python
# Taking integer input
number = pins.input_int(prompt="Enter a number: ",
prompt_color="dark_grey",
input_color="magenta")
print(f"You entered {number}")
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_205758_input_int.gif" />
</p>
```python
# Taking y/n (yes or no)
answer = pins.input_question(prompt="Accept terms & conditions? (y/N) ", prompt_color="light_green")
if answer:
print("Good boy. You may use Windows now.")
else:
print("No? create Windows yourself then.")
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_212352_input_question.gif" />
</p>
There are other similar input functions for **floats**, **strings**, **ip addresses**, **emails**, **passwords**, **urls**, **filepaths**, and **directory paths**.
You can also use `pins.inputc()` to create your own input functions similar to the ones `pinsy` provides.
```python
name = pins.inputc("Enter your name: ",
prompt_fg="dark_grey",
input_fg="light_green",
input_attrs=["italic"])
print("Your name in %s" % name)
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_232755_inputc.gif" />
</p>
You can also take multiline input using `pins.input_multiline()`.
```python
text = pins.input_multiline(prompt="Tell me about yourself: ", input_fg="green")
print(text)
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_234448_input_multiline.gif" />
</p>
Pressing `enter` twice submits the input.
There is another input function `pins.input_menu()`, which prints a menu in the terminal and lets user choose an option with up/down arrow keys.
```python
menu = ["Login", "Signup", "Exit"]
choice = pins.input_menu(menu, bullet="■", bullet_fg="light_green",
selected_fg="green", normal_fg="dark_grey")
print("\nYou chose option %d" % choice)
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241106_000000_menu.gif" />
</p>
It returns the index of choice that was selected. _(starting from 1)_
### How to create HRs _(horizontal rules)_
Use `pins.create_hr()` to create a horizontal line, or `pins.print_hr()` to create and then print the line.
```py
line = pins.create_hr(width=50, color="yellow")
print(line)
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_164513_line.png" />
</p>
You can also use `pins.print_hr()` to just print the line, it takes the same arguments as `pins.create_hr()`.
```python
pins.print_hr(width=50, color="magenta", fill_char="▼")
pins.print_hr(width=50, color="blue", fill_char="▒")
pins.print_hr(width=50, color="green", fill_char="▲")
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_165522_lines.png" />
</p>
### How to create box around text
You can easily create a box around text using `pins.boxify().`
```python
text = "Create a box around me"
print(pins.boxify(text, width=50))
print(pins.boxify(text, width=50, x_align="center", charset="ascii", text_color="blue"))
print(pins.boxify(text, width=50, x_align="right", charset="box", border_color="red"))
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_170508_boxes.png" />
</p>
This method use the `Box` class under the hood. You can use it too.
```python
from pinsy import Box
box = Box(width=50, x_align="center", y_align="center",
charset="box_round", pad_y=1,
border_color="dark_grey", text_color="yellow")
print(box.create("Create a box\naround this\nmultiline text."))
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_171935_box.png" />
</p>
### How to create a calendar
Use `pins.get_calendar()` to get a calendar of any month of any year.
```python
print(pins.get_calendar())
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_173318_calendar.png" />
</p>
You can also use `pins.print_calendar()` to print the calendar.
```py
pins.print_calendar(month_color="red", date_color="blue")
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_173737_calendar_colored.png" />
</p>
It's November 05, 2024 today.
### How to pretty-print json
You can use `pins.print_json()` to pretty-print json.
```python
import json
with open("person.json") as jfile:
data = json.load(jfile)
pins.print_json(data)
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_175903_json.png" />
</p>
This method uses `JsonHighlight` class under the hood. and so can you!
```python
from pinsy import JsonHighlight
data = {
"name": "anas",
"age": "22",
"hobbies": "coding, programming, writing code etc."
}
jsh = JsonHighlight(quotes=False,
str_color="light_green",
number_color="light_yellow",
key_color="red",
symbol_color="dark_grey")
print(jsh.highlight(data))
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_180420_json_colored.png" />
</p>
### How to print lengthy text for user to read easily
You can use `pins.print_more()` to print a lengthy multiline text in the terminal.
```python
with open("temp.md") as md:
text = md.read()
pins.print_more(text, prompt_fg="magenta")
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_190612_more.gif" />
</p>
It let's user read the text easily.
### How to print multiline text as pages
Use `pins.print_pages()` to print a length multiline text as pages. somewhat similar to paginations in websites.
```python
with open("temp.md") as md:
text = md.read()
pins.print_pages(text, lines_per_page=16, statusbar_fg="yellow")
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_191925_pages.gif" />
</p>
### How to print info about your program
Similar to softwares and webapps, you can print info about your program/application using `pins.print_about()`.
```python
pins.print_about(name="pinsy",
version="1.0",
author="Anas Shakeel",
source_url="https://github.com/anas-shakeel/pinsy",
license="MIT",
platforms=["Windows", "Mac", "Linux"],
border_color="dark_grey",
heading_fg="dark_grey",
heading_bg="light_blue",
heading_attrs=["dark", "reverse"],
keys_color="dark_grey",
values_color="light_blue")
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_225940_about.png" />
</p>
A bit verbose i know.
### How to print text with typewriter effect
You can use the typewriter effect in two ways: using `pins.typewrite()` or using `Typewrite` class (which `pins.typewrite`() uses under the hood).
```python
# Using pins.typewrite
text = "Print this text with the typewriter effect."
pins.typewrite(text, interval=0.04, hide_cursor=False)
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_194030_typewrite.gif" />
</p>
```python
# Using Typewrite class
writer = Typewriter(0.04)
writer.write(text)
```
Output is exactly the same.
### How to print text with reveal effect
You can use the `pins.reveal_text()` or `RevealText` class to print text with reveal effect.
```python
# Using pins.reveal_text
text = "Print this text with the reveal-text effect."
pins.reveal_text(text, initial_color="black", final_color="blue")
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_200951_reveal.gif" />
</p>
```python
# Using RevealText class
revealer = RevealText(initial_color="black", final_color="blue")
revealer.reveal(text)
```
Output will be somewhat similar to previous output. "somewhat" because there is randomness added to the effect. each time it outputs a slightly different result.
This is not a True-Reveal Effect. It's just an illusion _(sort of)_. let's see this effect in slow-motion with a different `initial_color`.
```python
pins.reveal_text(text, interval=0.1, max_seconds=3, initial_color="red", final_color="blue")
```
<p align="center">
<img src="https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_202116_reveal_slowmo.gif" />
</p>
It scrambles the text and then solves each letter using bruteforce method. `max_seconds` is the number of maximum seconds to let this effect run, and prints the original text afterwards.
And there's much more that you can do...
## Pinsy CLI
#### Coming soon!
Raw data
{
"_id": null,
"home_page": "https://github.com/Anas-Shakeel/pinsy",
"name": "pinsy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "python, cli, command-line, terminal, text formatting, color output, CLI app development, CLI tools, terminal UI, beautiful CLI apps, text styling",
"author": "Anas Shakeel",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f6/ac/965c01fbd8c50e42a339d8a6df495c1947abc0c94f3d0f17844456b43870/pinsy-0.1.2.tar.gz",
"platform": null,
"description": "<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241106_012559_output.jpg\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n`pinsy` (pronounced **pin-si**) _formerly `pins`_, is a powerful lightweight python package that helps speed up the workflow of creating visually apealing command-line applications.\r\n\r\n\r\n\r\n## Table of contents\r\n\r\n\r\n\r\n- [Features](#features)\r\n\r\n- [Dependencies](#dependencies)\r\n\r\n- [Installation](#installation)\r\n\r\n- [Basic Usage](#basic-usage)\r\n\r\n - [how to color text](#how-to-color-text)\r\n\r\n - [how to color a regex match](#how-to-color-a-regex-match)\r\n\r\n - [how to print status messages](#how-to-print-status-messages)\r\n\r\n - [how to align text](#how-to-align-text)\r\n\r\n - [how to indent text](#how-to-indent-text)\r\n\r\n - [how to wrap text](#how-to-wrap-text)\r\n\r\n - [how to create lists](#how-to-create-lists)\r\n\r\n - [how to take inputs of various types](#how-to-take-inputs-of-various-types)\r\n\r\n - [how to create hrs (horizontal rules)](#how-to-create-hrs-horizontal-rules)\r\n\r\n - [how to create box around text](#how-to-create-box-around-text)\r\n\r\n - [how to create a calendar](#how-to-create-a-calendar)\r\n\r\n - [how to pretty-print json](#how-to-pretty-print-json)\r\n\r\n - [how to print lengthy text for user to read easily](#how-to-print-lengthy-text-for-user-to-read-easily)\r\n\r\n - [how to print multiline text as pages](#how-to-print-multiline-text-as-pages)\r\n\r\n - [how to print info about your program](#how-to-print-info-about-your-program)\r\n\r\n - [how to print text with typewriter effect](#how-to-print-text-with-typewriter-effect)\r\n\r\n - [how to print text with reveal effect](#how-to-print-text-with-reveal-effect)\r\n\r\n- [Pinsy CLI](#pinsy-cli)\r\n\r\n\r\n\r\n## Features\r\n\r\n\r\n\r\n- Ability to create a **box** around text\r\n\r\n- Ability to print colorful calendars\r\n\r\n- Ability **align**, **indent** and **wrap** text\r\n\r\n- Ability to create nested **ordered** and **unordered** lists\r\n\r\n- Ability to create dynamic **HRs** (_Horizontal Rules_)\r\n\r\n- Syntax Highlight for **Json**\r\n\r\n- Text effects like _typewriter_ and _reveal text_ effect.\r\n\r\n- Text coloring and styling\r\n\r\n- Supports 3 color modes (`4-bit`, `8-bit`, `24-bit`)\r\n\r\n- Prompting and validation\r\n\r\n- Basic cursor manipulation functions using `ansi sequences`\r\n\r\n- Highly optimized\r\n\r\n- And much more!\r\n\r\n- And pretty lightweight\\* too (under `160kb`)\r\n\r\n\r\n\r\n## Dependencies\r\n\r\n\r\n\r\n`pinsy` has three small dependencies.\r\n\r\n\r\n\r\n- `colorama` (_to fix windows console for color output_)\r\n\r\n- `cursor` (to show/hide cursor in terminal)\r\n\r\n- `ansy` (_which i wrote specifically for `pinsy` for color support)_\r\n\r\n\r\n\r\n## Installation\r\n\r\n\r\n\r\nOpen terminal and run below command:\r\n\r\n\r\n\r\n```python\r\n\r\npip install pinsy\r\n\r\n```\r\n\r\n\r\n\r\n## Basic Usage\r\n\r\n\r\n\r\nThere is a `class` in _pinsy_ which is the heart of it, called `Pins`. Most of the time, you'll be using this class for all sorts of stuff. Rest of the package is just built around it or to extend it.\r\n\r\n\r\n\r\n```py\r\n\r\nfrom pinsy import Pins\r\n\r\n\r\n\r\n# Create an instance of Pins and pins is ready to be used or abused.\r\n\r\npins = Pins()\r\n\r\n```\r\n\r\n\r\n\r\n### How to color text\r\n\r\n\r\n\r\nUse `pins.colorize()` method to color text using any of the three color modes.\r\n\r\n\r\n\r\n```py\r\n\r\ntext = \"Color this text\"\r\n\r\nred_text = pins.colorize(text, fgcolor=\"red\")\r\n\r\nyellow_text = pins.colorize(text, fgcolor=\"yellow\")\r\n\r\nblue_text = pins.colorize(text, fgcolor=\"blue\")\r\n\r\n\r\n\r\nprint(red_text)\r\n\r\nprint(yellow_text)\r\n\r\nprint(blue_text)\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172244_colored_text.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n### How to color a regex match\r\n\r\n\r\n\r\nYou can color only specific parts of text that match a regular expression, using `pins.colorize_regex()`.\r\n\r\n\r\n\r\n```py\r\n\r\ntext = \"Thi5 t3xt c0ntain5 a l0t 0f number5.\"\r\n\r\nhighlights = pins.colorize_regex(text, pattern=\"\\d\", fgcolor=\"red\")\r\n\r\nprint(highlights)\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172238_highlights.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n`pattern` can also be a `re` compiled pattern.\r\n\r\n\r\n\r\n```py\r\n\r\npattern = re.compile(r\"\\d\")\r\n\r\npins.colorize_regex(text, pattern=pattern, fgcolor=\"red\")\r\n\r\n```\r\n\r\n\r\n\r\n### How to print status messages\r\n\r\n\r\n\r\nStatus messages include **info**, **warning**, **success**, and **error** messages. There are four built-in methods for printing these messages.\r\n\r\n\r\n\r\n```py\r\n\r\npins.print_info(\"This is an info message.\")\r\n\r\npins.print_warning(\"This is a warning message.\")\r\n\r\npins.print_success(\"This is a success message.\")\r\n\r\npins.print_error(\"This is an error message.\")\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172215_status_messages.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nColors are set by default for these built-in messages. But you can also create custom status messages for more control, using `pins.create_status()`.\r\n\r\n\r\n\r\n```py\r\n\r\nmessage = \"This is a hint message\"\r\n\r\nhint = pins.create_status(\"Hint\", message, label_fg=\"green\", text_fg=\"blue\")\r\n\r\nprint(hint)\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172159_hint.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n### How to align text\r\n\r\n\r\n\r\nYou can easily align text in the terminal using `pins.textalign_x()` (_for horizontal alignment_) or `pins.textalign_y` (_for vertical alignment_).\r\n\r\n\r\n\r\n```py\r\n\r\n# Horizontal Alignment\r\n\r\ntext = \"Align this text\"\r\n\r\nprint(pins.textalign_x(text, align=\"left\"))\r\n\r\nprint(pins.textalign_x(text, align=\"center\"))\r\n\r\nprint(pins.textalign_x(text, align=\"right\"))\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172028_align_x.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n### How to indent text\r\n\r\n\r\n\r\nUse `pins.indent_text()` to indent text, **Duh!**\r\n\r\n\r\n\r\n```py\r\n\r\ntext = \"Indent this 4 spaces\"\r\n\r\nprint(\"|\", pins.indent_text(text, indent=4))\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172019_indent.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n### How to wrap text\r\n\r\n\r\n\r\nYou can wrap text using `pins.wrap_text()`. This method is merely a wrapper around the `fill()` method from `textwrap` module.\r\n\r\n\r\n\r\n```py\r\n\r\ntext = \"Wrap this text if it exceeds 15 characters.\"\r\n\r\nprint(pins.wrap_text(text, 15))\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172013_wrap.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n### How to create lists\r\n\r\n\r\n\r\nThere are two types of lists that you can create, **ordered** and **unordered**, using `pins.create_list_ordered()` and `pins.create_list_unordered()` respectively.\r\n\r\n\r\n\r\n```py\r\n\r\n# Ordered List\r\n\r\nitems = [\"Assembly\", \"C\", \"Python\", [\"CPython\", \"PyPy\"], \"Javascript\"]\r\n\r\nordered_list = pins.create_list_ordered(items, num_color=\"green\", item_color=\"blue\")\r\n\r\nprint(ordered_list)\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_172003_ordered.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n```py\r\n\r\n# Unordered List\r\n\r\nitems = [\"Assembly\", \"C\", \"Python\", [\"CPython\", \"PyPy\"], \"Javascript\"]\r\n\r\nunordered_list = pins.create_list_unordered(items, bullet_color=\"green\", item_color=\"blue\")\r\n\r\nprint(unordered_list)\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_171953_unordered.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nYou can further tweak these lists using other arguments of both of these methods.\r\n\r\n\r\n\r\n### How to take inputs of various types\r\n\r\n\r\n\r\nThere are 13 input methods that can be used take all sorts of inputs from users. almost all of them support colors.\r\n\r\n\r\n\r\n```python\r\n\r\n# Taking integer input\r\n\r\nnumber = pins.input_int(prompt=\"Enter a number: \",\r\n\r\n prompt_color=\"dark_grey\",\r\n\r\n input_color=\"magenta\")\r\n\r\nprint(f\"You entered {number}\")\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_205758_input_int.gif\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n```python\r\n\r\n# Taking y/n (yes or no)\r\n\r\nanswer = pins.input_question(prompt=\"Accept terms & conditions? (y/N) \", prompt_color=\"light_green\")\r\n\r\nif answer:\r\n\r\n print(\"Good boy. You may use Windows now.\")\r\n\r\nelse:\r\n\r\n print(\"No? create Windows yourself then.\")\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_212352_input_question.gif\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nThere are other similar input functions for **floats**, **strings**, **ip addresses**, **emails**, **passwords**, **urls**, **filepaths**, and **directory paths**.\r\n\r\n\r\n\r\nYou can also use `pins.inputc()` to create your own input functions similar to the ones `pinsy` provides.\r\n\r\n\r\n\r\n```python\r\n\r\nname = pins.inputc(\"Enter your name: \",\r\n\r\n prompt_fg=\"dark_grey\",\r\n\r\n input_fg=\"light_green\",\r\n\r\n input_attrs=[\"italic\"])\r\n\r\nprint(\"Your name in %s\" % name)\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_232755_inputc.gif\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nYou can also take multiline input using `pins.input_multiline()`.\r\n\r\n\r\n\r\n```python\r\n\r\ntext = pins.input_multiline(prompt=\"Tell me about yourself: \", input_fg=\"green\")\r\n\r\nprint(text)\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_234448_input_multiline.gif\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nPressing `enter` twice submits the input.\r\n\r\n\r\n\r\nThere is another input function `pins.input_menu()`, which prints a menu in the terminal and lets user choose an option with up/down arrow keys.\r\n\r\n\r\n\r\n```python\r\n\r\nmenu = [\"Login\", \"Signup\", \"Exit\"]\r\n\r\nchoice = pins.input_menu(menu, bullet=\"\u25a0\", bullet_fg=\"light_green\",\r\n\r\n selected_fg=\"green\", normal_fg=\"dark_grey\")\r\n\r\n\r\n\r\nprint(\"\\nYou chose option %d\" % choice)\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241106_000000_menu.gif\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nIt returns the index of choice that was selected. _(starting from 1)_\r\n\r\n\r\n\r\n### How to create HRs _(horizontal rules)_\r\n\r\n\r\n\r\nUse `pins.create_hr()` to create a horizontal line, or `pins.print_hr()` to create and then print the line.\r\n\r\n\r\n\r\n```py\r\n\r\nline = pins.create_hr(width=50, color=\"yellow\")\r\n\r\nprint(line)\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_164513_line.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nYou can also use `pins.print_hr()` to just print the line, it takes the same arguments as `pins.create_hr()`.\r\n\r\n\r\n\r\n```python\r\n\r\npins.print_hr(width=50, color=\"magenta\", fill_char=\"\u25bc\")\r\n\r\npins.print_hr(width=50, color=\"blue\", fill_char=\"\u2592\")\r\n\r\npins.print_hr(width=50, color=\"green\", fill_char=\"\u25b2\")\r\n\r\n\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_165522_lines.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n### How to create box around text\r\n\r\n\r\n\r\nYou can easily create a box around text using `pins.boxify().`\r\n\r\n\r\n\r\n```python\r\n\r\ntext = \"Create a box around me\"\r\n\r\nprint(pins.boxify(text, width=50))\r\n\r\nprint(pins.boxify(text, width=50, x_align=\"center\", charset=\"ascii\", text_color=\"blue\"))\r\n\r\nprint(pins.boxify(text, width=50, x_align=\"right\", charset=\"box\", border_color=\"red\"))\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_170508_boxes.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nThis method use the `Box` class under the hood. You can use it too.\r\n\r\n\r\n\r\n```python\r\n\r\nfrom pinsy import Box\r\n\r\n\r\n\r\nbox = Box(width=50, x_align=\"center\", y_align=\"center\",\r\n\r\n charset=\"box_round\", pad_y=1,\r\n\r\n border_color=\"dark_grey\", text_color=\"yellow\")\r\n\r\n\r\n\r\nprint(box.create(\"Create a box\\naround this\\nmultiline text.\"))\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_171935_box.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n### How to create a calendar\r\n\r\n\r\n\r\nUse `pins.get_calendar()` to get a calendar of any month of any year.\r\n\r\n\r\n\r\n```python\r\n\r\nprint(pins.get_calendar())\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_173318_calendar.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nYou can also use `pins.print_calendar()` to print the calendar.\r\n\r\n\r\n\r\n```py\r\n\r\npins.print_calendar(month_color=\"red\", date_color=\"blue\")\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_173737_calendar_colored.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nIt's November 05, 2024 today.\r\n\r\n\r\n\r\n### How to pretty-print json\r\n\r\n\r\n\r\nYou can use `pins.print_json()` to pretty-print json.\r\n\r\n\r\n\r\n```python\r\n\r\nimport json\r\n\r\n\r\n\r\nwith open(\"person.json\") as jfile:\r\n\r\n data = json.load(jfile)\r\n\r\n\r\n\r\npins.print_json(data)\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_175903_json.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nThis method uses `JsonHighlight` class under the hood. and so can you!\r\n\r\n\r\n\r\n```python\r\n\r\nfrom pinsy import JsonHighlight\r\n\r\n\r\n\r\ndata = {\r\n\r\n \"name\": \"anas\",\r\n\r\n \"age\": \"22\",\r\n\r\n \"hobbies\": \"coding, programming, writing code etc.\"\r\n\r\n}\r\n\r\n\r\n\r\njsh = JsonHighlight(quotes=False,\r\n\r\n str_color=\"light_green\",\r\n\r\n number_color=\"light_yellow\",\r\n\r\n key_color=\"red\",\r\n\r\n symbol_color=\"dark_grey\")\r\n\r\n\r\n\r\nprint(jsh.highlight(data))\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_180420_json_colored.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n### How to print lengthy text for user to read easily\r\n\r\n\r\n\r\nYou can use `pins.print_more()` to print a lengthy multiline text in the terminal.\r\n\r\n\r\n\r\n```python\r\n\r\nwith open(\"temp.md\") as md:\r\n\r\n text = md.read()\r\n\r\n\r\n\r\npins.print_more(text, prompt_fg=\"magenta\")\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_190612_more.gif\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nIt let's user read the text easily.\r\n\r\n\r\n\r\n### How to print multiline text as pages\r\n\r\n\r\n\r\nUse `pins.print_pages()` to print a length multiline text as pages. somewhat similar to paginations in websites.\r\n\r\n\r\n\r\n```python\r\n\r\nwith open(\"temp.md\") as md:\r\n\r\n text = md.read()\r\n\r\n\r\n\r\npins.print_pages(text, lines_per_page=16, statusbar_fg=\"yellow\")\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_191925_pages.gif\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n### How to print info about your program\r\n\r\n\r\n\r\nSimilar to softwares and webapps, you can print info about your program/application using `pins.print_about()`.\r\n\r\n\r\n\r\n```python\r\n\r\npins.print_about(name=\"pinsy\",\r\n\r\n version=\"1.0\",\r\n\r\n author=\"Anas Shakeel\",\r\n\r\n source_url=\"https://github.com/anas-shakeel/pinsy\",\r\n\r\n license=\"MIT\",\r\n\r\n platforms=[\"Windows\", \"Mac\", \"Linux\"],\r\n\r\n border_color=\"dark_grey\",\r\n\r\n heading_fg=\"dark_grey\",\r\n\r\n heading_bg=\"light_blue\",\r\n\r\n heading_attrs=[\"dark\", \"reverse\"],\r\n\r\n keys_color=\"dark_grey\",\r\n\r\n values_color=\"light_blue\")\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_225940_about.png\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nA bit verbose i know.\r\n\r\n\r\n\r\n### How to print text with typewriter effect\r\n\r\n\r\n\r\nYou can use the typewriter effect in two ways: using `pins.typewrite()` or using `Typewrite` class (which `pins.typewrite`() uses under the hood).\r\n\r\n\r\n\r\n```python\r\n\r\n# Using pins.typewrite\r\n\r\ntext = \"Print this text with the typewriter effect.\"\r\n\r\npins.typewrite(text, interval=0.04, hide_cursor=False)\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_194030_typewrite.gif\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n```python\r\n\r\n# Using Typewrite class\r\n\r\nwriter = Typewriter(0.04)\r\n\r\nwriter.write(text)\r\n\r\n```\r\n\r\n\r\n\r\nOutput is exactly the same.\r\n\r\n\r\n\r\n### How to print text with reveal effect\r\n\r\n\r\n\r\nYou can use the `pins.reveal_text()` or `RevealText` class to print text with reveal effect.\r\n\r\n\r\n\r\n```python\r\n\r\n# Using pins.reveal_text\r\n\r\ntext = \"Print this text with the reveal-text effect.\"\r\n\r\npins.reveal_text(text, initial_color=\"black\", final_color=\"blue\")\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_200951_reveal.gif\" />\r\n\r\n</p>\r\n\r\n\r\n\r\n```python\r\n\r\n# Using RevealText class\r\n\r\nrevealer = RevealText(initial_color=\"black\", final_color=\"blue\")\r\n\r\nrevealer.reveal(text)\r\n\r\n```\r\n\r\n\r\n\r\nOutput will be somewhat similar to previous output. \"somewhat\" because there is randomness added to the effect. each time it outputs a slightly different result.\r\n\r\n\r\n\r\nThis is not a True-Reveal Effect. It's just an illusion _(sort of)_. let's see this effect in slow-motion with a different `initial_color`.\r\n\r\n\r\n\r\n```python\r\n\r\npins.reveal_text(text, interval=0.1, max_seconds=3, initial_color=\"red\", final_color=\"blue\")\r\n\r\n```\r\n\r\n\r\n\r\n<p align=\"center\">\r\n\r\n <img src=\"https://raw.githubusercontent.com/Anas-Shakeel/pinsy/main/assets/20241105_202116_reveal_slowmo.gif\" />\r\n\r\n</p>\r\n\r\n\r\n\r\nIt scrambles the text and then solves each letter using bruteforce method. `max_seconds` is the number of maximum seconds to let this effect run, and prints the original text afterwards.\r\n\r\n\r\n\r\nAnd there's much more that you can do...\r\n\r\n\r\n\r\n## Pinsy CLI\r\n\r\n\r\n\r\n#### Coming soon!\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package to help speed up the workflow of creating beautiful CLI apps.",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/Anas-Shakeel/pinsy"
},
"split_keywords": [
"python",
" cli",
" command-line",
" terminal",
" text formatting",
" color output",
" cli app development",
" cli tools",
" terminal ui",
" beautiful cli apps",
" text styling"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7d2d7727a179968fec42518386763f78ef1573e18e0a32907941bfff75ef8240",
"md5": "1ea0de3b2520e079b55507b96914dcac",
"sha256": "170311c1ebe4a4808c9756a606ceb187bb2772ab58ad34c4dc0aff3f419de08d"
},
"downloads": -1,
"filename": "pinsy-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1ea0de3b2520e079b55507b96914dcac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 41837,
"upload_time": "2024-11-16T21:33:12",
"upload_time_iso_8601": "2024-11-16T21:33:12.341009Z",
"url": "https://files.pythonhosted.org/packages/7d/2d/7727a179968fec42518386763f78ef1573e18e0a32907941bfff75ef8240/pinsy-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f6ac965c01fbd8c50e42a339d8a6df495c1947abc0c94f3d0f17844456b43870",
"md5": "f10b0d60574c6398510404f9ee2deb94",
"sha256": "fc18f2eb95a7279e2877942c1217ba138256788da102481ec8e35edda449d70d"
},
"downloads": -1,
"filename": "pinsy-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "f10b0d60574c6398510404f9ee2deb94",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 46710,
"upload_time": "2024-11-16T21:33:14",
"upload_time_iso_8601": "2024-11-16T21:33:14.498675Z",
"url": "https://files.pythonhosted.org/packages/f6/ac/965c01fbd8c50e42a339d8a6df495c1947abc0c94f3d0f17844456b43870/pinsy-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-16 21:33:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Anas-Shakeel",
"github_project": "pinsy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pinsy"
}
JSON
