syspathmodif 1.7.0

This library offers concise manners to modify list sys.path. The user should not need to directly interact with that list.

FRANÇAIS

Cette bibliothèque offre des manières concises de modifier la liste sys.path. L'utilisateur ne devrait pas avoir besoin d'interagir directement avec cette liste.

Le type Strath

La bibliothèque strath, une dépendance de syspathmodif, convertit les chemins de fichier en chaînes de caractères (str) ou en instances de pathlib.Path. Elle définit l'alias de type (TypeAlias) Strath comme un équivalent de str | Path.

Contenu

Les fonctions suivantes prennent un chemin de type str ou pathlib.Path comme argument. Elles convertissent les arguments de type pathlib.Path en str puisque sys.path n'est censée contenir que des chaînes de caractères.

• sp_append ajoute le chemin donné à la fin de sys.path.
• sp_contains indique si sys.path contient le chemin donné.
• sp_prepend ajoute le chemin donné au début de sys.path.
• sp_remove enlève le chemin donné de sys.path.

Au moment de sa création, une instance de SysPathBundle contient plusieurs chemins et les ajoute au début de sys.path. Quand on vide (clear) une instance, elle efface son contenu et l'enlève de sys.path. Ainsi, cette classe facilite l'ajout et le retrait d'un groupe de chemins.

Il est possible d'utiliser SysPathBundle comme un gestionnaire de contexte (context manager). Dans ce cas, l'instance est vidée à la fin du bloc with.

La fonction sm_contains prend comme argument un nom (str) de module. Elle indique si le dictionnaire sys.modules contient ce module.

Les fonctions suivantes permettent d'ajouter au début de sys.path le chemin de dossiers parents du fichier qui les appelle. Des indices passés en argument identifient les parents. Soit une instance p de pathlib.Path représentant le chemin du fichier appelant. Le dossier parent identifié par l'indice i passé à ces fonctions correspond au chemin renvoyé par p.parents[i].

• sp_prepend_parent ajoute un chemin parent à sys.path.
• sp_prepend_parent_bundle passe un ou plusieurs chemins parents à une instance de SysPathBundle puis renvoie cette dernière.

Pour plus d'informations, consultez la documentation et les démos dans le dépôt de code source.

Importations et sys.path

Il est possible d'importer un module si la liste sys.path contient le chemin de son dossier parent. On peut donc rendre un module importable en ajoutant son chemin parent à sys.path.

Importations et sys.modules

Le dictionnaire sys.modules associe des noms (str) de module au module correspondant. Le système d'importation l'utilise comme cache; tout module importé pour la première fois y est conservé. Puisque le système d'importation cherche d'abord les modules demandés dans sys.modules, les modules qu'il contient peuvent être importés partout sans qu'on modifie sys.path.

Sachant cela, on peut déterminer à l'aide de la fonction sm_contains si un module est déjà importable. Si sm_contains renvoie vrai (True), il n'est pas nécessaire de modifier sys.path pour importer le module donné.

ENGLISH

This library offers concise manners to modify list sys.path. The user should not need to directly interact with that list.

Type Strath

Library strath, a dependency of syspathmodif, converts file paths to character strings (str) or pathlib.Path instances. It defines type alias (TypeAlias) Strath as an equivalent of str | Path.

Content

The following functions take a path of type str or pathlib.Path as an argument. They convert arguments of type pathlib.Path to str since sys.path is supposed to contain only character strings.

• sp_append adds the given path to the end of sys.path.
• sp_contains indicates whether sys.path contains the given path.
• sp_prepend adds the given path to the beginning of sys.path.
• sp_remove removes the given path from sys.path.

Upon creation, a SysPathBundle instance stores several paths and prepends them to sys.path. When a bundle is cleared, it erases its content and removes it from sys.path. Thus, this class facilitates adding and removing a group of paths.

SysPathBundle can be used as a context manager. In that case, the instance is cleared at the with block's end.

Function sm_contains takes a module's name (str) as an argument. It indicates whether dictionary sys.modules contains the module.

The following functions allow to prepend to sys.path the paths to parent directories of the file that calls them. Indices passed as arguments identify the parents. Let be a pathlib.Path instance p representing the path to the calling file. The parent directory identified by index i passed to these functions matches the path returned by p.parents[i].

• sp_prepend_parent prepends one parent path to sys.path.
• sp_prepend_parent_bundle passes one or many parent paths to a SysPathBundle then returns the bundle.

For more information, consult the documentation and the demos in the source code repository.

Imports and sys.path

It is possible to import a module if list sys.path contains the path to its parent directory. Therefore, you can make a module importable by adding its parent path to sys.path.

Imports and sys.modules

Dictionary sys.modules maps module names (str) to the corresponding module. The import system uses it as a cache; any module imported for the first time is stored in it. Since the import system looks for the requested modules in sys.modules first, the modules that it contains can be imported everywhere with no modifications to sys.path.

Knowing this, you can use function sm_contains to determine if a module is already importable. If sm_contains returns True, modifiying sys.path is not required to import the given module.