cap3-intro_python-funcoes.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introdução ao Python - Capítulo 3 - Funções\n",
    "Funções são \"pedaços\" de código reutilizável que realizam uma tarefa específica, elas podem receber _input_ (argumentos) e também retornar algum resultado.\n",
    "\n",
    "---\n",
    "<br>\n",
    "\n",
    "**Índice**<a id='indice'></a><br>\n",
    "1 - [Definindo funções](#1)<br>\n",
    "2 - [Escopo de variável](#2)<br>\n",
    "3 - [Documentação](#3)<br>\n",
    "4 - [Expressões lambda](#4)<br>\n",
    "5 - [Iteradores e geradores](#5)<br>\n",
    "6 - [Gerador de expressões](#6)<br>\n",
    "7 - [_Built-in functions_ do Python](#7)<br>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Python 3.7.3\n"
     ]
    }
   ],
   "source": [
    "!python --version"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. Definindo funções<a id='1'></a>\n",
    "#### 1.1. Definindo funções\n",
    "Exemplo de uma definição de função:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "def cylinder_volume(height, radius):\n",
    "    pi = 3.14159\n",
    "    return height * pi * radius ** 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Depois de definir a função cylinder_volume, nós podemos recorrer à função assim:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "282.7431"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cylinder_volume(10, 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Uma definição de função inclui várias partes importantes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**1.1.1. Cabeçalho da função**\n",
    "Vamos começar com o cabeçalho da função, que é a primeira linha de uma definição de função.\n",
    "1. O cabeçalho da função sempre começa com a palavra-chave `def`, que indica que se trata de uma definição de função;\n",
    "2. Então, vem o nome da função (nesse caso, `cylinder_volume`), que segue as mesmas convenções de nomenclatura que as variáveis. Você pode revisitar as convenções de nomenclatura abaixo;\n",
    "3. Imediatamente após o nome, temos parênteses que podem incluir argumentos separados por vírgulas (aqui, `height` e `radius`). Argumentos, ou parâmetros, são valores que são passados como entradas quando a função é utilizada e são usados no corpo da função. Se uma função não aceita argumentos, esses parênteses são deixados vazios;\n",
    "4. O cabeçalho sempre termina com dois pontos `:`.\n",
    "\n",
    "**1.1.2. Corpo da função**\n",
    "O resto da função está contido no corpo, que é onde a função faz seu trabalho.\n",
    "1. O corpo de uma função é o código indentado que vem após a linha de cabeçalho. Aqui, são as duas linhas que definem `pi` e `return` para devolver o volume;\n",
    "2. Dentro desse corpo, podemos nos referir aos argumentos das variáveis e definir novas variáveis, que só podem ser utilizadas dentro dessas linhas indentadas;\n",
    "3. O corpo frequentemente incluirá uma declaração `return`, que é usada para devolver um valor de saída da função para a declaração que recorreu à função. Uma declaração `return` consiste na palavra-chave `return` seguida por uma expressão que é avaliada para obter o valor de saída para a função. Se não há nenhuma declaração `return`, a função simplesmente devolve none. Abaixo, você encontrará um editor de código onde pode testar isso.\n",
    "\n",
    "**1.1.3. Convenções de nomenclatura para funções**\n",
    "O nome de funções segue as mesmas convenções de nomenclatura que o das variáveis.\n",
    "1. Utilize apenas letras comuns, números e sublinhados no nome de suas funções. Ele não podem conter espaços e precisa começar com uma letra ou sublinhado;\n",
    "2. _Você não pode usar palavras reservadas ou identificadores internos_ que tenham finalidades importantes em Python, você vai aprender sobre elas durante todo esse curso. Você pode encontrar uma lista descrevendo as palavras reservadas do Python [aqui](https://pentangle.net/python/handbook/node52.html);\n",
    "3. Tente usar nomes descritivos, que podem ajudar os leitores a entender o que a função faz.\n",
    "\n",
    "#### 1.2. Argumentos padrão\n",
    "Podemos adicionar argumentos padrão em uma função para ter valores padrão para os parâmetros que não são especificados na hora de recorrer à função."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def cylinder_volume(height, radius=5):\n",
    "    pi = 3.14159\n",
    "    return height * pi * radius ** 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "No exemplo acima, `radius` é definido como 5, se esse parâmetro for omitido na hora de recorrer à função. Se usarmos `cylinder_volume(10)`, a função usará 10 como altura e 5 como raio. No entanto, se usamos `cylinder_volume(10,7)`, o 7 simplesmente substituirá o valor padrão de 5.\n",
    "\n",
    "Observe também que, aqui, estamos passando valores para nossos argumentos pela posição. É possível passar valores de duas maneiras - por posição e por nome. Cada uma dessas utilizações de função é avaliada da mesma maneira. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1539.3791"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cylinder_volume(10, 7)  # pass in arguments by position\n",
    "cylinder_volume(height=10, radius=7)  # pass in arguments by name"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right\"> <a href=\"#indice\">voltar ao topo </p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. Escopo de variável<a id='2'></a>\n",
    "**Escopo de variável** se refere a quais partes de um programa uma variável pode ser referenciada ou utilizada.\n",
    "\n",
    "É importante considerar o escopo quando usamos variáveis em funções. Se uma variável é criada dentro de uma função, só pode ser usada dentro dessa função. Não é possível acessá-la fora dessa função."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "ename": "NameError",
     "evalue": "name 'word' is not defined",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[1;31mNameError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-5-0ddf329b8322>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m\u001b[0m\n\u001b[0;32m      3\u001b[0m     \u001b[0mword\u001b[0m \u001b[1;33m=\u001b[0m \u001b[1;34m\"hello\"\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m      4\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m----> 5\u001b[1;33m \u001b[0mprint\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mword\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[1;31mNameError\u001b[0m: name 'word' is not defined"
     ]
    }
   ],
   "source": [
    "# This will result in an error\n",
    "def some_function():\n",
    "    word = \"hello\"\n",
    "\n",
    "print(word)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "No exemplo acima e no exemplo a seguir, dizemos que word tem um escopo que é somente local em cada função. Isso significa que você pode usar o mesmo nome para diferentes variáveis que são usadas em funções diferentes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This works fine\n",
    "def some_function():\n",
    "    word = \"hello\"\n",
    "\n",
    "def another_function():\n",
    "    word = \"goodbye\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Variáveis definidas fora de funções, como no exemplo abaixo, ainda podem ser acessadas de dentro de uma função. Aqui, dizemos que `word` tem um **escopo global**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello\n"
     ]
    }
   ],
   "source": [
    "# This works fine\n",
    "word = \"hello\"\n",
    "\n",
    "def some_function():\n",
    "    print(word)\n",
    "\n",
    "some_function()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Observe que ainda podemos acessar o valor da variável global `word` dentro dessa função. No entanto, o valor de uma variável global não pode ser **modificado** dentro da função. Se você quiser modificar o valor da variável dentro dessa função, ele deve ser passado como um argumento. Você verá mais sobre isso no próximo quiz.\n",
    "\n",
    "O escopo é essencial para compreender como as informações são passadas ao longo de programas em Python e em qualquer outra linguagem de programação.\n",
    "\n",
    "#### Mais sobre escopo de variável\n",
    "Quando você programa, você frequentemente vai ver que ideias semelhantes surgem diversas vezes. Você usará variáveis para coisas como contagem, iteração e acumulação de valores para retornar. Para escrever um código legível, você vai acabar usando nomes semelhantes para ideias parecidas. Assim que você reunir múltiplos pedaços de código (por exemplo, diversas funções ou recorrer a várias funções em um único script), pode preferir utilizar o mesmo nome para dois conceitos diferentes.\n",
    "\n",
    "Felizmente, você não precisa inventar novos nomes infinitamente. Reutilizar nomes para objetos não gera problemas, desde que você os deixe em escopos separados.\n",
    "\n",
    "**Recomendação:** é melhor definir variáveis no menor escopo em que elas serão necessárias. Enquanto funções podem se referir a variáveis definidas em um escopo maior, isso raramente é uma boa ideia, já que você pode não saber quais são as variáveis que definiu, se seu programa tiver muitas variáveis.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right\"> <a href=\"#indice\">voltar ao topo </p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3. Documentação<a id='3'></a>\n",
    "A documentação é usada para tornar seu código mais fácil de entender e usar. As funções em especial são legíveis porque, muitas vezes, elas usam documentação de strings, ou docstrings. Docstrings são um tipo de comentário usado para explicar a finalidade de uma função e como ela deve ser utilizada. Aqui está uma função de densidade populacional com uma docstring."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "def population_density(population, land_area):\n",
    "    \"\"\"Calculate the population density of an area. \"\"\"\n",
    "    return population / land_area"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Docstrings estão rodeadas por aspas triplas. A primeira linha da docstring é uma breve explicação do propósito da função. Se você acha que a documentação é suficiente, pode encerrar a docstring neste ponto; docstrings de linha única são perfeitamente aceitáveis, como no exemplo acima."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "def population_density(population, land_area):\n",
    "    \"\"\"Calculate the population density of an area.\n",
    "\n",
    "    INPUT:\n",
    "    population: int. The population of that area\n",
    "    land_area: int or float. This function is unit-agnostic, if you pass in values in terms\n",
    "    of square km or square miles the function will return a density in those units.\n",
    "\n",
    "    OUTPUT: \n",
    "    population_density: population / land_area. The population density of a particular area.\n",
    "    \"\"\"\n",
    "    return population / land_area"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Se você acha que uma descrição mais detalhada seria adequada para a função, pode adicionar mais informações após o resumo de uma linha. No exemplo acima, você pode ver que nós escrevemos uma explicação dos argumentos da função, indicando a finalidade e os tipos de cada um. Também é comum fornecer uma descrição da saída da função.\n",
    "\n",
    "Cada pedaço da docstring é opcional, no entanto, docstrings são parte das boas práticas de programação. Você pode ler mais sobre convenções de docstring [aqui](https://www.python.org/dev/peps/pep-0257)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right\"> <a href=\"#indice\">voltar ao topo </p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4. Expressões lambda<a id='4'></a>\n",
    "Você pode usar expressões lambda para criar funções anônimas. Ou seja, funções que não têm um nome. Elas são úteis para a criação de funções rápidas que não serão necessárias posteriormente em seu código. Isso pode ser especialmente útil para funções de ordem superior ou aquelas que aceitam outras funções como argumentos.\n",
    "\n",
    "Com uma expressão lambda, esta função:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "def multiply(x, y):\n",
    "    return x * y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "pode ser reduzida para:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "multiply = lambda x, y: x * y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ambas estas funções são usadas da mesma maneira. Em ambos os casos, podemos chamar `multiply` assim:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "28"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "multiply(4, 7)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Componentes de uma função lambda\n",
    "1. A palavra-chave lambda é utilizada para indicar que se trata de uma expressão lambda.\n",
    "2. Depois de lambda, temos um ou mais argumentos para a função anônima, separados por vírgulas e seguidos por dois pontos :. Semelhante às funções, a maneira como os argumentos são nomeados em uma expressão lambda é arbitrária.\n",
    "3. Por último está uma expressão que é avaliada e devolvida nessa função. Isto se parece muito com uma expressão que você pode ver como declaração de retorno em uma função.\n",
    "\n",
    "Com essa estrutura, as expressões lambda não são ideais para funções complexas, mas podem ser muito úteis para funções curtas e simples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right\"> <a href=\"#indice\">voltar ao topo </p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5. Iteradores e geradores<a id='5'></a>\n",
    "**Iteráveis** são objetos que podem retornar um de seus elementos de cada vez, assim como uma lista. Muitas das funções internas que usamos até agora, como `enumerate`, retornam um iterador.\n",
    "\n",
    "Um **iterador** é um objeto que representa uma corrente de dados. Isso é diferente de uma lista, que também é um iterável, mas não um iterador, porque não é uma corrente de dados.\n",
    "\n",
    "**Geradores** são uma maneira simples de criar iteradores usando funções. Você também pode definir os iteradores usando **classes**, sobre as quais você pode ler mais [aqui](https://docs.python.org/3/tutorial/classes.html#iterators).\n",
    "\n",
    "Aqui está um exemplo de uma função de gerador chamado `my_range`, que produz um iterador que é uma corrente de números de 0 até (x - 1)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "def my_range(x):\n",
    "    i = 0\n",
    "    while i < x:\n",
    "        yield i\n",
    "        i += 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Observe que, em vez de usar a palavra-chave return, ele usa `yield`. Isso permite que a função devolva um valor de cada vez, começando de onde parou a cada vez que recorremos a ele. A palavra-chave `yield` é o que diferencia um gerador de uma função típica.\n",
    "\n",
    "Lembre que, desde que retorne um iterador, podemos convertê-lo em uma lista ou iterar por meio dele com um loop para visualizar seu conteúdo. Por exemplo, este código:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "1\n",
      "2\n",
      "3\n",
      "4\n"
     ]
    }
   ],
   "source": [
    "for x in my_range(5):\n",
    "    print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 6. Gerador de expressões<a id='6'></a>\n",
    "Aqui está um conceito legal que combina geradores e compreensão de listas! Na verdade, você pode criar um gerador da mesma maneira que normalmente escreveria uma compreensão da lista, utilizando parênteses em vez de colchetes. Por exemplo:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]\n"
     ]
    }
   ],
   "source": [
    "sq_list = [x**2 for x in range(10)]  # isto produz uma lista de quadrados\n",
    "print(sq_list)\n",
    "\n",
    "sq_iterator = (x**2 for x in range(10))  # isto produz um iterador de quadrados"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Isso pode ajudá-lo a economizar tempo e criar um código eficiente!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right\"> <a href=\"#indice\">voltar ao topo </p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 7. _Built-in functions_ do Python<a id='7'></a>\n",
    "O Python possui várias funções integradas que estão sempre acessíveis, sem a necessidade de importar bibliotecas ou pacotes. Algumas já foram utilizadas nos capitulos anteriores, como: `type()`, `print()`, `zip()`, `len()`, `set()` e etc.\n",
    "\n",
    "[Aqui](https://docs.python.org/3.7/library/functions.html) temos a documentação oficial das _built-in functions_ do Python na versão usada nesse _notebook_."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Para exemplificar a conveniência das _built-in function_ vamos realizar o seguinte exercício: Considerando o dicionário de carros e seus valores, obter a soma dos valores."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'Jetta Variant': 88078.64, 'Passat': 106161.94, 'Crossfox': 72832.16}"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dados = {'Jetta Variant': 88078.64, 'Passat': 106161.94, 'Crossfox': 72832.16}\n",
    "dados"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Primeiro usamos um `for` para ir somando valor por valor:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dict_values([88078.64, 106161.94, 72832.16])\n",
      "267072.74\n"
     ]
    }
   ],
   "source": [
    "total = 0\n",
    "for valor in dados.values():\n",
    "    total += valor;\n",
    "print(total)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Agora usamos apenas a _built-in function_ `sum()`, que soma os elementos de um iterável:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "267072.74"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sum(dados.values())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 7.1. Função `help()`\n",
    "Esta é uma _built-in function_ muito útil, pois serve como um \"manualzinho\" das _built-in functions_."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on built-in function sum in module builtins:\n",
      "\n",
      "sum(iterable, start=0, /)\n",
      "    Return the sum of a 'start' value (default: 0) plus an iterable of numbers\n",
      "    \n",
      "    When the iterable is empty, return the start value.\n",
      "    This function is intended specifically for use with numeric values and may\n",
      "    reject non-numeric types.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(sum)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Outra forma de obter ajuda dentro dos _notebooks_ é digitar o nome de uma _built-in function_ e passar o sinal de interrogação ao lado:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "sum?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right\"> <a href=\"#indice\">voltar ao topo </p>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}