11.11.1 Oggetti NNTP

Le istanze NNTP possiedono i seguenti metodi. Le risposte response che vengono restituite come primo elemento nella tupla restituita da quasi tutti i metodi sono le risposte del server: una stringa che inizia con un codice di tre valori numerici. Se la risposta del server indica un errore, il metodo solleva una delle eccezioni precedenti.

getwelcome( ): Restituisce un messaggio di benvenuto, inviato dal server in risposta alla connessione iniziale. Questo messaggio, qualche volta, contiene un avviso o delle informazioni di aiuto che possono essere rilevanti per l'utente.

set_debuglevel( level): Imposta il livello di debugging dell'istanza. Questo controlla l'ammontare delle informazioni di debug stampate. Il valore predefinito, 0, non produce alcun output. Un valore di 1 produce un moderato quantitativo di messaggi di debugging, generalmente una riga singola per richiesta o risposta. Un valore di 2 o maggiore, produce il massimo ammontare di messaggi di debugging, registrando ogni riga inviata e ricevuta sulla connessione (incluso il testo del messaggio).

newgroups( date, time, [file]): Invia un comando "NEWGROUPS". L'argomento date deve essere un stringa nel formato 'yymmdd', indicante la data, e time dovrebbe essere una stringa nella forma 'hhmmss', indicante l'orario. Restituisce una coppia (risposta, gruppi) dove gruppi è una lista di nomi dei gruppi che risultano nuovi rispetto all'orario ed alla data indicate. Se il file dei parametri viene fornito, il risultato del comando "NEWGROUPS" viene memorizzato in un file. Se file è una stringa, il metodo aprirà un oggetto file con quel nome, ci scriverà sopra e lo chiuderà. Se file è un oggetto file, inizierà chiamandowrite() su di esso per memorizzare le righe del risultato del comando. Se file viene fornito, la lista restituita sarà una lista vuota.

newnews( group, date, time, [file]): Invia un comando "NEWNEWS". Qui group è un nome di gruppo o '*' e date e time hanno lo stesso significato come per newgroups(). Restituisce una coppia (risposta, articoli) dove articoli è una lista di id degli articoli. Se il parametro file viene indicato, il risultato del comando "NEWNEWS" viene memorizzato in un file. Se file è una stringa, il metodo aprirà un file oggetto con quel nome, vi scriverà sopra e lo chiuderà. Se file è un oggetto file, il metodo inizierà chiamando write() su di esso per memorizzare le righe del risultato del comando. Se file viene indicato, la list restituita sarà una lista vuota.

list( [file]): Invia un comando "LIST". Restituisce una coppia (risposta, lista) dove lista è una lista di tuple. Ogni tupla ha la forma (gruppo, ultimo, primo, opzione), dove gruppo è un nome di gruppo, ultimo e primo sono l'ultimo ed il primo numero dell'articolo (come stringa) ed opzione è y se il posting è autorizzato, n se no, e m se il newsgroup è moderato. Notare l'ordine: ultimo, primo. Se il parametro file viene indicato, il risultato del comando "LIST" viene inserito in un file. Se il file è una stringa, il metodo aprirà un file oggetto con quel nome, scriverà e quindi lo chiuderà. Se file è un oggetto file, allora verrà chiamato il metodo write() per memorizzare le righe del risultato del comando. Se file viene indicato, la lista list, restituita è una lista vuota.

group( name): Invia un comando "GROUP", dove name è il nome del gruppo. Restituisce una tupla (risposta, conteggio, primo, ultimo, nome) dove conteggio è il numero (stimato) di articoli nel gruppo, primo è il primo numero dell'articolo nel gruppo, ultimo è l'ultimo numero dell'articolo nel gruppo, e nome è il nome del gruppo. I numeri vengono restituiti come stringhe.

help( [file]): Invia un comando "HELP". Restituisce una coppia (risposta, lista) dove lista è la lista di stringhe di aiuto. Se il parametro file viene indicato, il risultato del comando "HELP" viene memorizzato in un file. Se file è una stringa, il metodo aprirà un oggetto file con quel nome, vi scriverà e quindi lo chiuderà. Se file è un oggetto file, il metodo chiamerà write() per memorizzare le righe del risultato del comando. Se file viene indicato, la lista restituita è una lista vuota.

stat( id): Invia un comando "STAT", dove id è l'id del messaggio (racchiuso tra "<" e ">") o il numero di un articolo (come stringa). Restituisce una tripla (risposta, numero, id) dove numero è il numero dell'articolo (come stringa) ed id è l'id dell'articolo (racchiuso tra "<" e ">").

next( ): Invia un comando "NEXT". Restituisce gli stessi valori di stat().

last( ): Invia un comando "LAST". Restituisce gli stessi valori di stat().

head( id): Invia un comando "HEAD", dove id possiede lo stesso significato che in stat(). Restituisce una tupla (risposta, numero, id, lista) dove i primi tre sono gli stessi di stat(), e lista è una lista di intestazioni di articolo (una lista non interpretata di righe, senza il carattere di fine riga).

body( id,[file]): Invia un comando "BODY", dove id possiede lo stesso significato di stat(). Se il parametro file viene indicato, allora il corpo del messaggio restituito viene memorizzato in un file. Se file è una stringa, allora il metodo aprirà un oggetto file con quel nome, vi scriverà e lo chiuderà. Se file è un oggetto file, verrà chiamato write() per memorizzare le righe del corpo del testo. Restituisce gli stessi valori di head(). Se file viene indicato, la lista restituita è una lista vuota.

article( id): Invia un comando "ARTICLE", dove id ha lo stesso significato di stat(). Restituisce gli stessi parametri di head().

slave( ): Invia un comando "SLAVE". Restituisce la risposta del server response.

xhdr( header, string, [file]): Invia un comando "XHDR". Questo comando non viene definito nelle rfc ma è un'estensione comune. L'argomento header è una chiave di intestazione, per esempio 'subject'. L'argomento string deve possedere la forma 'primo-ultimo' dove primo e ultimo sono il primo e l'ultimo numero dell'articolo da cercare. Restituisce una coppia (risposta, lista), dove list è una lista di coppie (id, testo), dove id è l'id di un'articolo (come una stringa) e test è il testo dell'intestazione richiesta per quell'articolo. Se il parametro file viene indicato, il risultato del comando "XHDR" viene memorizzato in un file. Se file è una stringa, il metodo aprirà un oggetto file con quel nome, vi scriverà e lo chiuderà. Se file è un oggetto file, si inizierà chiamando il metodo write() per memorizzare le righe del risultato del comando. Se file viene indicato, la lista restituita è una lista vuota.

post( file): Pubblica un articolo usando il comando "POST". L'argomento file è un oggetto file aperto che viene letto fino all'EOF con il proprio metodo readline(). Dovrebbe essere un articolo di news correttamente costruito, incluse le intestazioni richieste. Il metodo post() inserisce automaticamente l'escape per le linee che iniziano con ".".

ihave( id, file): Invia un comando "IHAVE". Se la riposta non è un errore, tratta file esattamente come il metodo post().

date( ): Restituisce una tripla (risposta, data, orario), contenente la data e l'ora corrente in un formato adatto ai metodi newnews() e newgroups(). Questa è un'estensione facoltativa NNTP e potrebbe non essere supportata da tutti i server.

xgtitle( name, [file]): Processa un comando "XGTITLE", restituendo una coppia (risposta, lista), dove lista è una lista di tuple contenenti (nome, titolo). Se il parametro file viene indicato, il risultato del comando "XGTITLE" viene memorizzato in un file. Se file è una stringa, il metodo aprirà un oggetto file con quel nome, vi scriverà e lo chiuderà. Se file è un oggetto file, inizierà chiamando write() sull'oggetto stesso per registrare le righe del risultato del comando. Se file viene indicato, la lista restituita è una lista vuota. Questa è un'estensione NNTP facoltativa, e potrebbe non essere supportata da tutti i server.

xover( start, end, [file]): Restituisce una coppia (risposta, lista). lista è una lista di tuple, una per ogni articolo nell'ambito delimitato dagli intervalli del numero corrispondente all'articolo con start ed end. Ogni tupla è nel formato ((article numero, soggetto, poster, data, id, riferimenti, dimensione, righe). Se il parametro file viene indicato, il risultato del comando "XOVER" viene memorizzato in un file. Se file è una stringa, il metodo aprirà un oggetto file con quel nome, vi scriverà sopra e quindi lo chiuderà. Se file è un oggetto file, si inizierà chiamando il metodo write() per memorizzare le righe del risultato del comando. Se file viene indicato, la lista restituita sarà una lista vuota. Questa è un'estensione NNTP facoltativa, e potrebbe non essere supportata da tutti i server.

xpath( id): Restituisce una coppia (risposta, percorso), dove percorso è la directory dell'articolo indicato dall'ID id. Questa è un'estensione NNTP facoltativa, e potrebbe non essere supportata da tutti i server.

quit( ): Invia un comando "QUIT" e chiude la connessione. Una volta che questo metodo è stato chiamato, non dovrebbe essere chiamato nessun'altro metodo sull'oggetto NNTP.

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