Metadata-Version: 2.5
Name: randompass
Version: 1.1.0
Summary: A simple generator of passwords and passphrases.
Project-URL: Homepage, https://github.com/pplayer7/randompass
Project-URL: Repository, https://github.com/pplayer7/randompass
Project-URL: Issues, https://github.com/pplayer7/randompass/issues
Author-email: pplayer7 <pplayer7@mail.ru>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: click>=8.4.2
Requires-Dist: platformdirs>=4.11.4
Requires-Dist: pyperclip>=1.11.0
Description-Content-Type: text/markdown

# randompass
## A simple generator of passwords and passphrases.

---
## Features

- Secure password generation using Python's `secrets` module.
- Guaranteed inclusion of selected character categories.
- Passphrase generation using a wordlist.
- Clipboard support.
- Save generated passwords/passphrases to a file.
- Generate multiple passwords/passphrases at once.
- CLI aliases: `pw` and `pp`.
- Persistent configuration for default settings.

---

## Installation
To install randompass, you need to have [uv](https://github.com/astral-sh/uv) installed.
### GitHub
```bash
git clone https://github.com/pplayer7/randompass.git
cd randompass
uv sync
```

Usage: `uv run randompass`

### PyPI
[PyPI](https://pypi.org/project/randompass/)

`pip install randompass` or `uv tool install randompass`

Usage: `randompass`


---

## Usage

Choose a mode to generate passwords or passphrases.

```
$ randompass
Usage: randompass [OPTIONS] COMMAND [ARGS]...

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  config
  passphrase
  password
  pw
  pp
```

For example, `randompass password` generates a 12-character password containing uppercase letters, digits, and special symbols (with default config).
All selected character categories are guaranteed to be included (with default config).

And `randompass passphrase` generates a 5-word passphrase using the
default wordlist (with default config).

> **Note:** `password` and `pw` are aliases.
>
> **Note:** `passphrase` and `pp` are aliases.

### Arguments:
#### Password mode

| Argument                                         | Description                                                        |
|--------------------------------------------------|--------------------------------------------------------------------|
| `-h, --help`                                     | Shows help page.                                                   |
| `-l, --length LENGTH`                            | Length of the password (default is 12).                            |
| `-u, --uppercase/--no-uppercase`                 | Whether uppercase letters should be included (enabled by default). |
| `-s, --special-symbols/--no-special-symbols`     | Whether special symbols should be included (enabled by default).   |
| `-d, --digits/--no-digits`                       | Whether digits should be included (enabled by default).            |
| `--exclude-similar`                              | Exclude visually similar characters such as 0, O, 1, and l.        |
| `--exclude`                                      | Exclude selected characters from the password.                     |
| `-n, --count`                                    | Number of passwords to generate (default is 1).                    |
| `-c, --copy`                                     | Copy the password to the clipboard (disabled by default).          |
| `-o, --output FILE`                              | Save the result to a file.                                         |

---

#### Passphrase mode

| Argument                       | Description                                                 |
|--------------------------------|-------------------------------------------------------------|
| `-h, --help`                   | Shows help page.                                            |
| `-l, --length LENGTH`          | Number of words in the passphrase (default is 8).           |
| `-s, --separator`              | Symbol that separates the words (default is "-").           |
| `-w, --wordlist WORDLIST_FILE` | Set custom wordlist.                                        |
| `-n, --count`                  | Number of passphrases to generate (default is 1).           |
| `-c, --copy`                   | Copy the passphrase to the clipboard (disabled by default). |
| `-o, --output FILE`            | Save the result to a file.                                  |

> **Note:** Clipboard copying is unavailable if no supported clipboard
> mechanism is detected.
>
> Multiple results cannot be copied at once, and `--copy` cannot be
> combined with `--output`.

### Examples:
#### Password mode

Generate a 12-character password:

```
$ randompass password -l 12
/Sy"KG6dtv#G
```

Generate a 20-character password with no digits:

```
$ randompass password -l 20 --no-digits
bd,+?swxL.Y?d`{&'F:%
```

Generate 5 10-character passwords with no uppercase letters or special symbols:

```
$ randompass password -l 10 --no-uppercase --no-special-symbols -n 5
345ra5peus
cfppy97hkv
jy24huia4i
0cvjqfy871
70ygxqrh4d
```

Generate a password and copy it to the clipboard:

```
$ randompass password -c
4?[SOr9&
```

Generate 100 passwords with no digits and write them to `output.txt` (No console output):

```
$ randompass password --no-digits -n 100 -o output.txt
```


#### Passphrase mode

Generate a passphrase with 10 words:

```
$ randompass passphrase -l 10
shady-stretch-sulfate-snub-gummy-earthly-tipoff-icon-deflected-punctual
```

Generate a passphrase with 8 words and "_" separator:

```
$ randompass passphrase -l 8 -s _
corny_constrain_clunky_crispness_heaviness_strength_impending_saved
```

Generate a passphrase with 12 words, "=" separator and copy it to clipboard:

```
$ randompass passphrase -l 12 -s = -c
prelaw=oxidize=bonanza=uniquely=startling=happily=blurt=large=wok=corset=mustiness=arena
```

Generate a passphrase with custom wordlist

```
$ randompass passphrase -w w.txt
steadfast-oblong-cartridge-qualifier-stainless
```

Generate 5 passphrases with "+" separator and write them to `example.txt` (No console output):

```
$ randompass passphrase -n 5 -s + -o example.txt
```


## Config
Config file is used to set default settings for randompass, so you don't have to specify the same options every time.

The config file is stored in the platform-specific user config directory.
> The default config file is located in the .config directory on Linux and macOS, or in APPDATA\Roaming on Windows.

You can access config settings via `config` command.

``` 
randompass config --help 
Usage: randompass config [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  init
  path
  reset
  set
  show
```

| Command               | Description                         | Flags                                        |
|-----------------------|-------------------------------------|----------------------------------------------|
| init                  | Init config file.                   | `-f, --force`  Force init config file.       |
| path                  | Print the path to the config file.  |
| reset                 | Reset config to default.            | `-f, --force`  Force reset config file.      |
| set MODE.OPTION VALUE | Set config settings.                |
| show                  | Print current config.               |

Example:
```sh
randompass config set password.length 20
randompass config set password.uppercase false
randompass config set passphrase.separator _
randompass config show
General:
  1000 warning: True

Password:
  Length: 20
  Uppercase: False
  Special symbols: True
  Digits: True
  Exclude similar: False

Passphrase:
  Length: 8
  Separator: _
  Wordlist: <path to default wordlist>
```

## Python API

`randompass` can also be used as a Python library.

```python
from randompass import Passgen, Passphrase
from pathlib import Path

password = Passgen(
    length=16,
    uppercase=True,
    special_symbols=True,
    digits=True,
    exclude_similar=False,
    exclude=''
).generate_password()

wordlist = Path("wordlist.txt") # The wordlist must contain one word per line.
phrase = Passphrase(
    length=6,
    separator="-",
    wordlist=wordlist,
).generate_passphrase()

print(password)
print(phrase)
```

## Tests

Tests are located in [tests](tests/) folder.

Run them with pytest:
```bash
uv run pytest
```

---

## Wordlist

The default wordlist is [EFF Large Wordlist](https://www.eff.org/files/2016/07/18/eff_large_wordlist.txt).

## License
randompass distributes under the [MIT License](LICENSE).
