Trasformare un progetto Python personale in una libreria rilasciabile

Sono un accademico piuttosto che un programmatore e ho molti anni di esperienza nella scrittura di programmi Python per uso personale, a supporto della mia ricerca. Il mio ultimo progetto sarà probabilmente utile a molti altri come me, e sto pensando di pubblicarlo come una libreria Python open source.

Tuttavia, sembrano esserci alcuni ostacoli da attraversare nel passaggio da un progetto personale funzionante a una libreria che può essere installata e utilizzata indolore da altri. Questa domanda riguarda i primi passi che dovrei prendere per iniziare a lavorare verso una versione pubblica.

Al momento, ho un unico repository git che contiene il mio codice che utilizza la libreria e la libreria stessa e utilizzo git come pulsante di annullamento di emergenza in caso di problemi. Tutto questo funziona bene per un singolo utente ma ovviamente non è appropriato se voglio rilasciarlo. Dove voglio finire è che la mia libreria è in un repository separato e può essere installata da altri utenti pipe ha un'API stabile.

Imparare a usare setuptools ecc. Non è probabilmente così difficile una volta che sono sul punto di volerlo pubblicare - il mio problema è sapere come dovrei lavorare per arrivare a quel punto.

Quindi la mia domanda è: quali sono i primi passi da fare per iniziare a preparare un progetto di libreria Python per il consumo pubblico? Come devo riorganizzare la mia struttura di directory, il mio repository git ecc. Per iniziare a lavorare verso un rilascio pubblico della libreria?

Più in generale, sarebbe molto utile se ci sono risorse che sono note per essere utili quando si tenta di farlo per la prima volta. Sarebbe anche molto utile dare indicazioni su buone pratiche ed errori da evitare, ecc.

Alcuni chiarimenti: le risposte attuali stanno rispondendo a una domanda sulla falsariga di "come posso rendere la mia libreria Python buona da usare per gli altri?" Questo è utile, ma è diverso dalla domanda che intendevo porre.

Sono attualmente all'inizio di un lungo viaggio verso il rilascio del mio progetto. Il nucleo della mia implementazione funziona (e funziona davvero bene), ma mi sento sopraffatto dalla quantità di lavoro che mi attende e sto cercando una guida su come navigare nel processo. Per esempio:

• Il mio codice libreria è attualmente accoppiato al mio codice specifico del dominio che lo utilizza. Vive in una sottocartella e condivide lo stesso repository git. Alla fine, dovrà essere trasformato in una libreria autonoma e messo nel suo repository, ma continuo a procrastinare questo perché non so come farlo. (Né come installare una libreria in "modalità di sviluppo" in modo che io possa ancora modificarla, né come mantenere sincronizzati i due repository git.)

• Le mie dotstring sono concise, perché so che alla fine dovrò usare Sphinx o qualche altro strumento. Ma questi strumenti sembrano non essere semplici da imparare, quindi questo diventa un grande sottoprogetto e continuo a rimandare.

• Ad un certo punto devo imparare a usare setuptools o qualche altro strumento per impacchettarlo e tenere traccia delle dipendenze, che sono piuttosto complesse. Non sono sicuro se devo farlo ora o no, e la documentazione è un labirinto assoluto per un nuovo utente, quindi continuo a decidere di farlo in seguito.

• Non ho mai dovuto fare test sistematici, ma lo farò sicuramente per questo progetto, quindi devo (i) imparare abbastanza sui test per sapere quale metodologia è giusta per il mio progetto; (ii) apprendere quali strumenti sono disponibili per la mia metodologia scelta; (iii) imparare a usare il mio strumento scelto; (iv) implementare test suite ecc. per il mio progetto. Questo è un progetto in sé.

• Potrebbero esserci anche altre cose che devo fare. Ad esempio, jonrsharpe ha pubblicato un link utile che menziona git-flow, tox, TravisCI, virtualenv e CookieCutter, nessuno dei quali avevo mai sentito parlare prima. (Il post è del 2013, quindi devo anche fare un po 'di lavoro per scoprire quanto è ancora attuale.)

Quando metti tutto insieme è una grande mole di lavoro, ma sono sicuro di riuscire a fare tutto se continuo a collegarlo, e non ho fretta. Il mio problema è sapere come suddividerlo in passaggi gestibili che possono essere eseguiti uno alla volta.

In altre parole, sto chiedendo quali sono i passi concreti più importanti che posso prendere ora, al fine di raggiungere un prodotto rilasciabile alla fine. Se ho un weekend libero, su quali di queste cose dovrei concentrarmi? Quale (se presente) può essere fatto in modo isolato dagli altri, in modo che io possa almeno fare un passo senza dover fare tutto? Qual è il modo più efficace per imparare queste cose in modo che avrò ancora il tempo di concentrarmi sul progetto stesso? (Tenendo presente che tutto ciò è essenzialmente un progetto di hobby, non il mio lavoro.) Esiste qualcosa che non ho davvero bisogno di fare , risparmiando così una grande quantità di tempo e fatica?

Tutte le risposte sono molto apprezzate, ma gradirei in particolare le risposte incentrate su questi aspetti della gestione dei progetti, con specifico riferimento allo sviluppo moderno di Python.

L'aggiunta di setup.py, se necessario, non è il passaggio più importante se si desidera utilizzare la libreria. Ancora più importante è aggiungere documentazione e pubblicizzare la tua biblioteca. Dato che il secondo punto dipende fortemente dalla biblioteca, vorrei piuttosto concentrarmi sull'aspetto della documentazione.

1. Sai tutto sulla tua biblioteca. E questo è problematico. Sai già come installare e come usarlo, quindi molte cose possono sembrare intuitive o chiaramente ovvie per te. Sfortunatamente, le stesse cose potrebbero non essere né ovvie, né intuitive per gli utenti. Cerca di guardare la tua biblioteca come se non ne sapessi nulla e, cosa più importante, chiedi ad altre persone di usarla e cerca di individuare tutte le difficoltà che hanno avuto.

2. Spiega, in parole povere, di cosa tratta la tua biblioteca. Troppe biblioteche presumono che tutti ne siano a conoscenza. In caso contrario, potrebbe essere difficile capire qual è lo scopo della libreria.

3. Scrivi una documentazione tecnica dettagliata, ma non dimenticare anche brevi parti di codice che mostrano come eseguire alcune attività con la tua libreria. La maggior parte degli sviluppatori ha fretta e se hanno bisogno di passare ore a cercare di capire come fare una cosa di base, possono tendere a passare ad altre librerie.

4. Includi le tue informazioni di contatto. Se la tua biblioteca ha successo (e la mia esperienza ha dimostrato che questo è il caso anche per quelli piuttosto sconosciuti), le persone incontrerebbero difficoltà con esso: o bug o semplicemente difficoltà a comprenderne o utilizzarne alcune parti. Spesso è utile ricevere il loro feedback per migliorare la tua biblioteca: per ogni persona che ha segnalato un problema, ci sono forse centinaia che, quando lo incontrano, preferiscono semplicemente passare a un'altra biblioteca.

Oltre a ciò:

1. Rendi chiaro se la tua libreria funziona con Python 2 o 3 o entrambi.

2. Se la libreria non funziona su Windows, dillo.

3. Assicurati di usare le convenzioni ufficiali (usa pep8 per verificare). In caso contrario, spiegalo chiaramente o correggilo.

4. Abbi cura di maneggiare i casi limite. Quando la tua libreria viene chiamata con un tipo sbagliato o con un valore che non è supportato, dovrebbe dire, in parole povere, che cosa è esattamente sbagliato. Ciò che non dovrebbe fare è aumentare un'eccezione criptica di dieci livelli in basso nello stack e lasciare che l'utente capisca cosa è andato storto.

Avendo usato poche librerie meno che mature nel corso degli anni, una volta che hai scelto il tuo strumento di distribuzione, un consiglio chiave è fare quanto segue: La tua biblioteca fa qualcosa di veramente utile su cui costruire una comunità?

Identifica le dipendenze della tua biblioteca.

Tentare una distribuzione in un ambiente pulito o un contenitore socket o VM. Considero questo passaggio cruciale perché spesso c'è qualcosa di unico in un ambiente personale che causa problemi.

Considera chi gestirà la biblioteca in futuro, non c'è niente di più frustrante che imbattersi in una biblioteca che è stata il progetto di animali domestici di qualcuno per tre o quattro anni e quindi non ottiene gli aggiornamenti necessari per tenerlo aggiornato.

Considera se tu o il tuo team volete impegnarvi a mantenere la libreria testata e documentata (i test unitari e le pipeline CI iniziano a far parte dell'equazione).

Forse potresti trovare un progetto OSS maturo nel tuo campo e contribuire con il tuo codice a quel progetto? Potrebbero esserci alcuni vantaggi, come:

• Puoi massimizzare il tuo contributo. In effetti, molti progetti OSS "hobby" sono potenzialmente preziosi ma usati poco dalla comunità (cfr. @ReaddyEddy risposta). È solo uno sforzo enorme per rendere il progetto da zero inizialmente, quindi per mantenerlo, pubblicizzarlo, fornire esempi e documentazione adeguati, ecc.
• Molte delle questioni tecniche che hai citato sarebbero già state risolte nel progetto maturo.
• Se la tua biblioteca aggiunge valore al progetto OSS, i suoi collaboratori potrebbero aiutarti ad adeguare il tuo codice agli standard del progetto. Quindi puoi risparmiare sforzo e acquisire esperienza. Riceverai anche risposte specifiche su Sphinx, TravisCI, CookieCutter e altri aspetti tecnici.

Se esiste un progetto OSS pertinente che ti piace e che forse usi, perché non aprire un problema o una richiesta pull o contattare i manutentori? (Un buon modo per iniziare potrebbe essere quello di risolvere un problema esistente.)

È il 2019, consiglio vivamente di iniziare con gli strumenti più moderni. Non hai bisogno di un setup.py, è qualcosa che le persone nella comunità di Python vogliono liberarsi, e credo che alla fine lo faranno.

Prova la poesia , non te ne pentirai.

Questa è una domanda complicata che stai ponendo e concordo pienamente sulla risposta di Arseni . Una buona documentazione è un aspetto molto importante. Se non riesco a far funzionare la tua libreria con pochi semplici passaggi, la sto semplicemente abbandonando lì (a meno che non sia davvero ansiosa di provarla).

Alcune cose che consideri sicuramente

• Pensa a come stai andando a versione la tua libreria. Volete avere retrocompatibilità ad un certo livello e correzioni di bug anche lungo il percorso. Leggi le versioni semantiche
• Stai usando git in un modo relativamente lineare (per annullare). Hai familiarità con la ramificazione in git . Non è poi così difficile e rende la vita facile. Una volta che hai preso le prese con i rami. Adatta un modello di diramazione per il tuo repository. Scegli le parti di questo modello di diramazione che ritieni rilevanti. Confrontalo anche con i rami dei repository che stai utilizzando.
• Licenze: è necessario fornire una licenza per la propria biblioteca. Non sono un esperto legale in materia, quindi posso solo condividere un link a questo confronto tra licenze comuni . Non prendere questa scelta alla leggera.
• Bugtracker. Desideri che l'utente possa fornirti segnalazioni di bug. Questo ti aiuta a migliorare la qualità del codice. Per ogni bug che risolvi, aggiungi un test al lavoro del frame di test, che assicuri che non si blocchi in futuro (test di regressione). Un sistema di tracciamento dei bug può essere utilizzato per le richieste di funzionalità.
• Contributi dell'utente. Vuoi i contributi degli utenti? Non sono sicuro di come funzioni in genere sui prodotti open source, ma posso immaginare che puoi consentire agli utenti di creare rami di funzionalità. Tramite github sembra che tu possa controllarlo tramite richieste pull

Non ho alcuna esperienza rilevante con Python, quindi non posso darti alcun suggerimento in quella direzione. Tuttavia, è possibile automatizzare tutti i test attivati ​​da ciascun commit sul repository remoto (ovvero utilizzando Jenkins ). Tuttavia, suggerisco di rimandare questo, perché è un sacco di lavoro da configurare senza esperienza precedente.

Queste sono grandi domande.

Informazioni su importanti passi incrementali concreti verso una libreria rilasciabile:

• Separare i file che diventeranno la libreria dal resto del progetto.
  • La libreria dovrebbe andare nel proprio repository git ma potresti trovarlo un utile passaggio intermedio per inserirlo in una directory di livello superiore separata all'interno del tuo repository corrente. Quando lo rendi un repository separato, archivia quello adiacente al resto del tuo progetto, che può quindi fare riferimento ad esso tramite ../libraryfino a quando non passi alle fasi del packaging e della modalità di sviluppo del pip.
  • Tutti gli accessi dal resto del progetto a questa libreria dovrebbero passare attraverso la sua API pubblica. Potresti trovare alcune interdipendenze da prendere in giro.
• Scrivere in modo incrementale docstring per documentare l'API della libreria.
  • Alla fine i documenti verranno inseriti in uno strumento di documentazione, ma l'importante lavoro è scrivere il testo che spieghi l'API in modo conciso e sufficiente ad altre persone. È più facile compilarlo un po 'alla volta che tutti in una volta, e ne uscirà molto meglio scrivendo bozze approssimative e tornando più tardi quando mi vengono in mente spiegazioni ed esempi migliori.
  • Se ritieni che una parte dell'API sia difficile da documentare, chiedi se quella parte dell'API ha margini di miglioramento. Potrebbe essere più semplice? Più regolare? È troppo generale? Troppo specializzato? Potrebbe usare nomi più familiari?
  • Le docstring possono documentare i tipi di argomenti usando commenti strutturati che gli strumenti possono controllare. Devo ancora trovare una vera documentazione su questo, ma l'IDE di PyCharm aiuterà a costruire quei documenti e controllerà immediatamente i tipi di argomenti durante la modifica delle chiamate al metodo.
  • A proposito, PyCharm è uno strumento meraviglioso per risparmiare tempo per gli sviluppatori e migliorare la qualità del codice. Eseguirà "ispezioni" per controllare il codice mentre lo modifichi, ad esempio controllando i tipi quando è possibile, controllando le importazioni mancanti e inutilizzate, i metodi duplicati, gli errori di stile PEP 8 e così via.
• Inizia a scrivere unit test usando pytest. Molto prima di rilasciare una versione, i test unitari ripagheranno nel tuo sviluppo trovando bug in casi angolari e assicurando che le modifiche al codice non hanno rotto le cose. Ancora una volta, puoi costruirlo nel tempo. È abbastanza facile iniziare.
• Sfoglia le librerie open source esistenti (che hanno all'incirca le stesse dimensioni) su GitHub per vedere come organizzano i file e le versioni. Guarda come eseguono il tracciamento dei bug / problemi e le richieste pull. Contribuisci a uno o più di essi per fare esperienza con questi processi di organizzazione di progetti multi-persona se non hai esperienza lì. GitHub ha buoni strumenti per questi processi. Fa cose carine con i README.mdfile di documentazione al livello superiore e in qualsiasi directory e con un file di licenza.
• Prendi in considerazione la possibilità di arruolare un collaboratore per ottenere feedback sulla libreria, sull'API e sulla documentazione.
  • Quando rilasci, sarà utile avere uno o più collaboratori per correggere i bug quando sei in vacanza, aiutare a rispondere alle domande degli utenti e nel frattempo iniziare a fare richieste pull con revisioni del codice, per dividere le attività di rilascio della libreria, e portare ulteriore esperienza con la gestione del progetto e la progettazione della biblioteca.
• Finora hai fatto una cronologia di commit git lineare. Alla fine sarà utile utilizzare "branch di problemi" per correzioni e modifiche specifiche, "branch di rilascio" per il run-up controllato di una release e "branch di sviluppo" per qualsiasi lavoro multiplo in corso che non sia pronto per unire nel ramo principale. Quindi metti da parte un paio di giorni lungo la strada per imparare questo e iniziare a fare pratica con esso prima di dover fare affidamento su quelle abilità git. git è molto flessibile e utile, ma l'interfaccia utente può diventare irta .
  • Un posto dove leggere sui rami di Git e sui loro usi è nel libro Pro Git . Dei molti modi per utilizzare i rami, inizia solo con "pubblica i rami".
  • L'app desktop GitHub è un ottimo strumento per gestire le filiali. È anche ottimo per eseguire commit poiché semplifica la scrittura del messaggio di commit durante la revisione di tutte le modifiche.