Modo standard per incorporare la versione nel pacchetto python?

Esiste un modo standard per associare la stringa di versione a un pacchetto python in modo che io possa fare quanto segue?

import foo
print foo.version

Immagino che ci sia un modo per recuperare quei dati senza alcun hardcoding aggiuntivo, dal momento che le stringhe minori / maggiori sono setup.pygià specificate . Una soluzione alternativa che ho trovato era quella di avere import __version__nel mio foo/__init__.pye poi __version__.pygenerato da setup.py.

Non direttamente una risposta alla tua domanda, ma dovresti considerare di nominarla __version__, no version.

Questo è quasi un quasi standard. Molti moduli nella libreria standard usano __version__, e questo è usato anche in molti moduli di terze parti, quindi è quasi standard.

Di solito, __version__è una stringa, ma a volte è anche un float o una tupla.

Modifica: come menzionato da S.Lott (Grazie!), PEP 8 lo dice esplicitamente:

Nomi secondari a livello di modulo

Modulo di livello "dunders" (cioè nomi con due principali e due sottolineature trascinamento) quali __all__, __author__, __version__, ecc devono essere posizionati dopo la docstring modulo ma prima di qualsiasi istruzione di importazione tranne da __future__importazioni.

È inoltre necessario assicurarsi che il numero di versione sia conforme al formato descritto in PEP 440 ( PEP 386 una versione precedente di questo standard).

Uso un singolo _version.pyfile come "luogo un tempo cannonico" per memorizzare le informazioni sulla versione:

1. Fornisce un __version__attributo.

2. Fornisce la versione standard dei metadati. Pertanto verrà rilevato da pkg_resourceso altri strumenti che analizzano i metadati del pacchetto (EGG-INFO e / o PKG-INFO, PEP 0345).

3. Non importa il pacchetto (o qualsiasi altra cosa) durante la creazione del pacchetto, il che può causare problemi in alcune situazioni. (Vedi i commenti qui sotto su quali problemi ciò può causare.)

4. C'è un solo posto in cui il numero di versione è scritto, quindi c'è solo un posto per cambiarlo quando cambia il numero di versione e c'è meno possibilità di versioni incoerenti.

Ecco come funziona: "un posto canonico" per memorizzare il numero di versione è un file .py, denominato "_version.py" che si trova nel pacchetto Python, ad esempio in myniftyapp/_version.py. Questo file è un modulo Python, ma setup.py non lo importa! (Ciò vanificherebbe la funzione 3.) Invece setup.py sa che il contenuto di questo file è molto semplice, qualcosa del tipo:

__version__ = "3.6.5"

E così setup.py apre il file e lo analizza, con codice come:

import re
VERSIONFILE="myniftyapp/_version.py"
verstrline = open(VERSIONFILE, "rt").read()
VSRE = r"^__version__ = ['\"]([^'\"]*)['\"]"
mo = re.search(VSRE, verstrline, re.M)
if mo:
    verstr = mo.group(1)
else:
    raise RuntimeError("Unable to find version string in %s." % (VERSIONFILE,))

Quindi setup.py passa quella stringa come valore dell'argomento "versione" a setup(), soddisfacendo così la funzione 2.

Per soddisfare la funzione 1, puoi avere il tuo pacchetto (in fase di esecuzione, non in fase di installazione!) Importare il file _version in myniftyapp/__init__.pyquesto modo:

from _version import __version__

Ecco un esempio di questa tecnica che utilizzo da anni.

Il codice in questo esempio è un po 'più complicato, ma l'esempio semplificato che ho scritto in questo commento dovrebbe essere un'implementazione completa.

Ecco un esempio di codice per importare la versione .

Se vedi qualcosa di sbagliato in questo approccio, per favore fatemelo sapere.

Riscritto 2017-05

Dopo più di dieci anni di scrittura del codice Python e la gestione di vari pacchetti sono giunto alla conclusione che il fai-da-te non è forse l'approccio migliore.

Ho iniziato a utilizzare il pbrpacchetto per gestire il controllo delle versioni nei miei pacchetti. Se stai usando git come SCM, questo si adatterà al tuo flusso di lavoro come per magia, salvando le tue settimane di lavoro (sarai sorpreso da quanto possa essere complesso il problema).

Ad oggi pbr è classificato al 11 ° pacchetto python più utilizzato e raggiungere questo livello non ha incluso alcun trucco sporco: era solo uno: risolvere un problema comune di packaging in un modo molto semplice.

pbr può fare più del carico di manutenzione del pacchetto, non si limita al controllo delle versioni ma non ti obbliga ad adottare tutti i suoi vantaggi.

Quindi, per darti un'idea di come sembra adottare pbr in un commit, dai un'occhiata al packaging di pbr

Probabilmente avresti osservato che la versione non è affatto archiviata nel repository. PBR lo rileva dai rami e dai tag Git.

Non c'è bisogno di preoccuparsi di ciò che accade quando non si dispone di un repository git perché pbr "compila" e memorizza nella cache la versione quando si impacchettano o installano le applicazioni, quindi non c'è dipendenza runtime da git.

Vecchia soluzione

Ecco la migliore soluzione che ho visto finora e spiega anche perché:

All'interno yourpackage/version.py:

# Store the version here so:
# 1) we don't load dependencies by storing it in __init__.py
# 2) we can import it in setup.py for the same reason
# 3) we can import it into your module module
__version__ = '0.12'

All'interno yourpackage/__init__.py:

from .version import __version__

All'interno setup.py:

exec(open('yourpackage/version.py').read())
setup(
    ...
    version=__version__,
    ...

Se conosci un altro approccio che sembra essere meglio, fammelo sapere.

Secondo il PEP 396 differito (numeri di versione del modulo) , esiste un modo proposto per farlo. Descrive, con logica, uno standard (certamente facoltativo) per i moduli da seguire. Ecco uno snippet:

3) Quando un modulo (o pacchetto) include un numero di versione, la versione DOVREBBE essere disponibile __version__nell'attributo.

4) Per i moduli che vivono all'interno di un pacchetto dello spazio dei nomi, il modulo DOVREBBE includere l' __version__attributo. Il pacchetto dello spazio dei nomi stesso NON DOVREBBE includere il proprio __version__attributo.

5) Il __version__valore dell'attributo DOVREBBE essere una stringa.

Sebbene questo sia probabilmente troppo tardi, esiste un'alternativa leggermente più semplice alla risposta precedente:

__version_info__ = ('1', '2', '3')
__version__ = '.'.join(__version_info__)

(E sarebbe abbastanza semplice convertire porzioni a incremento automatico dei numeri di versione in una stringa usando str().)

Ovviamente, da quello che ho visto, le persone tendono ad usare qualcosa come la versione precedentemente menzionata durante l'uso __version_info__, e quindi archiviarla come una tupla di ints; tuttavia, non vedo esattamente il punto nel farlo, poiché dubito che ci siano situazioni in cui eseguiresti operazioni matematiche come addizione e sottrazione su porzioni di numeri di versione per qualsiasi scopo oltre a curiosità o auto-incremento (e anche allora, int()e str()può essere usato abbastanza facilmente). (D'altra parte, c'è la possibilità che il codice di qualcun altro si aspetti una tupla numerica piuttosto che una tupla di stringa e quindi fallisca.)

Questa è, ovviamente, la mia opinione personale e mi piacerebbe volentieri il contributo degli altri sull'uso di una tupla numerica.

Come ha ricordato Shezi, i confronti (lessicali) delle stringhe di numeri non hanno necessariamente lo stesso risultato dei confronti numerici diretti; gli zeri iniziali sarebbero tenuti a provvedere per questo. Quindi, alla fine, l'archiviazione __version_info__(o come si chiamerebbe) come una tupla di valori interi consentirebbe confronti di versioni più efficienti.

Molte di queste soluzioni ignorano i gittag di versione, il che significa che è necessario tenere traccia della versione in più punti (non valido). Mi sono avvicinato a questo con i seguenti obiettivi:

• Deriva tutti i riferimenti alla versione di Python da un tag nel gitrepository
• Automatizza git tag/ pushe setup.py uploadpassi con un singolo comando che non accetta input.

Come funziona:

1. Da un make releasecomando, l'ultima versione taggata nel repository git viene trovata e incrementata. Il tag viene rinviato a origin.

2. I Makefilenegozi la versione in src/_version.pycui sarà letto da setup.pye comprendeva anche nella release. Non controllare _version.pynel controllo del codice sorgente!

3. setup.pyIl comando legge la nuova stringa di versione da package.__version__.

Dettagli:

Makefile

# remove optional 'v' and trailing hash "v1.0-N-HASH" -> "v1.0-N"
git_describe_ver = $(shell git describe --tags | sed -E -e 's/^v//' -e 's/(.*)-.*/\1/')
git_tag_ver      = $(shell git describe --abbrev=0)
next_patch_ver = $(shell python versionbump.py --patch $(call git_tag_ver))
next_minor_ver = $(shell python versionbump.py --minor $(call git_tag_ver))
next_major_ver = $(shell python versionbump.py --major $(call git_tag_ver))

.PHONY: ${MODULE}/_version.py
${MODULE}/_version.py:
    echo '__version__ = "$(call git_describe_ver)"' > $@

.PHONY: release
release: test lint mypy
    git tag -a $(call next_patch_ver)
    $(MAKE) ${MODULE}/_version.py
    python setup.py check sdist upload # (legacy "upload" method)
    # twine upload dist/*  (preferred method)
    git push origin master --tags

Il releasetarget incrementa sempre la terza cifra della versione, ma è possibile utilizzare next_minor_vero next_major_verper aumentare le altre cifre. I comandi si basano sullo versionbump.pyscript che è registrato nella radice del repository

versionbump.py

"""An auto-increment tool for version strings."""

import sys
import unittest

import click
from click.testing import CliRunner  # type: ignore

__version__ = '0.1'

MIN_DIGITS = 2
MAX_DIGITS = 3


@click.command()
@click.argument('version')
@click.option('--major', 'bump_idx', flag_value=0, help='Increment major number.')
@click.option('--minor', 'bump_idx', flag_value=1, help='Increment minor number.')
@click.option('--patch', 'bump_idx', flag_value=2, default=True, help='Increment patch number.')
def cli(version: str, bump_idx: int) -> None:
    """Bumps a MAJOR.MINOR.PATCH version string at the specified index location or 'patch' digit. An
    optional 'v' prefix is allowed and will be included in the output if found."""
    prefix = version[0] if version[0].isalpha() else ''
    digits = version.lower().lstrip('v').split('.')

    if len(digits) > MAX_DIGITS:
        click.secho('ERROR: Too many digits', fg='red', err=True)
        sys.exit(1)

    digits = (digits + ['0'] * MAX_DIGITS)[:MAX_DIGITS]  # Extend total digits to max.
    digits[bump_idx] = str(int(digits[bump_idx]) + 1)  # Increment the desired digit.

    # Zero rightmost digits after bump position.
    for i in range(bump_idx + 1, MAX_DIGITS):
        digits[i] = '0'
    digits = digits[:max(MIN_DIGITS, bump_idx + 1)]  # Trim rightmost digits.
    click.echo(prefix + '.'.join(digits), nl=False)


if __name__ == '__main__':
    cli()  # pylint: disable=no-value-for-parameter

Questo fa il duro lavoro su come elaborare e incrementare il numero di versione da git.

__init__.py

Il my_module/_version.pyfile viene importato in my_module/__init__.py. Inserire qui qualsiasi configurazione di installazione statica che si desidera distribuire con il modulo.

from ._version import __version__
__author__ = ''
__email__ = ''

setup.py

L'ultimo passo è leggere le informazioni sulla versione dal my_modulemodulo.

from setuptools import setup, find_packages

pkg_vars  = {}

with open("{MODULE}/_version.py") as fp:
    exec(fp.read(), pkg_vars)

setup(
    version=pkg_vars['__version__'],
    ...
    ...
)

Ovviamente, perché tutto ciò funzioni, per iniziare devi avere almeno un tag di versione nel tuo repository.

git tag -a v0.0.1

Uso un file JSON nella directory del pacchetto. Questo si adatta alle esigenze di Zooko.

All'interno pkg_dir/pkg_info.json:

{"version": "0.1.0"}

All'interno setup.py:

from distutils.core import setup
import json

with open('pkg_dir/pkg_info.json') as fp:
    _info = json.load(fp)

setup(
    version=_info['version'],
    ...
    )

All'interno pkg_dir/__init__.py:

import json
from os.path import dirname

with open(dirname(__file__) + '/pkg_info.json') as fp:
    _info = json.load(fp)

__version__ = _info['version']

Ho inserito anche altre informazioni pkg_info.json, come l'autore. Mi piace usare JSON perché posso automatizzare la gestione dei metadati.

Vale anche la pena notare che oltre ad __version__essere un semi-standard. in Python è così __version_info__che è una tupla, nei casi semplici puoi semplicemente fare qualcosa del tipo:

__version__ = '1.2.3'
__version_info__ = tuple([ int(num) for num in __version__.split('.')])

... e puoi ottenere la __version__stringa da un file o qualsiasi altra cosa.

Non sembra esserci un modo standard per incorporare una stringa di versione in un pacchetto python. La maggior parte dei pacchetti che ho visto usano alcune varianti della tua soluzione, vale a dire eitner

1. Incorporare la versione setup.pye setup.pygenerare un modulo (ad es. version.py) Contenente solo le informazioni sulla versione, importate dal pacchetto o

2. L'inverso: mettere le informazioni sulla versione nel pacchetto stesso, e l'importazione che per impostare la versione in setup.py

la freccia lo gestisce in modo interessante.

Ora (dal 2e5031b )

In arrow/__init__.py:

__version__ = 'x.y.z'

In setup.py:

from arrow import __version__

setup(
    name='arrow',
    version=__version__,
    # [...]
)

Prima

Nel arrow/__init__.py:

__version__ = 'x.y.z'
VERSION = __version__

In setup.py:

def grep(attrname):
    pattern = r"{0}\W*=\W*'([^']+)'".format(attrname)
    strval, = re.findall(pattern, file_text)
    return strval

file_text = read(fpath('arrow/__init__.py'))

setup(
    name='arrow',
    version=grep('__version__'),
    # [...]
)

Ho visto anche un altro stile:

>>> django.VERSION
(1, 1, 0, 'final', 0)

Utilizzando setuptoolsepbr

Non esiste un modo standard per gestire la versione, ma il modo standard per gestire i pacchetti è setuptools.

La migliore soluzione che ho trovato nel complesso per la gestione della versione è quella di utilizzare setuptoolsl' pbrestensione. Questo è ora il mio modo standard di gestire la versione.

L'impostazione del progetto per il packaging completo può essere eccessiva per progetti semplici, ma se è necessario gestire la versione, probabilmente si è al livello giusto per impostare tutto. In questo modo, il pacchetto può essere rilasciato su PyPi in modo che tutti possano scaricarlo e utilizzarlo con Pip.

PBR sposta la maggior parte dei metadati dagli setup.pystrumenti e in un setup.cfgfile che viene quindi utilizzato come sorgente per la maggior parte dei metadati, che può includere la versione. Ciò consente ai metadati di essere impacchettati in un eseguibile usando qualcosa come pyinstallerse necessario (in tal caso, probabilmente avrai bisogno di queste informazioni ) e separa i metadati dagli altri script di gestione / installazione del pacchetto. È possibile aggiornare direttamente la stringa di versione setup.cfgmanualmente e verrà estratta nella *.egg-infocartella durante la creazione delle versioni del pacchetto. Gli script possono quindi accedere alla versione dai metadati utilizzando vari metodi (questi processi sono descritti nelle sezioni seguenti).

Quando si utilizza Git per VCS / SCM, questa configurazione è ancora migliore, poiché trarrà molti metadati da Git in modo che il repository possa essere la fonte principale di verità per alcuni dei metadati, tra cui versione, autori, log delle modifiche, ecc. Per la versione specifica, creerà una stringa di versione per il commit corrente in base ai tag git nel repository.

• PyPA - Pacchetto di pacchetti Python con SetupTools - Tutorial
• Ultima documentazione sull'utilizzo della build PBR : come impostare un file a 8 righe setup.pye un setup.cfgfile con i metadati.

Poiché PBR estrarrà la versione, l'autore, il log delle modifiche e altre informazioni direttamente dal tuo repository git, così alcuni dei metadati setup.cfgpossono essere esclusi e generati automaticamente ogni volta che viene creata una distribuzione per il tuo pacchetto (usandosetup.py )

Versione corrente in tempo reale

setuptoolsestrarrà le ultime informazioni in tempo reale utilizzando setup.py:

python setup.py --version

Ciò estrarrà la versione più recente dal setup.cfgfile o dal repository git, in base all'ultimo commit eseguito e ai tag esistenti nel repository. Questo comando però non aggiorna la versione in una distribuzione.

Aggiornamento della versione

Quando si crea una distribuzione con setup.py(ad esempio py setup.py sdist, ad esempio), tutte le informazioni correnti verranno estratte e archiviate nella distribuzione. Questo essenzialmente esegue il setup.py --versioncomando e quindi memorizza le informazioni sulla versione nella package.egg-infocartella in un set di file che memorizzano i metadati di distribuzione.

Nota sul processo di aggiornamento dei metadati della versione:

Se non stai usando pbr per estrarre i dati della versione da git, allora aggiorna il tuo setup.cfg direttamente con le informazioni sulla nuova versione (abbastanza facile, ma assicurati che questa sia una parte standard del tuo processo di rilascio).

Se stai usando git e non hai bisogno di creare una distribuzione sorgente o binaria (usando python setup.py sdisto uno dei python setup.py bdist_xxxcomandi) il modo più semplice per aggiornare le informazioni di repository git nella <mypackage>.egg-infocartella dei metadati è semplicemente eseguire il python setup.py installcomando. Questo eseguirà tutte le funzioni PBR relative all'estrazione dei metadati dal repository git e aggiornerà la .egg-infocartella locale , installerà gli eseguibili di script per tutti i punti di ingresso che hai definito e altre funzioni che puoi vedere dall'output quando esegui questo comando.

Si noti che la .egg-infocartella è generalmente esclusa dall'archiviazione nel repository git stesso nei .gitignorefile Python standard (come da Gitignore.IO ), poiché può essere generata dal proprio sorgente. Se viene escluso, assicurarsi di disporre di un "processo di rilascio" standard per ottenere i metadati aggiornati localmente prima del rilascio e che tutti i pacchetti caricati su PyPi.org o altrimenti distribuiti devono includere questi dati per avere la versione corretta. Se vuoi che il repository Git contenga queste informazioni, puoi escludere file specifici dall'ignorare (cioè aggiungere !*.egg-info/PKG_INFOa .gitignore)

Accesso alla versione da uno script

Puoi accedere ai metadati dalla build corrente all'interno degli script Python nel pacchetto stesso. Per la versione, ad esempio, ci sono diversi modi per farlo che ho trovato finora:

## This one is a new built-in as of Python 3.8.0 should become the standard
from importlib-metadata import version

v0 = version("mypackage")
print('v0 {}'.format(v0))

## I don't like this one because the version method is hidden
import pkg_resources  # part of setuptools

v1 = pkg_resources.require("mypackage")[0].version
print('v1 {}'.format(v1))

# Probably best for pre v3.8.0 - the output without .version is just a longer string with
# both the package name, a space, and the version string
import pkg_resources  # part of setuptools

v2 = pkg_resources.get_distribution('mypackage').version
print('v2 {}'.format(v2))

## This one seems to be slower, and with pyinstaller makes the exe a lot bigger
from pbr.version import VersionInfo

v3 = VersionInfo('mypackage').release_string()
print('v3 {}'.format(v3))

Puoi inserire uno di questi direttamente nel tuo __init__.pypacchetto per estrarre le informazioni sulla versione come segue, in modo simile ad altre risposte:

__all__ = (
    '__version__',
    'my_package_name'
)

import pkg_resources  # part of setuptools

__version__ = pkg_resources.get_distribution("mypackage").version

Dopo diverse ore di ricerca della soluzione più semplice e affidabile, ecco le parti:

crea un file version.py ALL'INTERNO della cartella del tuo pacchetto "/ mypackage":

# Store the version here so:
# 1) we don't load dependencies by storing it in __init__.py
# 2) we can import it in setup.py for the same reason
# 3) we can import it into your module module
__version__ = '1.2.7'

in setup.py:

exec(open('mypackage/version.py').read())
setup(
    name='mypackage',
    version=__version__,

nella cartella principale init .py:

from .version import __version__

La exec()funzione esegue lo script al di fuori di qualsiasi importazione, poiché setup.py viene eseguito prima che il modulo possa essere importato. Devi solo gestire il numero di versione in un file in un unico posto, ma sfortunatamente non è in setup.py. (questo è il rovescio della medaglia, ma non avere bug di importazione è il lato positivo)

Molto lavoro verso il controllo uniforme delle versioni e a supporto delle convenzioni è stato completato da quando questa domanda è stata posta per la prima volta . Le opzioni appetibili sono ora dettagliate nella Guida per l'utente di Python Packaging . È anche degno di nota il fatto che gli schemi dei numeri di versione sono relativamente rigidi in Python per PEP 440 , e quindi mantenere le cose sane è fondamentale se il tuo pacchetto verrà rilasciato al Cheese Shop .

Ecco una suddivisione abbreviata delle opzioni di versioning:

1. Leggi il file in setup.py( setuptools ) e ottieni la versione.
2. Utilizzare uno strumento di generazione esterno (per aggiornare sia __init__.pyil controllo del codice sorgente), ad esempio bump2version , modifiche o zest.releaser .
3. Imposta il valore su una __version__variabile globale in un modulo specifico.
4. Inserire il valore in un semplice file di testo VERSION affinché sia ​​setup.py sia il codice da leggere.
5. Imposta il valore tramite una setup.pyversione e usa importlib.metadata per raccoglierlo in fase di esecuzione. (Attenzione, ci sono versioni pre-3.8 e post-3.8.)
6. Impostare il valore su __version__in sample/__init__.pye importare sample in setup.py.
7. Usa setuptools_scm per estrarre il controllo delle versioni dal controllo del codice sorgente in modo che sia il riferimento canonico, non il codice.

NOTA (7) potrebbe essere l' approccio più moderno (build metadata è indipendente dal codice, pubblicato dall'automazione). Si noti inoltre che se l'installazione viene utilizzata per il rilascio del pacchetto, un semplice python3 setup.py --versionriporterà direttamente la versione.

Per quello che vale, se stai usando NumPy distutils, numpy.distutils.misc_util.Configurationha un make_svn_version_py()metodo che incorpora il numero di revisione all'interno package.__svn_version__della variabile version.

1. Utilizzare un version.pyfile solo con __version__ = <VERSION>param nel file. Nel setup.pyfile importa il __version__parametro e inserisci il suo valore nel setup.pyfile in questo modo: version=__version__
2. Un altro modo è usare solo un setup.pyfile con version=<CURRENT_VERSION>- CURRENT_VERSION è hardcoded.

Dal momento che non vogliamo cambiare manualmente la versione nel file ogni volta che creiamo un nuovo tag (pronto a rilasciare una nuova versione del pacchetto), possiamo usare quanto segue ..

Consiglio vivamente il pacchetto bumpversion . Lo uso da anni per presentare una versione.

inizia aggiungendo version=<VERSION>al tuo setup.pyfile se non lo hai già.

Dovresti usare uno script breve come questo ogni volta che esegui il bump di una versione:

bumpversion (patch|minor|major) - choose only one option
git push
git push --tags

Quindi aggiungere un file per repository chiamato .bumpversion.cfg::

[bumpversion]
current_version = <CURRENT_TAG>
commit = True
tag = True
tag_name = {new_version}
[bumpversion:file:<RELATIVE_PATH_TO_SETUP_FILE>]

Nota:

• È possibile utilizzare il __version__parametro nel version.pyfile come è stato suggerito in altri post e aggiornare il file bumpversion in questo modo: [bumpversion:file:<RELATIVE_PATH_TO_VERSION_FILE>]
• È necessario git commit o git resettutto il resto del repository, altrimenti si otterrà un errore repository sporco.
• Assicurati che il tuo ambiente virtuale includa il pacchetto di bumpversion, senza di esso non funzionerà.

Se usi CVS (o RCS) e desideri una soluzione rapida, puoi utilizzare:

__version__ = "$Revision: 1.1 $"[11:-2]
__version_info__ = tuple([int(s) for s in __version__.split(".")])

(Naturalmente, il numero di revisione verrà sostituito per te da CVS.)

Questo ti dà una versione stampabile e informazioni sulla versione che puoi usare per verificare che il modulo che stai importando abbia almeno la versione prevista:

import my_module
assert my_module.__version_info__ >= (1, 1)