4.1 Specifiche del file da distribuire

Se non si fornisce un'esplicita lista di file (o le istruzioni su come generarne una), il comando sdist ne inserisce un insieme predefinito minimo nel sorgente da distribuire:

Qualche volta questo è sufficiente, ma solitamente si vuole specificare ulteriori file da distribuire. La procedura tipica per fare questo è scrivere un manifest template, chiamato MANIFEST.in predefinito. Lo schema del manifesto è semplicemente una lista di istruzioni su come generare il proprio file manifest, MANIFEST, che è l'esatto elenco dei file da includere nella propria distribuzione sorgente. Il comando sdist processa il template e genera il manifesto basato sulle sue istruzioni e con ciò che trova nel filesystem.

Se si preferisce creare autonomamente il proprio file di manifesto, il formato è semplice: un nome di file per riga, file regolari (o link simbolici riferiti a loro stessi). Se si fornisce il proprio MANIFEST, si deve specificare ogni cosa: l'insieme dei file predefiniti descritto sopra non si applica per questo caso.

Lo schema del manifesto ha un comando per riga, dove ogni comando specifica un insieme di file da includere o da escludere dalla distribuzione sorgente. Per un esempio, utilizzeremo ancora il template del manifesto proprio delle Distutils:

include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build

Il significato dovrebbe essere piuttosto chiaro: includere tutti i file nel livello principale della distribuzione che verificano *.txt o *.py ed escludere tutte le directory che verificano examples/sample?/build. Tutto questo viene fatto dopo l'inclusione standard dell'insieme, così che si possano escludere file dall'insieme standard con istruzioni esplicite nello schema del manifesto. (O si può usare l'opzione --no-defaults per disabilitare interamente l'insieme standard). Ci sono diversi altri comandi disponibili nel mini-linguaggio dello schema del manifesto; si veda la sezione 8.2.

L'ordine dei comandi nello schema del manifesto è organizzato così: inizialmente abbiamo la lista dei file predefiniti come descritto sopra ed ogni comando nel template né aggiunge né rimuove dalla lista alcun file. Una volta che si è completamente processato lo schema del manifesto, si rimuoveranno i file che non verranno inclusi nella distribuzione sorgente:

Adesso abbiamo l'elenco completo dei file, che viene scritto nel manifesto per usi futuri e quindi usato per costruire l'archivio, o gli archivi, della distribuzione sorgente.

Si può disabilitare l'insieme predefinito dei file include con l'opzione --no-defaults e si può disabilitare l'esclusione standard con --no-prune.

Seguendo lo schema del manifesto proprio delle Distutils, si può seguire come il comando sdist costruisca la lista dei file da includere nella distribuzione sorgente delle Distutils:

  1. include tutti i file sorgenti Python nelle sottodirectory distutils e distutils/command (in quanto i package corrispondenti a queste due directory erano menzionati nell'opzione packages nello script di setup--si veda la sezione 2)
  2. include README.txt, setup.py e setup.cfg (file standard)
  3. include test/test*.py (file standard)
  4. include *.txt nella distribuzione principale (questo cercherà README.txt in un secondo tempo, ma alcuni duplicati verranno eliminati successivamente)
  5. include qualsiasi cosa che verifichi *.txt o *.py nelle sottodirectory sotto examples
  6. esclude tutti file nelle sottodirectory a partire dalla directory che verifica examples/sample?/build--questo potrebbe escludere file inclusi nei precedenti due passagi, è quindi importante che il comando prune nello schema del manifesto venga dopo il comando recursive-include
  7. esclude l'intero albero build ed ogni directory RCS o CVS
Semplicemente, come nello script di setup, i nomi dei file e delle directory dello schema del manifesto devono sempre essere separati da slash; le Distutils si prenderanno carico di convertirle nella rappresentazione standard della propria piattaforma. In questo modo, lo schema del manifesto diventa portabile tra sistemi operativi diversi tra loro.

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