Metadata-Version: 2.4
Name: nf-icons
Version: 0.1.1
Summary: Typed Python access to every Nerd Fonts glyph.
Project-URL: Homepage, https://github.com/programmersd21/nerdicons
Project-URL: Documentation, https://github.com/programmersd21/nerdicons#readme
Project-URL: Repository, https://github.com/programmersd21/nerdicons
Project-URL: Issues, https://github.com/programmersd21/nerdicons/issues
Project-URL: Changelog, https://github.com/programmersd21/nerdicons/blob/main/CHANGELOG.md
Author-email: programmersd21 <geniussantu1983@gmail.com>
License: MIT
License-File: LICENSE
Keywords: cli,glyphs,icons,nerd-fonts,terminal,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: rapidfuzz>=3.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pillow>=11; extra == 'dev'
Requires-Dist: pyright>=1.1; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img alt="header" src="https://shieldcn.dev/header/surface.svg?title=nerdicons&amp;subtitle=Typed%2C+autocompletable+access+to+every+glyph+in+Nerd+Fonts&amp;mode=dark&amp;theme=zinc&amp;border=false&amp;image=https%3A%2F%2Fmedia.istockphoto.com%2Fid%2F2264007209%2Fphoto%2Fabstract-blurry-gradient-background-with-soft-neon-light-waves-and-dark-cinematic-shadows.webp%3Fa%3D1%26b%3D1%26s%3D612x612%26w%3D0%26k%3D20%26c%3Dmon5kgCQqPSLx1831YweWElWubx7SipT0t2_PMkKq4M%3D" />
</p>

<p align="center">
  <a href="https://github.com/programmersd21/nerdicons">
    <img alt="Stars" src="https://shieldcn.dev/github/stars/programmersd21/nerdicons.svg?variant=secondary" />
  </a>
  <a href="https://github.com/programmersd21/nerdicons/forks">
    <img alt="Forks" src="https://shieldcn.dev/github/forks/programmersd21/nerdicons.svg?variant=secondary" />
  </a>
  <a href="https://github.com/programmersd21/nerdicons/actions/workflows/ci.yml">
    <img alt="CI" src="https://shieldcn.dev/github/ci/programmersd21/nerdicons.svg?variant=secondary" />
  </a>
  <a href="https://github.com/programmersd21/nerdicons/issues">
    <img alt="Issues" src="https://shieldcn.dev/github/issues/programmersd21/nerdicons.svg?variant=secondary" />
  </a>
  <a href="https://github.com/programmersd21/nerdicons/blob/main/LICENSE">
    <img alt="License" src="https://shieldcn.dev/github/license/programmersd21/nerdicons.svg?variant=secondary" />
  </a>
  <a href="https://github.com/programmersd21/nerdicons/releases">
    <img alt="Release" src="https://shieldcn.dev/github/release/programmersd21/nerdicons.svg?variant=secondary" />
  </a>
  <a href="https://github.com/sponsors/programmersd21">
    <img alt="Sponsor" src="https://shieldcn.dev/badge/%E2%9D%A4%20Sponsor-this%20project-FF69B4.svg?variant=secondary&mode=light" />
  </a>
  <a href="https://pypi.org/project/nf-icons/">
    <img alt="PyPI Version" src="https://shieldcn.dev/pypi/nf-icons.svg?variant=branded&mode=light" />
  </a>
  <a href="https://pypi.org/project/nf-icons/">
    <img alt="PyPI Downloads" src="https://shieldcn.dev/pypi/dm/nf-icons.svg?variant=secondary&mode=light" />
  </a>
  <a href="https://pypi.org/project/nf-icons/">
    <img alt="PyPI License" src="https://shieldcn.dev/pypi/license/nf-icons.svg?variant=outline&mode=light" />
  </a>
</p>

<p align="center">
  Typed, autocompletable access to every <a href="https://www.nerdfonts.com/">Nerd Fonts</a> glyph — generated from a pinned <code>glyphnames.json</code> snapshot.<br/>
  Attribute access · exact lookups · fuzzy search · interactive terminal browser.
</p>

---

## Installation

```bash
pip install nf-icons
```

Configure a [Nerd Font](https://www.nerdfonts.com/font-downloads) in your terminal to render the glyphs.

## Python API

```python
from nerdicons import icons

# Attribute access — fully typed and autocompletable
print(icons.fa.github)
print(icons.md.home.unicode())  # U+F015

# Exact lookup: by canonical name, raw glyph, or codepoint
icon = icons.get("fa-github")
icon = icons["fa-github"]  # subscript is equivalent
icon = icons.from_codepoint("f09b")

# Fuzzy search
results = icons.search("rust", limit=5)

# Membership test
assert "fa-github" in icons

# Iterate all icons
for icon in icons:
    print(icon.namespace, icon.name)

# List available namespaces
print(icons.namespaces())  # ('cod', 'custom', 'dev', ...)
```

![demo](https://raw.githubusercontent.com/programmersd21/nerdicons/main/assets/nerdicons_sheet.png)

### `Icon` fields

| Field | Type | Example |
| --- | --- | --- |
| `name` | `str` | `"github"` |
| `glyph` | `str` | `""` |
| `codepoint` | `str` | `"f09b"` |
| `icon_set` | `str` | `"Font Awesome"` |
| `namespace` | `str` | `"fa"` |

`str(icon)` returns the glyph. `icon.unicode()` returns `"U+F09B"`.

### `IconRegistry` (the `icons` object)

| Method / operator | Description |
| --- | --- |
| `icons.get(query)` | Exact lookup by name, glyph, or codepoint. Raises `IconNotFoundError`. |
| `icons[query]` | Subscript — delegates to `get`. |
| `icons.from_codepoint(cp)` | Lookup by hex codepoint (with or without `U+`). |
| `icons.search(query, limit=10)` | Fuzzy-ranked list of matching icons. |
| `icons.namespaces()` | Sorted tuple of available namespace keys. |
| `query in icons` | Membership test (name, glyph, or codepoint). |
| `for icon in icons` | Iterate all icons. |
| `len(icons)` | Total icon count. |

## CLI

```console
$ nerdicons search rust
$ nerdicons search rust --limit 5
$ nerdicons search rust --json
$ nerdicons search rust --format "{glyph}  {codepoint}"
$ nerdicons search rust --interactive

$ nerdicons get fa-github
$ nerdicons get fa-github --json

$ nerdicons browse
$ nerdicons browse rust

$ nerdicons copy fa-github

$ nerdicons stats
$ nerdicons doctor
$ nerdicons --version
```

### Interactive browser

`browse` and `search --interactive` open a centered terminal UI with no extra dependencies:

| Key | Action |
| --- | --- |
| Type | Filter results |
| `↑` / `↓` or `k` / `j` | Move selection |
| `Enter` | Copy selected glyph to clipboard |
| `Esc` or `q` | Quit |
| Mouse wheel | Scroll |
| Double-click | Copy |

Clipboard support uses `wl-copy`, `pbcopy`, or `xclip` — whichever is on `PATH`.
Respects the `NO_COLOR` environment variable.

<p align="center">
  <img alt="nerdicons TUI demo" src="https://raw.githubusercontent.com/programmersd21/nerdicons/main/assets/demo.jpg" width="960" />
</p>

## Namespaces

| Key | Icon set | Count |
| --- | --- | ---: |
| `md` | Material Design Icons | 6,896 |
| `fa` | Font Awesome | 1,818 |
| `dev` | Devicons | 613 |
| `cod` | Codicons | 540 |
| `oct` | Octicons | 310 |
| `weather` | Weather Icons | 228 |
| `fae` | Font Awesome Extension | 170 |
| `seti` | Seti UI | 167 |
| `linux` | Font Linux | 134 |
| `custom` | Custom | 45 |
| `ple` | Powerline Extra | 34 |
| `extra` | Extra Symbols | 12 |
| `pom` | Pomodoro | 11 |
| `pl` | Powerline | 9 |
| `iec` | IEC Power Symbols | 5 |
| `indent` | Indentation | 2 |
| `indentation` | Indentation | 1 |

Pinned to **Nerd Fonts 3.5.0** — **10,995** icons total.

## Updating upstream

```bash
python generator/generate.py            # regenerate from checked-in snapshot
python generator/generate.py --refresh   # fetch pinned tag first
python generator/generate.py --check     # verify files are current (CI mode)
```

Change `PINNED_VERSION` in `generator/generate.py` to target a new Nerd Fonts release.
Review the manifest diff carefully — codepoints can change between releases.

## Examples

Runnable examples in [`examples/`](examples/):

```bash
python examples/basic.py
python examples/lookup.py
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Quick start:

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
ruff format . && ruff check . && mypy src generator tests && pyright && pytest
```


---

<p align="center">
  <a href="https://repostars.dev/?repos=programmersd21%2Fnerdicons&theme=espresso">
    <img src="https://repostars.dev/api/embed?repo=programmersd21%2Fnerdicons&theme=espresso" alt="RepoStars" />
  </a>
</p>
