def fmt_flag(
    self: GTSelf,
    columns: SelectExpr = None,
    rows: int | list[int] | None = None,
    height: str | int | float | None = "1em",
    sep: str = " ",
    use_title: bool = True,
) -> GTSelf:
    """Generate flag icons for countries from their country codes.

    While it is fairly straightforward to insert images into body cells (using `fmt_image()` is one
    way to it), there is often the need to incorporate specialized types of graphics within a table.
    One such group of graphics involves iconography representing different countries, and the
    `fmt_flag()` method helps with inserting a flag icon (or multiple) in body cells. To make this
    work seamlessly, the input cells need to contain some reference to a country, and this can be in
    the form of a 2- or 3-letter ISO 3166-1 country code (e.g., Egypt has the `"EG"` country code).
    This method will parse the targeted body cells for those codes and insert the appropriate flag
    graphics.

    Multiple flags can be included per cell by separating country codes with commas (e.g.,
    `"GB,TT"`). The `sep=` argument allows for a common separator to be applied between flag icons.

    Parameters
    ----------
    columns
        The columns to target. Can either be a single column name or a series of column names
        provided in a list.
    rows
        In conjunction with `columns=`, we can specify which of their rows should undergo
        formatting. The default is all rows, resulting in all rows in targeted columns being
        formatted. Alternatively, we can supply a list of row indices.
    height
        The height of the flag icons. The default value is `"1em"`. If given as a number, it is
        assumed to be in pixels.
    sep
        In the output of multiple flag icons within a body cell, `sep=` provides the separator
        between each of the flag icons.
    use_title
        The option to include a title attribute with the country name when hovering over the flag
        icon. The default is `True`.

    Returns
    -------
    GT
        The GT object is returned. This is the same object that the method is called on so that we
        can facilitate method chaining.

    Examples
    --------
    Let's use the `countrypops` dataset to create a new table with flag icons. We will only include
    a few columns and rows from that table. The `country_code_2` column has 2-letter country codes
    in the format required for `fmt_flag()` and using that method transforms the codes to circular
    flag icons.

    ```{python}
    from great_tables import GT
    from great_tables.data import countrypops
    import polars as pl

    countrypops_mini = (
        pl.from_pandas(countrypops)
        .filter(pl.col("year") == 2021)
        .filter(pl.col("country_name").str.starts_with("S"))
        .sort("country_name")
        .head(10)
        .drop(["year", "country_code_3"])
    )

    (
        GT(countrypops_mini)
        .fmt_integer(columns="population")
        .fmt_flag(columns="country_code_2")
        .cols_label(
            country_code_2="",
            country_name="Country",
            population="Population (2021)"
        )
        .cols_move_to_start(columns="country_code_2")
    )
    ```

    Here's another example (again using `countrypops`) where we generate a table providing
    populations every five years for the Benelux countries (`"BEL"`, `"NLD"`, and `"LUX"`). After
    some filtering and a pivot, the `fmt_flag()` method is used to obtain flag icons from 3-letter
    country codes present in the `country_code_3` column.

    ```{python}
    import polars.selectors as cs

    countrypops_mini = (
        pl.from_pandas(countrypops)
        .filter(pl.col("country_code_3").is_in(["BEL", "NLD", "LUX"]))
        .filter((pl.col("year") % 10 == 0) & (pl.col("year") >= 1960))
        .pivot("year", index = ["country_code_3", "country_name"], values="population")
    )

    (
        GT(countrypops_mini)
        .tab_header(title="Populations of the Benelux Countries")
        .tab_spanner(label="Year", columns=cs.numeric())
        .fmt_integer(columns=cs.numeric())
        .fmt_flag(columns="country_code_3")
        .cols_label(
            country_code_3="",
            country_name="Country"
        )
    )
    ```
    """

    formatter = FmtFlag(self._tbl_data, height=height, sep=sep, use_title=use_title)

    return fmt(
        self,
        fns=FormatFns(html=formatter.to_html, latex=formatter.to_latex, default=formatter.to_html),
        columns=columns,
        rows=rows,
    )
Generate flag icons for countries from their country codes.

    While it is fairly straightforward to insert images into body cells (using `fmt_image()` is one
    way to it), there is often the need to incorporate specialized types of graphics within a table.
    One such group of graphics involves iconography representing different countries, and the
    `fmt_flag()` method helps with inserting a flag icon (or multiple) in body cells. To make this
    work seamlessly, the input cells need to contain some reference to a country, and this can be in
    the form of a 2- or 3-letter ISO 3166-1 country code (e.g., Egypt has the `"EG"` country code).
    This method will parse the targeted body cells for those codes and insert the appropriate flag
    graphics.

    Multiple flags can be included per cell by separating country codes with commas (e.g.,
    `"GB,TT"`). The `sep=` argument allows for a common separator to be applied between flag icons.

    Parameters
    ----------
    columns
        The columns to target. Can either be a single column name or a series of column names
        provided in a list.
    rows
        In conjunction with `columns=`, we can specify which of their rows should undergo
        formatting. The default is all rows, resulting in all rows in targeted columns being
        formatted. Alternatively, we can supply a list of row indices.
    height
        The height of the flag icons. The default value is `"1em"`. If given as a number, it is
        assumed to be in pixels.
    sep
        In the output of multiple flag icons within a body cell, `sep=` provides the separator
        between each of the flag icons.
    use_title
        The option to include a title attribute with the country name when hovering over the flag
        icon. The default is `True`.

    Returns
    -------
    GT
        The GT object is returned. This is the same object that the method is called on so that we
        can facilitate method chaining.

    Examples
    --------
    Let's use the `countrypops` dataset to create a new table with flag icons. We will only include
    a few columns and rows from that table. The `country_code_2` column has 2-letter country codes
    in the format required for `fmt_flag()` and using that method transforms the codes to circular
    flag icons.

    ```{python}
    from great_tables import GT
    from great_tables.data import countrypops
    import polars as pl

    countrypops_mini = (
        pl.from_pandas(countrypops)
        .filter(pl.col("year") == 2021)
        .filter(pl.col("country_name").str.starts_with("S"))
        .sort("country_name")
        .head(10)
        .drop(["year", "country_code_3"])
    )

    (
        GT(countrypops_mini)
        .fmt_integer(columns="population")
        .fmt_flag(columns="country_code_2")
        .cols_label(
            country_code_2="",
            country_name="Country",
            population="Population (2021)"
        )
        .cols_move_to_start(columns="country_code_2")
    )
    ```

    Here's another example (again using `countrypops`) where we generate a table providing
    populations every five years for the Benelux countries (`"BEL"`, `"NLD"`, and `"LUX"`). After
    some filtering and a pivot, the `fmt_flag()` method is used to obtain flag icons from 3-letter
    country codes present in the `country_code_3` column.

    ```{python}
    import polars.selectors as cs

    countrypops_mini = (
        pl.from_pandas(countrypops)
        .filter(pl.col("country_code_3").is_in(["BEL", "NLD", "LUX"]))
        .filter((pl.col("year") % 10 == 0) & (pl.col("year") >= 1960))
        .pivot("year", index = ["country_code_3", "country_name"], values="population")
    )

    (
        GT(countrypops_mini)
        .tab_header(title="Populations of the Benelux Countries")
        .tab_spanner(label="Year", columns=cs.numeric())
        .fmt_integer(columns=cs.numeric())
        .fmt_flag(columns="country_code_3")
        .cols_label(
            country_code_3="",
            country_name="Country"
        )
    )
    ```
    
great_tables/_formats.py