Metadata-Version: 2.4
Name: vanta
Version: 0.3.1
Summary: A lightweight Python toolkit for beautiful, structured CLI output.
Author: zscopuv
License: VANTA SOURCE-AVAILABLE LICENSE
        Version 1.0
        
        Copyright © 2026 radecekq
        All rights reserved.
        
        1. DEFINITIONS
        
        For the purposes of this License:
        
        "Software" means the Vanta software, including its source code, documentation,
        configuration files, assets, and any other materials distributed with the
        Software.
        
        "Original Software" means the Software as distributed by the Copyright Holder.
        
        "Modified Version" means any version of the Software that has been altered,
        adapted, translated, extended, refactored, or otherwise changed from the
        Original Software.
        
        "Copyright Holder" means the individual or entity that owns the copyright in
        the Software.
        
        "User" means any individual or organization obtaining access to the Software.
        
        "Redistribution" means providing, publishing, transmitting, selling,
        licensing, sublicensing, uploading, mirroring, or otherwise making the
        Software or a Modified Version available to any third party.
        
        
        2. GRANT OF RIGHTS
        
        Subject to the terms and conditions of this License, the Copyright Holder
        grants the User a limited, non-exclusive, non-transferable, revocable license
        to:
        
            a. access and inspect the source code of the Software;
        
            b. copy the Software for personal use and development;
        
            c. create private forks of the Software;
        
            d. modify, adapt, extend, or otherwise alter the Software;
        
            e. compile and execute the Software and Modified Versions for personal
               use; and
        
            f. use the Software and Modified Versions for non-commercial purposes.
        
        These permissions do not constitute a transfer of ownership or copyright.
        
        
        3. REDISTRIBUTION PROHIBITED
        
        The User may not, without prior written permission from the Copyright Holder:
        
            a. redistribute the Original Software;
        
            b. redistribute any Modified Version;
        
            c. publish a fork of the Software;
        
            d. publish source code derived from the Software;
        
            e. distribute compiled binaries or executable versions of the Software
               or a Modified Version;
        
            f. upload the Software or a Modified Version to another repository,
               package registry, download service, file-sharing service, or similar
               distribution platform;
        
            g. sell, sublicense, rent, lease, or otherwise transfer the Software or
               a Modified Version to another person or organization; or
        
            h. make the Software or a Modified Version publicly available through
               any medium.
        
        
        4. PRIVATE FORKS
        
        The User may create and maintain private forks of the Software for personal
        development, experimentation, testing, education, or other lawful purposes.
        
        A private fork must not be made available to third parties without the
        express written permission of the Copyright Holder.
        
        Nothing in this section grants permission to publish or redistribute a fork.
        
        
        5. MODIFICATIONS
        
        The User is expressly permitted to modify the Software for private use.
        
        Modifications may include, but are not limited to:
        
            - adding or removing functionality;
            - changing the user interface;
            - changing configuration;
            - fixing bugs;
            - refactoring code;
            - creating experimental features; and
            - adapting the Software for personal environments.
        
        However, the creation of a Modified Version does not grant the User any
        additional right to redistribute that Modified Version.
        
        
        6. COPYRIGHT AND OWNERSHIP
        
        The Software remains the property of the Copyright Holder.
        
        This License does not transfer ownership of the Software, its source code,
        copyright, trademarks, trade names, or other intellectual property rights.
        
        All rights not expressly granted by this License are reserved by the
        Copyright Holder.
        
        
        7. ATTRIBUTION
        
        If the Software or a Modified Version is used privately, the User is
        encouraged to preserve all existing copyright notices, license notices,
        author information, and attribution contained within the Software.
        
        Nothing in this License permits the removal of copyright notices for the
        purpose of claiming ownership of the Original Software.
        
        
        8. COMMERCIAL USE
        
        Commercial use, including incorporation of the Software into a commercial
        product or service, is not permitted unless expressly authorized in writing
        by the Copyright Holder.
        
        The Copyright Holder may grant separate commercial licenses at their
        discretion.
        
        
        9. REQUESTS FOR REDISTRIBUTION
        
        A User wishing to redistribute the Software or a Modified Version may
        contact the Copyright Holder and request explicit permission.
        
        Permission may be granted or denied at the sole discretion of the Copyright
        Holder.
        
        Any permission to redistribute may be subject to additional terms and
        conditions established by the Copyright Holder.
        
        
        10. NO WARRANTY
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
        FOR A PARTICULAR PURPOSE, TITLE, OR NON-INFRINGEMENT.
        
        THE COPYRIGHT HOLDER SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
        LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE
        OR OTHER DEALINGS IN THE SOFTWARE.
        
        
        11. LIMITATION OF LIABILITY
        
        TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE COPYRIGHT HOLDER
        SHALL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL,
        OR EXEMPLARY DAMAGES ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE.
        
        
        12. TERMINATION
        
        This License automatically terminates if the User violates any of its terms.
        
        Upon termination, the User must cease all use of the Software and destroy
        copies of the Software and Modified Versions in their possession or control,
        except where retention is required by applicable law.
        
        Permissions may be reinstated only through explicit written authorization
        from the Copyright Holder.
        
        
        13. SEVERABILITY
        
        If any provision of this License is determined to be invalid or
        unenforceable, the remaining provisions shall remain in full force and
        effect.
        
        
        14. ENTIRE AGREEMENT
        
        This License constitutes the entire agreement concerning the Software and
        supersedes any prior or contemporaneous understanding concerning the rights
        granted under this License.
        
        
        15. RESERVATION OF RIGHTS
        
        The Copyright Holder reserves all rights not expressly granted by this
        License.
        
        No permission should be inferred merely because a particular restriction is
        not explicitly stated.
        
        
        16. LICENSE VERSION
        
        This license is designated:
        
            Vanta Source-Available License v1.0
        
        Future versions of this License may be published by the Copyright Holder.
        Unless explicitly stated otherwise, a particular version of the Software
        remains governed by the license version distributed with that version.
        
        
        Copyright © 2026 radecekq
        All rights reserved.
        
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colorama==0.4.6
Requires-Dist: packaging>=24.0
Dynamic: license-file

![vanta](https://i.ibb.co/q3HFNJV1/image.jpg)

# Vanta

A lightweight Python toolkit for clean, structured CLI output.

- Colored messages
- Timestamps & log levels
- Input & confirmations
- Exception handling
- Terminal utilities
- Automatic color detection
- Interactive / non-interactive mode
- Simple terminal tables
- Elapsed time measurement
- Timer pause and resume

## Installation

```bash
pip install vanta
````

## Quick Start

```python
import vanta

console = vanta.Console()

console.info("Hello, World!")

table = vanta.Table("Name", "Age", "Status")
table.add_row("Alice", 17, "Online")
table.print()
```

# Console
```python
console = vanta.Console(
    color=None,        # Auto-detect colors
    cls=False,         # Don't clear the terminal on startup
    *,
    stdout=None,       # Output stream for normal messages
    stderr=None,       # Output stream for warnings/errors
    interactive=None,  # Auto-detect interactive mode
    level="info",      # Minimum log level
)
```

## Options

| Option        | Description                       |
| ------------- | --------------------------------- |
| `color`       | Enable/disable colors             |
| `cls`         | Clear terminal on startup         |
| `stdout`      | Output stream for normal messages |
| `stderr`      | Output stream for warnings/errors |
| `interactive` | Enable/disable input              |
| `level`       | Minimum log level                 |

## Log Levels

Vanta provides 7 log levels:

| Level      | Value | Stream | Purpose                            |
| ---------- | ----: | ------ | ---------------------------------- |
| `debug`    |    10 | stdout | Detailed debugging information     |
| `info`     |    20 | stdout | General information                |
| `notice`   |    25 | stdout | Important information worth noting |
| `success`  |    30 | stdout | Successful operation               |
| `warning`  |    40 | stderr | Something may be wrong             |
| `error`    |    50 | stderr | An operation failed                |
| `critical` |    60 | stderr | Serious/critical failure           |

> Lower levels are more verbose.

- *`level="info"`* suppresses `debug` messages
- *`level="warning"`* only emits `warning`, `error`, and `critical`

## Examples

### Logging

```python
console.debug("Debug")
console.info("Info")
console.notice("Notice")
console.success("Success")
console.warning("Warning")
console.error("Error")
console.critical("Critical")
```

**Set a minimum log level:**

```python
console = vanta.Console(level="warning")
```

For example, `level="warning"` only emits `warning`, `error`, and `critical` messages.

### Input

```python
name = console.ask("Name:")
age = console.ask("Age:", int)

if console.confirm("Continue?"):
    print("Continuing!")
```

`ask()` supports custom converters and retries.

### Exceptions

```python
try:
    1 / 0
except Exception as exc:
    console.exception(exc)
```

Use `traceback=True` for the full traceback.

### Terminal

```python
console.clear()

print(console.width)
```

Vanta works on Windows, Linux, and macOS.

Colors can also be controlled with `NO_COLOR` and `FORCE_COLOR`.

## Methods

```python
console.debug(...)
console.info(...)
console.notice(...)
console.success(...)
console.warning(...)
console.error(...)
console.critical(...)

console.raw(...)
console.ask(...)
console.confirm(...)
console.exception(...)
console.clear(...)
```

# Tables
```python
table = vanta.Table(
    "Name",        # Column 1
    "Age",         # Column 2
    "Status",      # Column 3
    ...,
    align="left",  # Align cell text to the left
    border=True,   # Show table and cell borders
    header=True,   # Include column headers
)
```

## Options

| Option   | Description                 |
| -------- | --------------------------- |
| `align`  | Align cell text             |
| `border` | Show table and cell borders |
| `header` | Include column headers      |

`align` can be `left`, `center`, or `right`.

## Examples

```python
table = vanta.Table("Name", "Age", "Status")

table.add_row("Alice", 17, "Online")
table.add_row("Bob", 21, "Offline")

table.print()
```

Output:

```text
┌───────┬─────┬─────────┐
│ Name  │ Age │ Status  │
├───────┼─────┼─────────┤
│ Alice │ 17  │ Online  │
│ Bob   │ 21  │ Offline │
└───────┴─────┴─────────┘
```

## Methods

```python
table.add_row(...)
table.add_rows(...)
table.clear()
table.render()      # Returns the table as a string
table.print()       # Renders and prints the table
```

# Timer
```python
timer = vanta.Timer(
    autostart=False,  # Don't start the timer immediately
)
```

## Options

| Option      | Description                 |
| ----------- | --------------------------- |
| `autostart` | Start the timer immediately |

## Examples

### Basic

```python
import time
import vanta

timer = vanta.Timer(autostart=True)

time.sleep(1.5)

timer.stop()

print(timer.elapsed)
print(timer.ms)
```

### Pause

```python
from time import sleep

from vanta import Timer


timer = Timer(autostart=True)

sleep(1.525)

timer.stop()  # Optional, but recommended

print(timer.elapsed)  # Around 1.525 sec
print(timer.ms)       # Around 1525 ms
```

Paused time is not included in the elapsed time.

### Context Manager

```python
with vanta.Timer() as timer:
    time.sleep(2)

print(timer.elapsed)
```

## Properties

| Property     | Description                         |
| ------------ | ----------------------------------- |
| `elapsed`    | Elapsed active time in seconds      |
| `ms`         | Elapsed active time in milliseconds |
| `running`    | Whether the timer is running        |
| `paused`     | Whether the timer is paused         |
| `start_time` | Time when the timer was started     |
| `stop_time`  | Time when the timer was stopped     |

## Methods

```python
timer.start()
timer.stop()
timer.pause()
timer.unpause()
timer.reset() # Clears the timer and returns it to its initial state. Does not restart.
```

# Version

**0.3.1**

Vanta is currently in early development and the API may change before `1.0.0`.

# License

See [`LICENSE`](LICENSE).
