Organizing codes in libraries

En bref

Résumé de l’article

Dans cet article, nous expliquons comment organiser les codes en modules. En particulier, nous montrons que l’on peut les organiser en fichiers, et comment importer des fonctions depuis ces fichiers. C’est essentiel pour la réutilisabilité des codes que vous écrivez.

Points clés

• Les codes peuvent être stockés dans des fichiers (modules).

• Ces modules peuvent être importés dans vos scripts.

• Les modules doivent être conçus comme des collections cohérentes de fonctions et de variables.

• Structurer le code de cette manière est important pour la réutilisabilité du code.

Contenu de l’article

1 — Importer des fonctions

Une propriété clé des fonctions est qu’elles peuvent être facilement réutilisées. Les fonctions peuvent être regroupées thématiquement dans des fichiers séparés.

Pour appeler une fonction, appelée par exemple funct_ext, définie dans un fichier séparé nommé mymodule.py, vous devez indiquer explicitement à l’interpréteur Python où trouver cette fonction en utilisant l’instruction import.

Cependant, le fichier mymodule.py doit être trouvé par le système. En d’autres termes, son répertoire doit être dans la variable PATH, qui est une liste de répertoires où Python cherchera les fichiers. Si ce n’est pas le cas, vous pouvez soit ajouter votre répertoire à la variable PATH au niveau système, soit ajouter le répertoire à la variable Python sys.path.

sys.path.append(os.path.join("..", "my_python_modules"))

this_directory = os.path.dirname(os.path.realpath(__file__))
sys.path.append(os.path.join(this_directory, "..", "my_python_modules"))

Voici quelques façons possibles d’importer une fonction en Python :

# Let's assume the file is not in the path
# For instance, assume it's in a directory "my_python_modules" in the parent directory containing this script
import sys
import os
sys.path.append(os.path.join("..", "my_python_modules"))

# Let's import func_ext
from mymodule import func_ext

# Now we can use the function
funct_ext()

# Let's assume the file is not in the path
# For instance, assume it's in a directory "my_python_modules" in the parent directory containing this script
import sys
import os
sys.path.append(os.path.join("..", "my_python_modules"))

# Let's import all functions from "mymodule.py"
from mymodule import *

# Now we can use the function
funct_ext()

# Let's assume the file is not in the path
# For instance, assume it's in a directory "my_python_modules" in the parent directory containing this script
import sys
import os
sys.path.append(os.path.join("..", "my_python_modules"))

# Let's import the "mymodule" module
import mymodule

# Now we can use the function precising the module in which it is
# This can be very practical when multiple modules have functions with the same name
mymodule.funct_ext()

/**
 * To run this code, you need to have Java installed on your computer, then:
 * - Create a file named `Main.java` in a directory of your choice.
 * - Copy this code in the file.
 * - Open a terminal in the directory where the file is located.
 * - Run the command `javac Main.java` to compile the code.
 * - Run the command `java -ea Main` to execute the compiled code.
 * Note: '-ea' is an option to enable assertions in Java.
 */
public class Main {

    /**
     * This is the entry point of your program.
     * It contains the first codes that are going to be executed.
     * 
     * @param args Command line arguments received.
     */
    public static void main(String[] args) {
        // Now we can use the function
        MyModule m = new MyModule()
        m.func_ext();
    }

}

En Python, lorsque vous importez un fichier, tout son contenu est exécuté. Par exemple, considérons le code suivant, dans un fichier nommé mymodule.py :

def my_function () -> None:

    """
        A function that does something in your library.
        In:
            * None.
        Out:
            * None.
    """

    print("Hello")



# Let's test our code
print("Testing my function")
my_function()

Maintenant, considérons le script suivant :

# Import the function we want
from mymodule import my_function

# Let's use the function
my_function()

Lors de l’exécution de ce script, on obtient la sortie suivante :

Testing my function
Hello
Hello

Dans une telle situation, vous ne vouliez probablement pas que la partie test soit exécutée, mais seulement que la fonction soit importée. Pour corriger cela, vous pouvez indiquer à Python qu’un certain code doit être exécuté uniquement lorsque le fichier est exécuté directement, c’est-à-dire non importé. Voici comment mettre à jour mymodule.py :

def my_function () -> None:

    """
        A function that does something in your library.
        In:
            * None.
        Out:
            * None.
    """

    print("Hello")



# This test indicates that we only run this when the file is executed directly
if __name__ == "__main__":

    # Let's test our code
    print("Testing my function")
    my_function()

Maintenant, en exécutant à nouveau le script ci-dessus, on obtient la sortie attendue :

Hello

Notez qu’en Java, il y a un point d’entrée unique appelé la fonction main, tandis que chaque script Python peut être exécuté indépendamment.

2 — Structurer le code en fichiers séparés

Certain code que vous écrivez peut être suffisamment générique pour être utilisé dans d’autres projets. En général, il est bon de systématiquement séparer vos fonctions en fichiers thématiques. Les codes que vous écrivez maintenant peuvent être utiles dans quelques leçons, années de bourse, ou peut-être plus tard.

Pour créer un morceau de code réutilisable, on sauvegarde le code dans un fichier séparé avec une extension .py. Un tel fichier Python s’appelle un “module”.

Pour garder le code organisé, il est bon de le diviser en plusieurs fichiers. Par exemple :

• main.py – Le script principal.
• functions.py – Contient des fonctions réutilisables.

La structure d’un fichier tel que functions.py doit suivre la convention suivante :

"""
    General description of the document contents.
"""

# Needed imports
# ...

# Various functions, well documented.
# ...

# Things to do when running this code directly
if __name__ == "__main__":
    # ...

// Needed imports
// ...



/**
 * General description of the class contents.
 * Here, we name the class Functions for the example.
 * It should match file name.
 */
public class Functions
{

    /**
     * Various functions, well documented.
     */
    // ...

}

N’hésitez pas à avoir plusieurs fichiers auxiliaires de ce type, correspondant à des thèmes. Par exemple, vous pourriez avoir un fichier nommé math_functions.py, et un autre nommé network_functions.py.

Pour aller plus loin

On dirait que cette section est vide !

Y a-t-il quelque chose que vous auriez aimé voir ici ? Faites-le nous savoir sur le serveur Discord ! Peut-être que nous pourrons l’ajouter rapidement. Sinon, cela nous aidera à améliorer le cours pour l’année prochaine !

Pour aller encore plus loin

• pydoc – Générateur de documentation et système d’aide en ligne.

  Certains outils peuvent être utilisés pour analyser automatiquement la documentation et créer de belles pages web.

• Packaging Python projects.

  Si vous voulez savoir comment écrire votre propre package Python, que vous pourrez ensuite distribuer.