emoji¶
emoji supports Python 3.6+. The last version to support Python 2.7 and 3.5 was v2.4.0.
Usage and Examples¶
The main purpose of this package is converting Unicode emoji to emoji names and vice versa with emojize() and demojize() .
The entire set of Emoji codes as defined by the Unicode consortium is supported in addition to a bunch of aliases. By default, only the official list is enabled but doing emoji.emojize(language=’alias’) enables both the full list and aliases.
>>> print(emoji.emojize('Python is :thumbs_up:')) Python is 👍 >>> print(emoji.emojize('Python is :thumbsup:', language='alias')) Python is 👍 >>> print(emoji.demojize('Python is 👍')) Python is :thumbs_up: >>> print(emoji.emojize("Python is fun :red_heart:", variant="text_type")) Python is fun ❤︎ >>> print(emoji.emojize("Python is fun :red_heart:", variant="emoji_type")) Python is fun ❤️
Languages¶
By default, the language is English ( language=’en’ ) but also supported languages are:
Spanish ( ‘es’ ), Portuguese ( ‘pt’ ), Italian ( ‘it’ ), French ( ‘fr’ ), German ( ‘de’ ), Farsi/Persian ( ‘fa’ )
>>> print(emoji.emojize('Python es :pulgar_hacia_arriba:', language='es')) Python es 👍 >>> print(emoji.demojize('Python es 👍', language='es')) Python es :pulgar_hacia_arriba: >>> print(emoji.emojize("Python é :polegar_para_cima:", language='pt')) Python é 👍 >>> print(emoji.demojize("Python é 👍", language='pt')) Python é :polegar_para_cima:
Extracting emoji¶
The function analyze() finds all emoji in string and yields the emoji together with its position and the available meta information about the emoji.
analyze() returns a generator that yields each emoji, so you need to iterate or convert the output to a list.
>>> first_token = next(emoji.analyze('Python is 👍')) Token(chars='👍', value=EmojiMatch(👍, 10:11)) >>> emoji_match = first_token.value EmojiMatch(👍, 10:11) >>> emoji_match.data >>> list(emoji.analyze('A 👩🚀 aboard a 🚀')) [Token(chars='👩\u200d🚀', value=EmojiMatch(👩🚀, 2:5)), Token(chars='🚀', value=EmojiMatch(🚀, 15:16))] >>> list(emoji.analyze('A👩🚀B🚀', non_emoji=True)) [Token(chars='A', value='A'), Token(chars='👩\u200d🚀', value=EmojiMatch(👩🚀, 1:4)), Token(chars='B', value='B'), Token(chars='🚀', value=EmojiMatch(🚀, 5:6))]
The parameter join_emoji controls whether non-RGI emoji are handled as a single token or as multiple emoji:
>>> list(emoji.analyze('👨👩🏿👧🏻👦🏾', join_emoji=True)) [Token(chars='👨\u200d👩🏿\u200d👧🏻\u200d👦🏾', value=EmojiMatchZWJNonRGI(👨👩🏿👧🏻👦🏾, 0:10))] >>> list(emoji.analyze('👨👩🏿👧🏻👦🏾', join_emoji=False)) [Token(chars='👨', value=EmojiMatch(👨, 0:1)), Token(chars='👩🏿', value=EmojiMatch(👩🏿, 2:4)), Token(chars='👧🏻', value=EmojiMatch(👧🏻, 5:7)), Token(chars='👦🏾', value=EmojiMatch(👦🏾, 8:10))]
The function emoji_list() finds all emoji in string and their position. Keep in mind that an emoji can span over multiple characters:
>>> emoji.emoji_list('Python is 👍') [] >>> emoji.emoji_list('A 👩🚀 aboard a 🚀') [, ]
To retrieve the distinct set of emoji from a string, use distinct_emoji_list() :
>>> emoji.distinct_emoji_list('Some emoji: 🌍, 😂, 😃, 😂, 🌍, 🌦️') ['😃', '😂', '🌦️', '🌍']
To count the number of emoji in a string, use emoji_count() :
>>> emoji.emoji_count('Some emoji: 🌍, 😂, 😃, 😂, 🌍, 🌦️') 6 >>> emoji.emoji_count('Some emoji: 🌍, 😂, 😃, 😂, 🌍, 🌦️', unique=True) 4
You can check if a string is a single, valid emoji with is_emoji()
>>> emoji.is_emoji('🌍') True >>> emoji.is_emoji('🌍😂') False >>> emoji.is_emoji('test') False
While dealing with emojis, it is generally a bad idea to look at individual characters. Unicode contains modifier characters, such as variation selectors, which are not emojis themselves and modify the preceding emoji instead. You can check if a string has only emojis in it with purely_emoji()
>>> '\U0001f600\ufe0f' '😀' >>> emoji.is_emoji('\U0001f600\ufe0f') False >>> emoji.is_emoji('\U0001f600') True >>> emoji.is_emoji('\ufe0f') False >>> emoji.purely_emoji('\U0001f600\ufe0f') True
To get more information about an emoji, you can look it up in the EMOJI_DATA dict:
‘status’ is defined in STATUS . For example 2 corresponds to ‘fully_qualified’ . More information on the meaning can be found in the Unicode Standard http://www.unicode.org/reports/tr51/#Emoji_Variation_Selector_Notes
Replacing and removing emoji¶
With replace_emoji() you can replace, filter, escape or remove emoji in a string:
>>> emoji.replace_emoji('Python is 👍', replace='') 'Python is ' >>> emoji.replace_emoji('Python is 👍', replace='👎') 'Python is 👎' >>> def unicode_escape(chars, data_dict): >>> return chars.encode('unicode-escape').decode() >>> emoji.replace_emoji('Python is 👍', replace=unicode_escape) 'Python is \U0001f44d' >>> def xml_escape(chars, data_dict): >>> return chars.encode('ascii', 'xmlcharrefreplace').decode() >>> emoji.replace_emoji('Python is 👍', replace=xml_escape) 'Python is 👍' >>> emoji.replace_emoji('Python is 👍', replace=lambda chars, data_dict: chars.encode('ascii', 'namereplace').decode()) 'Python is \N' >>> emoji.replace_emoji('Python is 👍', replace=lambda chars, data_dict: data_dict['es']) 'Python is :pulgar_hacia_arriba:'
Emoji versions¶
The parameter version in replace_emoji() allows to replace only emoji above that Emoji version to prevent incompatibility with older platforms.
For the functions emojize() and demojize() the parameter version will replace emoji above the specified version with the value of the parameter handle_version . It defaults to an empty string, but can be set to any string or a function that returns a string.
For example the :croissant: 🥐 emoji was added in Emoji 3.0 (Unicode 9.0) in 2016 and :T-Rex: 🦖 was added later in Emoji 5.0 (Unicode 10.0) in 2017:
>>> emoji.replace_emoji('A 🦖 is eating a 🥐', replace='[Unsupported emoji]', version=1.0) 'A [Unsupported emoji] is eating a [Unsupported emoji]' >>> emoji.replace_emoji('A 🦖 is eating a 🥐', replace=lambda chars, data_dict: data_dict['en'], version=3.0) 'A :T-Rex: is eating a 🥐' >>> emoji.emojize('A :T-Rex: is eating a :croissant:', version=3.0) 'A is eating a 🥐' >>> emoji.emojize('A :T-Rex: is eating a :croissant:', version=3.0, handle_version='[Unsupported emoji]') 'A [Unsupported emoji] is eating a 🥐' >>> emoji.demojize('A 🦖 is eating a 🥐', version=3.0) 'A is eating a :croissant:' >>> emoji.replace_emoji('A 🦖 is eating a 🥐', replace='', version=5.0) 'A 🦖 is eating a 🥐'
You can find the version of an emoji with version() :
>>> emoji.version('🥐') 3 >>> emoji.version('🏌️♀️') 4 >>> emoji.version('🦖') 5
Non-RGI ZWJ emoji¶
Some emoji contain multiple persons and each person can have an individual skin tone.
Unicode supports Multi-Person Skin Tones as of Emoji 11.0. Skin tones can be add to the nine characters known as Multi-Person Groupings.
Multi-person groups with different skin tones can be represented with Unicode, but are not yet RGI (recommended for general interchange). This means Unicode.org recommends not to show them in emoji keyboards. However some browser and platforms already support some of them:
In the module configuration config you can control how such emoji are handled.
Migrating to version 2.0.0¶
There a two major, breaking changes in version 2.0.0
non-English short codes¶
The names of emoji in non-English languages have changed, because the data files were updated to the new version 41. See https://cldr.unicode.org/index/downloads.
That means some :short-code-emoji: with non-English names will no longer work in 2.0.0. emojize() will ignore the old codes.
This may be a problem if you have previously stored :short-code-emoji: with non-English names for example in a database or if your users have stored them.
Regular expression¶
The function get_emoji_regexp() was removed in 2.0.0. Internally the module no longer uses a regular expression when scanning for emoji in a string (e.g. in demojize() ).
The regular expression was slow in Python 3 and it failed to correctly find certain combinations of long emoji (emoji consisting of multiple Unicode codepoints).
If you used the regular expression to remove emoji from strings, you can use replace_emoji() as shown in the examples above.
If you want to extract emoji from strings, you can use emoji_list() as a replacement.
If you want to keep using a regular expression despite its problems, you can create the expression yourself like this:
import re import emoji def get_emoji_regexp(): # Sort emoji by length to make sure multi-character emojis are # matched first emojis = sorted(emoji.EMOJI_DATA, key=len, reverse=True) pattern = '(' + '|'.join(re.escape(u) for u in emojis) + ')' return re.compile(pattern) exp = get_emoji_regexp() print(exp.sub(repl='[emoji]', string='A 🏌️♀️ is eating a 🥐'))
A [emoji] is eating a [emoji]
Common problems¶
UnicodeWarning: Unicode unequal comparison failed to convert both arguments to Unicode - interpreting them as being unequal
This exception is thrown in Python 2.7 if you passed a str string instead of a unicode string. You should only pass Unicode strings to this module.
The API documentation¶
Reference documentation of all functions and properties in the module:
Replace emoji names with Unicode codes
Replace Unicode emoji with emoji shortcodes
Find Unicode emoji in a string
Replace Unicode emoji with a customizable string
Location of all emoji in a string
Distinct list of emojis in the string
Number of emojis in a string
Check if a string/character is a single emoji
Check if a string contains only emojis
Find Unicode/Emoji version of an emoji
Module variables:
Dict of Unicode/Emoji status
Module wide configuration
Links¶
Overview of all emoji:
(auto-generated list of the emoji that are supported by the current version of this package)
For English:
For Spanish:
For Portuguese:
For Italian:
Indices and tables¶
Python program to print Emojis
There are multiple ways we can print the Emojis in Python. Let’s see how to print Emojis with Unicodes, CLDR names and emoji module.
Using Unicodes:
Every emoji has a Unicode associated with it. Emojis also have a CLDR short name, which can also be used.
From the list of unicodes, replace “+” with “000”. For example – “U+1F600” will become “U0001F600” and prefix the unicode with “\” and print it.
Python3
Using CLDR short name:
Python3
Using emoji module:
Emojis can also be implemented by using the emoji module provided in Python. To install it run the following in the terminal.
emojize() function requires the CLDR short name to be passed in it as the parameter. It then returns the corresponding emoji. Replace the spaces with underscore in the CLDR short name.
Python3
demojize() function converts the emoji passed into its corresponding CLDR short name.
Below is a list of some common emoji Unicodes with their CLDR short names:
| CLDR Short Name | Unicode |
|---|---|
| grinning face | U+1F600 |
| grinning face with big eyes | U+1F603 |
| grinning face with smiling eyes | U+1F604 |
| beaming face with smiling eyes | U+1F601 |
| grinning squinting face | U+1F606 |
| grinning face with sweat | U+1F605 |
| rolling on the floor laughing | U+1F923 |
| face with tears of joy | U+1F602 |
| slightly smiling face | U+1F642 |
| upside-down face | U+1F643 |
| winking face | U+1F609 |
| smiling face with smiling eyes | U+1F60A |
| smiling face with halo | U+1F607 |
| smiling face with 3 hearts | U+1F970 |
| smiling face with heart-eyes | U+1F60D |
| star-struck | U+1F929 |
| face blowing a kiss | U+1F618 |
| kissing face | U+1F617 |
| smiling face | U+263A |
| kissing face with closed eyes | U+1F61A |
| kissing face with smiling eyes | U+1F619 |
| face savoring food | U+1F60B |
| face with tongue | U+1F61B |
| winking face with tongue | U+1F61C |
| zany face | U+1F92A |
| squinting face with tongue | U+1F61D |
| money-mouth face | U+1F911 |
| hugging face | U+1F917 |
| face with hand over mouth | U+1F92D |
| shushing face | U+1F92B |
| thinking face | U+1F914 |
| zipper-mouth face | U+1F910 |
| face with raised eyebrow | U+1F928 |
| neutral face | U+1F610 |
| expressionless face | U+1F611 |
| face without mouth | U+1F636 |
| smirking face | U+1F60F |
| unamused face | U+1F612 |
| face with rolling eyes | U+1F644 |
| grimacing face | U+1F62C |
| lying face | U+1F925 |
| relieved face | U+1F60C |
| pensive face | U+1F614 |
| sleepy face | U+1F62A |
| drooling face | U+1F924 |
| sleeping face | U+1F634 |
| face with medical mask | U+1F637 |
| face with thermometer | U+1F912 |
| face with head-bandage | U+1F915 |
| nauseated face | U+1F922 |