Modules
& Packages

# geometrie.py
"""Module de calculs géométriques."""
import math

PI = math.pi   # constante publique
_PRECISION = 6 # _ = convention "privé" (non exporté)

def aire_cercle(rayon: float) -> float:
    """Calcule l'aire d'un cercle."""
    return round(PI * rayon ** 2, _PRECISION)

def perimetre_cercle(rayon: float) -> float:
    return round(2 * PI * rayon, _PRECISION)

class Rectangle:
    def __init__(self, l, h): self.l, self.h = l, h
    def aire(self): return self.l * self.h

import geometrie

# Attributs automatiques
print(geometrie.__name__)    # "geometrie"
print(geometrie.__file__)    # chemin absolu du .py
print(geometrie.__doc__)     # docstring du module

# Lister les symboles publics
print(dir(geometrie))
# ['PI', 'Rectangle', 'aire_cercle', 'perimetre_cercle', …]
# Les _ sont inclus mais marqués comme privés par convention

# Vérifier si un module est déjà importé (cache)
import sys
print("geometrie" in sys.modules)  # True

# 1. Import du module entier (recommandé)
import math
print(math.pi)              # namespace clair

# 2. Alias (noms longs ou conventions)
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

# 3. Import de symboles spécifiques
from math import sqrt, pi, cos
print(sqrt(16))             # sans préfixe

# 4. Import avec alias
from datetime import datetime as dt

# 5. ✗ Import étoile — DÉCONSEILLÉ
from math import *    # pollue le namespace
# Seul cas acceptable : REPL interactif ou __init__.py réexportant

# Import conditionnel (compatibilité)
try:
    import ujson as json   # rapide si disponible
except ImportError:
    import json             # fallback stdlib

# Import paresseux (éviter les imports circulaires)
def traiter_image(chemin):
    from PIL import Image   # importé seulement si la fonction est appelée
    return Image.open(chemin)

# Import dynamique (importlib)
import importlib
module = importlib.import_module("json")
data = module.loads('{"clé": 42}')

# calculatrice.py

def additionner(a: float, b: float) -> float:
    return a + b

def diviser(a: float, b: float) -> float:
    if b == 0:
        raise ValueError("Division par zéro")
    return a / b

# Exécuté seulement si : python calculatrice.py
# PAS exécuté si :       import calculatrice
if __name__ == "__main__":
    print(additionner(3, 4))
    print(diviser(10, 2))
    # Tests rapides, démo, CLI…

# mon_package/__main__.py
# Permet : python -m mon_package

from . import main_function

if __name__ == "__main__":
    main_function()

# Lancer le serveur HTTP de la stdlib
python -m http.server 8080

# Lancer les tests
python -m pytest

# Installer une dépendance
python -m pip install requests

# Profiler un script
python -m cProfile mon_script.py

import sys

# Python cherche les modules dans cet ordre :
for chemin in sys.path:
    print(chemin)
# 1. "" ou le répertoire du script courant
# 2. PYTHONPATH (variable d'environnement)
# 3. Répertoires d'installation (stdlib)
# 4. site-packages (packages installés via pip)

# Ajouter un chemin dynamiquement
sys.path.insert(0, "/mon/chemin/custom")

# Meilleure approche : variable d'environnement
# export PYTHONPATH="/mon/chemin:$PYTHONPATH"

import requests
print(requests.__file__)
# /home/user/.venv/lib/python3.11/
#   site-packages/requests/__init__.py

# Ou en ligne de commande
python -c "import requests; print(requests.__file__)"

# Depuis main.py

# Import absolu (toujours préféré)
from mon_package.modele import Utilisateur
from mon_package.utils.validateurs import valider_email
import mon_package.service

# Utilisation
u = Utilisateur("Alice", "alice@heh.be")
ok = valider_email(u.email)
mon_package.service.traiter(u)

"""
mon_package — description du package.
Version : 1.0.0
"""

# Réexporter les symboles principaux
# Permet : from mon_package import Utilisateur
# au lieu de : from mon_package.modele import Utilisateur
from .modele  import Utilisateur
from .service import traiter, envoyer

# Métadonnées
__version__ = "1.0.0"
__author__  = "Erwin"

# Contrôle de import *  (optionnel)
__all__ = ["Utilisateur", "traiter", "envoyer"]

# Sans __init__.py réexportant :
from mon_package.modele import Utilisateur  # long

# Avec __init__.py réexportant :
from mon_package import Utilisateur          # simple
import mon_package
print(mon_package.__version__)                # "1.0.0"

# Dans mon_package/service.py

# . = package courant (mon_package)
from . import modele
from .modele import Utilisateur

# .utils = sous-package utils
from .utils import validateurs
from .utils.validateurs import valider_email

# .. = package parent
# (depuis mon_package/utils/convertisseurs.py)
from .. import modele           # remonte à mon_package
from ..service import traiter

# validateurs.py

__all__ = ["valider_email", "valider_telephone"]
# Seules ces fonctions sont exposées avec import *
# Les autres restent accessibles mais "privées"

def valider_email(email: str) -> bool:
    import re
    return bool(re.match(r"[^@]+@[^@]+\.[^@]+", email))

def valider_telephone(tel: str) -> bool:
    return tel.replace(" ", "").isdigit()

def _nettoyer_chaine(s: str) -> str:   # "privé"
    return s.strip().lower()

# from validateurs import *
# → importe uniquement valider_email et valider_telephone

# Public — utilisable depuis l'extérieur
def ma_fonction(): ...
class MaClasse: ...
CONSTANTE = 42

# "Protégé" — convention : ne pas utiliser hors du module
def _helper(): ...
class _BaseInterne: ...

# "Privé" Python — name mangling dans les classes
class MaClasse:
    def __init__(self):
        self.__secret = 42  # renommé _MaClasse__secret

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "mon-package"
version = "1.0.0"
description = "Description courte"
readme = "README.md"
requires-python = ">=3.10"
license = {text = "MIT"}
authors = [
    {name = "Erwin", email = "erwin.desmet@heh.be"}
]

# Dépendances obligatoires
dependencies = [
    "requests>=2.28",
    "pydantic>=2.0",
]

# Dépendances optionnelles
[project.optional-dependencies]
dev = ["pytest", "black", "ruff"]

# Point d'entrée CLI
[project.scripts]
mon-outil = "mon_package.__main__:main"

# Installer le projet en mode développement
# (les modifications sont prises en compte immédiatement)
pip install -e .

# Installer avec les dépendances dev
pip install -e ".[dev]"

# Construire le package distribuable
python -m build
# → dist/mon_package-1.0.0.tar.gz
# → dist/mon_package-1.0.0-py3-none-any.whl

# Publier sur PyPI
python -m twine upload dist/*

# ✗ Conflit — deux sqrt dans le namespace
from math  import sqrt
from cmath import sqrt  # écrase le précédent !

# ✓ Utiliser des alias
from math  import sqrt as sqrt_reel
from cmath import sqrt as sqrt_complexe

# ✓ Ou garder le module comme namespace
import math
import cmath
math.sqrt(4)    # 2.0
cmath.sqrt(-1)  # 1j

# ✗ Import circulaire — ERREUR
# a.py
from b import func_b  # b importe a → ImportError

# b.py
from a import func_a  # a importe b → cycle

# ✓ Solutions :
# 1. Restructurer : extraire le code partagé dans un 3e module
# 2. Import paresseux dans la fonction
def func_a():
    from b import func_b  # importé au moment de l'appel
    func_b()

# 3. Annotation de type en string (TYPE_CHECKING)
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from b import TypeB  # uniquement pour le type checker