feat: seção de módulos nativos + desafio

book/09-modulos/01-introducao.ipynb

@@ -11,8 +11,20 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Até o momento trabalhamos em um arquivo único que era executado do começo ao fim. A partir de agora vamos começar a trabalhar com mais arquivos para organizar melhor nosso código e permitir aumentar a complexidade dos programas. Neste capítulo, exploraremos um dos conceitos fundamentais da programação em Python: os módulos. \n",
-    "\n",
+    "Até o momento trabalhamos em um arquivo único que era executado do começo ao fim. A partir de agora vamos começar a trabalhar com mais arquivos para organizar melhor nosso código e permitir aumentar a complexidade dos programas. Neste capítulo, exploraremos um dos conceitos fundamentais da programação em Python: os módulos."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Definição"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "Um módulo em Python é simplesmente um arquivo contendo definições e declarações Python. O nome do arquivo é o nome do módulo com a extensão `.py` adicionada. Os módulos permitem que você organize seu código de maneira lógica e reutilizável. Até o momento trabalhamos em um arquivo único que era executado do começo ao fim. A partir de agora vamos começar a trabalhar com mais arquivos para organizar melhor nosso código e permitir aumentar a complexidade dos programas."
    ]
   },
@@ -114,7 +126,9 @@
     "\n",
     "```{image} ../img/09-01-pypi.png\n",
     ":width: 800\n",
-    "```"
+    "```\n",
+    "\n",
+    "Na próxima seção, vamos começar explorando o básico de módulos, começando pelos módulos nativos. Te vejo lá!"
    ]
   }
  ],

book/09-modulos/02-modulos-nativos.ipynb

@@ -0,0 +1,244 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Módulos nativos"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Conforme já mencionamos na seção anterior, o Python traz uma série de módulos nativos prontos para uso. Nesta seção, vamos explorar o conceito básico de importações de módulos e alguns módulos nativos que podem ser úteis em diversas situações. Como já disse, a lista de módulos nativos é enorme, e a ideia é apenas dar um passo inicial nesse mundo. Você pode explorar a lista completa de módulos nativos na [documentação oficial](https://docs.python.org/3/library/index.html)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Importação de módulos"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Importando um módulo inteiro"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Diferentemente de funções nativas, módulos nativos precisam ser importados antes de serem utilizados. \n",
+    "\n",
+    "A sintaxe de importação a princípio é simples:\n",
+    "\n",
+    "```python\n",
+    "import <nome_do_modulo_desejado>\n",
+    "```\n",
+    "\n",
+    "Para isso, utilizamos a palavra-chave `import` seguida do nome do módulo. Por exemplo, para importar o módulo `math`, que contém funções matemáticas, usamos a seguinte sintaxe:\n",
+    "\n",
+    "```python\n",
+    "import math\n",
+    "```\n",
+    "\n",
+    "Aqui estamos trazendo para o escopo do nosso programa o módulo `math`, que contém uma série de funcionalidades matemáticas. Como um módulo é um arquivo `.py` contendo uma série de funções, métodos, classes, variáveis e outras coisas, podemos acessar esses elementos utilizando a notação de ponto. Por exemplo, para acessar a função `sqrt` do módulo `math`, para calcular a raiz quadrada de um número, fazemos:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import math  # (1)\n",
+    "\n",
+    "print(math.sqrt(16))  # (2)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Do código acima, podemos entender as etapas:\n",
+    "\n",
+    "1. Importamos o módulo `math` com a palavra-chave `import` trazendo para o escopo do nosso programa todas as funcionalidades contidas nesse módulo.\n",
+    "2. Acessamos a função `sqrt` do módulo `math` utilizando a notação de ponto, `math.sqrt()`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Importando objetos específicoss"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Quando fazemos a importação do módulo inteiro com `import math`, estamos trazendo para o escopo do nosso programa todas as funcionalidades contidas no módulo `math`. No entanto, em muitos casos, não precisamos de todas as funcionalidades de um módulo, e importar o módulo inteiro pode não ser necessário. Nesses casos, podemos importar funções e variáveis específicas de um módulo ao invés de importar o módulo inteiro.\n",
+    "\n",
+    "A sintaxe para importar apenas partes específicas de um módulo é a seguinte:\n",
+    "\n",
+    "```python\n",
+    "from <nome_do_modulo> import <nome_da_funcao_ou_variavel>\n",
+    "```\n",
+    "\n",
+    "Por exemplo, para importar apenas a função `sqrt` do módulo `math`, fazemos:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from math import sqrt\n",
+    "\n",
+    "print(sqrt(16))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Aqui, diferentemente do exemplo anterior, estamos importando apenas a função `sqrt` do módulo `math`. Com isso, não precisamos mais utilizar a notação de ponto para acessar a função `sqrt`, e podemos utilizá-la diretamente no nosso código. Se quisermos importar várias funções ou variáveis de um módulo, podemos fazer isso separando os nomes por vírgula:\n",
+    "\n",
+    "```python\n",
+    "from math import sqrt, pi\n",
+    "```\n",
+    "\n",
+    "Neste exemplo, estamos trazendo para o escopo do nosso programa a função `sqrt` e a variável matemática `pi` do módulo `math`.\n",
+    "\n",
+    "Caso queira acessar a documentação oficial do módulo `math`, você pode acessar [este link](https://docs.python.org/3/library/math.html). Conforme disse (e vou repetir várias vezes), a lista de módulos nativos é enorme, e a ideia é apenas dar uma visão geral sobre o conceito de módulos. Recomendo fortemente que você explore a lista completa de módulos nativos na [documentação oficial](https://docs.python.org/3/library/index.html)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Um pequeno desafio matemático"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Antes sequer de apresentar o desafio, vou fazer um comentário para deixar claro algo que sempre me perguntam sobre *problemas reais* em programação. \n",
+    "\n",
+    "Programação é só uma ferramenta, um meio para resolver um problema fim. Caso você não saiba a área do problema fim (biologia, matemática, direito, medicina, finanças, RH, esporte, seja lá qual área for), de nada adianta você saber programar...\n",
+    "\n",
+    "```{image} ../gifs/09-01-tapa-na-cara.gif\n",
+    ":name: tapa-na-cara\n",
+    "```\n",
+    "\n",
+    "... desculpem por esse *tapa na cara*, mas essa é a realidade que pouquíssima gente fala (talvez porque falar a verdade não vende, sei lá, mas meu livro é meu e é de graça, então posso falar...)\n",
+    "\n",
+    "Dito isso, vamos ao desafio, que envolve um pouco de geografia e matemática:\n",
+    "\n",
+    "> A superfície da Terra é curva, e a distância entre graus de longitude varia com a latitude. Como resultado, encontrar a distância em linha reta entre dois pontos na superfície da Terra considerando a sua curvatura é mais complicado do que simplesmente usar o teorema de Pitágoras.\n",
+    "> \n",
+    "> Sejam (lat1, long1) e (lat2, long2) a latitude e longitude de dois pontos na superfície da Terra. A distância entre esses pontos, em linha reta, seguindo a superfície da Terra, em quilômetros (km) é:\n",
+    "> \n",
+    "> $$\\text{distância}=6371.01\\times\\arccos(\\sin(lat_1)\\times\\sin(lat_2)+\\cos(lat_1)\\times\\cos(lat_2)\\times\\cos(long_1-long_2))$$\n",
+    "> \n",
+    "> O valor 6371.01 na equação anterior não foi selecionado aleatoriamente. É o raio médio da Terra em quilômetros.\n",
+    "> \n",
+    "> Crie um programa que exiba a distância entre os pontos dados, seguindo a superfície da terra, em quilômetros.\n",
+    "> ```{admonition} Dica (radianos)\n",
+    "> :class: hint\n",
+    ">\n",
+    "> As funções trigonométricas do Python operam em radianos. Como resultado, você precisará converter as coordenadas de graus para radianos antes de calcular a distância com a fórmula discutida anteriormente. O módulo `math` contém uma função chamada radians que converte de graus para radianos.\n",
+    "> ```\n",
+    "\n",
+    "Este é um problema real! Depois da resolução, vou mostrar que o Google Maps mostra exatamente a mesma distância entre dois pontos que o nosso programa. Vamos lá!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "A distância em linha reta entre os dois pontos dados é de 8.95 km\n"
+     ]
+    }
+   ],
+   "source": [
+    "import math\n",
+    "\n",
+    "\n",
+    "def calcular_distancia(lat1, lon1, lat2, lon2):\n",
+    "    # Converter graus para radianos\n",
+    "    lat1, lon1, lat2, lon2 = map(math.radians, [lat1, lon1, lat2, lon2])\n",
+    "\n",
+    "    distancia = 6371.01 * math.acos(\n",
+    "        math.sin(lat1) * math.sin(lat2)\n",
+    "        + math.cos(lat1) * math.cos(lat2) * math.cos(lon1 - lon2)\n",
+    "    )\n",
+    "\n",
+    "    return distancia\n",
+    "\n",
+    "\n",
+    "# ponto 1: coordenadas da praça da Sé em São Paulo capturadas usando Google Maps\n",
+    "lat_praca_da_se = -23.550305025464485\n",
+    "lon_praca_da_se = -46.634182529683606\n",
+    "\n",
+    "# ponto 2: coordenadas do aeroporto de Congonhas em São Paulo capturadas usando Google Maps\n",
+    "lat_aeroporto_congonhas = -23.627975178268755\n",
+    "long_aeroporto_congonhas = -46.65714724537711\n",
+    "\n",
+    "distancia = calcular_distancia(\n",
+    "    lat_praca_da_se, lon_praca_da_se, lat_aeroporto_congonhas, long_aeroporto_congonhas\n",
+    ")\n",
+    "\n",
+    "print(f\"A distância em linha reta entre os dois pontos dados é de {distancia:.2f} km\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Vejam no print abaixo que a distância do nosso programa é exatamente a mesma do Google Maps.\n",
+    "\n",
+    "```{image} ../img/09-02-distancia-se-congonhas.png\n",
+    ":height: 800px\n",
+    "```\n",
+    "\n",
+    "```{admonition} Nota (distância em linha reta!)\n",
+    ":class: note\n",
+    "Apesar de aparecer no print a distância do trajeto de carro de 10 km, o que calculamos é a distância em linha reta entre dois pontos na superfície da Terra considerando sua curvatura.\n",
+    "```"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "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.12.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

book/_config.yml

@@ -40,3 +40,7 @@ parse:
     # don't forget to list any other extensions you want enabled,
     # including those that are enabled by default! See here: https://jupyterbook.org/en/stable/customize/config.html
     - html_image
+
+sphinx:
+  config:
+    mathjax_path: https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

book/_toc.yml

@@ -57,6 +57,7 @@ parts:
 - caption: Módulos e pacotes
   chapters:
   - file: 09-modulos/01-introducao.ipynb
+  - file: 09-modulos/02-modulos-nativos.ipynb
 
 - caption: Pratique
   chapters: