# NerdMan 🎨
A powerful Python library and command-line tool for working with Nerd Fonts icons. NerdMan provides easy access to thousands of Nerd Fonts icons with search, filtering, and export capabilities.
## 🚀 Features
- **🔍 Icon Search**: Search icons by name with literal or regex patterns
- **📊 Icon Information**: Get detailed information about any icon including Unicode codes
- **🎲 Random Icons**: Generate random icons for testing or inspiration
- **📁 Category Organization**: Browse icons organized by prefix categories
- **🔗 Similar Icon Finding**: Find icons with similar names using Levenshtein distance
- **💾 Export Capabilities**: Export icon lists in multiple formats (simple, detailed, CSV)
- **🌐 HTML Cheatsheet**: Generate beautiful, interactive HTML cheatsheets
- **🔄 Auto-Updates**: Automatically update icon data from Nerd Fonts repository
- **⚙️ Configurable**: Flexible configuration with multiple update modes
- **🎯 Unicode Search**: Find icons by Unicode code points
- **✅ Validation**: Validate icon names and check data integrity
## 📦 Installation
### From PyPI (Recommended)
```bash
pip install nerdman
```
### From Source
```bash
git clone https://github.com/yourusername/nerdman.git
cd nerdman
pip install -e .
```
## 🏃♂️ Quick Start
### As a Python Library
```python
import nerdman
# Get an icon by name
home_icon = nerdman.icon("cod-home")
print(f"Home icon: {home_icon}")
# Search for icons
file_icons = nerdman.search_icons("file")
print(f"Found {len(file_icons)} file-related icons")
# Get detailed icon information
info = nerdman.icon_data("dev-git")
if info:
print(f"Name: {info['name']}")
print(f"Character: {info['char']}")
print(f"Unicode: {info['code']}")
# Get random icons
random_icons = nerdman.get_random_icons(5)
for name, char in random_icons:
print(f"{name}: {char}")
```
### Command Line Interface
```bash
# Show help
nerdman help
# Show specific icon details
nerdman show cod-home
# Generate HTML cheatsheet
nerdman cheat
# Export icons to file
nerdman export simple
nerdman export detailed
nerdman export csv
# Check for updates
nerdman update
# View current configuration
nerdman view-config
# Verify JSON data integrity
nerdman verify-json
# Show version information
nerdman version
```
## 📚 API Reference
### Core Functions
#### `icon(name: str) -> str`
Returns the icon character for a given name, or '?' if not found.
```python
home_icon = nerdman.icon("cod-home")
# Returns: ''
```
#### `icon_data(name: str) -> dict | None`
Returns detailed information about an icon.
```python
info = nerdman.icon_data("cod-home")
# Returns: {
# 'name': 'cod-home',
# 'char': '',
# 'rendered': '',
# 'code': 'ea60'
# }
```
#### `search_icons(query: str, use_regex: bool = False) -> dict`
Search for icons matching a query.
```python
# Literal search
results = nerdman.search_icons("home")
# Regex search
results = nerdman.search_icons(r"file.*", use_regex=True)
```
#### `get_categories() -> Dict[str, List[str]]`
Get icons organized by category prefixes.
```python
categories = nerdman.get_categories()
print(f"Categories: {list(categories.keys())}")
```
#### `get_random_icons(count: int = 5) -> List[Tuple[str, str]]`
Get random icons for testing or inspiration.
```python
random_icons = nerdman.get_random_icons(10)
```
#### `find_similar_icons(name: str, limit: int = 10) -> List[Tuple[str, str, int]]`
Find icons with similar names using Levenshtein distance.
```python
similar = nerdman.find_similar_icons("cod-home", limit=5)
```
### Export Functions
#### `export_icon_list(filename: str = None, format_type: str = "simple")`
Export icons to a file in various formats.
```python
# Export simple list
nerdman.export_icon_list("icons.txt", "simple")
# Export detailed information
nerdman.export_icon_list("icons_detailed.txt", "detailed")
# Export as CSV
nerdman.export_icon_list("icons.csv", "csv")
```
#### `create_icon_cheatsheet(output_file: str = "nerd_fonts_cheatsheet.html")`
Generate an interactive HTML cheatsheet.
```python
nerdman.create_icon_cheatsheet("my_cheatsheet.html")
```
### Update Functions
#### `update_nerdfonts_data(url: str = None, force: bool = False) -> bool`
Update the Nerd Fonts data.
```python
# Update from default source
success = nerdman.update_nerdfonts_data()
# Force update even if current
success = nerdman.update_nerdfonts_data(force=True)
```
#### `check_for_updates(url: str = None) -> Dict[str, Any]`
Check for available updates without downloading.
```python
update_info = nerdman.check_for_updates()
if update_info['update_available']:
print("Update available!")
```
### Utility Functions
#### `validate_icon_name(name: str) -> bool`
Check if an icon name exists.
```python
exists = nerdman.validate_icon_name("cod-home") # True
```
#### `get_icon_count() -> int`
Get the total number of available icons.
```python
total = nerdman.get_icon_count()
print(f"Total icons: {total}")
```
#### `search_by_unicode(unicode_code: str) -> Optional[Tuple[str, str]]`
Find an icon by its Unicode code.
```python
result = nerdman.search_by_unicode("ea60")
if result:
name, char = result
print(f"Found: {name} = {char}")
```
## ⚙️ Configuration
NerdMan creates a configuration file at `~/.nerdman/config.ini` with the following options:
```ini
[updates]
update_mode = notify
```
### Update Modes
- **auto**: Automatically download updates when available
- **notify**: Prompt user before downloading updates (default)
- **manual**: Never auto-update, require explicit calls
## 🎨 HTML Cheatsheet
The HTML cheatsheet feature generates a beautiful, interactive webpage with:
- **Searchable Interface**: Real-time search filtering
- **Category Organization**: Icons grouped by prefixes
- **Copy to Clipboard**: Click any icon to copy its name
- **Responsive Design**: Works on desktop and mobile
- **Statistics**: Shows total icons and categories
- **Modern UI**: Beautiful gradients and smooth animations
## 📁 File Structure
After installation, NerdMan creates the following directory structure:
```plaintext
~/nerdman/
├── config.ini # Configuration file
├── nerdfonts_complete.json # Icon data (auto-downloaded)
└── nerdfonts_complete.json.backup # Backup of previous data
```
## 🔧 Development
### Setting up for Development
```bash
git clone https://github.com/yourusername/nerdman.git
cd nerdman
pip install -e ".[dev]"
```
### Running Tests
```bash
python -m pytest tests/
```
### Building Documentation
```bash
python -m sphinx docs/ docs/_build/
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
### Development Guidelines
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [Nerd Fonts](https://www.nerdfonts.com/) for providing the amazing icon fonts
- [Ryan L McIntyre](https://github.com/ryanoasis) for creating and maintaining Nerd Fonts
- The open-source community for inspiration and feedback
## 🐛 Issue Reporting
If you encounter any issues or have feature requests, please [open an issue](https://github.com/yourusername/nerdman/issues) on GitHub.
## 📊 Statistics
- **Supported Icons**: 8000+ icons from Nerd Fonts
- **Categories**: 20+ icon categories (cod, dev, fa, oct, etc.)
- **Export Formats**: 3 formats (simple, detailed, CSV)
- **Search Types**: Literal and regex search
- **Python Versions**: 3.7+
---
**Made with ❤️ for the developer community**
Raw data
{
"_id": null,
"home_page": "https://github.com/mralfiem591/nerdman",
"name": "nerdman",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Alfie McCabe <iamamccabe@gmail.com>",
"keywords": "nerd-fonts, icons, fonts, cli, terminal, unicode, symbols, glyphs, developer-tools, font-icons",
"author": "Alfie McCabe",
"author_email": "Alfie McCabe <iamamccabe@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/fd/e2/7dee1938732eface03b08ef78df14bc0fdef760fe890b65366286dd8ad01/nerdman-0.1.1.tar.gz",
"platform": "any",
"description": "# NerdMan \ud83c\udfa8\n\nA powerful Python library and command-line tool for working with Nerd Fonts icons. NerdMan provides easy access to thousands of Nerd Fonts icons with search, filtering, and export capabilities.\n\n## \ud83d\ude80 Features\n\n- **\ud83d\udd0d Icon Search**: Search icons by name with literal or regex patterns\n- **\ud83d\udcca Icon Information**: Get detailed information about any icon including Unicode codes\n- **\ud83c\udfb2 Random Icons**: Generate random icons for testing or inspiration\n- **\ud83d\udcc1 Category Organization**: Browse icons organized by prefix categories\n- **\ud83d\udd17 Similar Icon Finding**: Find icons with similar names using Levenshtein distance\n- **\ud83d\udcbe Export Capabilities**: Export icon lists in multiple formats (simple, detailed, CSV)\n- **\ud83c\udf10 HTML Cheatsheet**: Generate beautiful, interactive HTML cheatsheets\n- **\ud83d\udd04 Auto-Updates**: Automatically update icon data from Nerd Fonts repository\n- **\u2699\ufe0f Configurable**: Flexible configuration with multiple update modes\n- **\ud83c\udfaf Unicode Search**: Find icons by Unicode code points\n- **\u2705 Validation**: Validate icon names and check data integrity\n\n## \ud83d\udce6 Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install nerdman\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/yourusername/nerdman.git\ncd nerdman\npip install -e .\n```\n\n## \ud83c\udfc3\u200d\u2642\ufe0f Quick Start\n\n### As a Python Library\n\n```python\nimport nerdman\n\n# Get an icon by name\nhome_icon = nerdman.icon(\"cod-home\")\nprint(f\"Home icon: {home_icon}\")\n\n# Search for icons\nfile_icons = nerdman.search_icons(\"file\")\nprint(f\"Found {len(file_icons)} file-related icons\")\n\n# Get detailed icon information\ninfo = nerdman.icon_data(\"dev-git\")\nif info:\n print(f\"Name: {info['name']}\")\n print(f\"Character: {info['char']}\")\n print(f\"Unicode: {info['code']}\")\n\n# Get random icons\nrandom_icons = nerdman.get_random_icons(5)\nfor name, char in random_icons:\n print(f\"{name}: {char}\")\n```\n\n### Command Line Interface\n\n```bash\n# Show help\nnerdman help\n\n# Show specific icon details\nnerdman show cod-home\n\n# Generate HTML cheatsheet\nnerdman cheat\n\n# Export icons to file\nnerdman export simple\nnerdman export detailed\nnerdman export csv\n\n# Check for updates\nnerdman update\n\n# View current configuration\nnerdman view-config\n\n# Verify JSON data integrity\nnerdman verify-json\n\n# Show version information\nnerdman version\n```\n\n## \ud83d\udcda API Reference\n\n### Core Functions\n\n#### `icon(name: str) -> str`\n\nReturns the icon character for a given name, or '?' if not found.\n\n```python\nhome_icon = nerdman.icon(\"cod-home\")\n# Returns: ''\n```\n\n#### `icon_data(name: str) -> dict | None`\n\nReturns detailed information about an icon.\n\n```python\ninfo = nerdman.icon_data(\"cod-home\")\n# Returns: {\n# 'name': 'cod-home',\n# 'char': '',\n# 'rendered': '',\n# 'code': 'ea60'\n# }\n```\n\n#### `search_icons(query: str, use_regex: bool = False) -> dict`\n\nSearch for icons matching a query.\n\n```python\n# Literal search\nresults = nerdman.search_icons(\"home\")\n\n# Regex search\nresults = nerdman.search_icons(r\"file.*\", use_regex=True)\n```\n\n#### `get_categories() -> Dict[str, List[str]]`\n\nGet icons organized by category prefixes.\n\n```python\ncategories = nerdman.get_categories()\nprint(f\"Categories: {list(categories.keys())}\")\n```\n\n#### `get_random_icons(count: int = 5) -> List[Tuple[str, str]]`\n\nGet random icons for testing or inspiration.\n\n```python\nrandom_icons = nerdman.get_random_icons(10)\n```\n\n#### `find_similar_icons(name: str, limit: int = 10) -> List[Tuple[str, str, int]]`\n\nFind icons with similar names using Levenshtein distance.\n\n```python\nsimilar = nerdman.find_similar_icons(\"cod-home\", limit=5)\n```\n\n### Export Functions\n\n#### `export_icon_list(filename: str = None, format_type: str = \"simple\")`\n\nExport icons to a file in various formats.\n\n```python\n# Export simple list\nnerdman.export_icon_list(\"icons.txt\", \"simple\")\n\n# Export detailed information\nnerdman.export_icon_list(\"icons_detailed.txt\", \"detailed\")\n\n# Export as CSV\nnerdman.export_icon_list(\"icons.csv\", \"csv\")\n```\n\n#### `create_icon_cheatsheet(output_file: str = \"nerd_fonts_cheatsheet.html\")`\n\nGenerate an interactive HTML cheatsheet.\n\n```python\nnerdman.create_icon_cheatsheet(\"my_cheatsheet.html\")\n```\n\n### Update Functions\n\n#### `update_nerdfonts_data(url: str = None, force: bool = False) -> bool`\n\nUpdate the Nerd Fonts data.\n\n```python\n# Update from default source\nsuccess = nerdman.update_nerdfonts_data()\n\n# Force update even if current\nsuccess = nerdman.update_nerdfonts_data(force=True)\n```\n\n#### `check_for_updates(url: str = None) -> Dict[str, Any]`\n\nCheck for available updates without downloading.\n\n```python\nupdate_info = nerdman.check_for_updates()\nif update_info['update_available']:\n print(\"Update available!\")\n```\n\n### Utility Functions\n\n#### `validate_icon_name(name: str) -> bool`\n\nCheck if an icon name exists.\n\n```python\nexists = nerdman.validate_icon_name(\"cod-home\") # True\n```\n\n#### `get_icon_count() -> int`\n\nGet the total number of available icons.\n\n```python\ntotal = nerdman.get_icon_count()\nprint(f\"Total icons: {total}\")\n```\n\n#### `search_by_unicode(unicode_code: str) -> Optional[Tuple[str, str]]`\n\nFind an icon by its Unicode code.\n\n```python\nresult = nerdman.search_by_unicode(\"ea60\")\nif result:\n name, char = result\n print(f\"Found: {name} = {char}\")\n```\n\n## \u2699\ufe0f Configuration\n\nNerdMan creates a configuration file at `~/.nerdman/config.ini` with the following options:\n\n```ini\n[updates]\nupdate_mode = notify\n```\n\n### Update Modes\n\n- **auto**: Automatically download updates when available\n- **notify**: Prompt user before downloading updates (default)\n- **manual**: Never auto-update, require explicit calls\n\n## \ud83c\udfa8 HTML Cheatsheet\n\nThe HTML cheatsheet feature generates a beautiful, interactive webpage with:\n\n- **Searchable Interface**: Real-time search filtering\n- **Category Organization**: Icons grouped by prefixes\n- **Copy to Clipboard**: Click any icon to copy its name\n- **Responsive Design**: Works on desktop and mobile\n- **Statistics**: Shows total icons and categories\n- **Modern UI**: Beautiful gradients and smooth animations\n\n## \ud83d\udcc1 File Structure\n\nAfter installation, NerdMan creates the following directory structure:\n\n```plaintext\n~/nerdman/\n\u251c\u2500\u2500 config.ini # Configuration file\n\u251c\u2500\u2500 nerdfonts_complete.json # Icon data (auto-downloaded)\n\u2514\u2500\u2500 nerdfonts_complete.json.backup # Backup of previous data\n```\n\n## \ud83d\udd27 Development\n\n### Setting up for Development\n\n```bash\ngit clone https://github.com/yourusername/nerdman.git\ncd nerdman\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npython -m pytest tests/\n```\n\n### Building Documentation\n\n```bash\npython -m sphinx docs/ docs/_build/\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n### Development Guidelines\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- [Nerd Fonts](https://www.nerdfonts.com/) for providing the amazing icon fonts\n- [Ryan L McIntyre](https://github.com/ryanoasis) for creating and maintaining Nerd Fonts\n- The open-source community for inspiration and feedback\n\n## \ud83d\udc1b Issue Reporting\n\nIf you encounter any issues or have feature requests, please [open an issue](https://github.com/yourusername/nerdman/issues) on GitHub.\n\n## \ud83d\udcca Statistics\n\n- **Supported Icons**: 8000+ icons from Nerd Fonts\n- **Categories**: 20+ icon categories (cod, dev, fa, oct, etc.)\n- **Export Formats**: 3 formats (simple, detailed, CSV)\n- **Search Types**: Literal and regex search\n- **Python Versions**: 3.7+\n\n---\n\n**Made with \u2764\ufe0f for the developer community**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A powerful Python library and CLI tool for working with Nerd Fonts icons",
"version": "0.1.1",
"project_urls": {
"Bug Reports": "https://github.com/mralfiem591/nerdman/issues",
"Changelog": "https://github.com/mralfiem591/nerdman/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/mralfiem591/nerdman#readme",
"Homepage": "https://github.com/mralfiem591/nerdman",
"Repository": "https://github.com/mralfiem591/nerdman.git"
},
"split_keywords": [
"nerd-fonts",
" icons",
" fonts",
" cli",
" terminal",
" unicode",
" symbols",
" glyphs",
" developer-tools",
" font-icons"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "84328ba66cfd1845f409f48d00799ab61ba02ab7a08326300736c4b636f6f270",
"md5": "c42d710dc397c421055956a1b6ee810c",
"sha256": "3cbfaf06eb16d40a935b67b2fb5690d021d731cd2075cf1daf7a3085df3cc62c"
},
"downloads": -1,
"filename": "nerdman-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c42d710dc397c421055956a1b6ee810c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 17903,
"upload_time": "2025-07-12T14:16:48",
"upload_time_iso_8601": "2025-07-12T14:16:48.631656Z",
"url": "https://files.pythonhosted.org/packages/84/32/8ba66cfd1845f409f48d00799ab61ba02ab7a08326300736c4b636f6f270/nerdman-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fde27dee1938732eface03b08ef78df14bc0fdef760fe890b65366286dd8ad01",
"md5": "f37028a40909b6749b11a01a5e4a350a",
"sha256": "f283d4e24e9b87d08864121057a25b26080aa45391953d2141067584d3239079"
},
"downloads": -1,
"filename": "nerdman-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f37028a40909b6749b11a01a5e4a350a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 24568,
"upload_time": "2025-07-12T14:16:49",
"upload_time_iso_8601": "2025-07-12T14:16:49.769571Z",
"url": "https://files.pythonhosted.org/packages/fd/e2/7dee1938732eface03b08ef78df14bc0fdef760fe890b65366286dd8ad01/nerdman-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 14:16:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mralfiem591",
"github_project": "nerdman",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "nerdman"
}
JSON
