Désapprouver un paramètre de fonction — Guide de contribution

[tantale]

Désapprouver un paramètre de fonction

Introduction

Cet article concerne l’ajout d’un (ou plusieurs) décorateur(s) permettant de désapprouver l’utilisation d’un paramètre de fonction. Par exemple :

@deprecated_param(version="0.2.3",
                  reason="you may consider using *styles* instead.",
                  deprecated_args='color background_color')
def paragraph(text, color=None, background_color=None, styles=None):
    styles = styles or {}
    if color:
        styles['color'] = color
    if background_color:
        styles['background-color'] = background_color
    html_styles = " ".join("{k}: {v};".format(k=k, v=v) for k, v in styles.items())
    html_text = xml.sax.saxutils.escape(text)
    return ('<p styles="{html_styles}">{html_text}</p>'
            .format(html_styles=html_styles, html_text=html_text))

Un tel décorateur pourrait être codé ainsi :

import functools


def deprecated_param(version, reason, deprecated_args):
    def decorate(func):
        @functools.wraps(func)
        def call(*args, **kwargs):
            # todo: check deprecated arguments here...
            return func(*args, **kwargs)

        return call

    return decorate

Avantages et désavantages du décorateur

Utiliser un décorateur pour désapprouver l’usage d’un paramètre de fonction est intéressant et offre certains avantages :

• Le décorateur permet d’isoler le code qui vérifie l’usage de ce paramètre du reste du traitement de la fonction : séparation des concepts (Separation of Concerns design pattern).
• Le décorateur permet une documentation explicite du code, l’utilisation de commentaire est donc inutile : « La lisibilité compte ».
• Le décorateur pourrait permettre d’enrichir la documentation du code (la docstring de la fonction décorée).

Désavantage :

• L’implémentation d’un tel décorateur est nécessairement plus complexe qu’une solution spécifique.
• La fonction résultante de la décoration est nécessairement plus lente que la fonction décorée à cause l’introspection et de la vérification de l’usage des paramètres.

Autre considération importante :

• La fonction résultante de la décoration doit être de même nature que la fonction décorée : fonction, méthode, méthode statique, etc.

Généralisation

Outre le cas de déprécation de l’usage d’un paramètre, on pourrait aussi émettre un avertissement dans les cas suivants :

• Un paramètre a été renommé : le nouveau nom est plus parlant, plus explicite, etc.
• Un paramètre est remplacé par un autre d’usage plus général.
• Le type d’un paramètre change, il est préférable d’en utiliser un autre.
• Un paramètre est considéré obsolète, il sera supprimé dans une version future.
• Un nouveau paramètre a été rajouté, son usage est fortement recommandé.
• Etc.

Les cas d’utilisation cités ci-dessus rentrent dans 3 catégories :

1. Paramètre supprimé,
2. Paramètre ajouté,
3. Paramètre modifié (valeur par défaut, type ou usage modifié).
   Le troisième cas (paramètre modifié) est le plus difficile à spécifier de manière générale.

Exemples de déprécations

(Cette rubrique est incomplète)
Avant de ce lancer dans une implémentation complexe, il faudrait étudier ce qui ce fait, d’une part dans la Bibliothèque Standard, et d’autre part dans les bibliothèques populaires du monde Open Source telles que : pip, urllib3, boto3, six, requests, setuptools, futures, Flask, Django, etc.
Au moins deux questions sont à considérer concernant la déprécation :

• Comment est-ce mis en œuvre dans le code source ?
• Comment est-ce documenté ?

Implémentation

(Cette rubrique est incomplète)
L’implémentation d’un décorateur de déprécation de paramètre doit être flexible. Il est nécessaire d’être aussi souple que possible et de reprendre ce qu’il existe pour @deprecated.basic.deprecated et @deprecated.sphinx.deprecated. Notamment, l’usage de Wrapt est un must-have.
Il faut aussi définir des cas de tests qui correspondent aux scénarios les plus courant. Il est probable aussi que certaines situations atypiques soient clairement non implémentées.
Pour l’instant, je souhaite continuer le support de Python 2.7, car il est encore utilisé part 25 % des utilisateurs (selon le sondage State of Developer Ecosystem de 2018).