docs/index.rst
.. 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 <https://github.com/cvzi/flag>`_
This is based on `http://schinckel.net/2015/10/29/unicode-flags-in-python/ <http://web.archive.org/web/20180425063617/https://schinckel.net/2015/10/29/unicode-flags-in-python/>`_ by `schinckel <https://github.com/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/ <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 <https://en.wikipedia.org/wiki/Regional_Indicator_Symbol>`_.
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? <How subregional flags work_>`_
Functions
=========
.. currentmodule:: flag
.. autofunction:: flag
.. autofunction:: flagize
.. autofunction:: dflagize
.. autofunction:: flagize_subregional
.. autofunction:: dflagize_subregional
.. autoclass:: Flag
:special-members: __init__
:members: flagize, dflagize, flagize_subregional, dflagize_subregional
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 <https://en.wikipedia.org/wiki/ISO_3166-2:GB#Countries_and_province>`_ 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 <https://github.com/unicode-org/cldr/blob/master/common/subdivisions/en.xml>`_
It's also possible to use a 3-digit-code from `github.com/unicode-org/.../UnMacroRegions.txt <https://github.com/unicode-org/cldr/blob/master/tools/java/org/unicode/cldr/util/data/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.
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`