| Name | gwanicli JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | https://github.com/bhantsi/gwani-cli |
| Summary | A command-line interface for accessing Quranic verses and translations |
| upload_time | 2025-08-05 13:53:48 |
| maintainer | None |
| docs_url | None |
| author | B. Hantsi |
| requires_python | >=3.11 |
| license | MIT License
Copyright (c) 2025 GwaniCLI Contributors
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:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
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.
|
| keywords |
quran
islam
cli
terminal
verses
translation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
click
requests
toml
arabic-reshaper
python-bidi
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# GwaniCLI
A command-line interface for accessing Quranic verses and translations with elegant formatting and caching capabilities.
## Features
- 🔄 **Random verses**: Get random Quranic verses with translations
- 📖 **Surah browsing**: Access specific surahs and ayahs
- 🌍 **Multiple translations**: Support for various translation options
- 💾 **Smart caching**: Offline access with configurable TTL
- 🎨 **Beautiful formatting**: Colored console output with Arabic text support
- ⚙️ **Configurable**: User-friendly configuration management
- 📱 **JSON output**: Machine-readable output option
## Installation
### From PyPI
```bash
pip install gwanicli
```
### From Source
```bash
git clone https://github.com/bhantsi/gwani-cli.git
cd gwani-cli
pip install -e .
```
## Quick Start
### Get a random verse
```bash
gwani random
```
### Get a specific surah
```bash
gwani surah 1 # Al-Fatiha
gwani surah "Al-Baqarah" --ayah 255 # Ayat al-Kursi
```
### Configure translation
```bash
gwani config set translation en.sahih
gwani config get translation
```
### JSON output
```bash
gwani random --json
```
## Commands
### `gwani random`
Get a random Quranic verse with translation.
**Options:**
- `--translation, -t TEXT`: Specify translation (e.g., en.pickthall)
- `--no-cache`: Skip cache and fetch fresh data
- `--json`: Output in JSON format
**Examples:**
```bash
gwani random
gwani random --translation en.sahih
gwani random --json --no-cache
```
## Arabic Text Display
GwaniCLI provides intelligent Arabic text rendering that automatically adapts to your terminal's capabilities.
### Display Modes
Use the global `--arabic-mode` option to control how Arabic text is displayed:
```bash
# Automatic detection (default)
gwani random
# Unicode Arabic text only
gwani --arabic-mode unicode random
# Transliterated text only
gwani --arabic-mode transliteration random
# Both Arabic and transliteration
gwani --arabic-mode both random
```
### Font Recommendations
Check your terminal's Arabic support and get font recommendations:
```bash
gwani fonts
```
For optimal Arabic display, consider installing these fonts:
**Ubuntu/Debian:**
```bash
sudo apt install fonts-noto fonts-amiri fonts-scheherazade-new
```
**macOS (with Homebrew):**
```bash
brew install --cask font-noto-sans-arabic font-amiri font-scheherazade-new
```
**Recommended fonts:**
- Noto Sans Arabic (comprehensive Unicode support)
- Amiri (traditional Arabic calligraphy)
- Cairo (modern, clean Arabic font)
- Scheherazade New (academic/traditional style)
### Terminal Compatibility
GwaniCLI works with any terminal:
- **Modern terminals** (xterm, GNOME Terminal, iTerm2, etc.): Full Unicode Arabic support
- **Basic terminals**: Automatic fallback to transliteration
- **Windows**: Enhanced UTF-8 support with automatic optimizations
### `gwani surah <identifier>`
Get verses from a specific surah by number or name.
**Arguments:**
- `identifier`: Surah number (1-114) or name (e.g., "Al-Fatiha")
**Options:**
- `--ayah, -a INT`: Specific ayah number
- `--translation, -t TEXT`: Specify translation
- `--no-cache`: Skip cache and fetch fresh data
- `--json`: Output in JSON format
**Examples:**
```bash
gwani surah 1 # Entire Al-Fatiha
gwani surah 2 --ayah 255 # Ayat al-Kursi
gwani surah "Al-Fatiha" --json # JSON format
```
### `gwani fonts`
Check Arabic text display capabilities and get font recommendations.
**Examples:**
```bash
gwani fonts # Check terminal capabilities and show font recommendations
```
This command will:
- Test your terminal's Arabic text support
- Show terminal and encoding information
- Display sample Arabic text in different modes
- Provide font installation instructions for your platform
### `gwani config`
Manage configuration settings.
**Subcommands:**
- `set <key> <value>`: Set a configuration value
- `get <key>`: Get a configuration value
**Supported Keys:**
- `translation`: Default translation (e.g., en.pickthall)
- `cache_ttl`: Cache time-to-live in seconds
**Examples:**
```bash
gwani config set translation en.sahih
gwani config set cache_ttl 3600
gwani config get translation
```
### `gwani version`
Show version information.
## Configuration
GwaniCLI stores configuration in `~/.config/gwanicli/config.toml`.
**Default configuration:**
```toml
translation = "en.pickthall"
cache_ttl = 86400
```
## Caching
The application caches API responses to improve performance and enable offline access:
- **Location**: `~/.cache/gwanicli/cache.db`
- **Storage**: SQLite database
- **TTL**: Configurable expiration time
- **Management**: Automatic cleanup of expired entries
## Translations
Common translation identifiers:
- `en.pickthall`: Pickthall English translation
- `en.sahih`: Sahih International
- `en.yusufali`: Abdullah Yusuf Ali
- `ar.alafasy`: Arabic (Mishary Alafasy)
## Development
### Setup Development Environment
```bash
git clone https://github.com/bhantsi/gwani-cli.git
cd gwani-cli
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```
### Run Tests
```bash
pytest
```
### Code Formatting
```bash
black qwanicli/
flake8 qwanicli/
mypy qwanicli/
```
## Project Structure
```
qwanicli/
├── __init__.py # Package initialization
├── cli.py # Main CLI entry point with Click commands
├── api_client.py # HTTP client for Quran API
├── config.py # Configuration management
├── cache.py # SQLite-based caching layer
├── formatter.py # Output formatting (console & JSON)
└── utils.py # Common utilities and error handling
```
## API
GwaniCLI uses the [Al-Quran Cloud API](https://alquran.cloud/api) to fetch Quranic content.
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [Al-Quran Cloud API](https://alquran.cloud/) for providing the Quranic data
- [Click](https://click.palletsprojects.com/) for the excellent CLI framework
- The open-source community for various Python packages used
## Support
If you encounter any issues or have questions:
1. Check the [Issues](https://github.com/bhantsi/gwani-cli/issues)
2. Create a [new issue](https://github.com/bhantsi/gwani-cli/issues/new)
---
**Note**: This tool is for educational and personal use. Please respect the sacred nature of the Quranic content.
Raw data
{
"_id": null,
"home_page": "https://github.com/bhantsi/gwani-cli",
"name": "gwanicli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "quran, islam, cli, terminal, verses, translation",
"author": "B. Hantsi",
"author_email": "Hamza Danjaji <bhantsi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/87/4b/d537fb9c7b68d49beaf39ef2f5c1063a3881a3958be1ef476ec71ef37638/gwanicli-0.2.0.tar.gz",
"platform": null,
"description": "# GwaniCLI\n\n\n\n\n\n\n\nA command-line interface for accessing Quranic verses and translations with elegant formatting and caching capabilities.\n\n## Features\n\n- \ud83d\udd04 **Random verses**: Get random Quranic verses with translations\n- \ud83d\udcd6 **Surah browsing**: Access specific surahs and ayahs\n- \ud83c\udf0d **Multiple translations**: Support for various translation options\n- \ud83d\udcbe **Smart caching**: Offline access with configurable TTL\n- \ud83c\udfa8 **Beautiful formatting**: Colored console output with Arabic text support\n- \u2699\ufe0f **Configurable**: User-friendly configuration management\n- \ud83d\udcf1 **JSON output**: Machine-readable output option\n\n## Installation\n\n### From PyPI\n```bash\npip install gwanicli\n```\n\n### From Source\n```bash\ngit clone https://github.com/bhantsi/gwani-cli.git\ncd gwani-cli\npip install -e .\n```\n\n## Quick Start\n\n### Get a random verse\n```bash\ngwani random\n```\n\n### Get a specific surah\n```bash\ngwani surah 1 # Al-Fatiha\ngwani surah \"Al-Baqarah\" --ayah 255 # Ayat al-Kursi\n```\n\n### Configure translation\n```bash\ngwani config set translation en.sahih\ngwani config get translation\n```\n\n### JSON output\n```bash\ngwani random --json\n```\n\n## Commands\n\n### `gwani random`\nGet a random Quranic verse with translation.\n\n**Options:**\n- `--translation, -t TEXT`: Specify translation (e.g., en.pickthall)\n- `--no-cache`: Skip cache and fetch fresh data\n- `--json`: Output in JSON format\n\n**Examples:**\n```bash\ngwani random\ngwani random --translation en.sahih\ngwani random --json --no-cache\n```\n\n## Arabic Text Display\n\nGwaniCLI provides intelligent Arabic text rendering that automatically adapts to your terminal's capabilities.\n\n### Display Modes\n\nUse the global `--arabic-mode` option to control how Arabic text is displayed:\n\n```bash\n# Automatic detection (default)\ngwani random\n\n# Unicode Arabic text only\ngwani --arabic-mode unicode random\n\n# Transliterated text only \ngwani --arabic-mode transliteration random\n\n# Both Arabic and transliteration\ngwani --arabic-mode both random\n```\n\n### Font Recommendations\n\nCheck your terminal's Arabic support and get font recommendations:\n\n```bash\ngwani fonts\n```\n\nFor optimal Arabic display, consider installing these fonts:\n\n**Ubuntu/Debian:**\n```bash\nsudo apt install fonts-noto fonts-amiri fonts-scheherazade-new\n```\n\n**macOS (with Homebrew):**\n```bash\nbrew install --cask font-noto-sans-arabic font-amiri font-scheherazade-new\n```\n\n**Recommended fonts:**\n- Noto Sans Arabic (comprehensive Unicode support)\n- Amiri (traditional Arabic calligraphy)\n- Cairo (modern, clean Arabic font)\n- Scheherazade New (academic/traditional style)\n\n### Terminal Compatibility\n\nGwaniCLI works with any terminal:\n- **Modern terminals** (xterm, GNOME Terminal, iTerm2, etc.): Full Unicode Arabic support\n- **Basic terminals**: Automatic fallback to transliteration\n- **Windows**: Enhanced UTF-8 support with automatic optimizations\n\n### `gwani surah <identifier>`\nGet verses from a specific surah by number or name.\n\n**Arguments:**\n- `identifier`: Surah number (1-114) or name (e.g., \"Al-Fatiha\")\n\n**Options:**\n- `--ayah, -a INT`: Specific ayah number\n- `--translation, -t TEXT`: Specify translation\n- `--no-cache`: Skip cache and fetch fresh data\n- `--json`: Output in JSON format\n\n**Examples:**\n```bash\ngwani surah 1 # Entire Al-Fatiha\ngwani surah 2 --ayah 255 # Ayat al-Kursi\ngwani surah \"Al-Fatiha\" --json # JSON format\n```\n\n### `gwani fonts`\nCheck Arabic text display capabilities and get font recommendations.\n\n**Examples:**\n```bash\ngwani fonts # Check terminal capabilities and show font recommendations\n```\n\nThis command will:\n- Test your terminal's Arabic text support\n- Show terminal and encoding information\n- Display sample Arabic text in different modes\n- Provide font installation instructions for your platform\n\n### `gwani config`\nManage configuration settings.\n\n**Subcommands:**\n- `set <key> <value>`: Set a configuration value\n- `get <key>`: Get a configuration value\n\n**Supported Keys:**\n- `translation`: Default translation (e.g., en.pickthall)\n- `cache_ttl`: Cache time-to-live in seconds\n\n**Examples:**\n```bash\ngwani config set translation en.sahih\ngwani config set cache_ttl 3600\ngwani config get translation\n```\n\n### `gwani version`\nShow version information.\n\n## Configuration\n\nGwaniCLI stores configuration in `~/.config/gwanicli/config.toml`.\n\n**Default configuration:**\n```toml\ntranslation = \"en.pickthall\"\ncache_ttl = 86400\n```\n\n## Caching\n\nThe application caches API responses to improve performance and enable offline access:\n\n- **Location**: `~/.cache/gwanicli/cache.db`\n- **Storage**: SQLite database\n- **TTL**: Configurable expiration time\n- **Management**: Automatic cleanup of expired entries\n\n## Translations\n\nCommon translation identifiers:\n- `en.pickthall`: Pickthall English translation\n- `en.sahih`: Sahih International\n- `en.yusufali`: Abdullah Yusuf Ali\n- `ar.alafasy`: Arabic (Mishary Alafasy)\n\n## Development\n\n### Setup Development Environment\n```bash\ngit clone https://github.com/bhantsi/gwani-cli.git\ncd gwani-cli\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\npip install -e \".[dev]\"\n```\n\n### Run Tests\n```bash\npytest\n```\n\n### Code Formatting\n```bash\nblack qwanicli/\nflake8 qwanicli/\nmypy qwanicli/\n```\n\n## Project Structure\n\n```\nqwanicli/\n\u251c\u2500\u2500 __init__.py # Package initialization\n\u251c\u2500\u2500 cli.py # Main CLI entry point with Click commands\n\u251c\u2500\u2500 api_client.py # HTTP client for Quran API\n\u251c\u2500\u2500 config.py # Configuration management\n\u251c\u2500\u2500 cache.py # SQLite-based caching layer\n\u251c\u2500\u2500 formatter.py # Output formatting (console & JSON)\n\u2514\u2500\u2500 utils.py # Common utilities and error handling\n```\n\n## API\n\nGwaniCLI uses the [Al-Quran Cloud API](https://alquran.cloud/api) to fetch Quranic content.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [Al-Quran Cloud API](https://alquran.cloud/) for providing the Quranic data\n- [Click](https://click.palletsprojects.com/) for the excellent CLI framework\n- The open-source community for various Python packages used\n\n## Support\n\nIf you encounter any issues or have questions:\n\n1. Check the [Issues](https://github.com/bhantsi/gwani-cli/issues)\n2. Create a [new issue](https://github.com/bhantsi/gwani-cli/issues/new)\n\n---\n\n**Note**: This tool is for educational and personal use. Please respect the sacred nature of the Quranic content.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 GwaniCLI Contributors\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "A command-line interface for accessing Quranic verses and translations",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/bhantsi/gwani-cli#readme",
"Homepage": "https://github.com/bhantsi/gwani-cli",
"Issues": "https://github.com/bhantsi/gwani-cli/issues",
"Repository": "https://github.com/bhantsi/gwani-cli"
},
"split_keywords": [
"quran",
" islam",
" cli",
" terminal",
" verses",
" translation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6b9c4a976fb287cec45e83fa117eae1214ea151529f3ba6aaa63881a0437b958",
"md5": "2264109b3736b74a69b4a9083a034063",
"sha256": "adcf16938e0bd9b7a0c9deec269d1953e901637fc2cb4d9780e7952ec5746643"
},
"downloads": -1,
"filename": "gwanicli-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2264109b3736b74a69b4a9083a034063",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 30500,
"upload_time": "2025-08-05T13:53:47",
"upload_time_iso_8601": "2025-08-05T13:53:47.059292Z",
"url": "https://files.pythonhosted.org/packages/6b/9c/4a976fb287cec45e83fa117eae1214ea151529f3ba6aaa63881a0437b958/gwanicli-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "874bd537fb9c7b68d49beaf39ef2f5c1063a3881a3958be1ef476ec71ef37638",
"md5": "062331c3876858f83485608c945196c2",
"sha256": "c9a400b0dab034a4e6c7442f471054e5be13a55155f98e574e80b3d3a51c5f1a"
},
"downloads": -1,
"filename": "gwanicli-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "062331c3876858f83485608c945196c2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 27744,
"upload_time": "2025-08-05T13:53:48",
"upload_time_iso_8601": "2025-08-05T13:53:48.791413Z",
"url": "https://files.pythonhosted.org/packages/87/4b/d537fb9c7b68d49beaf39ef2f5c1063a3881a3958be1ef476ec71ef37638/gwanicli-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 13:53:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bhantsi",
"github_project": "gwani-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "toml",
"specs": [
[
">=",
"0.10.0"
]
]
},
{
"name": "arabic-reshaper",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "python-bidi",
"specs": [
[
">=",
"0.4.0"
]
]
}
],
"lcname": "gwanicli"
}
