Metadata-Version: 2.4
Name: mukimov
Version: 0.1.4
Summary: Tiny cross-platform password prompt with customizable masking
Author-email: mukimov <mukimov.shop@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/mukimov/mukimov
Keywords: password,getpass,stars,prompt,cli
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# mukimov

A tiny cross-platform Python library for masked password input in the terminal.

[![PyPI version](https://img.shields.io/pypi/v/mukimov.svg)](https://pypi.org/project/mukimov/)
[![Python versions](https://img.shields.io/pypi/pyversions/mukimov.svg)](https://pypi.org/project/mukimov/)
[![License: MIT](https://img.shields.io/pypi/l/mukimov.svg)](https://pypi.org/project/mukimov/)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-blue.svg)](https://pypi.org/project/mukimov/)

Developed by Mukimov Studio

## What is mukimov?

`mukimov` lets you read a password or any other secret text in the terminal
while showing a mask character instead of the real keystrokes.

For example, the user really types:

```text
123456
```

but the terminal shows:

```text
Password: ******
```

And the function returns the real text `"123456"`.

> **Important:** this is **NOT hashing** and **NOT encryption**.
> The library only visually hides input from people who may be looking
> at the screen. The real password is still returned to your program
> as a plain string.

## Installation

```bash
pip install mukimov
```

Upgrade to the latest version:

```bash
pip install --upgrade mukimov
```

Check the installed version:

```bash
pip show mukimov
```

## Quick Start

The simplest possible example:

```python
from mukimov import stars

password = stars("Password: ")
```

What the user sees:

```text
Password: ******
```

If the user typed `123456`, the variable `password` contains:

```python
"123456"
```

## Custom Mask ✨

The second argument controls which character is shown
for every typed symbol:

```python
stars("Password: ", "*")  # Password: ******
stars("Password: ", "/")  # Password: //////
stars("Password: ", "#")  # Password: ######
stars("Password: ", "•")  # Password: ••••••
```

API:

```python
stars(prompt, mask="*")
```

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `prompt`  | `str` | Text displayed before input. |
| `mask`    | `str` | Character shown instead of each typed symbol. Defaults to `"*"`. |

> **Important:** `mask` must contain exactly **ONE** character.

## Full Example

A realistic login prompt:

```python
from mukimov import stars

username = input("Username: ")
password = stars("Password: ")

print(f"Welcome, {username}!")
```

Example terminal session:

```text
Username: Mukimov
Password: ********
Welcome, Mukimov!
```

Note that the real password is never printed — only the mask is shown.

## Colors

`mukimov.color` provides 12 pleasant ANSI colors for the terminal.
Each function takes a string and returns it wrapped in color
(reset automatically applied at the end):

```python
from mukimov.color import red, green, blue

print(red("Error"))
print(green("Success"))
print(blue("Information"))

username = input(red("Username: "))
password = stars(green("Password: "))
```

Available colors: `red`, `green`, `blue`, `yellow`, `orange`,
`purple`, `pink`, `cyan`, `lime`, `gray`, `white`, `gold`.

No third-party dependencies — pure Python, works in
Windows Terminal, PowerShell and Linux terminals.

## Errors

`mukimov` raises clear, descriptive errors **in Russian**.
Each message tells you which parameter is wrong, what value was passed,
why it is wrong, what was expected, and shows a correct example.

Wrong usage:

```python
stars("Password: ", "//")
```

Error:

```text
ValueError: Параметр mask='//' содержит 2 символа. Допускается только 1 символ.
Пример: stars("Password: ", "*")
```

More examples (real messages from the library):

```python
stars("Password: ", "")
```

```text
ValueError: Параметр mask='' пустой. Укажите ровно 1 символ для маскировки.
Пример: stars("Password: ", "*")
```

```python
stars("Password: ", 123)
```

```text
TypeError: Параметр mask должен быть строкой (str), но получен int: 123.
Пример: stars("Password: ", "*")
```

```python
stars(123)
```

```text
TypeError: Параметр prompt должен быть строкой (str), но получен int: 123.
Пример: stars("Password: ")
```

## Platform Support

Only systems actually supported by the current code are listed:

| OS | Backend |
| -- | ------- |
| Windows | `msvcrt` |
| Linux | `termios` / `tty` |
| macOS | `termios` / `tty` |

The library uses **only the Python standard library** — no third-party
dependencies. When standard input is not a TTY (pipes, IDE consoles, CI),
it safely falls back to `getpass` with no echo.

Extra behavior worth knowing:

- Backspace deletes the last mask character and the last symbol.
- Enter finishes input.
- `Ctrl+C` raises `KeyboardInterrupt`, `Ctrl+D` on empty input raises `EOFError`.

## Why mukimov?

The goal of `mukimov` is a simple, short API for masked terminal input.

mukimov:

```python
from mukimov import stars

password = stars("Password: ", "•")
```

And the standard-library alternative, where your Python version
supports `echo_char`:

```python
from getpass import getpass

password = getpass("Password: ", echo_char="•")
```

If you like the classic `getpass`, keep using it — `mukimov` is just
a compact option when you want per-character masking with a tiny API.

## Security 🔒

`mukimov` hides the password **only visually, while it is being typed**.

It does NOT:

- hash the password
- encrypt the password
- store the password securely by itself
- protect the process from malware
- protect the contents of the process memory

After input, the function returns the real password as a regular
Python string. To store passwords, developers must separately use
a reliable password-hashing solution.

Also, error messages and logs of this library never include
the typed password — only configuration values (`prompt`, `mask`)
may appear in validation errors.

## API

```python
stars(prompt="Password: ", mask="*")
```

Parameters:

- `prompt: str` — text displayed before input.
- `mask: str` — exactly one character shown instead of each typed symbol.

Returns:

- `str` — the real text the user typed.

Exceptions:

- `TypeError` — `prompt` or `mask` is not a string.
- `ValueError` — `mask` is empty or longer than one character.

## Project

- PyPI: https://pypi.org/project/mukimov/
- GitHub: https://github.com/mukimov/mukimov
- Author: mukimov
- Organization: Mukimov Studio
- Email: mukimov.shop@gmail.com
- License: MIT
