Bioinfo Blog!

In questi giorni sto cercando di proporre l’utilizzo del modulo doctest all’interno del progetto biopython, perché penso ne potrebbe migliorare la documentazione.

doctest é un modulo incluso nella distribuzione standard di python, che permette di introdurre i test per i propri script direttamente nella loro documentazione.

Facciamo un piccolo esempio. Mettiamo di voler scrivere un modulo in grado di parsare un nuovo formato di sequenze, che chiameremo ‘MinusMinus’. Senza dettagliare il codice, la sua documentazione con doctest sarebbe qualcosa del genere:

def MinusMinusFormatParser(filehandle, options):
    """
    Parse the 'MinusMinus' file format for sequences.
    Returns a 'SequenceSet' object.

    # Here it is a sample 'MinusMinus' file:
    >>> from StringIO import StringIO
    >>> testfile = StringIO('''
    ... --seq1
    ... ACGTCGATCGATCGTCAGTCGATC
    ... ACGTACGTATCGTACGTACGTAGC
    ... --seq2
    ... AGATCGTACGTAGCTAGCTAGTCG
    ... ''')
    >>> sequences = MinusMinusFormatParser(testfile, options=None)
    File parsed. ok!

    # MinuxMinusFormatParser returns a SequenceSet object:
    >>> print sequences
    SequenceSet object with 2 sequences

    # use the .format method to print these sequences in the fasta format:
    >>> print sequences.format('fasta')
    >seq1
    ACGTCGATCGATCGTCAGTCGATC
    ACGTACGTATCGTACGTACGTAGC
    >seq2
    AGATCGTACGTAGCTAGCTAGTCG

    """
    pass

if __name__ == '__main__':
    import doctest
    doctest.testmod()

Questa é la documentantazione di un ipotetico parser per il formato MinusMinus.
Vedete che nella stessa docstring del modulo ho messo degli esempi di come questo dovrebbe essere utilizzato, imitando la tipica shell di python.
Le prime due istruzioni:

    >>> from StringIO import StringIO
    >>> testfile = StringIO('''
    ... --seq1
    ... ACGTCGATCGATCGTCAGTCGATC
    ... ACGTACGTATCGTACGTACGTAGC
    ... --seq2
    ... AGATCGTACGTAGCTAGCTAGTCG
    ... ''')

illustrano un esempio di formato ‘MinusMinus’. Così, quando digitate help(MinusMinusFormatParser), potete capire subito se state utilizzando il parser corretto, oppure se vi siete confusi con un altro.

La terza istruzione, invece, vi mostra qual é la sintassi tipica di una chiamata alla funzione.
Se lanciate MinusMinusFormatParser sopra un file simile a quello precedente, dovreste ricevere il messaggio ‘File parsed. ok!’:

    >>> sequences = MinusMinusFormatParser(testfile, options=None)
    File parsed. ok!

E così via, per le altre istruzioni mostrate nel doctest il funzionamento é molto simile.
Scrivo gli esempi di comandi come se mi trovassi su una shell python, prefissandoli con ‘>>> ‘; e il loro output immediatamente sotto.

Notate anche che eseguendo il programma come uno script in python, viene eseguita la funzione doctest.testmod():

if __name__ == '__main__':
    import doctest
    doctest.testmod()

Questa é la chiamata al modulo doctest che esegue la vera magia. Quando chiamo ‘testmod()’, gli esempi che ho posto nella documentazione vengono eseguiti, come se fossero codice vero e proprio: il risultato della loro esecuzione viene confrontato con quello previsto nell’esempio, e nel caso di differenze, mi viene segnalato un errore.
Se per esempio, la chiamata a MinusMinusFormatParser non mi avesse restituito ‘File parsed. ok!’, avrei ricevuto una notificazione, aiutandomi a risolvere un possibile bug.

La mia idea era di proporre questo tipo di documentazione al progetto biopython. Sono già riuscito a far accettare alcune doctest in biopython 1.49 , ma spero di riuscire a contribuire maggiormente nei prossimi giorni, affinchè ve ne siano altre.

A voi che ve ne pare, come idea? Questo é il bug report che ho inviato: 2640.
Vi sembrano più chiare le doctest? Pensate che un loro utilizzo massiccio potrebbe aiutare a rendere biopython più facile da utilizzare, più diffuso?
Una ultima cosa: come vedete, in questo caso ho scritto la documentazione e i test prima di iniziare a scrivere il codice. Se dovessi veramente scrivere un parser per il formato MinusMinus, adesso mi sarebbe molto più facile, perché già saprei come questo si dovrebbe comportare. La lezione é: scrivete sempre i test e la documentazione per le vostre funzioni prima del codice .

links:

- la mia proposta su biopython: http://bugzilla.open-bio.org/show_bug.cgi?id=2640
- documentazione ufficiale sulle doctest http://www.python.org/doc/2.5.2/lib/module-doctest.htm