# -*- coding: utf-8 -*-

example_variable = 12345
"""int: Module level variable documented inline.

The docstring may span multiple lines. The type may optionally be specified
on the first line, separated by a colon.
"""


def example_function(param1, param2=None, *args, **kwargs):
    """This is an example of a module level function.

    Function parameters should be documented in the `Args` section. The name
    of each parameter is required. The type and description of each parameter
    is optional, but should be included if not obvious.

    Parameter types -- if given -- should be specified according to
    `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.

    Args:

      * param1 (int): The first parameter.
      * param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.
      * *args: Variable length argument list.
      * **kwargs: Arbitrary keyword arguments.

    Returns:

      * bool: True if successful, False otherwise.

    Raises:
      * AttributeError: The ``Raises`` section is a list of all exceptions
            that are relevant to the interface.
      * ValueError: If `param2` is equal to `param1`.


    .. _PEP 484:
       https://www.python.org/dev/peps/pep-0484/

    """
    if param1 == param2:
        raise ValueError('param1 may not be equal to param2')
    return True


def example_generator(n):
    """Generators have a ``Yields`` section instead of a ``Returns`` section.

    Args:

      * n (int): The upper limit of the range to generate, from 0 to `n` - 1.

    Yields:

      * int: The next number in the range of 0 to `n` - 1.

    Examples:
        >>> print([i for i in example_generator(4)])
        [0, 1, 2, 3]

    """
    for i in range(n):
        yield i


class ExampleError(Exception):
    """Exceptions are documented in the same way as classes.

    The __init__ method may be documented in either the class level
    docstring, or as a docstring on the __init__ method itself.

    Either form is acceptable, but the two should not be mixed. Choose one
    convention to document the __init__ method and be consistent with it.

    Note:

      Do not include the `self` parameter in the `Args` section.

    Args:

      * msg (str): Human readable string describing the exception.
      * code (Optional[int]): Error code.

    Attributes:

      * msg (str): Human readable string describing the exception.
      * code (int): Exception error code.

    """

    def __init__(self, msg, code):
        self.msg = msg
        self.code = code