Documenter différentes possibilités d'argument sur la même fonction

Question

J'utilise des docstrings de type Google avec sphinx.ext.autodoc pour générer automatiquement la documentation de mes fonctions et m'assurer qu'elles sont correctement auto-documentées dans le code.

J'ai une fonction def myfunc(id=None, size=None, hash=None) qui renvoie des informations basées sur idousize + hash. Si nous avons id comme argument, size et hash ne sont pas nécessaires, si nous avons size et hash comme arguments, alors id n'est pas nécessaire.

Avec sphinx, il est possible de spécifier un argument optionnel, mais dans ce cas nous ne savons pas ce qui sera obligatoire et ce qui sera optionnel. Voici un exemple:

def get_file(id=0, size=0, hash="") 
    """ 
    Get file metadata. 

    Args: 
     id (int): id of the file. 
     size (int): file size in bytes. 
     hash (str): md5 hash of file. 

    Returns: 
     file_data (str): metadata information about the file. 
    """ 
    if id: 
     # Get file with id. 
     ... 
    elif size and hash: 
     # Get file with size and hash. 
     ... 
    else: 
     # Bad arguments, handle error. 
     ... 

    return file_data 

La question est: comment dire quels arguments sont nécessaires dans le docstring?

Vous pouvez facilement arguer que la fonction elle-même est la question, que les deux paires d'arguments devraient être même dans des fonctions distinctes si le résultat est le même:

def get_file_by_id(id) 
    """ 
    Get file metadata from id. 

    Args: 
     id (int): id of the file. 

    Returns: 
     file_data (str): metadata information about the file. 
    """ 

    # Get file with id. 
    ... 

    return file_data 

def get_file_by_hash(size, hash) 
    """ 
    Get file metadata from hash. 

    Args: 
     size (int): file size in bytes. 
     hash (str): md5 hash of file. 

    Returns: 
     file_data (str): metadata information about the file. 
    """ 

    # Get file with hash+size. 
    ... 

    return file_data 

Mais dans ce cas, une seule fonction serait préférable si possible, car la fonction est une liaison à une autre API qui utilise une seule fonction.

Answer 1

Selon la documentation, here, la définition de la méthode exemple suivant:

def module_level_function(param1, param2=None, *args, **kwargs): 

a-t-le docstring défini comme:

Args: 
    param1 (int): The first parameter. 
    param2 (:obj:`str`, optional): The second parameter. Defaults to None. 
     Second line of description should be indented. 
    *args: Variable length argument list. 
    **kwargs: Arbitrary keyword arguments. 

Donc, vous déclarez explicitement ce qui est en option comme indiqué, sinon, il serait compris comme un argument obligatoire.