savioxavier / pyboxen

Incredibly customizable terminal boxes for Python

pyboxen

Create beautiful boxes in the terminal using Python

This package is a Python "port" of the popular NPM package boxen.

It's built on top of Rich, and features an API that would be familiar to the users of the NPM boxen package.

🛠️ Install

Using pip

pip install pyboxen

---

🔗 Usage

• Simplest of simple boxes

from pyboxen import boxen

print(boxen("Python is cool!"))

• Define options

from pyboxen import boxen

print(
    boxen(
        "Python is cool!",
        padding=1,
        margin=1,
        color="cyan",
    )
)

• Multiple texts and Rich Renderables

You can even use Rich's special color style syntax for the text, title and subtitle as well

Example: [red]Hello[/red] [bold italic]World[/]

from pyboxen import boxen

# Multiple texts

print(
    boxen(
        "Python is cool!",
        "Yeah it totally is!",
        "I [red]:heart:[/red]  [yellow bold]Python[/]!",  # You can even use Rich syntax here too!
        padding=1,
        margin=1,
        color="cyan",
    )
)

# Rich renderables, with a mix of strings and renderables

from rich.table import Table

table = Table(show_header=True, header_style="bold magenta")

table.add_column("Date", style="dim", width=12)
table.add_column("Title")
table.add_column("Production Budget", justify="right")
table.add_column("Box Office", justify="right")
table.add_row(
    "Dec 20, 2019", "Star Wars: The Rise of Skywalker", "$275,000,000", "$375,126,118"
)
table.add_row(
    "May 25, 2018",
    "[red]Solo[/red]: A Star Wars Story",
    "$275,000,000",
    "$393,151,347",
)
table.add_row(
    "Dec 15, 2017",
    "Star Wars Ep. VIII: The Last Jedi",
    "$262,000,000",
    "[bold]$1,332,539,889[/bold]",
)

print(
    boxen(
        "Python is cool!",
        table
    )
)

• Title and subtitles

from pyboxen import boxen

print(
    boxen(
        "Titles and subtitles!",
        title="Hello, [black on cyan] World [/]",
        subtitle="Cool subtitle goes here",
        subtitle_alignment="center",
        color="yellow",
        padding=1,
    )
)

---

🔮 API

boxen(*text, **kwargs)

text

A variable (infinite) amount of text strings or Rich Renderables, or a mix of both.

kwargs

Customize options for the box

Available options include:

color: str = "white",
style: Literal["ascii", "ascii2", "ascii_double_head", "square", "square_double_head", "minimal", "horizontals", "rounded", "heavy", "double"] = "rounded"
padding: Union[int, tuple[int]] = 0,
margin: Union[int, tuple[int]] = 0,
text_alignment: Literal["left", "center", "right"] = "center",
box_alignment: Literal["left", "center", "right"] = "left",
title: str = None,
title_alignment: Literal["left", "center", "right"] = "left",
subtitle: str = None,
subtitle_alignment: Literal["left", "center", "right"] = "left",
fullwidth: bool = False,

color

The color of the box in color or hex code starting with #, defaults to white

style

The style of the box, defaults to rounded

padding

The padding between the text and the box in int or tuple of ints, defaults to 0

margin

The margin around the box in int or tuple of ints, defaults to 0

text_alignment

The alignment of the text inside the box, defaults to center

box_alignment

The alignment of the box in the terminal, defaults to left

title

The title of the box, displayed on the top of the box, if provided

title_alignment

The alignment of the title, defaults to left

subtitle

The subtitle of the box, displayed on the bottom of the box, if provided

subtitle_alignment

The alignment of the subtitle, defaults to left

fullwidth

If True, the box will expand to fill the entire terminal width, defaults to False

Note padding and margin attributes can be either an int, a tuple of ints (with a total of either 2 elements or 4 elements) Example:

2 - all of top, right, bottom, left

(2, 4) - (top = bottom, right = left)

(2, 4, 6, 8) - (top, right, bottom, left)

---

❤️ Support

You can support further development of this project by giving it a 🌟 and help me make even better stuff in the future by buying me a ☕

Also, if you liked this repo, consider checking out my other projects, that would be real cool!

---

💫 Attributions and special thanks

• boxen - the NPM package I was inspired from
• rich - for making such an incredibly powerful text customization tool

pyboxen's Issues

Requires Python >=3.10

Not an "issue" but a question. I see that pyboxen requires Python >=3.10. I'm not quite ready to update some of my code to 3.10, and I'm just wondering if this is a requirement for a reason or if pyboxen would work with, say, Python 3.9? If not, I'll just have to wait until I'm ready to upgrade everything :) Thanks!

Does not support Python 3.8

Hallo,

Dispite the claim made in pyproject,.toml to support Python 3.8, this "Incredibly customizable terminal boxes for Python" does not work with Python 3.8. Obviously.

The problem begins when importing the library:

    ALL_BOXES: dict[str, Box] = {
TypeError: 'type' object is not subscriptable

Reason: the syntax dict[str, Box], intead of Dict[str, Box] first appeared in Python 3.9. Please check here: https://www.python.org/downloads/release/python-390/ (mention of https://peps.python.org/pep-0585/)

To make this library usable with Python 3.8, it is sufficient to replace some type annotations

dict[...] --> Dict[...]
tuple[...] --> Tuple[...]

and extend import statement correspondingly

from typing import Dict, Tuple