4.2.3 Contenuti del modulo

Il modulo definisce le seguenti funzioni e costanti, e un'eccezione:

compile( pattern[, flags])

Compila un modello di espressione regolare in un oggetto espressione regolare, che può venire usato per la corrispondenza, utilizzando i suoi metodi match() e search(), descritti sotto.

Il comportamento dell'espressione può venire modificato specificando un valore per il campo flags. I valori possono essere uno delle seguenti variabili, combinate usando l'OR bit per bit (l'operatore |).

La sequenza:

prog = re.compile(pat)
result = prog.match(str)

è equivalente a

result = re.match(pat, str)

ma la versione che utilizza compile() è più efficiente quando l'espressione verrà usata più di una volta in un singolo programma.

I
IGNORECASE: Effettua una corrispondenza case-insensitive; espressioni come [A-Z] corrisponderanno anche alle lettere minuscole. Non viene influenzato dalla localizzazione corrente.

L
LOCALE: Fa in modo che \w, \W, \b e \B dipendano dalla localizzazione corrente.

M
MULTILINE: Quando specificato, il carattere del modello "^" corrisponde all'inizio della stringa e all'inizio di ogni riga (subito dopo un carattere di fine riga); il carattere del modello "$" corrisponde alla fine della stringa e alla fine di ogni riga (immediatamente prima del carattere di fine riga). In modo predefinito, "^" corrisponde solo all'inizio della stringa e "$" solo alla fine della stringa e subito prima di un fine riga (se presente) alla fine della stringa.

S
DOTALL: Fa in modo che il carattere speciale "." corrisponda ad ogni carattere, incluso il fine riga; senza questa opzione, "." corrisponderà a qualsiasi cosa, eccetto il fine riga.

U
UNICODE: Fa in modo che \w, \W, \b e \B dipendano dal database delle proprietà dei caratteri Unicode. Nuovo nella versione 2.0.

X
VERBOSE: Questa opzione permette di scrivere espressioni regolari che risultino di aspetto più piacevole. I caratteri di spaziatura all'interno del modello vengono ignorati, a meno che non siano in una classe di caratteri, o preceduti da un backslash che non faccia parte di un escape (NdT: quindi NON "\\"), e quando una linea contenga un carattere "#" sia in una classe di caratteri sia preceduto da un backslash che non faccia parte di un escape, tutti i caratteri a partire dal carattere "#" più a sinistra fino alla fine della stringa vengono ignorati.

search( pattern, string[, flags]): Analizza la string cercando una posizione dove il pattern delll'espressione regolare genera una corrispondenza, e restituisce una corrispondente istanza di MatchObject. Restituisce None se nessuna posizione della stringa corrisponde al modello; notate che questo è diverso dal trovare una corrispondenza di lunghezza zero in qualche punto della stringa.

match( pattern, string[, flags]): Se zero o più caratteri all'inizio della string corrispondono al pattern dell'espressione regolare, restituisce una corrispondenze istanza di MatchObject. Restituisce None se la stringa non corrisponde al modello; notate che questo è differente rispetto ad una corrispondenza di lunghezza zero.
Note: Se volete localizzare una corrispondenza ovunque nella string, utilizzate search().

split( pattern, string[, maxsplit = 0])

Divide la string rispetto alle occorrenze del pattern. Se nel pattern sono presenti delle parentesi che indicano dei gruppi, anche il testo di tutti i gruppi nel modello viene restituito come parte della lista risultante. Se maxsplit è un valore diverso da zero, vengono effettuate al più maxsplit divisioni, e la rimanenza della stringa viene restituita come elemento finale della lista. (Note di incompatibilità: nella versione originale di Python 1.5, maxsplit veniva ignorato. Questo comportamento è stato sistemato nelle versioni successive.)

>>> re.split('\W+', 'Parole, parole, parole.')
['Parole', 'parole', 'parole', '']
>>> re.split('(\W+)', 'Parole, parole, parole.')
['Parole', ', ', 'parole', ', ', 'parole', '.', '']
>>> re.split('\W+', 'Parole, parole, parole.', 1)
['Parole', 'parole, parole.']

Questa funzione combina ed estende le funzionalità delle vecchie regsub.split() e regsub.splitx().

findall( pattern, string): Restituisce una lista di tutte le corrispondenze (senza sovrapposizioni) del pattern in string. Se uno o più gruppi sono presenti nel modello, restituisce una lista di gruppi; questa sarà una lista di tuple se il modello ha più di un gruppo. Le corrispondenze vuote vengono incluse nel risultato a meno che non tocchino l'inizio di un'altra corrispondenza. Nuovo nella versione 1.5.2.

finditer( pattern, string): Restituisce un iteratore sulle corrispondenze (senza sovrapposizioni) del pattern modello dell'espressione regolare sulla stringa. Per ogni corrispondenza, l'iteratore restituisce un oggetto corrispondenza. Le corrispondenze vuote vengono incluse nel risultato, a meno che non tocchino l'inizio di un'altra corrispondenza. Nuovo nella versione 2.2.

sub( pattern, repl, string[, count])

Restituisce la stringa ottenuta sostituento le occorrenze di pattern (senza sovrapposizioni) nella parte più a sinistra della string, con le sostituzioni repl. Se il pattern non viene trovato, string viene restituita invariata. repl può essere una stringa o una funzione; se è una stringa, tutti i backslash di escape vengono elaborati. Ad esempio, "\n" viene convertito in un singolo carattere di fine riga, "\r" viene convertito in un linefeed, e così via. Gli escape sconosciuti, come "\j", vengono lasciati soli. I backreference, come "\6", vengono sostituiti con la sotto stringa corrispondente al gruppo 6 nel modello. Per esempio:

>>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):',
...        r'static PyObject*\npy_\1(void)\n{',
...        'def myfunc():')
'static PyObject*\npy_myfunc(void)\n{'

Se repl è una funzione, viene chiamata per ogni occorrenza (senza sovrapposizioni) del pattern. La funzione prende un singolo oggetto corrispondente come argomento, e restituisce la stringa sostitutiva. Per esempio:

>>> def dashrepl(matchobj):
....    if matchobj.group(0) == '-': return ' '
....    else: return '-'
>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
'pro--gram files'

Il modello può essere una stringa o un oggetto RE; se necessitate di specificare opzioni delle espressioni regolari, dovete usare un oggetto RE o utilizzare i modificatori integrati nel modello; per esempio "sub("(?i)b+", "x", "bbbb BBBB")" returns 'x x'.

L'argomento facoltativo count indica il massimo numero di occorrenze del modello che devono venire sostituite; count deve essere un intero non negativo. Se omesso o zero, tutte le occorrenze verranno sostituite. Le corrispondenze vuote per il modello vengono sostituite solo quando non adiacenti ad una corrispondenza precedente, così "sub('x*', '-', 'abc')" restituisce '-a-b-c-'.

In aggiunta ai caratteri di escape e ai backreference come descritti sopra, "\g<name>" utilizzerà la sotto stringa che corrisposta dal gruppo chiamato "name", come definito dalla sintassi (?P<name>...). "\g<number>" utilizza il corrispondente numero del gruppo; "\g<2>" è quindi equivalente a "\2", ma non è ambiguo in una sostituzione come "\g<2>0". "\20" verrebbe interpretato come un riferimento al gruppo 20, non come un riferimento al gruppo 2 seguito dalla costante carattere "0". Il backreference "\g<0>" sostituisce l'intera sotto stringa che corrisponde all'espressione regolare.

subn( pattern, repl, string[, count]): Effettua la stessa operazione di sub(), ma restituisce una tupla (new_string, number_of_subst_made).

escape( string): Restituisce la string con tutti i caratteri non alfanumerici preceduti da un backslash (NdT: "." diventa "\\."); questo è utile se volete far corrispondere una stringa costante arbitraria che può avere metacaratteri delle espressioni regolari al suo interno.

exception error: Eccezione sollevata quando una stringa passata ad una delle funzioni descritte, non è un'espressione regolare valida (per esempio, potrebbe contenere parentesi non bilanciate), o quando si verifica qualche errore durante la compilazione o la corrispondenza. Non è mai un errore se una stringa non contiene corrispondenze per il modello.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.