flag

Flag emoji for Python.

Converts flag emoji to ASCII and other way round.

This is based on http://schinckel.net/2015/10/29/unicode-flags-in-python/ by schinckel

Example

>>> import flag

>>> flag.flag("IL")
'🇮🇱'

>>> flag.flag("GBENG")
'🏴󠁧󠁢󠁥󠁮󠁧󠁿'

>>> flag.flagize("Flag of Israel :IL:")
'Flag of Israel 🇮🇱'

>>> flag.dflagize("Flag of Israel 🇮🇱")
'Flag of Israel :IL:'

>>> flag.flagize("England :gb-eng: is part of the UK :GB:", subregions=True)
'England 🏴󠁧󠁢󠁥󠁮󠁧󠁿 is part of the UK 🇬🇧'

>>> flag.dflagize("England 🏴󠁧󠁢󠁥󠁮󠁧󠁿 is part of the UK 🇬🇧", subregions=True)
'England :gb-eng: is part of the UK :GB:'

Install

pip install emoji-country-flag

See: https://pypi.org/project/emoji-country-flag/

Hint

If you don’t see the flags in your browser, try with your phone

https://flag.readthedocs.org

How it works

All the flag emoji are actually composed of two unicode letters. These are the 26 regional indicator symbols.

Alone they look like this: 🇦 🇧 🇨 🇩 🇪 🇫 🇬 🇭 🇮 🇯 🇰 🇱 🇲 🇳 🇴 🇵 🇶 🇷 🇸 🇹 🇺 🇻 🇼 🇽 🇾 🇿

If you pair them up according to ISO 3166 some browsers and phones will display a flag. For example TW is Taiwan: 🇹 + 🇼 = 🇹🇼

So, to encode an ASCII code like :TW: to 🇹🇼, we just need to convert the ASCII T and R to the corresponding regional indicator symbols 🇹 and 🇼. To reverse it, we translate the regional indicator symbols back to ASCII letters.

How do subregional flags work?

Functions

flag.flag(countrycode: str) → str[source]

Encodes a single flag to unicode. Two letters are converted to regional indicator symbols Three or more letters/digits are converted to tag sequences. Dashes, colons and other symbols are removed from input, only a-z, A-Z and 0-9 are processed.

In general a valid flag is either a two letter code from ISO 3166 (e.g. GB), a code from ISO 3166-2 (e.g. GBENG) or a numeric code from ISO 3166-1. However, not all codes produce valid unicode, see http://unicode.org/reports/tr51/#flag-emoji-tag-sequences for more information. From ISO 3166-2 only England gbeng, Scotland gbsct and Wales gbwls are considered RGI (recommended for general interchange) by the Unicode Consortium, see http://www.unicode.org/Public/emoji/latest/emoji-test.txt

Parameters:: countrycode (str) – Two letter ISO 3166 code or a regional code from ISO 3166-2.
Returns:: The unicode representation of the flag
Return type:: str

flag.flagize(text: str, subregions: bool = False) → str[source]

Encode flags. Replace all two letter codes :XX: with unicode flags (emoji flag sequences)

Parameters:

text (str) – The text
subregions (bool) – Also replace subregional/subdivision codes :xx-xxx: with unicode flags (flag emoji tag sequences).

Returns:

The text with all occurrences of :XX: replaced by unicode flags

Return type:

str

flag.dflagize(text: str, subregions: bool = False) → str[source]

Decode flags. Replace all unicode country flags (emoji flag sequences) in text with ascii two letter code :XX:

Parameters:

text (str) – The text
subregions (bool) – Also replace subregional/subdivision flags (flag emoji tag sequences) with :xx-xxx:

Returns:

The text with all unicode flags replaced by ascii sequence :XX:

Return type:

str

flag.flagize_subregional(text: str) → str[source]

Encode subregional/subdivision flags. Replace all regional codes :xx-xxx: with unicode flags (flag emoji tag sequences)

Parameters:: text (str) – The text
Returns:: The text with all occurrences of :xx-xxx: replaced by unicode flags
Return type:: str

flag.dflagize_subregional(text: str) → str[source]

Decode subregional/subdivision flags. Replace all unicode regional flags (flag emoji tag sequences) in text with their ascii code :xx-xxx:

Parameters:: text (str) – The text
Returns:: The text with all regional flags replaced by ascii sequence :xx-xxx:
Return type:: str

class flag.Flag(prefix_str: str = ':', suffix_str: str = ':', warn: bool = True)[source]

Use this class if you want a different prefix and suffix instead of colons. Offers the same methods as the module.

__init__(prefix_str: str = ':', suffix_str: str = ':', warn: bool = True) → None[source]

Set a custom prefix and suffix. Instead of :XY: it will use {prefix}XY{suffix}.

To encode subregional flags, use a suffix that is either longer than 4 characters or that does not contain A-Z, a-z, 0-9 and does not start with a - (minus).

Parameters:

prefix_str (str) – The leading symbols
suffix_str (str) – The trailing symbols

dflagize(text: str, subregions: bool = False) → str[source]

Decode flags. Replace all unicode country flags (emoji flag sequences) in text with ascii two letter code {prefix}XX{suffix}

Parameters:

text (str) – The text
subregions (bool) – Also replace subregional/subdivision flags (flag emoji tag sequences) with {prefix}xx-xxx{suffix}

Returns:

The text with all unicode flags replaced by ascii sequence {prefix}XX{suffix}

Return type:

str

dflagize_subregional(text: str) → str[source]

Decode subregional/subdivision flags. Replace all unicode regional flags (flag emoji tag sequences) in text with their ascii code {prefix}xx-xxx{suffix}

Parameters:: text (str) – The text
Returns:: The text with all regional flags replaced by ascii sequence {prefix}xx-xxx{suffix}
Return type:: str

flagize(text: str, subregions: bool = False) → str[source]

Encode flags. Replace all two letter codes {prefix}XX{suffix} with unicode flags (emoji flag sequences)

For this method the suffix should not contain A-Z, a-z or 0-9 and not start with a - (minus).

Parameters:

text (str) – The text
subregions (bool) – Also replace subregional/subdivision codes {prefix}xx-xxx{suffix} with unicode flags (flag emoji tag sequences).

Returns:

The text with all occurrences of {prefix}XX{suffix} replaced by unicode flags

Return type:

str

flagize_subregional(text: str) → str[source]

Encode subregional/subdivision flags. Replace all regional codes {prefix}xx-xxx{suffix} with unicode flags (flag emoji tag sequences)

For this method the suffix should not contain A-Z, a-z or 0-9 and not start with a - (minus).

Parameters:: text (str) – The text
Returns:: The text with all occurrences of {prefix}xx-xxx{suffix} replaced by unicode flags
Return type:: str

Supported emojis and patterns

(List may be incomplete)

Code	Emoji
`:UN:`	🇺🇳
`:AC:`	🇦🇨
`:AD:`	🇦🇩
`:AE:`	🇦🇪
`:AF:`	🇦🇫
`:AG:`	🇦🇬
`:AI:`	🇦🇮
`:AL:`	🇦🇱
`:AM:`	🇦🇲
`:AO:`	🇦🇴
`:AQ:`	🇦🇶
`:AR:`	🇦🇷
`:AS:`	🇦🇸
`:AT:`	🇦🇹
`:AU:`	🇦🇺
`:AW:`	🇦🇼
`:AX:`	🇦🇽
`:AZ:`	🇦🇿
`:BA:`	🇧🇦
`:BB:`	🇧🇧
`:BD:`	🇧🇩
`:BE:`	🇧🇪
`:BF:`	🇧🇫
`:BG:`	🇧🇬
`:BH:`	🇧🇭
`:BI:`	🇧🇮
`:BJ:`	🇧🇯
`:BL:`	🇧🇱
`:BM:`	🇧🇲
`:BN:`	🇧🇳
`:BO:`	🇧🇴
`:BQ:`	🇧🇶
`:BR:`	🇧🇷
`:BS:`	🇧🇸
`:BT:`	🇧🇹
`:BV:`	🇧🇻
`:BW:`	🇧🇼
`:BY:`	🇧🇾
`:BZ:`	🇧🇿
`:CA:`	🇨🇦
`:CC:`	🇨🇨
`:CD:`	🇨🇩
`:CF:`	🇨🇫
`:CG:`	🇨🇬
`:CH:`	🇨🇭
`:CI:`	🇨🇮
`:CK:`	🇨🇰
`:CL:`	🇨🇱
`:CM:`	🇨🇲
`:CN:`	🇨🇳
`:CO:`	🇨🇴
`:CP:`	🇨🇵
`:CR:`	🇨🇷
`:CU:`	🇨🇺
`:CV:`	🇨🇻
`:CW:`	🇨🇼
`:CX:`	🇨🇽
`:CY:`	🇨🇾
`:CZ:`	🇨🇿
`:DE:`	🇩🇪
`:DG:`	🇩🇬
`:DJ:`	🇩🇯
`:DK:`	🇩🇰
`:DM:`	🇩🇲
`:DO:`	🇩🇴
`:DZ:`	🇩🇿
`:EA:`	🇪🇦
`:EC:`	🇪🇨
`:EE:`	🇪🇪
`:EG:`	🇪🇬
`:EH:`	🇪🇭
`:ER:`	🇪🇷
`:ES:`	🇪🇸
`:ET:`	🇪🇹
`:EU:`	🇪🇺
`:FI:`	🇫🇮
`:FJ:`	🇫🇯
`:FK:`	🇫🇰
`:FM:`	🇫🇲
`:FO:`	🇫🇴
`:FR:`	🇫🇷
`:GA:`	🇬🇦
`:GB:`	🇬🇧
`:GD:`	🇬🇩
`:GE:`	🇬🇪
`:GF:`	🇬🇫
`:GG:`	🇬🇬
`:GH:`	🇬🇭
`:GI:`	🇬🇮
`:GL:`	🇬🇱
`:GM:`	🇬🇲
`:GN:`	🇬🇳
`:GP:`	🇬🇵
`:GQ:`	🇬🇶
`:GR:`	🇬🇷
`:GS:`	🇬🇸
`:GT:`	🇬🇹
`:GU:`	🇬🇺
`:GW:`	🇬🇼
`:GY:`	🇬🇾
`:HK:`	🇭🇰
`:HM:`	🇭🇲
`:HN:`	🇭🇳
`:HR:`	🇭🇷
`:HT:`	🇭🇹
`:HU:`	🇭🇺
`:IC:`	🇮🇨
`:ID:`	🇮🇩
`:IE:`	🇮🇪
`:IL:`	🇮🇱
`:IM:`	🇮🇲
`:IN:`	🇮🇳
`:IO:`	🇮🇴
`:IQ:`	🇮🇶
`:IR:`	🇮🇷
`:IS:`	🇮🇸
`:IT:`	🇮🇹
`:JE:`	🇯🇪
`:JM:`	🇯🇲
`:JO:`	🇯🇴
`:JP:`	🇯🇵
`:KE:`	🇰🇪
`:KG:`	🇰🇬
`:KH:`	🇰🇭
`:KI:`	🇰🇮
`:KM:`	🇰🇲
`:KN:`	🇰🇳
`:KP:`	🇰🇵
`:KR:`	🇰🇷
`:KW:`	🇰🇼
`:KY:`	🇰🇾
`:KZ:`	🇰🇿
`:LA:`	🇱🇦
`:LB:`	🇱🇧
`:LC:`	🇱🇨
`:LI:`	🇱🇮
`:LK:`	🇱🇰
`:LR:`	🇱🇷
`:LS:`	🇱🇸
`:LT:`	🇱🇹
`:LU:`	🇱🇺
`:LV:`	🇱🇻
`:LY:`	🇱🇾
`:MA:`	🇲🇦
`:MC:`	🇲🇨
`:MD:`	🇲🇩
`:ME:`	🇲🇪
`:MF:`	🇲🇫
`:MG:`	🇲🇬
`:MH:`	🇲🇭
`:MK:`	🇲🇰
`:ML:`	🇲🇱
`:MM:`	🇲🇲
`:MN:`	🇲🇳
`:MO:`	🇲🇴
`:MP:`	🇲🇵
`:MQ:`	🇲🇶
`:MR:`	🇲🇷
`:MS:`	🇲🇸
`:MT:`	🇲🇹
`:MU:`	🇲🇺
`:MV:`	🇲🇻
`:MW:`	🇲🇼
`:MX:`	🇲🇽
`:MY:`	🇲🇾
`:MZ:`	🇲🇿
`:NA:`	🇳🇦
`:NC:`	🇳🇨
`:NE:`	🇳🇪
`:NF:`	🇳🇫
`:NG:`	🇳🇬
`:NI:`	🇳🇮
`:NL:`	🇳🇱
`:NO:`	🇳🇴
`:NP:`	🇳🇵
`:NR:`	🇳🇷
`:NU:`	🇳🇺
`:NZ:`	🇳🇿
`:OM:`	🇴🇲
`:PA:`	🇵🇦
`:PE:`	🇵🇪
`:PF:`	🇵🇫
`:PG:`	🇵🇬
`:PH:`	🇵🇭
`:PK:`	🇵🇰
`:PL:`	🇵🇱
`:PM:`	🇵🇲
`:PN:`	🇵🇳
`:PR:`	🇵🇷
`:PS:`	🇵🇸
`:PT:`	🇵🇹
`:PW:`	🇵🇼
`:PY:`	🇵🇾
`:QA:`	🇶🇦
`:RE:`	🇷🇪
`:RO:`	🇷🇴
`:RS:`	🇷🇸
`:RU:`	🇷🇺
`:RW:`	🇷🇼
`:SA:`	🇸🇦
`:SB:`	🇸🇧
`:SC:`	🇸🇨
`:SD:`	🇸🇩
`:SE:`	🇸🇪
`:SG:`	🇸🇬
`:SH:`	🇸🇭
`:SI:`	🇸🇮
`:SJ:`	🇸🇯
`:SK:`	🇸🇰
`:SL:`	🇸🇱
`:SM:`	🇸🇲
`:SN:`	🇸🇳
`:SO:`	🇸🇴
`:SR:`	🇸🇷
`:SS:`	🇸🇸
`:ST:`	🇸🇹
`:SV:`	🇸🇻
`:SX:`	🇸🇽
`:SY:`	🇸🇾
`:SZ:`	🇸🇿
`:TA:`	🇹🇦
`:TC:`	🇹🇨
`:TD:`	🇹🇩
`:TF:`	🇹🇫
`:TG:`	🇹🇬
`:TH:`	🇹🇭
`:TJ:`	🇹🇯
`:TK:`	🇹🇰
`:TL:`	🇹🇱
`:TM:`	🇹🇲
`:TN:`	🇹🇳
`:TO:`	🇹🇴
`:TR:`	🇹🇷
`:TT:`	🇹🇹
`:TV:`	🇹🇻
`:TW:`	🇹🇼
`:TZ:`	🇹🇿
`:UA:`	🇺🇦
`:UG:`	🇺🇬
`:UM:`	🇺🇲
`:US:`	🇺🇸
`:UY:`	🇺🇾
`:UZ:`	🇺🇿
`:VA:`	🇻🇦
`:VC:`	🇻🇨
`:VE:`	🇻🇪
`:VG:`	🇻🇬
`:VI:`	🇻🇮
`:VN:`	🇻🇳
`:VU:`	🇻🇺
`:WF:`	🇼🇫
`:WS:`	🇼🇸
`:XK:`	🇽🇰
`:YE:`	🇾🇪
`:YT:`	🇾🇹
`:ZA:`	🇿🇦
`:ZM:`	🇿🇲
`:ZW:`	🇿🇼

Subregional flags

The only widely supported subregional flags are currently: England, Scotland and Wales (as of iOS 12 and Android 9).

Code	Emoji
`:gb-sct:`	🏴󠁧󠁢󠁳󠁣󠁴󠁿
`:gb-wls:`	🏴󠁧󠁢󠁷󠁬󠁳󠁿
`:gb-eng:`	🏴󠁧󠁢󠁥󠁮󠁧󠁿
`:us-tx:`	🏴󠁵󠁳󠁴󠁸󠁿

WhatsApp offers one other state flag: Texas.
If you use WhatsApp’s emoji panel to select the Texas flag, WhatsApp uses 🇽🇹 i.e. flagize(“:XT:”) for Texas. This code “XT” is specified by Unicode as “excluded” meaning it is explicitly for private use and can be defined by anyone. Therefore, it is likely not displayed as the Texas flag on other platforms.
But WhatsApp also recognizes the flag emoji tag sequence flagize(“:us-tx:”, subregions=True) and displays the same flag.

How subregional flags work

They work very similar to the country flags. The ASCII codes are transformed by replacing them with specific codepoints that are called “tags”.

The basic format for a tag flag is:

black_flag_emoji followed by region_code_in_tag followed by cancel_tag

Note

black_flag_emoji:

U+1F3F4 ( 🏴 )

cancel_tag:

U+E007F (invisible, signifies the end of the flag code)

region_code_in_tag:

It is formed using the abbreviation defined in ISO 3166-2 and adding 0xE0000 to every ASCII value of the code. For example England is GB-ENG.

A full list of valid codes can be found here: github.com/unicode-org/…/subdivisions/en.xml

It’s also possible to use a 3-digit-code from github.com/unicode-org/…/UnMacroRegions.txt

Example:

England is GB-ENG in ISO 3166-2.
We drop the hyphen and make it lowercase to get gbeng.
To transform this to “tags”, we need to add the value 0xE0000 = 917504 to every unicode value of gbeng:

g is unicode 0x67 or decimal 103, so 103 + 917504 = 917607 or 0xE0067
b is 0x62 and becomes 0xE0062
e is 0x65 and becomes 0xE0065
n is 0x6E and becomes 0xE006E
g is 0x67 and becomes 0xE0067

Together it’s:

                      g        b        e        n        g
ASCII:                0x67     0x62     0x65     0x6E     0x67
Tags:   0x1F3F4    0xE0067  0xE0062  0xE0065  0xE006E  0xE0067  0xE007F
        black_flag                                             cancel_tag

Unlike the regional indicator symbols, tags are not rendered on incompatible system, they will simply be invisible and have no width. So, if the particular flag is not supported or if tag flags are not supported at all, the only visible character will be a black flag.

flag

Example

Install

How it works

Functions

Supported emojis and patterns

Subregional flags

How subregional flags work

Example:

Indices and tables