borders 1.1.2

A module to create a frame when printing a list of strings, with control on the alignment of the text and frame. In addition can be configured to act as 'input()'.

Borders

Description

Borders 1.1.2 is an updated version ofborders. It enhances the functionality of creating frames around text output, adding new features and improving existing ones. Borders creates a frame around the content of a list, where any item of the list is considered a new line.

Features

• Colour Support: Expanded colour options now accept ANSI colour codes 0, 30 to 37, and 90 to 97 for setting text and frame colours.
• Input Functionality: Provides an option to use the frame() function in place of input() to create a framed prompt for user input.

New Features

• Enhanced Spacing Control: Added alignment control for the frame and the text within the frame.
• Improved Width Customization: Better control over minimum and maximum width of the frame and text lines.

Table of Contents

• Getting Started
  • Prerequisites
  • Installation
• Usage
  • Parameters
  • Examples
    • Default settings
    • Text and Frame Colours
    • Tuples
    • Alignment
    • Display
    • Spacing
    • Minimum Width
    • Maximum Width
    • Input
• Contributing
• License

Getting Started

Prerequisites

This script relies on the Python standard library and requires textlinebreaker library

Installation

• Install the package

    pip install borders

• or upgrade it to the latest version

    pip install --upgrade borders

• Import the package in your program

  from borders import frame

Usage

Add the following line in your code to import the module

from borders import frame

Simply use the function frame() instead of print() to print a frame around your output.
Alternatively set the parameter window = "input" to use frame() in place of input().

The text to be printed can be a mixed list of:

• strings
• tuples containing a string with the text to print and at least one of the following parameters:
  • Optional value (integers or strings) for the colour of the text
  • Optional value (integers or strings) for the background colour of the text
  • Optional value (string) for the alignment of the line

Parameters

colour: set the text colour.
$\hspace{1cm}$ allowed values: ANSI colour codes 0, 30 to 37, and 90 to 97
$\hspace{1cm}$ default value = 37.
text_background: set the background colour of the text.
$\hspace{1cm}$ allowed values: ANSI colour codes 0, 40 to 47, and 100 to 107
$\hspace{1cm}$ default value = 0.
frame_colour: set the frame colour.
$\hspace{1cm}$ allowed values: ANSI colour codes 0, 30 to 37, and 90 to 97
$\hspace{1cm}$ default value = 37.
frame_background: set the background colour of the frame.
$\hspace{1cm}$ allowed values: ANSI colour codes 0, 40 to 47, and 100 to 107
$\hspace{1cm}$ default value = 0.
alignment: set the alignment of the text inside the frame.
$\hspace{1cm}$ allowed values: 'left', 'centre', 'center', 'right'
$\hspace{1cm}$ default value = 'left'
display: set the position of the frame inside the terminal.
$\hspace{1cm}$ allowed values: 'left', 'centre', 'center', 'right'
$\hspace{1cm}$ default value = 'left'
spacing: set the space between the frame and the text.
$\hspace{1cm}$ allowed values: from 0 to 3
$\hspace{1cm}$ default value = 1
min_width: set the min length of text in a line.
$\hspace{1cm}$ allowed values: integers above 8, 'max'(this value assign to the frame the width of the terminal)
$\hspace{1cm}$ default value = 42
max_width: set the max length of text in a line.
$\hspace{1cm}$ allowed values: integers above 8, 'max'(this value assign to the frame the width of the terminal)
$\hspace{1cm}$ default value = 70
window: Set the behaviour of the function, to output or input.
$\hspace{1cm}$ allowed values: 'print', 'input'
$\hspace{1cm}$ default value = 'print'

Examples

Here are some examples of how to use the frame() function with different parameters.

Default settings

Simply using frame() will print a frame around a given output.

from borders import frame

# Example 1: Default settings
output = ["Hello,", "World!"]
frame(output)

Output 1

Text and Frame Colours

We can set a colour for the text (e.g. 34 for Blue) and one for the frame (e.g. 31 for Red)

from borders import frame

# Example 2: Setting text and frame colours
output = ["Hello,", "World!"]
frame(output, colour="34", frame_colour="31")

Output 2

Tuples

Using a tuple we can set different colours for each line, let's try setting blue, and red as general colours for the text and the frame.
Then let's set one line with yellow text, one with green, and highlight one in white.

from borders import frame

# Example 3: Using tuple to set different colours for each line
output = [
    "Hello,",
    "World!",
    ("This line is yellow", 33),
    ("This line is green", 32),
    ("This line is highlighted in white", "", 47),
    "This line is back to the general colour"
]
frame(output, colour="34", frame_colour="31")

Output 3

Alignment

The parameteralignmentallows you to change the alignment of the text inside the frame.
Withalignment="right"will allign the text to the right of the frame.

from borders import frame

# Example 4: Setting lines width equal to 60,
# the general alignment of the text to the right,
# and the alignment of the second line to the left
output = ["There are only 10 kinds of people in this world:", ("Those who know binary and Those who don't.","left"), "Anonymous"]
frame(output, min_width=60, alignment="right")

Output 4

Display

The parameterdisplay allows you to change the position of the frame inside the terminal.

from borders import frame

# Example 5: Setting the position of the frame in the centre of the terminal
# and the alignment of the text to the right 
output = ["There are only 10 kinds of people in this world:", "Those who know binary and Those who don't.", "Anonymous"]
frame(output, alignment="right", display="centre")

Output 5

Spacing

Specifying different values for the parameterspacing, you can increase or decrease the space between text and frame.

spacing=2

Withspacing=2it will leave 2 blank lines at the top and the bottom, and 8 blank spaces before and after the text.

from borders import frame  

# Example 6: Setting the spacing between the text and the frame equal to 2
output = ["Hello,", "World!"]
frame(output, spacing=2)

Output 6

Spacing = 0

Withspacing=0it will create the frame around the text with no spaces.

from borders import frame  

# Example 7: Setting the spacing between the text and the frame equal to 0
output = ["Hello,", "World!"]
frame(output, spacing=0)

Output 7

Minimum Width

The parameter min_width set the minimum width inside the frame.
Withmin_width=30the output frame will have a wider space on the left.

from borders import frame  

# Example 8:
output = ["Hello,", "World!"]
frame(output, min_width=30)

Output 8

Maximum Width

The parameter max_width set the max length of text on a line.
Let's see what happens to the following string: "There are only 10 kinds of people in this world: Those who know binary and Those who don’t."

max_width=100

from borders import frame  

# Example 9:
output = ["There are only 10 kinds of people in this world: Those who know binary and Those who don't."]
frame(output, max_width=100)

Output 9

max_width=50

from borders import frame  

# Example 10:
output = ["There are only 10 kinds of people in this world: Those who know binary and Those who don't."]
frame(output, max_width=50)

Output 10

max_width=25

from borders import frame

# Example 11:
output = ["There are only 10 kinds of people in this world: Those who know binary and Those who don't."]
frame(output, max_width=25)

Output 11

Input

You can use the function frame() in place of input() to create a frame around the prompt and get the input from the user.

from borders import frame

# Example 12: Using frame() in place of input()
num1 = int(frame(["Please,", "enter a number"], window="input"))
num2 = num1 * 2
output = [f"The double of {num1}",f"is {num2}"]
frame(output)

Output 12

Contributing

If you'd like to contribute to this project, please follow these steps:

1. Fork the repository on GitHub.
2. Clone the fork to your local machine.
3. Create a new branch for your feature or bug fix.
4. Make your changes and commit them.
5. Push the changes to your fork on GitHub.
6. Create a pull request to the original repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.