def union_categoricals(to_union, sort_categories=False, ignore_order=False):
from pandas import Index, Categorical, CategoricalIndex, Series<EOL>from pandas.core.arrays.categorical import _recode_for_categories<EOL>if len(to_union) == <NUM_LIT:0>:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>def _maybe_unwrap(x):<EOL><INDENT>if isinstance(x, (CategoricalIndex, Series)):<EOL><INDENT>return x.values<EOL><DEDENT>elif isinstance(x, Categorical):<EOL><INDENT>return x<EOL><DEDENT>else:<EOL><INDENT>raise TypeError("<STR_LIT>")<EOL><DEDENT><DEDENT>to_union = [_maybe_unwrap(x) for x in to_union]<EOL>first = to_union[<NUM_LIT:0>]<EOL>if not all(is_dtype_equal(other.categories.dtype, first.categories.dtype)<EOL>for other in to_union[<NUM_LIT:1>:]):<EOL><INDENT>raise TypeError("<STR_LIT>")<EOL><DEDENT>ordered = False<EOL>if all(first.is_dtype_equal(other) for other in to_union[<NUM_LIT:1>:]):<EOL><INDENT>categories = first.categories<EOL>ordered = first.ordered<EOL>if all(first.categories.equals(other.categories)<EOL>for other in to_union[<NUM_LIT:1>:]):<EOL><INDENT>new_codes = np.concatenate([c.codes for c in to_union])<EOL><DEDENT>else:<EOL><INDENT>codes = [first.codes] + [_recode_for_categories(other.codes,<EOL>other.categories,<EOL>first.categories)<EOL>for other in to_union[<NUM_LIT:1>:]]<EOL>new_codes = np.concatenate(codes)<EOL><DEDENT>if sort_categories and not ignore_order and ordered:<EOL><INDENT>raise TypeError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT>if sort_categories and not categories.is_monotonic_increasing:<EOL><INDENT>categories = categories.sort_values()<EOL>indexer = categories.get_indexer(first.categories)<EOL>from pandas.core.algorithms import take_1d<EOL>new_codes = take_1d(indexer, new_codes, fill_value=-<NUM_LIT:1>)<EOL><DEDENT><DEDENT>elif ignore_order or all(not c.ordered for c in to_union):<EOL><INDENT>cats = first.categories.append([c.categories for c in to_union[<NUM_LIT:1>:]])<EOL>categories = Index(cats.unique())<EOL>if sort_categories:<EOL><INDENT>categories = categories.sort_values()<EOL><DEDENT>new_codes = [_recode_for_categories(c.codes, c.categories, categories)<EOL>for c in to_union]<EOL>new_codes = np.concatenate(new_codes)<EOL><DEDENT>else:<EOL><INDENT>if all(c.ordered for c in to_union):<EOL><INDENT>msg = ("<STR_LIT>"<EOL>"<STR_LIT>")<EOL>raise TypeError(msg)<EOL><DEDENT>else:<EOL><INDENT>raise TypeError('<STR_LIT>')<EOL><DEDENT><DEDENT>if ignore_order:<EOL><INDENT>ordered = False<EOL><DEDENT>return Categorical(new_codes, categories=categories, ordered=ordered,<EOL>fastpath=True)<EOL>
Combine list-like of Categorical-like, unioning categories. All
categories must have the same dtype.

.. versionadded:: 0.19.0

Parameters
----------
to_union : list-like of Categorical, CategoricalIndex,
           or Series with dtype='category'
sort_categories : boolean, default False
    If true, resulting categories will be lexsorted, otherwise
    they will be ordered as they appear in the data.
ignore_order : boolean, default False
    If true, the ordered attribute of the Categoricals will be ignored.
    Results in an unordered categorical.

    .. versionadded:: 0.20.0

Returns
-------
result : Categorical

Raises
------
TypeError
    - all inputs do not have the same dtype
    - all inputs do not have the same ordered property
    - all inputs are ordered and their categories are not identical
    - sort_categories=True and Categoricals are ordered
ValueError
    Empty list of categoricals passed

Notes
-----

To learn more about categories, see `link
<http://pandas.pydata.org/pandas-docs/stable/categorical.html#unioning>`__

Examples
--------

>>> from pandas.api.types import union_categoricals

If you want to combine categoricals that do not necessarily have
the same categories, `union_categoricals` will combine a list-like
of categoricals. The new categories will be the union of the
categories being combined.

>>> a = pd.Categorical(["b", "c"])
>>> b = pd.Categorical(["a", "b"])
>>> union_categoricals([a, b])
[b, c, a, b]
Categories (3, object): [b, c, a]

By default, the resulting categories will be ordered as they appear
in the `categories` of the data. If you want the categories to be
lexsorted, use `sort_categories=True` argument.

>>> union_categoricals([a, b], sort_categories=True)
[b, c, a, b]
Categories (3, object): [a, b, c]

`union_categoricals` also works with the case of combining two
categoricals of the same categories and order information (e.g. what
you could also `append` for).

>>> a = pd.Categorical(["a", "b"], ordered=True)
>>> b = pd.Categorical(["a", "b", "a"], ordered=True)
>>> union_categoricals([a, b])
[a, b, a, b, a]
Categories (2, object): [a < b]

Raises `TypeError` because the categories are ordered and not identical.

>>> a = pd.Categorical(["a", "b"], ordered=True)
>>> b = pd.Categorical(["a", "b", "c"], ordered=True)
>>> union_categoricals([a, b])
TypeError: to union ordered Categoricals, all categories must be the same

New in version 0.20.0

Ordered categoricals with different categories or orderings can be
combined by using the `ignore_ordered=True` argument.

>>> a = pd.Categorical(["a", "b", "c"], ordered=True)
>>> b = pd.Categorical(["c", "b", "a"], ordered=True)
>>> union_categoricals([a, b], ignore_order=True)
[a, b, c, c, b, a]
Categories (3, object): [a, b, c]

`union_categoricals` also works with a `CategoricalIndex`, or `Series`
containing categorical data, but note that the resulting array will
always be a plain `Categorical`

>>> a = pd.Series(["b", "c"], dtype='category')
>>> b = pd.Series(["a", "b"], dtype='category')
>>> union_categoricals([a, b])
[b, c, a, b]
Categories (3, object): [b, c, a]