Objectifs d'apprentissage

À la fin de cette section, vous devriez être en mesure de :

• Utiliser la fonction help() pour explorer le contenu d'un module.
• Identifier les parties de code incluses dans la documentation.

Les couleurs sur les sites web

Cette section présente un exemple de module permettant de manipuler les couleurs HTML. Le langage HyperText Markup Language (HTML) est utilisé pour concevoir des sites web et des applications graphiques. Les navigateurs web comme Chrome et Safari lisent le code HTML et affichent les contenus correspondants. Ex. : le code HTML <p style="color: Red">Look out!</p> représente un paragraphe contenant du texte rouge.

HTML définit 140 noms de couleurs standard. D'autres couleurs peuvent être spécifiées au format hexadécimal : #RRGGBB. Les chiffres RR, GG et BB représentent les composantes rouge, verte et bleue de la couleur. Ex. : #DC143C correspond à 220 rouge + 20 vert + 60 bleu, ce qui correspond à la couleur Crimson.

Les valeurs rouge, verte et bleue vont de 0 à 255 (ou de 00 à FF en hexadécimal). Des valeurs plus faibles donnent des couleurs plus sombres, et des valeurs plus élevées donnent des couleurs plus claires. Ex. : #008000 correspond à la couleur Green, et #00FF00 correspond à la couleur Lime.

Exemple de module colors

Un module permettant de manipuler les codes de couleur HTML serait utile aux graphistes et aux développeurs web. Le code Python suivant se trouve dans un fichier nommé colors.py.

• La ligne 1 est la docstring du module.
• Les lignes 3–16 affectent des valeurs à des variables pour les couleurs fréquemment utilisées.
• Les lignes 18–24 définissent une fonction destinée à être utilisée au sein du module.
• Les lignes 26–45 définissent des fonctions destinées à être utilisées dans d'autres modules.

Remarque : les fonctions tohex() et torgb() utilisent des fonctionnalités de Python (le formatage et le découpage de chaînes) décrites plus loin dans l'ouvrage. Pour le moment, la documentation et les commentaires sont plus importants que les détails d'implémentation.

    """Functions for working with color names and hex/rgb values."""

    # Primary colors
    RED = "#FF0000"
    YELLOW = "#FFFF00"
    BLUE = "#0000FF"

    # Secondary colors
    ORANGE = "#FFA500"
    GREEN = "#008000"
    VIOLET = "#EE82EE"

    # Neutral colors
    BLACK = "#000000"
    GRAY = "#808080"
    WHITE = "#FFFFFF"

    def _tohex(value):
      """Converts an integer to an 8-bit (2-digit) hexadecimal string."""
      if value <= 0:
        return "00"
      if value >= 255:
        return "FF"
      return format(value, "02X")

    def tohex(r, g, b):
      """Formats red, green, and blue integers as a color in hexadecimal."""
      return "#" + _tohex(r) + _tohex(g) + _tohex(b)

    def torgb(color):
      """Converts a color in hexadecimal to red, green, and blue integers."""
      r = int(color[1:3], 16) # First 2 digits
      g = int(color[3:5], 16) # Middle 2 digits
      b = int(color[5:7], 16) # Last 2 digits
      return r, g, b

    def lighten(color):
      """Increases the red, green, and blue values of a color by 32 each."""
      r, g, b = torgb(color)
      return tohex(r+32, g+32, b+32)

    def darken(color):
      """Decreases the red, green, and blue values of a color by 32 each."""
      r, g, b = torgb(color)
      return tohex(r-32, g-32, b-32)

Documentation d'un module

La fonction intégrée help() fournit un résumé des fonctions et des données d'un module. Appeler help(module_name) dans un shell est un moyen pratique de se renseigner sur un module.

help(colors)

    Help on module colors:

    NAME
      colors - Functions for working with color names and hex/rgb values.

    FUNCTIONS
      darken(color)
        Decreases the red, green, and blue values of a color by 32 each.

      lighten(color)
        Increases the red, green, and blue values of a color by 32 each.

      tohex(r, g, b)
        Formats red, green, and blue integers as a color in hexadecimal.

      torgb(color)
        Converts a color in hexadecimal to red, green, and blue integers.

    DATA
      BLACK = '#000000'
      BLUE = '#0000FF'
      GRAY = '#808080'
      GREEN = '#008000'
      ORANGE = '#FFA500'
      RED = '#FF0000'
      VIOLET = '#EE82EE'
      WHITE = '#FFFFFF'
      YELLOW = '#FFFF00'

    FILE
      /home/student/Desktop/colors.py
    >>> help(colors)

    Help on module colors:

    NAME
      colors - Functions for working with color names and hex/rgb values.

    FUNCTIONS
      darken(color)
        Decreases the red, green, and blue values of a color by 32 each.

      lighten(color)
        Increases the red, green, and blue values of a color by 32 each.

      tohex(r, g, b)
        Formats red, green, and blue integers as a color in hexadecimal.

      torgb(color)
        Converts a color in hexadecimal to red, green, and blue integers.

    DATA
      BLACK = '#000000'
      BLUE = '#0000FF'
      GRAY = '#808080'
      GREEN = '#008000'
      ORANGE = '#FFA500'
      RED = '#FF0000'
      VIOLET = '#EE82EE'
      WHITE = '#FFFFFF'
      YELLOW = '#FFFF00'

    FILE
      /home/student/Desktop/colors.py