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

#-------------------------------------------------------------------------------

# Copyright (c) 2015 Artur Eganyan

#

# This work is provided "AS IS", WITHOUT ANY WARRANTY, express or implied.

#-------------------------------------------------------------------------------

# Кратко:

# - функция - это объект, который можно выполнять

# - параметры передаются по ссылке

# - параметры можно передавать по порядку и по именам (в т.ч. переменное количество)

# - "переменная = значение" создает/меняет локальную переменную

# - при чтении переменной, она ищется среди локальных, а затем в вышестоящих блоках кода

# - если указано "global переменная", запись/чтение будет для глобальной переменной

# - значение по умолчанию для параметра вычисляется один раз

# - есть безымянные функции из одного выражения: lambda <параметры>: <возвращаемое выражение>

# Функция - это объект, который можно выполнять. Она описывается так:

#

# def <имя>(<параметр 1>, ..., <параметр N>):

# <код>

#

# Поскольку все значения - это объекты, при передаче параметров в функцию

# передаются ссылки на эти объекты. Параметры можно передавать по порядку

# и по именам: f(1, 2, a=4). Можно принимать переменное количество параметров

# по порядку и по именам, используя специальные параметры *<имя1> и **<имя2>,

# где <имя1> станет кортежем, а <имя2> - словарем:

#

# def f(arg1, arg2, *more_args, **named_args):

# ...

#

# f(1, 2, 3, 4, a=1, b=2) # more_args == (3, 4), named_args == {'a':1, 'b':2}

#

# Обычно <имя1> - args, <имя2> - kwargs (или kwds). Можно передать

# последовательность значений для параметров, идущих по порядку, и словарь

# значений для параметров с нужными именами:

#

# by_order = (2, 3, 4) # Или by_order = [2, 3, 4]

# by_name = {'a':1, 'b':2}

# f(1, *by_order, **by_name) # То же самое, что f(1, 2, 3, 4, a=1, b=2)

#

# Внутри функции присваивание "переменная = значение" создает/меняет локальную

# переменную. При чтении переменной она ищется среди локальных переменных

# функции, а затем в вышестоящих блоках (обычно это глобальные переменные).

# Если переменная объявлена через global, будет меняться/читаться глобальная

# переменная. Если функция не возвращает значение явно, будет возвращен None.

#

# Замечание: При вызове функции любой параметр можно задать только один раз:

# например, нельзя вызвать f(a=1, a=2).

#

# Замечание: В документации различают "параметр" и "аргумент", считая

# аргументом значение, переданное в качестве параметра.

x = 1

def f( a1, a2 = 2, a3 = 3 ):

x = a1 + a2 + a3 # Создаст локальную переменную x

print f(1, a3 = 5) # None (это функция возвращает по умолчанию)

print x # 1

#f() # Ошибка, не заданы обязательные параметры

#f(1, a2=5, 3) # Ошибка, после именных параметров не могут идти обычные

#f(1, 5, a2=5) # Ошибка, параметр a2 передан два раза

#f(1, a4=4) # Ошибка, параметр a4 не существует

# args - кортеж параметров, переданных по порядку, kwargs - словарь параметров,

# переданных по имени.

def g( a1, *args, **kwargs ):

print args

for k, v in kwargs.iteritems():

print k, "=", v

g(1, 2, 3, b=4, c=5) # (2, 3), c = 5, b = 4

args_by_order = (3, 4)

args_by_name = {'c': 5, 'd':6}

g(1, 2, *args_by_order, b=4, **args_by_name) # (2, 3, 4), c = 5, b = 4, d = 6

# Замечание: Функция может быть создана внутри другой функции - тогда она

# может читать локальные переменные вышестоящей функции. Такие функции

# можно даже возвращать и потом использовать.

def h():

x = 123

def g():

print x

return g

hg = h()

hg() # 123

# Замечание: Если для параметра задано значение по умолчанию, оно создается

# один раз, когда python читает описание функции.

def t( a, b = [] ):

b.append(a)

print b

t(1) # [1]

t(2) # [1, 2]

t(3, []) # [3]

t(4) # [1, 2, 4]

# В функции можно добавлять документацию. Она должна быть строкой, обычно -

# многострочной, т.е. в тройных кавычках ("""многострочная строка""" или

# '''многострочная строка''').

def w():

u"""Краткое описание функции.

Подробное описание функции, может быть любой длины.

"""

print "w()"

print w.__doc__

print help(w) # Выведет то же описание + заголовок функции

# Лямбда-функция (анонимная функция): lambda <параметры>: <возвращаемое выражение>

# Может состоять только из одного выражения.

u = lambda a1, a2: a1 + a2

print u(1, 2) # 3

# У функции есть специальные атрибуты

print w.__name__ # Имя функции

print w.__module__ # Имя модуля, в котором находится функция

print w.__defaults__ # Кортеж значений по умолчанию для параметров функции

print w.__globals__ # Словарь глобальных переменных функции

print w.__dict__ # Словарь, который может содержать дополнительные атрибуты функции

print w.__closure__ # Кортеж свободных переменных функции, или None, если их нет

# (см. variables.py про свободные переменные). Для hg выше это

# переменная x из h.

# Замечание: При выводе на экран через print функция.__doc__, все отступы

# описания выводятся как есть. Но при генерации документации сторонними

# программами, они должны удалять начальный отступ перед каждым абзацем и

# сохранять все дополнительные отступы.