Metadata-Version: 2.4
Name: emoji-lexicon
Version: 0.1.2
Summary: A build-time generated emoji lexicon for Python
Project-URL: Homepage, https://github.com/kimikato/emoji-lexicon
Project-URL: Source, https://github.com/kimikato/emoji-lexicon
Project-URL: Issues, https://github.com/kimikato/emoji-lexicon/issues
Project-URL: Documentation, https://github.com/kimikato/emoji-lexicon/tree/main/docs
Author: Kiminori KATO
License: MIT License
        
        Copyright (c) 2025 Kiminori Kato
        
        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:
        
        [以下 MIT License の全文 …]
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: msgpack>=1.0.7
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: build; extra == 'dev'
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# emoji-lexicon

![Tests](https://github.com/kimikato/emoji-lexicon/actions/workflows/tests.yml/badge.svg?branch=main)
[![coverage](https://img.shields.io/codecov/c/github/kimikato/emoji-lexicon/main?label=coverage&logo=codecov)](https://codecov.io/gh/kimikato/emoji-lexicon)
[![PyPI version](https://img.shields.io/pypi/v/emoji-lexicon.svg)](https://pypi.org/project/emoji-lexicon/)
[![Python](https://img.shields.io/pypi/pyversions/emoji-lexicon.svg)](https://pypi.org/project/emoji-lexicon/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

🚀 **emoji-lexicon** is a fast, build-time generated emoji lexicon for Python,
powered by Unicode emoji-test and CLDR annotations.

## Features

-   Fast emoji lookup by short name, alias, or tag
-   Designed for CLI, IME, and dictionary tools
-   Unicode / CLDR based canonical data
-   Build-time normalization, runtime zero-cost lookup
-   Optional gemoji-compatible export

## Requirements

-   Python 3.12+

## Installation

```bash
pip install emoji-lexicon
```

## Usage

```python
from emoji_lexicon import get_catalog

catalog = get_catalog()

# lookup by short name or alias
catalog.get("smile")
# -> Emoji | None

# Slack / gemoji style
catalog.get(":smile:")

# lookup by emoji character
catalog.get_by_char("😁")
# -> Emoji | None

# get all emojis
catalog.get_all()

# total emoji count
len(catalog)

# iterator
for emoji in catalog:
	print(emoji.char, emoji.short_name)
```

### `.search()` , `.find()`

```python
# partial match (short_name / alias / tag)
catalog.search("happy")
# -> tuple[Emoji, ...]

# alias of .search()
catalog.find("happy")
# -> tuple[Emoji, ...]
```

`.search()` and `.find()` perform partial matching and return multiple emojis.
`.find()` is a user-facing alias of `.search()`.

### `.groups()`, `.subgroups()`

```python
from emoji_lexicon import get_catalog
catalog = get_catalog()

# available emoji groups
catalog.groups()

# available emoji subgroups
catalog.subgroups()

```

Application examples:

-   Categories UI
-   IME candidate narrowing down
-   emoji picker

## Design philosophy

-   runtime zero-cost
-   immutable catalog
-   Pythonic & typed

## License

MIT License
© 2026 Kiminori Kato
