xphrase 1.0.4
Expressive phrase generator, strong, modern and minimalist
License: MIT
Requires Python: >=3.8
Keywords: cryptography, english, generator, german, multilingual, password, phrase, portuguese, security

# 🧩 XPHRASE GENERATION

**Expressive phrase generator — strong, modern, and minimalist.**  
Built entirely in Python for CLI environments on Linux and Windows.

[![Maintained](https://img.shields.io/badge/Maintained-Yes%202025-4fc08d?style=flat&logo=maintenance&logoColor=white)](https://github.com/gerivanc/xphrase)
[![CI](https://github.com/gerivanc/xphrase/actions/workflows/python-app.yml/badge.svg)](https://github.com/gerivanc/xphrase/actions/workflows/python-app.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat&logo=licenses)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue?style=flat&logo=python)](https://python.org)
[![PyPI](https://img.shields.io/badge/PyPI-xphrase-blue?style=flat&logo=pypi)](https://pypi.org/project/xphrase/)
[![TestPyPI](https://img.shields.io/badge/TestPyPI-xphrase-3700b3?style=flat&logo=pypi)](https://test.pypi.org/project/xphrase/)

--- 

## 📑 Table of Contents
- [🧠 Project Overview](#-project-overview)
- [📜 Disclaimer](#-disclaimer)
- [🌍 Interactive Web Version](#-interactive-web-version)
- [✨ Features](#-features)
- [📋 Requirements](#-requirements)
- [💾 Installation](#-installation)
- [📟 Command Line Interface](#-command-line-interface)
- [🔐 Generation Rules](#-generation-rules)
- [📚 Word Bank Specs](#-word-bank-specs)
- [📊 XPhrase Calculation Methodology](#-xphrase-calculation-methodology)
- [📢 Reporting Issues](#-reporting-issues)
- [🐞 Reporting Bugs](#-reporting-bugs)
- [🛡️ Security - Reporting a Vulnerability](#️-security---reporting-a-vulnerability)
- [🤝 Contributing](#-contributing)
- [📝 Release Notes](#-release-notes)
- [📅 Changelog](#-changelog)
- [💬 Contact](#-contact)
- [📄 License](#-license)

--- 

# 🧠 Project Overview
**XPhrase Generation** is a multilingual phrase generator designed for command-line interface (CLI) usage.  
It creates expressive, randomized phrases using words from **Portuguese**, **English**, and **German**, interlinked with special characters and digits.
The principle of randomness enables the generation of over 12.6 trillion unique combinations by interconnecting words from three languages, along with the inclusion of special characters and numerical digits.

This project is:
- 💯 Written 100% in Python
- 🖥️ CLI-compatible for Linux and Windows
- 🌐 The CLI project has been fully converted to the web version of the HTML interface, maintaining the same phrase generation method, now accessible directly in your browser. 

---

# 📜 Disclaimer
Do not attempt to memorize the passwords generated by this tool. Instead, use a reliable password manager, such as [Bitwarden©](https://bitwarden.com/), which I personally recommend. The only password you should memorize is the master password for your password manager's vault, created with a strong combination of uppercase and lowercase letters, numbers, and special characters. Enable two-factor authentication (2FA) whenever possible to enhance security. A great option for managing your 2FA is Ente Auth , a free, open-source, and cross-platform app that provides end-to-end encrypted backups. [Ente Auth](https://ente.io/auth/) ensures your 2FA codes are secure and synced across devices, with externally audited encryption, offering robust protection for all your accounts that support 2FA.

---

# 🌍 Interactive Web Version

Experience the XPhrase Generation directly in your browser! The web version offers all the functionality of the Python script in an intuitive and responsive interface.

### 🚀 Access the Web Version

<div align="center">
  
[**🌐 Try It Now on XPhrase Generation**](https://xphrase.gerivan.me/xphrase.html)

</div>

### ⚡ Interactive Demo

<div align="center">

[**📚 Interactive Readme**](https://xphrase.gerivan.me/)

</div>

---

# ✨ Features
- Generates phrases with **3 to 21 words**
- Words are randomly selected from **Portuguese**, **English**, and **German** word banks
- Each word is **interlinked** with:
  - At least **one special character**: `!@#$%^&*()_+-=[]{}|;:,.<>?~\\`
  - At least **one digit**: `0123456789`
- The **last character of the final word** is always **uppercase**
- Example of output for generating a phrase with eight words plus numeric and special characters:  
  `Note,8oxidar+6truly=3Chaos\1ressaca[3kind;1achtzehn_9descréditO`

---

# 📋 Requirements
- Python 3.8+
- No external dependencies
- Works on:
  - ✅ Linux (Debian, Ubuntu, Arch, etc.)
  - ✅ Windows (PowerShell, CMD)

---

# 💾 Installation
1. No additional dependencies are required, as the project uses only Python standard libraries.
2. Ensure you have Python 3.8 or higher installed.
3. Clone the repository:

```
git clone https://github.com/gerivanc/xphrase.git
cd xphrase
```

---

# 📟 Command Line Interface
## 📦️ After installation, navigate to the directory where the XPhrase Generation repository folder was installed, then choose one of the following options to generate the phrases:

### 🧪  Mode 'PYTHONPATH=' 

#### 5️⃣🔟 The parameter should be between 5 and 10 words long.
```
PYTHONPATH=src python src/xphrase/main.py --count 5
```

#### ➖➕ Defines the minimum and maximum number of words to be generated in the sentence. --min and --max must be between 3-21 and min <= max.
```
PYTHONPATH=src python src/xphrase/main.py --min 5 --max 21
```

#### 📋🔘 Interactive menu - generates unique and multiple phrases.
```
PYTHONPATH=src python src/xphrase/main.py --interactive
```

#### 📦✨ Show which version of XPhrase Generation it is.
```
PYTHONPATH=src python src/xphrase/main.py --version
```

---

### 🧪  Mode 'echo PYTHONPATH='

#### 5️⃣🔟 The parameter should be between 5 and 10 words long. 

```
echo 'PYTHONPATH=src python src/xphrase/main.py "$@"' > xphrase.sh
chmod +x xphrase.sh
./xphrase.sh --count 10
```

#### ➖➕ Defines the minimum and maximum number of words to be generated in the sentence. --min and --max must be between 3-21 and min <= max.
```
echo 'PYTHONPATH=src python src/xphrase/main.py "$@"' > xphrase.sh
chmod +x xphrase.sh
./xphrase.sh --min 5 --max 21
```

#### 📋🔘 Interactive menu - generates unique and multiple phrases.
```
echo 'PYTHONPATH=src python src/xphrase/main.py "$@"' > xphrase.sh
chmod +x xphrase.sh
./xphrase.sh --interactive
```

#### 📦✨ Show which version of XPhrase Generation it is.
```
echo 'PYTHONPATH=src python src/xphrase/main.py "$@"' > xphrase.sh
chmod +x xphrase.sh
./xphrase.sh --version
```

---

### 🧪 Mode './gerar'.  Apply the script below before activating the './generate' mode to generate the phrases. Do this only on the first installation; after installation, navigate to the directory and generate the phrase using the function.:
```
cd xphrase
cat > gerar << 'EOF'
#!/usr/bin/env python3
import sys
sys.path.insert(0, 'src')
from xphrase.main import main
if __name__ == '__main__':
    main()
EOF

chmod +x gerar
```

#### 📏✨ The parameter generates a single sentence with 8 words.
```
./gerar
```

#### 5️⃣🔟 The parameter should be between 5 and 10 words long.
```
./gerar --count 7
```

#### ➖➕ Defines the minimum and maximum number of words to be generated in the sentence. --min and --max must be between 3-21 and min <= max.
```
./gerar --min 5 --max 21
```

#### 📋🔘 Interactive menu - generates unique and multiple phrases.
```
./gerar --interactive
```

#### 📦✨ Show which version of XPhrase Generation it is.
```
./gerar --version
```

---

### 🧪 Mode './run.py'.  Apply the script below before activating the './run.py' mode to generate the phrases. Do this only on the first installation; after installation, navigate to the directory and generate the phrase using the function.:
```
cd xphrase
cat > run.py << 'EOF'
#!/usr/bin/env python3
import sys
import os

sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))

from xphrase.main import main

if __name__ == '__main__':
    main()
EOF

chmod +x run.py
```

#### 📏✨ The parameter generates a single sentence with 8 words.
```
./run.py
```

#### 5️⃣🔟 The parameter should be between 5 and 10 words long.
```
./run.py --count 9
```

#### ➖➕ Defines the minimum and maximum number of words to be generated in the sentence. --min and --max must be between 3-21 and min <= max.
```
./run.py --min 5 --max 21
```

#### 📋🔘 Interactive menu - generates unique and multiple phrases.
```
./run.py --interactive
```

#### 📦✨ Show which version of XPhrase Generation it is.
```
./run.py --version
```

---

# 🔐 Generation Rules
- Phrase length: **3 to 21 words**
- Each word must include:
  - **1+ special character**
  - **1+ digit**
- Final word must end with a **capital letter**
- Language order is **randomized**

---

# 📚 Word Bank Specs
- It contains 4,000 specific words, selected from the vocabulary of three different languages.
- This project was created by selecting words to generate sentences in three languages: English, Portuguese, and German.
- All words are stored in separate `.txt` files inside the `data/` folder.
- Words are randomly selected and mixed across languages.

| Language    | Word Count |
|-------------|------------|
| English     | 1,334      |
| Portuguese  | 1,333      |
| German      | 1,333      |

---

# 📊 XPhrase Calculation Methodology
Generation phrase  by Phrase Formation Rules:

For a phrase with \( n \) words (\( 3 \leq n \leq 21 \)):

### 1. **Word Selection**
   - Each word is selected **randomly with replacement** from the pool of 4,000
   - Language origin is **random per word** (uniform distribution across 3 languages)
   - **Order matters**, repetitions allowed

### 2. **Per-Word Modification**
   For each selected word:
   - Insert **at least one digit** (`0–9`) → 10 options
   - Insert **at least one special character** from:
     ```
     !@#$%^&*()_+-=[]{}|;:,.<>?~\\
     ```
     → **29 special characters**
   - Insertions occur **between letters**, **before**, or **after** the word
   - **Multiple insertions allowed** (no upper limit per word)
   - **No fixed pattern** — randomness ensures entropy

### 3. **Inter-Word Linking**
   - Words are **concatenated directly** with their modifications
   - No fixed separator between augmented words
   - Example: `davor,9Möglichkeit]3ThermometeR`

### 4. **Final Word Capitalization**
   - The **last character of the final word** must be a **letter** and is **forced uppercase**
   - If the last character after modification is not a letter, a **valid letter is appended and uppercased**

See the [XPHRASECALCULATION.md](https://github.com/gerivanc/xphrase/blob/main/XPHRASECALCULATION.md) for details.

---

# 📢 REPORTING ISSUES
Help us improve **XPhrase Generation** by reporting bugs or suggesting enhancements to project. 
To report a bug, suggest a feature, or ask a question:
1. Go to the [Issues tab](https://github.com/gerivanc/xphrase/issues).

2. Click **New issue**.

3. View the available options and select to: **Report Bug** and/or [**Report Issue**](https://github.com/gerivanc/xphrase/blob/main/.github/ISSUE_TEMPLATE/issue_template.md). For security vulnerabilities, please follow our [Security Policy](https://github.com/gerivanc/xphrase/blob/main/SECURITY.md).

---

# 🐞 REPORTING BUGS
If you encounter a bug in the **XPhrase Generation**, please report it using our dedicated [Bug Report template](https://github.com/gerivanc/xphrase/blob/main/.github/ISSUE_TEMPLATE/bug_report.md). This template ensures that your report includes essential details, such as steps to reproduce, environment information, and logs, enabling us to address issues efficiently. For other types of contributions or inquiries, refer to our [CONTRIBUTING.md](https://github.com/gerivanc/xphrase/blob/main/CONTRIBUTING.md).

---

# 🛡️ Security - Reporting a Vulnerability
For security vulnerabilities, follow the process in [SECURITY.md](https://github.com/gerivanc/xphrase/blob/main/SECURITY.md) instead of opening a public issue. We recommend using a password manager and enabling 2FA for enhanced security.

---

# 🤝 CONTRIBUTING
Contributions are welcome! Please follow the guidelines in [CONTRIBUTING.md](https://github.com/gerivanc/xphrase/blob/main/CONTRIBUTING.md).

---

# 📝 RELEASE NOTES
See the [RELEASE.md](https://github.com/gerivanc/xphrase/blob/main/RELEASE.md) for detailed release notes for each version.

---

# 📅 CHANGELOG
See the [CHANGELOG.md](https://github.com/gerivanc/xphrase/blob/main/CHANGELOG.md) for a detailed history of changes to this project.

---

# 💬 CONTACT
E-mail: ask@gerivan.me  
Location: Brazil  
Feel free to reach out for collaboration or feedback!

---

# 📜 LICENSE
This repository is licensed under the [MIT License](https://github.com/gerivanc/xphrase/blob/main/LICENSE.md).

---

#### Copyright © 2025 Gerivan Costa dos Santos
**XPhrase Generation — Expressive phrases. Strong logic. Minimalist design © 2025**