.. flag documentation master file, created by sphinx-quickstart on Fri Oct 26 10:43:48 2018. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. .. toctree:: :maxdepth: 2 :caption: Contents: flag ~~~~ Flag emoji for Python. Converts flag emoji to ASCII and other way round. `Source on Github `_ This is based on `http://schinckel.net/2015/10/29/unicode-flags-in-python/ `_ by `schinckel `_ Example ======= .. code-block:: python >>> 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 ======= .. code-block:: shell 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 |QR| https://flag.readthedocs.org .. |QR| image:: _static/qr.png :alt: QR Code containg https://flag.readthedocs.org :target: 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 ========= .. currentmodule:: flag .. autofunction:: flag .. autofunction:: flag_safe .. autofunction:: flagize .. autofunction:: dflagize .. autofunction:: flagize_subregional .. autofunction:: dflagize_subregional .. autofunction:: info .. autofunction:: infos .. autofunction:: version .. autoclass:: Flag :special-members: __init__ :members: flagize, dflagize, flagize_subregional, dflagize_subregional, add_flag Supported emojis and patterns ============================= Complete list can be found :download:`here <_static/report.html>`. The following flags are supported on all major platforms. ======== ======== 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 17 and Android 14). ============ ======== 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: .. code-block:: none 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. Validity and Support ==================== Unicode publishes a listing of all country codes and subregional codes that are available. The data can be found in the CLDR downloads or in the repository at https://github.com/unicode-org/cldr/blob/release-45/common/validity/region.xml The module offers this data as a dictionary (roughly 6000 country codes): .. code-block:: python import flag # For a single country code: flag.info("US") # {'id_status': 'regular', 'supported': True, 'valid': True} # List of all country codes flag.infos(extended=True) # {'US': {'id_status': 'regular', 'supported': True, 'valid': True}, {'IT': {...}, ...} The validity (dict-key ``'valid'``) is specified in the Unicode Emoji reports: https://www.unicode.org/reports/tr51/#Flags The module also offers information about the support of the flags (dict-key ``'supported'``). This data is based on visual inspection on major devices and platforms. Platforms with full-support are macOS 14, iOS 17, Android 14, Firefox 127, Telegram 10, WhatsApp 2.20. The data disregards Windows as it does not support any flags by default. Some third-party Windows apps like Firefox or Telegram do support flags. Also it is disregarded that the People's Republic of China censors some flags on some devices or on some language/region settings. You can view the complete list of flags at :download:`here <_static/report.html>`. Unsupported flags: ------------------ An Android, Firefox, WhatsApp and Telegram: unsupported two-letter flags are generally displayed as two (white on blue) letters, subregional flags are displayed as black flags. On Windows two-letter codes are displayed as the letters themselves, subregional codes are displayed as a black flag. On iOS and macOS unsupported two-letter flags are displayed as two letters with a black rectangle areound the letters, subregional codes are displayed similarly or as a black flag. Example: -------- .. code-block:: python import flag my_flags = flag.Flag(only_supported=True, only_valid=True, allow_subregions=True) print(my_flags.flagize("Flag of the United States :US:")) # This will show the US flag instead of :US: print(my_flags.flagize("A invalid flag :XT:")) # :XT: is kept, as it is not supported my_flags.flag("XY") # TRaise an error, because XY is not a valid country code # Add the custom code XT, which is used for the Texas flag by WhatsApp # And also the standard code US-TX which is understood by WhatsApp (but not generated) my_flags.add_flag("XT") my_flags.add_flag("US-TX") # This will show the Texas flag on WhatsApp # On other platforms, the first will show the letters 🇽🇹, the second an emmpty flag 🏴󠁵󠁳󠁴󠁸󠁿 print(my_flags.flagize("The Texas flag :XT:")) p print(my_flags.flagize("The Texas flag :us-tx:")) Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`