{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 🐍 Les fonctions en Python\n",
    "### SNT – Seconde\n",
    "\n",
    "Dans ce notebook, tu vas découvrir comment **créer tes propres fonctions** pour éviter de répéter le même calcul des dizaines de fois.\n",
    "\n",
    "> 💡 **Rappel** : pour exécuter une cellule, clique dessus puis appuie sur **Shift + Entrée**.\n",
    "\n",
    "---\n",
    "## Pourquoi des fonctions ?\n",
    "\n",
    "Imagine que tu dois calculer la vitesse de 6 véhicules différents. Sans fonction, tu répètes le même calcul 6 fois :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Sans fonction : on répète le même calcul pour chaque véhicule\n",
    "# (distance en mètres, temps en secondes)\n",
    "\n",
    "v1 = (500 / 1000) / (45 / 3600)   # voiture\n",
    "v2 = (200 / 1000) / (28 / 3600)   # vélo\n",
    "v3 = (1200 / 1000) / (60 / 3600)  # train\n",
    "\n",
    "print(v1, \"km/h\")\n",
    "print(v2, \"km/h\")\n",
    "print(v3, \"km/h\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ce code fonctionne, mais il est long, répétitif, et difficile à relire.  \n",
    "Et si on veut corriger une erreur dans la formule, il faut la corriger **partout** !\n",
    "\n",
    "→ La solution : **écrire la formule une seule fois dans une fonction**, puis l'appeler autant de fois qu'on veut."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## Partie 1 – Créer une fonction simple\n",
    "\n",
    "Une fonction, c'est un **bloc de code réutilisable** auquel on donne un nom.\n",
    "\n",
    "```python\n",
    "def nom_de_la_fonction(paramètre):\n",
    "    résultat = ...        # on fait le calcul\n",
    "    return résultat       # on renvoie le résultat\n",
    "```\n",
    "\n",
    "- `def` : mot-clé qui signifie « je définis une fonction »\n",
    "- Le **paramètre** : la valeur qu'on donne à la fonction (ce qu'elle reçoit)\n",
    "- `return` : ce que la fonction **renvoie** comme résultat\n",
    "\n",
    "### 📐 Exemple 1 : convertir des mètres en kilomètres\n",
    "\n",
    "Pour convertir des mètres en kilomètres, on divise par 1000. On va écrire cette conversion une fois pour toutes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def metres_en_km(distance_m):\n",
    "    distance_km = distance_m / 1000\n",
    "    return distance_km"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "La cellule ci-dessus **définit** la fonction, mais ne fait aucun calcul encore.  \n",
    "Pour l'utiliser, il faut **l'appeler** avec une valeur :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# On appelle la fonction avec différentes valeurs\n",
    "print(metres_en_km(500))    # 500 m → ? km\n",
    "print(metres_en_km(1200))   # 1200 m → ? km\n",
    "print(metres_en_km(42195))  # marathon → ? km"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# On peut aussi stocker le résultat dans une variable\n",
    "distance_marathon = metres_en_km(42195)\n",
    "print(f\"Un marathon mesure {distance_marathon} km\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### ✏️ Exercice 1\n",
    "\n",
    "Sur le modèle de `metres_en_km`, crée une fonction `secondes_en_heures` qui convertit une durée en secondes en heures.  \n",
    "*(Pour convertir des secondes en heures, on divise par 3600)*\n",
    "\n",
    "Teste-la avec :\n",
    "- 3600 secondes → doit donner 1.0 h\n",
    "- 5400 secondes → doit donner 1.5 h\n",
    "- 45 secondes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Écris ta fonction ici\n",
    "def secondes_en_heures(duree_s):\n",
    "    duree_h = ...       # à compléter\n",
    "    return duree_h\n",
    "\n",
    "# Tests\n",
    "print(secondes_en_heures(3600))   # doit afficher 1.0\n",
    "print(secondes_en_heures(5400))   # doit afficher 1.5\n",
    "print(secondes_en_heures(45))     # à toi de vérifier"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## Partie 2 – Fonction avec plusieurs paramètres\n",
    "\n",
    "Une fonction peut recevoir **plusieurs paramètres**, séparés par des virgules.\n",
    "\n",
    "```python\n",
    "def nom_fonction(param1, param2):\n",
    "    résultat = ...   # calcul utilisant param1 et param2\n",
    "    return résultat\n",
    "```\n",
    "\n",
    "### 🚗 Exemple 2 : calculer une vitesse en km/h\n",
    "\n",
    "La vitesse se calcule avec : **v = distance / temps**  \n",
    "Mais les données brutes sont souvent en **mètres** et en **secondes**.  \n",
    "On va utiliser les deux fonctions déjà créées !"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def vitesse_kmh(distance_m, temps_s):\n",
    "    # On convertit d'abord les unités\n",
    "    d_km = metres_en_km(distance_m)        # on réutilise notre fonction !\n",
    "    t_h  = secondes_en_heures(temps_s)     # idem\n",
    "    # Puis on calcule la vitesse\n",
    "    v = d_km / t_h\n",
    "    return v"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Testons avec quelques véhicules\n",
    "v_voiture = vitesse_kmh(500, 45)\n",
    "v_velo    = vitesse_kmh(200, 28)\n",
    "v_train   = vitesse_kmh(1200, 60)\n",
    "\n",
    "print(f\"Voiture : {v_voiture:.1f} km/h\")\n",
    "print(f\"Vélo    : {v_velo:.1f} km/h\")\n",
    "print(f\"Train   : {v_train:.1f} km/h\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Observe comme le code est maintenant **lisible et compact** : on comprend immédiatement ce que fait chaque ligne, et la formule n'est écrite qu'une seule fois.\n",
    "\n",
    "### ✏️ Exercice 2\n",
    "\n",
    "Lors d'une sortie sportive, des élèves ont mesuré les données suivantes :\n",
    "\n",
    "| Élève | Distance (m) | Temps (s) |\n",
    "|-------|-------------|----------|\n",
    "| Alice | 400 | 72 |\n",
    "| Bruno | 400 | 68 |\n",
    "| Chloé | 400 | 75 |\n",
    "\n",
    "Utilise la fonction `vitesse_kmh` pour calculer et afficher la vitesse de chaque élève en km/h.  \n",
    "Affiche les résultats avec des f-strings lisibles."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Écris ton code ici\n",
    "v_alice = vitesse_kmh(..., ...)\n",
    "v_bruno = vitesse_kmh(..., ...)\n",
    "v_chloe = vitesse_kmh(..., ...)\n",
    "\n",
    "print(f\"Alice : {v_alice:.1f} km/h\")\n",
    "print(f\"Bruno : ...\")\n",
    "print(f\"Chloé : ...\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## Partie 3 – Documenter une fonction\n",
    "\n",
    "Une bonne fonction s'accompagne d'une courte description appelée **docstring** (entre triple guillemets `\"\"\"`).  \n",
    "Elle explique ce que fait la fonction, ce qu'elle reçoit, et ce qu'elle renvoie."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def vitesse_kmh(distance_m, temps_s):\n",
    "    \"\"\"\n",
    "    Calcule la vitesse en km/h.\n",
    "    \n",
    "    Paramètres :\n",
    "      distance_m : distance parcourue en mètres\n",
    "      temps_s    : durée du trajet en secondes\n",
    "    \n",
    "    Renvoie : la vitesse en km/h (float)\n",
    "    \"\"\"\n",
    "    d_km = metres_en_km(distance_m)\n",
    "    t_h  = secondes_en_heures(temps_s)\n",
    "    return d_km / t_h\n",
    "\n",
    "# La fonction help() affiche la docstring\n",
    "help(vitesse_kmh)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## ✏️ Exercice Final — Analyse d'une course\n",
    "\n",
    "Lors d'une compétition de natation, on a relevé les temps des nageurs sur **50 m**, **100 m** et **200 m**.\n",
    "\n",
    "| Nageur | 50 m (s) | 100 m (s) | 200 m (s) |\n",
    "|--------|---------|----------|----------|\n",
    "| Léo    | 28.4    | 59.1     | 128.5    |\n",
    "| Maya   | 27.9    | 58.3     | 125.2    |\n",
    "| Théo   | 29.1    | 61.0     | 131.7    |\n",
    "\n",
    "**Questions :**\n",
    "\n",
    "1. Calcule la vitesse de chaque nageur sur 50 m (en km/h) en utilisant `vitesse_kmh`\n",
    "2. Crée une fonction `temps_moyen_par_50m(temps_total_s, nb_longueurs)` qui calcule le temps moyen pour parcourir 50 m lorsqu'on en a parcouru plusieurs.  \n",
    "   *(Formule : temps_total / nb_longueurs)*  \n",
    "   Teste-la pour calculer le temps moyen par 50 m de Léo sur 200 m (4 longueurs).\n",
    "3. **Bonus** : Qui a la vitesse moyenne la plus élevée sur 200 m ?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Question 1 — Vitesses sur 50 m\n",
    "v_leo_50   = vitesse_kmh(50, ...)\n",
    "v_maya_50  = vitesse_kmh(..., ...)\n",
    "v_theo_50  = vitesse_kmh(..., ...)\n",
    "\n",
    "print(\"=== Vitesses sur 50 m ===\")\n",
    "print(f\"Léo  : {v_leo_50:.2f} km/h\")\n",
    "print(f\"Maya : ...\")\n",
    "print(f\"Théo : ...\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Question 2 — Fonction temps moyen par 50 m\n",
    "def temps_moyen_par_50m(temps_total_s, nb_longueurs):\n",
    "    \"\"\"\n",
    "    Calcule le temps moyen pour parcourir 50 m.\n",
    "    \n",
    "    Paramètres :\n",
    "      temps_total_s  : temps total de la course en secondes\n",
    "      nb_longueurs   : nombre de longueurs de 50 m\n",
    "    \n",
    "    Renvoie : le temps moyen par longueur (float)\n",
    "    \"\"\"\n",
    "    temps_moyen = ...   # à compléter\n",
    "    return temps_moyen\n",
    "\n",
    "# Test : Léo sur 200 m = 4 longueurs de 50 m\n",
    "t_moyen_leo = temps_moyen_par_50m(128.5, 4)\n",
    "print(f\"Léo — temps moyen par 50 m : {t_moyen_leo:.2f} s\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Bonus — Vitesses moyennes sur 200 m\n",
    "v_leo_200  = vitesse_kmh(200, ...)\n",
    "v_maya_200 = vitesse_kmh(200, ...)\n",
    "v_theo_200 = vitesse_kmh(200, ...)\n",
    "\n",
    "print(\"=== Vitesses sur 200 m ===\")\n",
    "print(f\"Léo  : {v_leo_200:.2f} km/h\")\n",
    "print(f\"Maya : {v_maya_200:.2f} km/h\")\n",
    "print(f\"Théo : {v_theo_200:.2f} km/h\")\n",
    "\n",
    "# Qui est le plus rapide ?\n",
    "vitesse_max = max(v_leo_200, v_maya_200, v_theo_200)\n",
    "print(f\"\\nVitesse maximale sur 200 m : {vitesse_max:.2f} km/h\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## 🎯 Bilan\n",
    "\n",
    "Dans ce notebook, tu as appris à :\n",
    "\n",
    "| Notion | Ce que tu sais faire |\n",
    "|--------|---------------------|\n",
    "| `def` | Définir une fonction avec un nom et des paramètres |\n",
    "| `return` | Renvoyer un résultat depuis une fonction |\n",
    "| **Appeler** une fonction | Utiliser une fonction avec des valeurs concrètes |\n",
    "| **Composer** des fonctions | Appeler une fonction depuis une autre |\n",
    "| **Docstring** | Documenter une fonction avec `\"\"\"` |\n",
    "\n",
    "> 💡 **À retenir** : une bonne fonction fait **une seule chose**, a un **nom clair**, et peut être **réutilisée** partout dans le programme.\n",
    "\n",
    "**Bravo ! 🐍**"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}