API reference

Everything lives in the emojet module, and all optional parameters are keyword-only.

Functions that take a language parameter accept any language code from LANGUAGES, or "alias" for the English aliases used on GitHub and Slack, like :thumbsup:. Unsupported language codes raise ValueError.

Emoji names include their delimiters, ":" by default, so a full name looks like :thumbs_up:. The names and data match those of the emoji package - see History and benchmarks for how the two libraries relate.

Strings must be well-formed Unicode: lone surrogates raise UnicodeEncodeError.

Conversion

emojet.emojize(string, *, language='en', delimiters=(':', ':'), variant=None)

Return string with delimited emoji names replaced by the emoji themselves. Unknown names are left unchanged.

>>> emojet.emojize("Python is fun :thumbs_up:")
'Python is fun 👍'
>>> emojet.emojize("Python is fun :thumbsup:", language="alias")
'Python is fun 👍'
>>> emojet.emojize("Python ist toll :daumen_hoch:", language="de")
'Python ist toll 👍'
>>> emojet.emojize("An :unknown_name: stays")
'An :unknown_name: stays'

delimiters is a tuple of two non-empty strings that surround each name:

>>> emojet.emojize("Python is fun __thumbs_up__", delimiters=("__", "__"))
'Python is fun 👍'

variant may be "text_type" or "emoji_type" to force a text or emoji presentation, for emoji that support both. It appends the relevant Unicode variation selector, U+FE0E or U+FE0F:

>>> emojet.emojize(":red_heart:", variant="text_type")
'❤︎'
>>> emojet.emojize(":red_heart:", variant="emoji_type")
'❤️'

emojet.demojize(string, *, language='en', delimiters=(':', ':'))

Return string with emoji replaced by their delimited names. The inverse of emojize(): emojizing the result returns the original string.

>>> emojet.demojize("Python is fun 👍")
'Python is fun :thumbs_up:'
>>> emojet.demojize("Python is fun 👍", language="de")
'Python is fun :daumen_hoch:'
>>> emojet.demojize("Python is fun 👍", delimiters=("__", "__"))
'Python is fun __thumbs_up__'

Matching is greedy: at each position, the longest known emoji sequence wins. Multi-code-point sequences like family emoji or flags convert to a single name:

>>> emojet.demojize("👨‍👩‍👧‍👦")
':family_man_woman_girl_boy:'
>>> emojet.demojize("🇫🇷")
':France:'

emojet.replace_emoji(string, replace='')

Return string with emoji replaced. replace may be a string, or a callable that receives each emoji and returns its replacement.

>>> emojet.replace_emoji("Python is fun 👍")
'Python is fun '
>>> emojet.replace_emoji("Python is fun 👍", replace="?")
'Python is fun ?'
>>> emojet.replace_emoji("Python is fun 👍", replace=lambda e: f"<{e}>")
'Python is fun <👍>'

Searching

emojet.emoji_list(string)

Return a list of dicts describing each emoji in string, with its start and end indexes.

>>> emojet.emoji_list("Unicode is tricky 😯, very tricky 🤯")
[{'emoji': '😯', 'match_start': 18, 'match_end': 19}, {'emoji': '🤯', 'match_start': 33, 'match_end': 34}]

emojet.distinct_emoji_list(string)

Return the distinct emoji in string, in order of first appearance.

>>> emojet.distinct_emoji_list("Some emoji repeat 😁😁👍😁")
['😁', '👍']

emojet.emoji_count(string, *, unique=False)

Return the number of emoji in string. Pass unique=True to count each distinct emoji once.

>>> emojet.emoji_count("Some emoji repeat 😁😁👍😁")
4
>>> emojet.emoji_count("Some emoji repeat 😁😁👍😁", unique=True)
2

emojet.is_emoji(string)

Return whether string is exactly one emoji.

>>> emojet.is_emoji("👍")
True
>>> emojet.is_emoji("👍👍")
False

emojet.purely_emoji(string)

Return whether string consists only of emoji.

>>> emojet.purely_emoji("👍👍")
True
>>> emojet.purely_emoji("Python 👍")
False

Lookup

emojet.version(string)

Return the Unicode emoji version of the first emoji or delimited English name in string, as a float. Versions match those in Unicode’s emoji-test.txt, where 0.6 and 0.7 mark emoji that predate the versioned releases. Raises ValueError if string contains no emoji.

>>> emojet.version("👍")
0.6
>>> emojet.version("Python 🤯")
5.0
>>> emojet.version(":thumbs_up:")
0.6

emojet.get_emoji_by_name(name, *, language='en')

Return the emoji for an exact delimited name, or None if the name is unknown.

>>> emojet.get_emoji_by_name(":thumbs_up:")
'👍'
>>> emojet.get_emoji_by_name(":daumen_hoch:", language="de")
'👍'
>>> emojet.get_emoji_by_name(":not_a_real_name:") is None
True

emojet.emoji_status(string)

Return the Unicode qualification status of an emoji: "component", "fully_qualified", "minimally_qualified", or "unqualified". Raises ValueError if string is not exactly one emoji.

>>> emojet.emoji_status("👍")
'fully_qualified'
>>> emojet.emoji_status("☺")
'unqualified'
>>> emojet.emoji_status("\N{EMOJI MODIFIER FITZPATRICK TYPE-1-2}")
'component'

Data

emojet.LANGUAGES

The supported language codes, as a list of strings.

>>> sorted(emojet.LANGUAGES)
['ar', 'de', 'en', 'es', 'fa', 'fr', 'id', 'it', 'ja', 'ko', 'pt', 'ru', 'tr', 'zh']

emojet.UNICODE_VERSION

The Unicode version that the emoji data was built from, as a string.

>>> emojet.UNICODE_VERSION
'17.0.0'