Python Academy · Lezione

Versionamento e metadati

Gestire i metadati del pacchetto

Versionamento e metadati è una lezione Python Academy gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Python Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Python Academy include 4 lezioni in totale.

Perché i metadati sono importanti

I metadati comprendono tutto ciò che riguarda il pacchetto tranne il codice: versione, descrizione, licenza, autore e collegamenti. PyPI li usa per visualizzare il progetto, mentre pip li usa per risolvere le dipendenze.

Metadati accurati rendono il pacchetto affidabile e installabile.

Versionamento semantico

La convenzione è MAJOR.MINOR.PATCH:

MAJOR: modifiche incompatibili
MINOR: nuove funzionalità compatibili con le versioni precedenti
PATCH: correzioni di bug compatibili con le versioni precedenti

Gli utenti si affidano a questa convenzione per capire se un aggiornamento è sicuro.

version = '2.4.1'
major, minor, patch = version.split('.')
print('Major', major, 'Minor', minor, 'Patch', patch)
print('Bug fix -> bump patch to', major + '.' + minor + '.' + str(int(patch) + 1))

Scegliere la versione successiva

La scelta dell'incremento di versione segue regole precise: l'API è stata modificata in modo incompatibile, è stata aggiunta una funzionalità o è stato semplicemente corretto un bug? Codificare la regola rende coerenti i rilasci.

def bump(version, kind):
    major, minor, patch = (int(x) for x in version.split('.'))
    if kind == 'major':
        return str(major + 1) + '.0.0'
    if kind == 'minor':
        return str(major) + '.' + str(minor + 1) + '.0'
    return str(major) + '.' + str(minor) + '.' + str(patch + 1)

print(bump('1.2.3', 'minor'))
print(bump('1.2.3', 'major'))

Versioni preliminari e di sviluppo

Python consente di usare dei suffissi: 1.0.0a1 (alpha), 1.0.0b2 (beta), 1.0.0rc1 (release candidate) e 1.0.0.dev3. pip considera queste versioni precedenti alla versione finale 1.0.0, così chi esegue i test può aderire senza influire sugli utenti normali.

Un'unica fonte di verità

Mantenga la versione in un solo punto. La dichiari staticamente in pyproject.toml, oppure la contrassegni come dynamic e la legga dal codice (o da un tag) tramite strumenti come setuptools-scm. Due copie finiscono inevitabilmente per divergere.

Descrizione e README

Una description breve compare nei risultati di ricerca. La descrizione lunga proviene dal Suo readme (di solito README.md) e viene visualizzata come pagina del progetto su PyPI. La indichi con readme = 'README.md'.

Un README chiaro è il Suo miglior strumento di presentazione.

Licenza

Dichiari una licenza, così gli utenti conoscono i propri diritti. I progetti moderni utilizzano un'espressione SPDX come license = 'MIT'. In assenza di una licenza, tutti i diritti sono riservati, scoraggiando l'adozione.

popular = ['MIT', 'Apache-2.0', 'BSD-3-Clause', 'GPL-3.0-only']
for lic in popular:
    print('SPDX:', lic)

Classificatori

I classifiers sono tag standardizzati tratti dall'elenco di PyPI, come 'Programming Language :: Python :: 3.11' o 'Development Status :: 4 - Beta'. Alimentano i filtri di PyPI e comunicano il livello di maturità e le versioni supportate.

URL del progetto

Nella sezione [project.urls] aggiunga collegamenti come Pagina principale, Documentazione, Sorgente e Changelog. Questi collegamenti appaiono in una barra laterale su PyPI e aiutano gli utenti a trovare il repository e la documentazione.

urls = {
    'Homepage': 'https://example.com',
    'Source': 'https://github.com/me/mytool',
    'Issues': 'https://github.com/me/mytool/issues',
}
for label, link in urls.items():
    print(label.ljust(10), link)

Parole chiave per la reperibilità

Il campo keywords è un elenco di termini brevi che aiutano gli utenti a trovare il pacchetto nelle ricerche. Scelga parole che le persone digiterebbero davvero, come ['cli', 'automation', 'excel'], anziché riempitivi generici.

Insieme ai classificatori, le parole chiave migliorano la reperibilità del progetto.

Un changelog

Mantenga un CHANGELOG che registri le modifiche apportate in ogni versione. Gli utenti lo leggono prima di eseguire un aggiornamento, per conoscere le nuove funzionalità e le modifiche incompatibili. Collegarlo nella sezione [project.urls] lo rende raggiungibile con un clic dalla pagina PyPI.

Un buon changelog trasforma un numero di versione in una storia che gli utenti possono seguire.

Verifica rapida

Metta alla prova le Sue conoscenze sul versionamento.

Riepilogo

Ha gestito i metadati del pacchetto:

Versionamento semantico MAJOR.MINOR.PATCH, oltre ai suffissi delle versioni preliminari
Mantenga la versione in un'unica fonte di verità
Fornisca description, una descrizione estesa nel README e una license
Aggiunga classifiers e [project.urls] affinché PyPI presenti bene il progetto

Domande Frequenti

La lezione «Versionamento e metadati» è gratuita?

Sì — il testo completo di «Versionamento e metadati» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Python Academy, passa a CoddyKit PRO. Il corso Python Academy include 4 lezioni in totale.

Cosa imparerò in «Versionamento e metadati»?

Gestire i metadati del pacchetto Eserciti Python Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Python Academy?

Non è richiesta alcuna esperienza precedente. Python Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.

Quanto tempo richiede la lezione «Versionamento e metadati»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Python Academy?

Sì. Ogni lezione Python Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a Python Academy