distribuire-librerie-python.html

<!DOCTYPE html>
<meta charset=utf-8>
<title>Distribuire librerie Python - Immersione in Python 3</title>
<!--[if IE]><script src=j/html5.js></script><![endif]-->
<link rel=stylesheet href=dip3.css>
<style>
body{counter-reset:h1 16}
mark{display:inline}
</style>
<link rel=stylesheet media='only screen and (max-device-width: 480px)' href=mobile.css>
<link rel=stylesheet media=print href=print.css>
<meta name=viewport content='initial-scale=1.0'>
<form action=http://www.google.com/cse><div><input type=hidden name=cx value=014021643941856155761:l5eihuescdw><input type=hidden name=ie value=UTF-8>&nbsp;<input type=search name=q size=25 placeholder="powered by Google&trade;">&nbsp;<input type=submit name=root value=Search></div></form>
<p>Voi siete qui: <a href=index.html>Inizio</a> <span class=u>&#8227;</span> <a href=indice.html#distribuire-librerie-python>Immersione in Python 3</a> <span class=u>&#8227;</span>
<p id=level>Livello di difficoltà: <span class=u title=avanzato>&#x2666;&#x2666;&#x2666;&#x2666;&#x2662;</span>
<h1>Distribuire librerie Python</h1>
<blockquote class=q>
<p><span class=u>&#x275D;</span> Scoprirai che la vergogna è come il dolore; si sente solo una volta. <span class=u>&#x275E;</span><br>&mdash; Marchesa di Merteuil, <a href=http://italian.imdb.com/title/tt0094947/quotes><cite>Le relazioni pericolose</cite></a>
</blockquote>
<p id=toc>&nbsp;
<h2 id=divingin>Immersione!</h2>
<p class=f>Tra l&#8217;artista e la sua consacrazione c&#8217;è di mezzo la consegna dell&#8217;opera finita, o almeno questo è quello che sostengono alcuni. Se volete rilasciare un programma, una libreria, un framework, un&#8217;applicazione scritta in Python, potete utilizzare il framework di distribuzione Distutils incluso in Python 3. Distutils è molte cose: uno strumento di assemblaggio (per voi), uno strumento di installazione (per i vostri utenti), un formato di metadati per pacchetti software (per i motori di ricerca) e anche di più. Si integra con il <a href=http://pypi.python.org/>Python Package Index</a> (&#8220;PyPI&#8221;, Indice dei Pacchetti Python), un archivio centrale per librerie Python open source.

<p>Tutte queste caratteristiche di Distutils si basano su un <i>programma di installazione</i> tradizionalmente chiamato <code>setup.py</code>. In effetti, avete già visto diversi programmi di installazione di Distutils in questo libro. Avete usato Distutils per installare <code>httplib2</code> nel capitolo <a href=servizi-web-http.html#introducing-httplib2>Servizi web HTTP</a> e ancora per installare <code>chardet</code> nel capitolo <a href=caso-di-studio-convertire-chardet-verso-python-3.html>Caso di studio: convertire <code>chardet</code> verso Python 3</a>.

<p>In questo capitolo, imparerete come funzionano i programmi di installazione per <code>chardet</code> e <code>httplib2</code> e seguirete passo per passo il processo di rilascio del vostro software Python.

<pre class=pp><code># file setup.py di chardet
from distutils.core import setup
setup(
    name = "chardet",
    packages = ["chardet"],
    version = "1.0.2",
    description = "Riconoscitore di codifiche universale",
    author = "Mark Pilgrim",
    author_email = "mark@diveintomark.org",
    url = "http://chardet.feedparser.org/",
    download_url = "http://chardet.feedparser.org/download/python3-chardet-1.0.1.tgz",
    keywords = ["encoding", "i18n", "xml"],
    classifiers = [
        "Programming Language :: Python",
        "Programming Language :: Python :: 3",
        "Development Status :: 4 - Beta",
        "Environment :: Other Environment",
        "Intended Audience :: Developers",
        "License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)",
        "Operating System :: OS Independent",
        "Topic :: Software Development :: Libraries :: Python Modules",
        "Topic :: Text Processing :: Linguistic",
        ],
    long_description = """\
Riconoscitore di codifiche universale
-------------------------------------

Riconosce
 - ASCII, UTF-8, UTF-16 (2 varianti), UTF-32 (4 varianti)
 - Big5, GB2312, EUC-TW, HZ-GB-2312, ISO-2022-CN (Cinese tradizionale e semplificato)
 - EUC-JP, SHIFT_JIS, ISO-2022-JP (Giapponese)
 - EUC-KR, ISO-2022-KR (Coreano)
 - KOI8-R, MacCyrillic, IBM855, IBM866, ISO-8859-5, windows-1251 (Cirillico)
 - ISO-8859-2, windows-1250 (Ungherese)
 - ISO-8859-5, windows-1251 (Bulgaro)
 - windows-1252 (Inglese)
 - ISO-8859-7, windows-1253 (Greco)
 - ISO-8859-8, windows-1255 (Ebraico visuale e logico)
 - TIS-620 (Thai)

Questa versione richiede Python 3 o successivo; una versione per Python 2 è disponibile separatamente.
"""
)</code></pre>

<blockquote class=note>
<p><span class=u>&#x261E;</span><code>chardet</code> e <code>httplib2</code> sono open source, ma non c&#8217;è alcun requisito che vi obbliga a rilasciare le vostre librerie Python secondo i termini di qualche licenza particolare. Il processo descritto in questo capitolo funzionerà per qualsiasi software Python a prescindere dalla licenza.
</blockquote>

<p class=a>&#x2042;

<h2 id=cantdo>Cose che Distutils non può fare per voi</h2>

<p>Rilasciare il vostro primo pacchetto Python è un processo che potrebbe intimidirvi. (Rilasciare il secondo è un po&#8217; più facile.) Distutils cerca di automatizzare questo processo per quanto è possibile, ma ci sono alcune cose che dovete proprio fare da soli.

<ul>
<li><b>Scegliete una licenza</b>. Questo è un argomento complicato, gravido di politica e di problemi. Se desiderate rilasciare il vostro software come open source, vi offro umilmente cinque consigli:
<ol>
<li>Non scrivete la vostra licenza.
<li>Non scrivete la vostra licenza.
<li>Non scrivete la vostra licenza.
<li>La licenza non deve per forza essere <abbr>GPL</abbr>, ma <a href=http://www.dwheeler.com/essays/gpl-compatible.html>deve essere <abbr>GPL</abbr>-compatibile</a>.
<li>Non scrivete la vostra licenza.
</ol>
<li><b>Classificate il vostro software</b> usando il sistema di classificazione offerto da PyPI. Spiegherò cosa significa questo più avanti in questo capitolo.
<li><b>Scrivete un file &#8220;leggimi&#8221;</b>. Non risparimatevi su questo. Come minimo, il file dovrebbe offrire ai vostri utenti una descrizione di quello che fa il vostro software e di come installarlo.
</ul>

<p class=a>&#x2042;

<h2 id=structure>La struttura delle directory</h2>

<p>Per cominciare a impacchettare il vostro software, avete bisogno di mettere ordine tra i vostri file e le vostre directory. La directory di <code>httplib2</code> è strutturata in questo modo:

<pre class=screen>
<a>httplib2/                 <span class=u>&#x2460;</span></a>
|
<a>+--README.txt             <span class=u>&#x2461;</span></a>
|
<a>+--setup.py               <span class=u>&#x2462;</span></a>
|
<a>+--httplib2/              <span class=u>&#x2463;</span></a>
   |
   +--__init__.py
   |
   +--iri2uri.py</pre>
<ol>
<li>Create una directory radice per contenere ogni cosa. Datele lo stesso nome del vostro modulo Python.
<li>Per favorire gli utenti Windows, il vostro file &#8220;leggimi&#8221; dovrebbe includere un&#8217;estensione <code>.txt</code> e dovrebbe usare i ritorni a capo in stile Windows. Solo perché <em>voi</em> usate un esotico editor di testo che lanciate dalla riga di comando e che include il proprio linguaggio di macro non significa che dovete rendere la vita difficile ai vostri utenti. (I vostri utenti usano Blocco note. Triste ma vero.) Anche se vi trovate su Linux o Mac OS X, il vostro esotico editor di testo senza dubbio è dotato di un&#8217;opzione per salvare i file con i ritorni a capo in stile Windows.
<li>Il vostro programma di installazione per Distutils dovrebbe essere chiamato <code>setup.py</code> a meno che non abbiate una buona ragione per chiamarlo diversamente. E non avete una buona ragione per chiamarlo diversamente.
<li>Se il vostro software Python è composto da un singolo file <code>.py</code>, dovreste mettere quel file nella directory radice a fianco del vostro file &#8220;leggimi&#8221; e del vostro programma di installazione. Ma <code>httplib2</code> non è composto da un singolo file <code>.py</code>, bensì è <a href=caso-di-studio-convertire-chardet-verso-python-3.html#multifile-modules>un modulo multifile</a>. Ma questo va benissimo! Semplicemente, mettete la directory <code>httplib2</code> nella directory radice, in modo da avere un file <code>__init__.py</code> all&#8217;interno della directory <code>httplib2/</code> all&#8217;interno della directory radice <code>httplib2/</code>. Questo non è un problema, e in effetti semplificherà il vostro processo di impacchettamento.
</ol>

<p>La directory <code>chardet</code> è strutturata in maniera leggermente differente. Come <code>httplib2</code>, anche <code>chardet</code> è un <a href=caso-di-studio-convertire-chardet-verso-python-3.html#multifile-modules>modulo multifile</a>, quindi contiene una directory <code>chardet/</code> all&#8217;interno della directory radice <code>chardet/</code>. In aggiunta al file <code>README.txt</code>, <code>chardet</code> include la propria documentazione formattata in <abbr>HTML</abbr> nella directory <code>docs/</code>. La directory <code>docs/</code> contiene diversi file <code>.html</code> e <code>.css</code> e una sottodirectory <code>images/</code> che contiene diversi file <code>.png</code> e <code>.gif</code>. (Questo risulterà importante più avanti.) Infine, per rispettare le convenzioni del software rilasciato sotto licenza <abbr>(L)GPL</abbr>, include un file separato chiamato <code>COPYING.txt</code> che contiene il testo completo della licenza <abbr>LGPL</abbr>.

<pre class=nd><code>
chardet/
|
+--COPYING.txt
|
+--setup.py
|
+--README.txt
|
+--docs/
|  |
|  +--index.html
|  |
|  +--usage.html
|  |
|  +--images/ ...
|
+--chardet/
   |
   +--__init__.py
   |
   +--big5freq.py
   |
   +--...
</code></pre>

<p class=a>&#x2042;

<h2 id=setuppy>Scrivere il vostro programma di installazione</h2>

<p>Il programma di installazione di Distutils è un programma Python. In teoria, può fare qualsiasi cosa che Python è in grado di fare. In pratica, dovrebbe limitarsi a fare il meno possibile nel modo più standard possibile. I programmi di installazione dovrebbero essere noiosi. Più esotico è il vostro processo di installazione, più esotici saranno i bug che vi verranno segnalati.

<p>La prima riga di tutti i programmi di installazione di Distutils è sempre la stessa:

<pre class='nd pp'><code>from distutils.core import setup</code></pre>

<p>Questa riga importa la funzione <code>setup()</code>, che è il punto d&#8217;ingresso principale di Distutils. Il 95% di tutti i programmi di installazione di Distutils è composto da una singola invocazione a <code>setup()</code> e basta. (Mi sono assolutamente appena inventato questa statistica, ma se il vostro programma di installazione di Distutils fa altre cose oltre a invocare la funzione <code>setup()</code>, dovreste avere una buona ragione. Avete una buona ragione? Non penso proprio.)

<p>La funzione <code>setup()</code> <a href=http://docs.python.org/3.1/distutils/apiref.html#distutils.core.setup>può accettare dozzine di parametri</a>. Per salvaguardare la sanità mentale di chiunque sia coinvolto, dovete usare gli <a href=il-vostro-primo-programma-python.html#optional-arguments>argomenti con nome</a> per tutti i parametri. Questa non è semplicemente una convenzione, ma un requisito vincolante. Il vostro programma di installazione si bloccherà se provate a invocare la funzione <code>setup()</code> con argomenti senza nome.

<p>I seguenti argomenti con nome sono obbligatori:

<ul>
<li><b>name</b>, il nome del pacchetto;
<li><b>version</b>, il numero di versione del pacchetto;
<li><b>author</b>, il vostro nome completo;
<li><b>author_email</b>, il vostro indirizzo email;
<li><b>url</b>, la pagina web principale del vostro progetto, che può essere la pagina del pacchetto ospitata da <a href=http://pypi.python.org/>PyPI</a> se non avete un sito web separato per il progetto.
</ul>

<p>Sebbene non siano richiesti, vi raccomando di includere anche i seguenti argomenti nel vostro programma di installazione:

<ul>
<li><b>description</b>, una riga di riepilogo del progetto;
<li><b>long_description</b>, una stringa su più righe in <a href=http://docutils.sourceforge.net/rst.html>formato reStructuredText</a>, che <a href=http://pypi.python.org/>PyPI</a> converte in <abbr>HTML</abbr> e mostra sulla pagina del vostro pacchetto;
<li><b>classifiers</b>, una lista di stringhe formattate in modo speciale che vengono descritte nella prossima sezione.
</ul>

<blockquote class=note>
<p><span class=u>&#x261E;</span>I metadati da utilizzare nei programmi di installazione sono definiti nella <a href=http://www.python.org/dev/peps/pep-0314/><abbr>PEP</abbr> 314</a>.
</blockquote>

<p>Ora diamo un&#8217;occhiata al programma di installazione per <code>chardet</code>. Contiene tutti questi parametri obbligatori e raccomandati, più uno che non ho ancora menzionato: <code>packages</code>.

<pre class='nd pp'><code>from distutils.core import setup
setup(
    name = 'chardet',
    <mark>packages = ['chardet']</mark>,
    version = '1.0.2',
    description = 'Riconoscitore di codifiche universale',
    author = 'Mark Pilgrim',
    ...
)</code></pre>

<p>Il parametro <code>packages</code> evidenzia una sfortunata sovrapposizione di vocaboli nel processo di distribuzione. Abbiamo parlato del &#8220;pacchetto&#8221; come della cosa che state assemblando (e potenzialmente elencando nell&#8217;Indice dei Pacchetti Python). Il parametro <code>packages</code> non si riferisce a questo, ma al fatto che il modulo <code>chardet</code> è un <a href=caso-di-studio-convertire-chardet-verso-python-3.html#multifile-modules>modulo multifile</a>, talvolta noto come&hellip; &#8220;pacchetto&#8221;. Il parametro <code>packages</code> dice a Distutils di includere la directory <code>chardet/</code>, il suo file <code>__init__.py</code> e tutti gli altri file <code>.py</code> che costituiscono il modulo <code>chardet</code>. Questo è piuttosto importante: tutte le nostre allegre chiacchiere su documentazione e metadati sono irrilevanti se dimenticate di includere il codice vero e proprio!

<p class=a>&#x2042;

<h2 id=trove>Classificare il vostro pacchetto</h2>

<p>Il Python Package Index (&#8220;PyPI&#8221;, Indice dei Pacchetti Python) contiene migliaia di librerie Python. I corretti metadati di classificazione consentiranno alle persone interessate di trovare la vostra libreria più facilmente. PyPI vi consente di <a href='http://pypi.python.org/pypi?:action=browse'>scorrere i pacchetti per classificatore</a>. Potete anche selezionare molteplici classificatori per restringere il campo della vostra ricerca. I classificatori non sono metadati invisibili che potete semplicemente ignorare!

<p>Per classificare il vostro software, passate un parametro <code>classifiers</code> alla funzione <code>setup()</code> di Distutils. Il parametro <code>classifiers</code> è una lista di stringhe. Il formato di queste stringhe <em>non</em> è libero, perché tutte le stringhe di classificazione dovrebbero provenire da <a href='http://pypi.python.org/pypi?:action=list_classifiers'>questa lista su PyPI</a>.

<p>I classificatori sono opzionali. Potete scrivere un programma di installazione di Distutils senza alcun classificatore. <strong>Non fatelo.</strong> Dovreste <em>sempre</em> includere almeno i seguenti classificatori.

<ul>
<li><b>Programming Language</b>. In particolare, dovreste includere sia <code>"Programming Language :: Python"</code> che <code>"Programming Language :: Python :: 3"</code>. Se non li includete, il vostro pacchetto non verrà mostrato in <a href='http://pypi.python.org/pypi?:action=browse&amp;c=533&amp;show=all'>questa lista di librerie compatibili con Python 3</a>, che viene segnalata a lato di ogni singola pagina del sito <code>pypi.python.org</code>.
<li><b>License</b>. Questa è <em>la prima cosa in assoluto che controllo</em> quando sto considerando librerie di terze parti. Non obbligatemi a dare la caccia a questa informazione vitale. Non includete più di un classificatore di licenza a meno che il vostro software non sia esplicitamente rilasciato secondo i termini di più di una licenza. (E non rilasciate software secondo i termini di più di una licenza a meno che non siate obbligati a farlo. E non obbligate altri sviluppatori a farlo. La questione delle licenze è già una seccatura così com&#8217;è, non peggioratela.)
<li><b>Operating System</b>. Se il vostro software funziona solo su Windows (o Mac OS X, o Linux), voglio saperlo prima, non dopo. Se il vostro software funziona ovunque senza alcun codice specifico per la piattaforma, usate il classificatore <code>"Operating System :: OS Independent"</code>. Classificatori <code>Operating System</code> molteplici sono necessari solo se il vostro software richiede uno specifico supporto per ogni piattaforma. (Questo non è molto comune.)
</ul>

<p>Vi raccomando di includere anche i seguenti classificatori.

<ul>
<li><b>Development Status</b>. Il vostro software ha la qualità di una versione beta? Alfa? Pre-alfa? Sceglietene una. Siate onesti.
<li><b>Intended Audience</b>. Chi scaricherebbe il vostro software? Le scelte più comuni sono <code>Developers</code>, <code>End Users/Desktop</code>, <code>Science/Research</code> e <code>System Administrators</code>.
<li><b>Framework</b>. Se il vostro software è un componente aggiuntivo per un framework Python più grande come <a href=http://www.djangoproject.com/>Django</a> o <a href=http://www.zope.org/>Zope</a>, includete l&#8217;appropriato classificatore <code>Framework</code>, altrimenti omettetelo.
<li><b>Topic</b>. C&#8217;è un <a href='http://pypi.python.org/pypi?:action=list_classifiers'>vasta gamma di argomenti tra cui scegliere</a>; scegliete tutti quelli che si applicano al vostro caso.
</ul>

<h3 id=trove-examples>Esempi di buoni classificatori</h3>

<p>Per fare un esempio, ecco i classificatori di <a href=http://pypi.python.org/pypi/Django/>Django</a>, un framework per applicazioni web da eseguire sul vostro server web che è pronto per essere usato in ambienti di produzione, indipendente dalla piattaforma e distribuito secondo i termini della licenza <abbr>BSD</abbr>. (Django non è ancora compatibile con Python 3, quindi il classificatore <code>Programming Language :: Python :: 3</code> non viene elencato.)

<pre><code>Programming Language :: Python
License :: OSI Approved :: BSD License
Operating System :: OS Independent
Development Status :: 5 - Production/Stable
Environment :: Web Environment
Framework :: Django
Intended Audience :: Developers
Topic :: Internet :: WWW/HTTP
Topic :: Internet :: WWW/HTTP :: Dynamic Content
Topic :: Internet :: WWW/HTTP :: WSGI
Topic :: Software Development :: Libraries :: Python Modules</code></pre>

<p>Ecco i classificatori di <a href=http://pypi.python.org/pypi/chardet><code>chardet</code></a>, la libreria per il riconoscimento delle codifiche di carattere descritta nel capitolo <a href=caso-di-studio-convertire-chardet-verso-python-3.html>Caso di studio: convertire <code>chardet</code> verso Python 3</a>. <code>chardet</code> è di qualità beta, indipendente dalla piattaforma, compatibile con Python 3, distribuita secondo la licenza <abbr>LGPL</abbr> e pensata per essere integrata nei prodotti di altri sviluppatori.

<pre><code>Programming Language :: Python
Programming Language :: Python :: 3
License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
Operating System :: OS Independent
Development Status :: 4 - Beta
Environment :: Other Environment
Intended Audience :: Developers
Topic :: Text Processing :: Linguistic
Topic :: Software Development :: Libraries :: Python Modules</code></pre>

<p>Ed ecco i classificatori di <a href=http://pypi.python.org/pypi/httplib2><code>httplib2</code></a>, la libreria su cui si basa il capitolo <a href=servizi-web-http.html>Servizi web <abbr>HTTP</abbr></a>. <code>httplib2</code> è di qualità beta, indipendente dalla piattaforma, distribuita secondo la licenza <abbr>MIT</abbr> e rivolta agli sviluppatori che programmano in Python.

<pre><code>Programming Language :: Python
Programming Language :: Python :: 3
License :: OSI Approved :: MIT License
Operating System :: OS Independent
Development Status :: 4 - Beta
Environment :: Web Environment
Intended Audience :: Developers
Topic :: Internet :: WWW/HTTP
Topic :: Software Development :: Libraries :: Python Modules</code></pre>

<h2 id=manifest>Specificare file aggiuntivi con un manifesto</h2>

<p>Per default, Distutils includerà i seguenti file nel vostro pacchetto di distribuzione:

<ul>
<li><code>README.txt</code>;
<li><code>setup.py</code>;
<li>i file <code>.py</code> che occorrono ai moduli multifile elencati nel parametro <code>packages</code>;
<li>i singoli file <code>.py</code> elencati nel parametro <code>py_modules</code>.
</ul>

<p>Questo includerà <a href=#structure>tutti i file del progetto <code>httplib2</code></a>. Ma per il progetto <code>chardet</code> vogliamo anche includere il file di licenza <code>COPYING.txt</code> e l&#8217;intera directory <code>docs/</code> che contiene immagini e file <abbr>HTML</abbr>. Per dire a Distutils di includere anche questi file e queste directory aggiuntive quando assembla il pacchetto di distribuzione per <code>chardet</code>, avete bisogno di un <i>file manifesto</i>.

<p>Un file manifesto è un file di testo chiamato <code>MANIFEST.in</code>. Mettetelo nella directory radice del progetto, a fianco di <code>README.txt</code> e <code>setup.py</code>. I file manifesto <em>non</em> sono programmi Python, ma sono file di testo che contengono una serie di &#8220;comandi&#8221; in un formato definito da Distutils. I comandi di manifesto vi permettono di includere o escludere specifici file e directory.

<p>Questo è l&#8217;intero file manifesto per il progetto <code>chardet</code>:

<pre class=nd><code><a>include COPYING.txt                                <span class=u>&#x2460;</span></a>
<a>recursive-include docs *.html *.css *.png *.gif    <span class=u>&#x2461;</span></a></code></pre>
<ol>
<li>La prima riga è ovvia: include il file <code>COPYING.txt</code> che si trova nella directory radice del progetto.
<li>La seconda riga è un po&#8217; più complicata. Il comando <code>recursive-include</code> prende un nome di directory e uno o più nomi di file. I nomi di file non si limitano a indicare file specifici, ma possono includere wildcard. Questa riga significa: &#8220;Vedi quella directory <code>docs/</code> nella directory radice del progetto? Cerca (ricorsivamente) in quella directory i file <code>.html</code>, <code>.css</code>, <code>.png</code> e <code>.gif</code>. Li voglio tutti nel mio pacchetto di distribuzione.&#8221;
</ol>

<p>Tutti i comandi di manifesto preservano la struttura di directory che avete impostato nella directory del vostro progetto. Quel comando <code>recursive-include</code> non metterà un gruppo di file <code>.html</code> e <code>.png</code> nella directory radice del pacchetto di distribuzione. Invece, manterrà la struttura della directory <code>docs/</code> esistente, includendo solo quei file contenuti dentro quella directory che corrispondono alle wildcard date. (Non l&#8217;ho detto prima, ma la documentazione di <code>chardet</code> è in realtà scritta in <abbr>XML</abbr> e convertita in <abbr>HTML</abbr> da un programma separato. Non voglio includere i file <abbr>XML</abbr> nel pacchetto di distribuzione, ma solo i file <abbr>HTML</abbr> e le immagini.)

<blockquote class=note>
<p><span class=u>&#x261E;</span>I file manifesto hanno il proprio singolare formato. Leggete <a href=http://docs.python.org/3.1/distutils/sourcedist.html#manifest>Specificare i file da distribuire</a> e <a href=http://docs.python.org/3.1/distutils/commandref.html#sdist-cmd>I comandi per i modelli di manifesto</a> se volete conoscere i dettagli.
</blockquote>

<p>Per ripetermi: avete bisogno di creare un file manifesto solo se volete includere file che Distutils non include per default. Se avete bisogno di un file manifesto, dovreste includere solo i file e le directory che Distutils non sarebbe altrimenti in grado di trovare da solo.

<h2 id=check>Controllare che il vostro programma di installazione non contenga errori</h2>

<p>Ci sono molte cose di cui tenere traccia. Distutils include un comando di validazione predefinito che controlla la presenza di tutti i metadati obbligatori nel vostro programma di installazione. Per esempio, se dimenticate di includere il parametro <code>version</code>, Distutils ve lo ricorderà.

<pre class=screen>
<samp class=p>c:\Users\pilgrim\chardet> </samp><kbd>c:\python31\python.exe setup.py check</kbd>
<samp>eseguo il comando check
attenzione: controllo: metadato richiesto mancante: version</samp></pre>

<p>Una volta che includete un parametro <code>version</code> (e tutti gli altri metadati obbligatori), l&#8217;esecuzione del comando <code>check</code> somiglierà a questa:

<pre class=screen>
<samp class=p>c:\Users\pilgrim\chardet> </samp><kbd>c:\python31\python.exe setup.py check</kbd>
<samp>eseguo il comando check</samp></pre>

<p class=a>&#x2042;

<h2 id=sdist>Creare una distribuzione dei sorgenti</h2>

<p>Distutils supporta l&#8217;assemblaggio di diversi tipi di pacchetti di distribuzione. Come minimo, dovreste creare una &#8220;distribuzione dei sorgenti&#8221; che contenga il vostro codice sorgente, il vostro programma di setup di Distutils, il vostro file &#8220;leggimi&#8221; e tutti i <a href=#manifest>file aggiuntivi che volete includere</a>. Per creare una distribuzione dei sorgenti passate il comando <code>sdist</code> al vostro programma di installazione di Distutils.

<pre class=screen>
<samp class=p>c:\Users\pilgrim\chardet> </samp><kbd><mark>c:\python31\python.exe setup.py sdist</mark></kbd>
<samp>eseguo il comando sdist
eseguo il comando check
leggo il modello di manifesto 'MANIFEST.in'
scrivo il file di manifesto 'MANIFEST'
creo chardet-1.0.2
creo chardet-1.0.2\chardet
creo chardet-1.0.2\docs
creo chardet-1.0.2\docs\images
copio i file in chardet-1.0.2...
copio COPYING -> chardet-1.0.2
copio README.txt -> chardet-1.0.2
copio setup.py -> chardet-1.0.2
copio chardet\__init__.py -> chardet-1.0.2\chardet
copio chardet\big5freq.py -> chardet-1.0.2\chardet
...
copio chardet\universaldetector.py -> chardet-1.0.2\chardet
copio chardet\utf8prober.py -> chardet-1.0.2\chardet
copio docs\faq.html -> chardet-1.0.2\docs
copio docs\history.html -> chardet-1.0.2\docs
copio docs\how-it-works.html -> chardet-1.0.2\docs
copio docs\index.html -> chardet-1.0.2\docs
copio docs\license.html -> chardet-1.0.2\docs
copio docs\supported-encodings.html -> chardet-1.0.2\docs
copio docs\usage.html -> chardet-1.0.2\docs
copio docs\images\caution.png -> chardet-1.0.2\docs\images
copio docs\images\important.png -> chardet-1.0.2\docs\images
copio docs\images\note.png -> chardet-1.0.2\docs\images
copio docs\images\permalink.gif -> chardet-1.0.2\docs\images
copio docs\images\tip.png -> chardet-1.0.2\docs\images
copio docs\images\warning.png -> chardet-1.0.2\docs\images
creo 'dist'
creo 'dist\chardet-1.0.2.zip' e vi aggiungo 'chardet-1.0.2'
aggiungo 'chardet-1.0.2\COPYING'
aggiungo 'chardet-1.0.2\PKG-INFO'
aggiungo 'chardet-1.0.2\README.txt'
aggiungo 'chardet-1.0.2\setup.py'
aggiungo 'chardet-1.0.2\chardet\big5freq.py'
aggiungo 'chardet-1.0.2\chardet\big5prober.py'
...
aggiungo 'chardet-1.0.2\chardet\universaldetector.py'
aggiungo 'chardet-1.0.2\chardet\utf8prober.py'
aggiungo 'chardet-1.0.2\chardet\__init__.py'
aggiungo 'chardet-1.0.2\docs\faq.html'
aggiungo 'chardet-1.0.2\docs\history.html'
aggiungo 'chardet-1.0.2\docs\how-it-works.html'
aggiungo 'chardet-1.0.2\docs\index.html'
aggiungo 'chardet-1.0.2\docs\license.html'
aggiungo 'chardet-1.0.2\docs\supported-encodings.html'
aggiungo 'chardet-1.0.2\docs\usage.html'
aggiungo 'chardet-1.0.2\docs\images\caution.png'
aggiungo 'chardet-1.0.2\docs\images\important.png'
aggiungo 'chardet-1.0.2\docs\images\note.png'
aggiungo 'chardet-1.0.2\docs\images\permalink.gif'
aggiungo 'chardet-1.0.2\docs\images\tip.png'
aggiungo 'chardet-1.0.2\docs\images\warning.png'
rimuovo 'chardet-1.0.2' (e ogni cosa al suo interno)</samp></pre>

<p>Ci sono diverse cose da notare qui:

<ul>
<li>Distutils ha notato la presenza del file manifesto (<code>MANIFEST.in</code>);
<li>Distutils ha riconosciuto con successo il contenuto del file manifesto aggiungendo i file che volevamo&nbsp;&mdash;&nbsp;<code>COPYING.txt</code>, i file <abbr>HTML</abbr> e le immagini contenute nella directory <code>docs/</code>;
<li>se guardate nella vostra directory di progetto, vedrete che Distutils ha creato una directory <code>dist/</code> in cui si trova il file <code>.zip</code> che potete distribuire.
</ul>

<pre class=screen>
<samp class=p>c:\Users\pilgrim\chardet> </samp><kbd><mark>dir dist</mark></kbd>
<samp> Il volume nell'unità C non ha etichetta.
 Numero di serie del volume: DED5-B4F8

 Directory di c:\Users\pilgrim\chardet\dist

30/07/2009  06:29    &lt;DIR>          .
30/07/2009  06:29    &lt;DIR>          ..
30/07/2009  06:29           206,440 <mark>chardet-1.0.2.zip</mark>
               1 File        206.440 byte
               2 Directory   61.424.635.904 byte disponibili</samp></pre>

<p class=a>&#x2042;

<h2 id=bdist>Creare un programma di installazione grafico</h2>

<p>A mio parere, tutte le librerie Python si meritano un programma di installazione grafico per utenti Windows. &Egrave; facile da creare (anche se voi stessi non usate Windows) e gli utenti Windows lo apprezzano.

<p>Distutils può <a href=http://docs.python.org/3.1/distutils/builtdist.html#creating-windows-installers>creare un programma di installazione grafico per Windows</a> se passate il comando <code>bdist_wininst</code> al vostro programma di installazione di Distutils.

<pre class=screen>
<samp class=p>c:\Users\pilgrim\chardet> </samp><kbd><mark>c:\python31\python.exe setup.py bdist_wininst</mark></kbd>
<samp>eseguo il comando bdist_wininst
eseguo il comando build
eseguo il comando build_py
creo build
creo build\lib
creo build\lib\chardet
copio chardet\big5freq.py -> build\lib\chardet
copio chardet\big5prober.py -> build\lib\chardet
...
copio chardet\universaldetector.py -> build\lib\chardet
copio chardet\utf8prober.py -> build\lib\chardet
copio chardet\__init__.py -> build\lib\chardet
installo in build\bdist.win32\wininst
eseguo il comando install_lib
creo build\bdist.win32
creo build\bdist.win32\wininst
creo build\bdist.win32\wininst\PURELIB
creo build\bdist.win32\wininst\PURELIB\chardet
copio build\lib\chardet\big5freq.py -> build\bdist.win32\wininst\PURELIB\chardet
copio build\lib\chardet\big5prober.py -> build\bdist.win32\wininst\PURELIB\chardet
...
copio build\lib\chardet\universaldetector.py -> build\bdist.win32\wininst\PURELIB\chardet
copio build\lib\chardet\utf8prober.py -> build\bdist.win32\wininst\PURELIB\chardet
copio build\lib\chardet\__init__.py -> build\bdist.win32\wininst\PURELIB\chardet
eseguo il comando install_egg_info
Scrivo build\bdist.win32\wininst\PURELIB\chardet-1.0.2-py3.1.egg-info
creo 'c:\users\pilgrim\appdata\local\temp\tmp2f4h7e.zip' e vi aggiungo '.'
aggiungo 'PURELIB\chardet-1.0.2-py3.1.egg-info'
aggiungo 'PURELIB\chardet\big5freq.py'
aggiungo 'PURELIB\chardet\big5prober.py'
...
aggiungo 'PURELIB\chardet\universaldetector.py'
aggiungo 'PURELIB\chardet\utf8prober.py'
aggiungo 'PURELIB\chardet\__init__.py'
rimuovo 'build\bdist.win32\wininst' (e ogni cosa al suo interno)</samp>
<samp class=p>c:\Users\pilgrim\chardet> </samp><kbd><mark>dir dist</mark></kbd>
<samp> Il volume nell'unità C non ha etichetta.
 Numero di serie del volume: DED5-B4F8

 Directory di c:\Users\pilgrim\chardet\dist

30/07/2009  10:14    &lt;DIR>          .
30/07/2009  10:14    &lt;DIR>          ..
30/07/2009  10:14           371,236 <mark>chardet-1.0.2.win32.exe</mark>
30/07/2009  06:29           206,440 chardet-1.0.2.zip
               2 File        577.676 byte
               2 Directory   61.424.070.656 byte disponibili</samp></pre>

<h3 id=linux>Assemblare pacchetti di installazione per altri sistemi operativi</h3>

<p>Distutils può aiutarvi ad <a href=http://docs.python.org/3.1/distutils/builtdist.html#creating-rpm-packages>assemblare pacchetti di installazione per gli utenti Linux</a>. A mio parere, probabilmente non ne vale la pena. Se volete che il vostro software venga distribuito per Linux, spendereste meglio il vostro tempo lavorando con i membri della comunità che si sono specializzati nel creare pacchetti software per le distribuzioni Linux più importanti.

<p>Per esempio, la mia libreria <code>chardet</code> si trova <a href=http://packages.debian.org/python-chardet>negli archivi della distribuzione Debian GNU/Linux</a> (e di conseguenza anche <a href=http://packages.ubuntu.com/python-chardet>negli archivi di Ubuntu</a>). Io non ho avuto niente a che fare con questo: un giorno il pacchetto è semplicemente comparso. La comunità di Debian ha <a href=http://www.debian.org/doc/packaging-manuals/python-policy/>le proprie politiche per distribuire librerie Python</a> e il pacchetto Debian <code>python-chardet</code> è realizzato in modo da seguire queste convenzioni. Dato che il pacchetto si trova negli archivi della distribuzione Debian, gli utenti Debian riceveranno aggiornamenti di sicurezza e/o nuove versioni a seconda delle impostazioni di sistema con cui hanno deciso di gestire il proprio computer.

<p>I pacchetti Linux che vengono assemblati da Distutils non offrono nessuno di questi vantaggi. Il vostro tempo è speso meglio da qualche altra parte.

<p class=a>&#x2042;

<h2 id=pypi>Aggiungere il vostro software all&#8217;Indice dei Pacchetti Python</h2>

<p>Caricare il vostro software sull&#8217;Indice dei Pacchetti Python è un processo che si svolge in tre fasi.

<ol>
<li>Registrazione di un utente
<li>Registrazione del software
<li>Caricamento del pacchetto creato con <code>setup.py sdist</code> e <code>setup.py bdist_*</code>
</ol>

<p>Per registrarvi, andate alla <a href="http://pypi.python.org/pypi?:action=register_form">pagina di registrazione per gli utenti di PyPI</a>. Inserite il nome utente e la password che desiderate, fornite un indirizzo email valido e cliccate il bottone <code>Register</code>. (Se avete una chiave <abbr>PGP</abbr> o <abbr>GPG</abbr> potete fornire anche quella. Se non ne avete una o non sapete cosa significa, non fatelo.) Controllate la vostra casella email: entro pochi minuti dovreste ricevere un messaggio da PyPI contenente un link di verifica. Cliccate sul link per completare il processo di registrazione.

<p>Ora dovete registrare il vostro software su PyPI e caricarlo. Potete farlo in un unico passo.

<pre class=screen>
<a><samp class=p>c:\Users\pilgrim\chardet> </samp><kbd>c:\python31\python.exe setup.py register sdist bdist_wininst upload</kbd>  <span class=u>&#x2460;</span></a>
<samp>eseguo il comando register
Abbiamo bisogno di sapere chi sei, quindi scegli una tra le seguenti alternative:
 1. usa i tuoi dati di accesso esistenti,
 2. registrati come nuovo utente,
 3. chiedi al server di generarti una nuova password (e di spedirtela via email), o
 4. esci</samp>
<a><samp class=p>La tua selezione [default 1]: </samp><kbd>1</kbd>                                                                <span class=u>&#x2461;</span></a>
<a><samp class=p>Utente: </samp><kbd>MarkPilgrim</kbd>                                                                            <span class=u>&#x2462;</span></a>
<samp class=p>Password:</samp>
<a><samp>Registro chardet su http://pypi.python.org/pypi</samp>                                                <span class=u>&#x2463;</span></a>
<samp>Risposta del server (200): OK</samp>
<a><samp>eseguo il comando sdist</samp>                                                                        <span class=u>&#x2464;</span></a>
<samp>... messaggi omessi per brevità ...</samp>
<a><samp>eseguo il comando bdist_wininst</samp>                                                                <span class=u>&#x2465;</span></a>
<samp>... messaggi omessi per brevità ...</samp>
<a><samp>eseguo il comando upload</samp>                                                                       <span class=u>&#x2466;</span></a>
<samp>Invio dist\chardet-1.0.2.zip a http://pypi.python.org/pypi
Risposta del server (200): OK
Invio dist\chardet-1.0.2.win32.exe a http://pypi.python.org/pypi
Risposta del server (200): OK
Posso memorizzare i tuoi dati di accesso su PyPI per rendere più veloci le future trasmissioni.
(i dati verranno memorizzati in c:\home\.pypirc)</samp>
<a><samp class=p>Salvare i tuoi dati di accesso (y/N)?</samp> <kbd class=pp>n</kbd>                                                        <span class=u>&#x2467;</span></a></pre>
<ol>
<li>Quando rilasciate il vostro progetto per la prima volta, Distutils aggiungerà il vostro software all&#8217;Indice dei Pacchetti Python e gli darà un proprio <abbr>URL</abbr>. Tutte le volte successive si limiterà ad aggiornare i metadati del progetto con qualsiasi cambiamento possiate aver apportato ai parametri del vostro file <code>setup.py</code>. Poi, assemblerà una distribuzione dei sorgenti (<code>sdist</code>) e un pacchetto di installazione per Windows (<code>bdist_wininst</code>) e li caricherà entrambi su PyPI (<code>upload</code>).
<li>Digitate <kbd>1</kbd> o premete semplicemente <kbd>INVIO</kbd> per selezionare &#8220;usa i tuoi dati di accesso esistenti&#8221;.
<li>Inserite il nome utente e la password che avete selezionato sulla <a href="http://pypi.python.org/pypi?:action=register_form">pagina di registrazione per gli utenti di PyPI</a>. Distuils non mostrerà la vostra password sullo schermo, né mostrerà asterischi al posto dei caratteri. Digitate semplicemente la vostra password e premete <kbd>INVIO</kbd>.
<li>Distutils registra il vostro pacchetto sull&#8217;Indice dei Pacchetti Python&hellip;
<li>&hellip;assembla la vostra distribuzione dei sorgenti&hellip;
<li>&hellip;crea il pacchetto di installazione per Windows&hellip;
<li>&hellip;e li carica entrambi sull&#8217;Indice dei Pacchetti Python.
<li>Se volete automatizzare il processo di rilascio delle nuove versioni, avrete bisogno di salvare le vostre credenziali su PyPI in un file locale. Questo è assolutamente insicuro e completamente opzionale.
</ol>

<p>Congratulazioni, ora avete la vostra pagina sull&#8217;Indice dei Pacchetti Python! L&#8217;indirizzo è <code>http://pypi.python.org/pypi/<i>NOME</i></code>, dove <i>NOME</i> è la stringa che avete passato nel parametro <var>name</var> nel vostro file <code>setup.py</code>.

<p>Se volete rilasciare una nuova versione, vi basta aggiornare il vostro file <code>setup.py</code> con il nuovo numero di versione e invocare lo stesso comando di prima:

<pre class='nd screen'>
<samp class=p>c:\Users\pilgrim\chardet> </samp><kbd>c:\python31\python.exe setup.py register sdist bdist_wininst upload</kbd>
</pre>

<p class=a>&#x2042;

<h2 id=future>I molti possibili futuri della distribuzione di librerie Python</h2>

<p>Distutils non è la quintessenza della distribuzione di librerie Python, ma al momento della scrittura (agosto 2009) è l&#8217;unico framework per la creazione di pacchetti che funziona con Python 3. Ci sono un certo numero di altri framework per Python 2: alcuni si concentrano sull&#8217;installazione, altri sul collaudo e il deployment. In futuro, alcuni o persino tutti potrebbero venire convertiti verso Python 3.

<p>Questi framework si concentrano sull&#8217;installazione:

<ul>
<li><a href=http://pypi.python.org/pypi/setuptools>Setuptools</a>
<li><a href=http://pypi.python.org/pypi/pip>Pip</a>
<li><a href=http://bitbucket.org/tarek/distribute/>Distribute</a>
</ul>

<p>Questi si concentrano sul collaudo e il deployment:

<ul>
<li><a href=http://pypi.python.org/pypi/virtualenv><code>virtualenv</code></a>
<li><a href=http://pypi.python.org/pypi/zc.buildout><code>zc.buildout</code></a>
<li><a href=http://www.blueskyonmars.com/projects/paver/>Paver</a>
<li><a href=http://fabfile.org/>Fabric</a>
<li><a href=http://www.py2exe.org/><code>py2exe</code></a>
</ul>

<p class=a>&#x2042;

<h2 id=furtherreading>Letture di approfondimento</h2>

<p>Su Distutils:

<ul>
<li><a href=http://docs.python.org/3.1/distutils/>Distribuire moduli Python con Distutils</a>
<li><a href=http://docs.python.org/3.1/distutils/apiref.html#module-distutils.core>Le funzionalità principali di Distutils</a> elenca tutti i possibili argomenti per la funzione <code>setup()</code>
<li><a href=http://wiki.python.org/moin/Distutils/Cookbook>Il ricettario di Distutils</a>
<li><a href=http://www.python.org/dev/peps/pep-0370/><abbr>PEP</abbr> 370: directory <code>site-packages</code> per il singolo utente</a>
<li><a href=http://jessenoller.com/2009/07/19/pep-370-per-user-site-packages-and-environment-stew/>La <abbr>PEP</abbr> 370 e lo &#8220;stufato d&#8217;ambiente&#8221;</a>
</ul>

<p>Su altri framework per la creazione di pacchetti:

<ul>
<li><a href=http://groups.google.com/group/django-developers/msg/5407cdb400157259>L&#8217;ecosistema della creazione di pacchetti Python</a>
<li><a href=http://www.b-list.org/weblog/2008/dec/14/packaging/>Sulla distribuzione</a>
<li><a href=http://blog.ianbicking.org/2008/12/14/a-few-corrections-to-on-packaging/>Alcune correzioni a &#8220;Sulla distribuzione&#8221;</a>
<li><a href=http://www.b-list.org/weblog/2008/dec/15/pip/>Perché mi piace Pip</a>
<li><a href=http://cournape.wordpress.com/2009/04/01/python-packaging-a-few-observations-cabal-for-a-solution/>La distribuzione di pacchetti Python: alcune osservazioni</a>
<li><a href=http://jacobian.org/writing/nobody-expects-python-packaging/>Nessuno si aspetta la distribuzione di pacchetti Python!</a>
</ul>

<p class=v><a rel=prev href=caso-di-studio-convertire-chardet-verso-python-3.html title='indietro a &#8220;Caso di studio: convertire chardet verso Python 3&#8221;'><span class=u>&#x261C;</span></a> <a rel=next href=convertire-codice-verso-python-3-con-2to3.html title='avanti a &#8220;Convertire codice verso Python 3 con 2to3&#8221;'><span class=u>&#x261E;</span></a>
<p class=c>&copy; 2001&ndash;10 <a href=informazioni-sul-libro.html>Mark Pilgrim</a><br>
&copy; 2009&ndash;10 <a href=informazioni-sulla-traduzione.html>Giulio Piancastelli</a> per la traduzione italiana
<script src=j/jquery.js></script>
<script src=j/prettify.js></script>
<script src=j/dip3.js></script>