1.2 Un semplice esempio

Solitamente, lo script di setup è piuttosto semplice, visto che è scritto direttamente in Python e non esistono limiti arbitrari all'impl ementazione di nuove funzionalità da fargli compiere; altresì si deve sempre fare attenzione nell'inserire operazioni arbitrare complesse nello script di setup. Gli script di configurazione in stile Autoconf possono eseguire lo script di setup più volte, durante il procedimento di compilazione ed installazione del proprio modulo da distribuire.

Se tutto quello che si vuole è distribuire un modulo chiamato foo, contenuto in un file foo.py, lo script di setup potrebbe essere tanto semplice quanto quello che segue:

from distutils.core import setup
setup(name='foo',
      version='1.0',
      py_modules=['foo'],
      )

Alcune osservazioni:

la maggior parte delle informazioni che vengono indicate a Distutils vengono fornite come argomenti chiave alla funzione setup()
questi argomenti chiave rientrano in due categorie: metadata di package (nome, numero di versione) ed informazioni circa il contenuto del package (in questo caso, una lista di puri moduli Python)
i moduli vengono specificati per nome di modulo, non per nome di file (la medesima cosa verrà fatta per package ed estensioni)
Si raccomanda di fornire un insieme di metadata adeguati, tra cui, in particolare, il nome, l'indirizzo email ed un indirizzo URL per il progetto (vedete la sezione 2 per un esempio)

Per creare una distribuzione di sorgenti per questo modulo, si deve creare uno script di setup, setup.py, contenente il precedente codice, ed eseguire:

python setup.py sdist

che creerà un file archivio (per esempio un tarball in Unix, un file ZIP in Windows) contenente lo script di setup setup.py ed il proprio modulo foo.py. Il file archivio verrà chiamato foo-1.0.tar.gz (o .zip) e scompattato in una directory foo-1.0.

Se un utente finale desidera installare il modulo foo, le uniche cose che deve fare è scaricare foo-1.0.tar.gz (o .zip), scompattarlo, e nella directory foo-1.0--eseguire:

python setup.py install

che completa la copia di foo.py nella giusta directory per i moduli di terze parti nella propria installazione Python.

Questo semplice esempio dimostra alcuni fondamentali concetti delle Distutils. Primo, sia lo sviluppatore che l'installatore si trovano davanti alla stessa interfaccia, come ad esempio lo script di setup. La differenza è quale comando delle Distutils usano: il comando sdist viene eseguito per lo più dallo sviluppatore, mentre install è più spesso eseguito dall'installatore (comunque la maggior parte degli sviluppatori, vogliono occasionalmente installare il proprio codice).

Se si desidera rendere la vita realmente facile ai propri utenti, si possono preparare una o più distribuzioni precompilate. Solitamente, se si sta lavorando su di una macchina Windows e si vogliono facilitare le cose per gli altri utenti Windows, si possono creare degli installer eseguibili (il tipo più appropriato di distribuzione precompilata per questa piattaforma) con il comando bdistwininst. Per esempio:

python setup.py bdist_wininst

creerà un installatore eseguibile, foo-1.0.win32.exe, nella directory corrente.

Altri tipici formati per distribuzioni precompilate sono gli RPM, implementati con il comando bdist_rpm, Solaris pkgtool (bdist_pkgtool) e HP_UX swinstall (bdist_sdux). Per esempio, il seguente comando creerà un file RPM chiamato foo-1.0.noarch.rpm:

python setup.py bdist_rpm

(Il comando bdist_rpm usa l'eseguibile rpm, che comunque deve essere eseguito su di un sistema basato sugli RPM come RedHat Linux, SuSe Linux o Mandrake Linux).

È possibile sapere quali formati di distribuzione sono disponibili, in qualsiasi momento, digitando:

python setup.py bdist --help-formats

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