new-print-function 2.0.0
A Python library that extends the functionality of the built-in print function.
Requires Python: >=3.0
Keywords: new print function, color print, pretty print, ansi

# New Print Function

A Python library that extends the functionality of the built-in print function.

This library allows Python programmers to style terminal output by applying foreground color, background color, and font styles directly as arguments to the `print` function. The library supports [**140+ color names**](#color-names), [**all rgb colors**](#rgb-colors), [**all hex colors**](#hex-colors), and [**6 different font styles**](#supported-font-styles).

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
- [Features](#features)
- [Licence](#license)
- [Release History](#release-history)

## Installation

Install via pip:

```bash
pip install new-print-function
```

## Usage

The library consists of two main functions:

1. ### print

    An extension of the built-in `print` function.

    #### Function Signature
    ```python
    def print(*values, sep=' ', end='\n', file=None, flush=False, fg=None, bg=None, fs=None): ...
    ```
    - `values`: The objects to be printed.
    - `sep`: String inserted between values.
    - `end`: String appended after the last value.
    - `file`: A file-like object (stream); defaults to the current sys.stdout.
    - `fg`: Foreground color for the text.
    - `bg`: Background color for the text.
    - `fs`: Font style for the text.

    #### Example Usage

    ##### Method 1 (Recommended)

    ```python
    import new_print_function as npf

    npf.print("Hello, world!", fg="red", bg="white", fs="bold")
    ```

    ##### Method 2 (Redefines Built-in `print`)

    ```python
    from new_print_function import print

    print("Hello, world!", fg="red", bg="white", fs="bold")
    ```
2. ### style

    Styles text and returns the text with specified styles.

    #### Function Signature

    ```python
    def style(text, fg=None, bg=None, fs=None, terminate=True): ...
    ```
    - `text`: The text to be styled.
    - `fg`: Foreground color for the text.
    - `bg`: Background color for the text.
    - `fs`: Font style for the text.
    - `terminate`: Whether to end styling after the `text`. Otherwise, any plain text **printed** after the `text` will inherit its styles (`fg`, `bg`, and/or `fs`).

    #### Example Usage

    ```python
    import new_print_function as npf

    styled_text = npf.style("Hello, world!", fg="red", bg="white", fs="bold")  # stores text with styles.
    ```

## Features

### Supported Colors

Three forms of color are supported:

1. #### Rgb Colors
    **All rgb colors** are supported. Rgb values should be separated by commas e.g., `128,0,128`.

2. #### Hex Colors
    **All hex colors** are supported. Hex colors should be prefixed by a `#` sign e.g., `#00ffff`

3. #### Color Names
    **140+ color names** are supported. These include all valid **HTML color names** and more. These are categorized below:

    - **A**: `aqua`, `aquamarine`, `azure`, `alice-blue`, `antique-white`

    - **B**: `blue`, `blanched-almond`, `bisque`, `burly-wood`, `brown`, `black`, `blue-violet`, `beige`

    - **C**: `cyan`, `cadet-blue`, `cornflower-blue`, `cornsilk`, `chocolate`, `chartreuse`, `coral`, `crimson`

    - **D**: `dark-turquoise`, `deep-sky-blue`, `dodger-blue`, `dark-blue`, `dark-goldenrod`, `dark-green`, `dark-olive-green`, `dark-sea-green`, `dark-cyan`, `dark-grey`, `dim-grey`, `dark-slate-grey`, `dark-orange`, `deep-pink`, `dark-violet`, `dark-orchid`, `dark-magenta`, `dark-slate-blue`, `dark-salmon`, `dark-red`, `dark-khaki`

    - **F**: `forest-green`, `fuchsia`, `fire-brick`, `floral-white`

    - **G**: `goldenrod`, `green-yellow`, `green`, `gainsboro`, `grey`, `gray`, `ghost-white`, `gold`

    - **H**: `hot-pink`, `honeydew`

    - **I**: `indigo`, `indian-red`, `ivory`

    - **K**: `khaki`

    - **L**: `light-cyan`, `light-steel-blue`, `light-blue`, `light-sky-blue`, `lawn-green`, `lime`, `lime-green`, `light-green`, `light-sea-green`, `light-grey`, `light-slate-grey`, `light-salmon`, `light-pink`, `lavender`, `light-coral`, `linen`, `lavender-blush`, `light-yellow`, `lemon-chiffon`, `light-goldenrod-yellow`

    - **M**: `medium-turquoise`, `medium-slate-blue`, `medium-blue`, `midnight-blue`, `maroon`, `medium-spring-green`, `medium-sea-green`, `medium-aquamarine`, `medium-violet-red`, `magenta`, `medium-orchid`, `medium-purple`, `mint-cream`, `misty-rose`, `moccasin`

    - **N**: `navy`, `navajo-white`

    - **O**: `olive-drab`, `olive`, `orange-red`, `orange`, `orchid`, `old-lace`

    - **P**: `pale-turquoise`, `powder-blue`, `peru`, `pale-green`, `pink`, `pale-violet-red`, `plum`, `purple`, `papaya-whip`, `peach-puff`, `pale-goldenrod`

    - **R**: `royal-blue`, `rosy-brown`, `rebecca-purple`, `red`

    - **S**: `steel-blue`, `sky-blue`, `sandy-brown`, `saddle-brown`, `sienna`, `spring-green`, `sea-green`, `silver`, `slate-grey`, `slate-blue`, `salmon`, `snow`, `seashell`

    - **T**: `turquoise`, `tan`, `teal`, `tomato`, `thistle`

    - **V**: `violet`

    - **W**: `wheat`, `white`, `white-smoke`

    - **Y**: `yellow-green`, `yellow`

    **Note**: Both `grey` and `gray` are supported spellings for the color.

### Supported Font Styles

**6 font styles** are supported. These are:

- `bold`
- `italic`
- `underline`
- `double-underline`
- `overline`
- `strikethrough`

## License

The MIT License

Copyright (c) 2025 Haripo Wesley T. ([Email](mailto:haripowesleyt@proton.me)) ([GitHub](https://github.com/haripowesleyt))

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

1. The above copyright notice and this permission notice shall be included in all
   copies or substantial portions of the Software.

2. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
   SOFTWARE.

## Release History

### v1.0.0 - 2025-01-03
- Initial public release.
- Implemented core features.

### v2.0.0 - 2025-02-12
- Same principles to **v1.0.0**, but better implementation, design, and overall structure.
- Replaced the `format` function with a more efficient function called `style`.
- Removed some **not-really-font-styles** "font styles": `dim`, `blink`, `inverse`, `hidden`, and `frame`.
- Added **support for rgb and hex colors**.
- Added the ability to **specify multiple font styles**.
- Fixed a bug where a new line character, `\n`, would leak styling to whole new line regardless of content.
- Better source code documentation through docstings and comments.