Verwandeln eines persönlichen Python-Projekts in eine freigebbare Bibliothek

Ich bin eher ein Akademiker als ein Programmierer, und ich habe viele Jahre Erfahrung darin, Python-Programme für meinen eigenen Gebrauch zu schreiben, um meine Forschung zu unterstützen. Mein neuestes Projekt wird wahrscheinlich auch vielen anderen nützlich sein und ich denke darüber nach, es als Open-Source-Python-Bibliothek herauszubringen.

Es scheint jedoch einige Hürden zu geben, von einem funktionierenden persönlichen Projekt zu einer Bibliothek überzugehen, die von anderen problemlos installiert und verwendet werden kann. Diese Frage handelt von den ersten Schritten, die ich unternehmen sollte, um auf eine Veröffentlichung hinzuarbeiten.

Derzeit habe ich ein einzelnes Git-Repository, das meinen Code enthält, der die Bibliothek sowie die Bibliothek selbst verwendet, und ich verwende Git als Notfall-Rückgängig-Schaltfläche, falls etwas kaputt geht. All dies funktioniert gut für einen einzelnen Benutzer, ist aber offensichtlich nicht angebracht, wenn ich es freigeben möchte. Am Ende möchte ich wissen, dass sich meine Bibliothek in einem separaten Repository befindet, von anderen mithilfe von installiert werden pipkann und über eine stabile API verfügt.

Das Erlernen der Verwendung von Setuptools usw. ist wahrscheinlich nicht so schwierig, wenn ich es erst einmal veröffentlichen möchte. Mein Problem besteht darin, zu wissen, wie ich arbeiten soll, um an diesen Punkt zu gelangen.

Meine Frage ist also, welche ersten Schritte sollten Sie unternehmen, um ein Python-Bibliotheksprojekt für den öffentlichen Konsum vorzubereiten? Wie sollte ich meine Verzeichnisstruktur, mein Git-Repository usw. neu organisieren, um auf eine Veröffentlichung der Bibliothek hinzuarbeiten?

Generell wäre es sehr hilfreich, wenn es Ressourcen gibt, von denen bekannt ist, dass sie hilfreich sind, wenn Sie dies zum ersten Mal versuchen. Hinweise auf bewährte Verfahren und zu vermeidende Fehler usw. wären ebenfalls sehr hilfreich.

Einige Erläuterungen: Die aktuellen Antworten beziehen sich auf eine Frage wie "Wie kann ich meine Python-Bibliothek für andere gut machen?" Dies ist nützlich, unterscheidet sich aber von der Frage, die ich stellen wollte.

Ich bin gerade am Anfang einer langen Reise in Richtung Veröffentlichung meines Projekts. Der Kern meiner Implementierung funktioniert (und funktioniert wirklich gut), aber ich fühle mich von der Menge an Arbeit, die vor mir liegt, überwältigt und suche nach Anleitungen zur Steuerung des Prozesses. Beispielsweise:

• Mein Bibliothekscode ist derzeit an meinen eigenen domänenspezifischen Code gekoppelt, der ihn verwendet. Es befindet sich in einem Unterordner und hat dasselbe Git-Repository. Irgendwann muss es zu einer eigenständigen Bibliothek gemacht und in ein eigenes Repository gestellt werden, aber ich zögere das immer wieder, weil ich nicht weiß, wie es geht. (Weder wie man eine Bibliothek im 'Entwicklungsmodus' installiert, damit ich sie noch bearbeiten kann, noch wie man die beiden Git-Repos synchron hält.)

• Meine Dokumente sind knapp, weil ich weiß, dass ich irgendwann Sphinx oder ein anderes Tool verwenden muss. Aber diese Werkzeuge scheinen nicht einfach zu erlernen zu sein, so dass dies ein wichtiges Unterprojekt wird und ich es immer wieder aufschiebe.

• Irgendwann muss ich lernen, setuptools oder ein anderes Tool zu verwenden, um es zu packen und die Abhängigkeiten zu verfolgen, die recht komplex sind. Ich bin mir nicht sicher, ob ich das jetzt tun muss oder nicht, und die Dokumentation ist ein absolutes Labyrinth für einen neuen Benutzer, deshalb entscheide ich mich weiterhin dafür, es später zu tun.

• Ich musste noch nie systematisch testen, werde es aber definitiv für dieses Projekt tun. Daher muss ich (i) genug über das Testen lernen, um zu wissen, welche Methodik für mein Projekt geeignet ist. (ii) zu erfahren, welche Tools für die von mir gewählte Methodik zur Verfügung stehen; (iii) lernen, mein gewähltes Werkzeug zu benutzen; (iv) Implementieren von Testsuiten usw. für mein Projekt. Dies ist ein Projekt für sich.

• Es kann auch andere Dinge geben, die ich tun muss. Zum Beispiel hat jonrsharpe einen hilfreichen Link gepostet , der auf git-flow, tox, TravisCI, virtualenv und CookieCutter verweist, von denen ich vorher noch nichts gehört hatte. (Der Beitrag stammt aus dem Jahr 2013, daher muss ich noch einige Arbeiten durchführen, um herauszufinden, wie viel noch aktuell ist.)

Wenn Sie das alles zusammenstellen, ist das eine enorme Menge an Arbeit, aber ich bin sicher, dass ich alles erledigen kann, wenn ich weiter dranbleibe, und ich habe es nicht eilig. Mein Problem ist, zu wissen, wie man es in handhabbare Schritte zerlegt, die einzeln ausgeführt werden können.

Mit anderen Worten, ich frage nach den wichtigsten konkreten Schritten, die ich jetzt unternehmen kann, um schließlich zu einem ablösbaren Produkt zu gelangen. Auf welche dieser Dinge sollte ich mich konzentrieren, wenn ich ein freies Wochenende habe? Was kann (wenn überhaupt) isoliert von den anderen gemacht werden, so dass ich wenigstens einen Schritt machen kann, ohne das Ganze machen zu müssen? Was ist der effizienteste Weg, um diese Dinge zu lernen, sodass ich noch Zeit habe, mich auf das Projekt selbst zu konzentrieren? (In Anbetracht dessen, dass all dies im Wesentlichen ein Hobbyprojekt ist, nicht mein Job.) Gibt es etwas, das ich eigentlich nicht tun muss , wodurch ich mir viel Zeit und Mühe erspare?

Alle Antworten werden sehr geschätzt, aber ich würde mich besonders über Antworten freuen, die sich auf diese Projektmanagementaspekte konzentrieren, unter besonderer Berücksichtigung der modernen Python-Entwicklung.

Das Hinzufügen einer setup.py ist zwar erforderlich, aber nicht der wichtigste Schritt, wenn Sie möchten, dass Ihre Bibliothek verwendet wird. Noch wichtiger ist es, Dokumentation hinzuzufügen und Werbung für Ihre Bibliothek zu machen. Da der zweite Punkt stark von der Bibliothek abhängt, möchte ich mich eher auf den Dokumentationsaspekt konzentrieren.

1. Sie wissen alles über Ihre Bibliothek. Und das ist problematisch. Sie wissen bereits, wie Sie es installieren und verwenden, sodass Ihnen viele Dinge intuitiv oder offensichtlich erscheinen. Leider können die gleichen Dinge weder offensichtlich noch für die Benutzer intuitiv sein. Schauen Sie sich Ihre Bibliothek an, als wüssten Sie nichts darüber, und, was noch wichtiger ist, bitten Sie andere, sie zu benutzen, und versuchen Sie, alle Schwierigkeiten zu erkennen, die sie hatten.

2. Erklären Sie im Klartext, worum es in Ihrer Bibliothek geht. Zu viele Bibliotheken gehen davon aus, dass jeder etwas über sie weiß. Wenn dies nicht der Fall ist, kann es schwierig sein, den Zweck der Bibliothek zu erfassen.

3. Verfassen Sie detaillierte technische Dokumentationen, aber vergessen Sie auch nicht die kurzen Codeteile, die zeigen, wie Sie einige der Aufgaben mit Ihrer Bibliothek erledigen. Die meisten Entwickler haben es eilig und wenn sie Stunden damit verbringen müssen, zu verstehen, wie eine grundlegende Sache zu tun ist, tendieren sie möglicherweise dazu, zu anderen Bibliotheken zu wechseln.

4. Geben Sie Ihre Kontaktinformationen an. Wenn Ihre Bibliothek ein Erfolg ist (und meine eigenen Erfahrungen haben gezeigt, dass dies auch bei eher unbekannten Bibliotheken der Fall ist), stoßen die Leute auf Schwierigkeiten: entweder auf Fehler oder einfach auf Schwierigkeiten, Teile davon zu verstehen oder zu verwenden. Es ist oft nützlich, Feedback zu erhalten, um Ihre Bibliothek zu verbessern: Für jede Person, die ein Problem gemeldet hat, gibt es möglicherweise Hunderte, die es einfach vorziehen, zu einer anderen Bibliothek zu wechseln, wenn sie auf dieses Problem stößt.

Zusätzlich dazu:

1. Stellen Sie klar, ob Ihre Bibliothek mit Python 2 oder 3 oder beiden kompatibel ist.

2. Wenn die Bibliothek unter Windows nicht funktioniert, sagen Sie es.

3. Stellen Sie sicher, dass Sie offizielle Konventionen verwenden (verwenden Sie pep8, um dies zu überprüfen). Wenn nicht, erklären Sie es klar oder beheben Sie es.

4. Achten Sie auf die Handhabung von Edge Cases. Wenn Ihre Bibliothek mit einem falschen Typ oder mit einem Wert aufgerufen wird, der nicht unterstützt wird, sollte im Klartext angegeben werden, was genau falsch ist. Was es nicht tun sollte, ist eine kryptische Ausnahme zehn Ebenen weiter unten im Stapel auszulösen und den Benutzer herausfinden zu lassen, was schief gelaufen ist.

Nachdem Sie im Laufe der Jahre ein paar weniger als ausgereifte Bibliotheken verwendet haben, ist es ein wichtiger Ratschlag, wenn Sie Ihr Bereitstellungstool ausgewählt haben, Folgendes zu tun: Tut Ihre Bibliothek etwas wirklich Nützliches, um das Sie eine Community aufbauen können?

Identifizieren Sie die Abhängigkeiten Ihrer Bibliothek.

Versuchen Sie eine Bereitstellung in einer sauberen Umgebung, entweder in einem Docket-Container oder einer virtuellen Maschine. Ich halte diesen Schritt für entscheidend, da ein persönliches Umfeld, das Probleme verursacht, häufig etwas Einzigartiges aufweist.

Überlegen Sie, wer die Bibliothek in Zukunft unterhalten wird, es gibt nichts Frustrierenderes, als auf eine Bibliothek zu stoßen, die drei oder vier Jahre lang das Lieblingsprojekt einer anderen Person war und dann nicht die Aktualisierungen erhält, die erforderlich sind, um sie auf dem neuesten Stand zu halten.

Überlegen Sie sich, ob Sie oder Ihr Team die Verpflichtung eingehen möchten, die Bibliothek zu testen und zu dokumentieren (Unit-Tests und CI-Pipelines werden Teil der Gleichung).

Vielleicht könnten Sie ein ausgereiftes OSS-Projekt in Ihrem Bereich finden und Ihren Code zu diesem Projekt beitragen? Es könnte einige Vorteile geben, wie zum Beispiel:

• Sie können Ihren Beitrag maximieren. In der Tat sind viele "Hobby" -OSS-Projekte potenziell wertvoll, werden jedoch von der Community nur wenig genutzt (siehe @ReaddyEddy-Antwort). Es ist nur ein großer Aufwand, das Projekt zunächst auf den neuesten Stand zu bringen, es dann zu warten, zu bewerben, geeignete Beispiele und Dokumentationen bereitzustellen usw.
• Viele der von Ihnen erwähnten technischen Probleme würden bereits im ausgereiften Projekt gelöst.
• Wenn Ihre Bibliothek dem OSS-Projekt einen Mehrwert verleiht, können Ihnen die Mitwirkenden dabei helfen, Ihren Code an die Projektstandards anzupassen. So können Sie Aufwand sparen und Erfahrungen sammeln. Sie erhalten auch spezifische Antworten zu Sphinx, TravisCI, CookieCutter und anderen technischen Aspekten.

Wenn es ein relevantes OSS-Projekt gibt, das Sie mögen und vielleicht verwenden, warum nicht ein Problem oder eine Pull-Anfrage eröffnen oder sich auf andere Weise mit den Betreuern in Verbindung setzen? (Ein guter Anfang kann darin bestehen, ein vorhandenes Problem zu lösen.)

Es ist 2019, ich empfehle dringend, mit den modernsten Werkzeugen zu beginnen. Sie brauchen keine setup.py, das ist etwas, was die Leute in der Python-Community loswerden wollen, und ich glaube, dass sie es irgendwann tun werden.

Probieren Sie Poesie , Sie werden es nicht bereuen.

Dies ist eine komplizierte Frage, die Sie stellen, und ich stimme der Antwort von Arseni voll und ganz zu . Gute Dokumentation ist ein sehr wichtiger Aspekt. Wenn es mir nicht gelingt, Ihre Bibliothek mit ein paar einfachen Schritten zum Laufen zu bringen, lasse ich sie einfach dort fallen (es sei denn, ich bin wirklich darauf bedacht, es zu versuchen).

Einige Dinge, die Sie auf jeden Fall berücksichtigen

• Überlegen Sie, wie Sie Ihre Bibliothek versionieren möchten. Sie möchten Abwärtskompatibilität bis zu einem gewissen Grad und Bugfixes entlang der Route haben. Lesen Sie mehr über die semantische Versionierung
• Sie verwenden Git relativ linear (um es rückgängig zu machen). Sind Sie vertraut mit in git Verzweigung . Es ist wirklich nicht so schwierig und erleichtert das Leben. Sobald du dich mit Ästen beschäftigt hast. Passen Sie ein Verzweigungsmodell für Ihr Repository an. Wählen Sie die Teile dieses Verzweigungsmodells aus , die Sie für relevant halten. Vergleichen Sie dies auch mit Zweigen aus Repositorys, die Sie verwenden.
• Lizenzierung: Sie sollten eine Lizenz für Ihre Bibliothek bereitstellen. Ich bin in dieser Angelegenheit kein Rechtsexperte, daher kann ich nur einen Link zu diesem Vergleich zwischen gemeinsamen Lizenzen teilen . Treffen Sie diese Wahl nicht leichtfertig.
• Bugtracker. Sie möchten, dass der Benutzer Ihnen Fehlerberichte zur Verfügung stellt. Auf diese Weise können Sie die Qualität des Codes verbessern. Fügen Sie für jeden Fehler, den Sie beheben, einen Test zu Ihrem Testrahmen hinzu, der sicherstellt, dass er in Zukunft nicht bremst (Regressionstests). Ein Fehlerverfolgungssystem kann für Funktionsanforderungen verwendet werden.
• Nutzerbeiträge. Möchten Sie Benutzerbeiträge? Ich bin mir nicht sicher, wie dies normalerweise bei Open-Source-Produkten funktioniert, aber ich kann mir vorstellen, dass Sie Benutzern das Erstellen von Feature-Zweigen ermöglichen können. Über Github scheinen Sie dies über Pull-Requests steuern zu können

Ich habe keine relevanten Erfahrungen mit Python, daher kann ich Ihnen keine Hinweise in diese Richtung geben. Es ist jedoch möglich, alle Tests zu automatisieren, die von jedem Commit in Ihrem Remote-Repository ausgelöst werden (z. B. mit Jenkins ). Ich schlage jedoch vor, dies zu verschieben, da die Einrichtung ohne vorherige Erfahrung viel Arbeit erfordert.

Das sind tolle Fragen.

Über wichtige konkrete inkrementelle Schritte in Richtung einer freigebbaren Bibliothek:

• Trennen Sie die Dateien, die zur Bibliothek werden sollen, vom Rest des Projekts.
  • Die Bibliothek sollte sich in einem eigenen Git-Repository befinden, aber es ist möglicherweise ein nützlicher Zwischenschritt, um sie in einem separaten Verzeichnis der obersten Ebene in Ihrem aktuellen Repository abzulegen. Wenn Sie ein separates Repository erstellen, speichern Sie das Repository neben dem Rest Ihres Projekts, das dann über referenziert werden kann, ../librarybis Sie zu den Schritten im Pip-Packaging- und Entwicklungsmodus gelangen.
  • Alle Zugriffe vom Rest des Projekts auf diese Bibliothek sollten über die öffentliche API erfolgen. Möglicherweise gibt es einige Abhängigkeiten, die auseinanderfallen können.
• Schreiben Sie inkrementell Docstrings, um die API der Bibliothek zu dokumentieren.
  • Irgendwann werden die Dokumentationszeichenfolgen in ein Dokumentationswerkzeug eingespeist, aber die wichtige Arbeit besteht darin, den Text zu schreiben, der die API anderen Personen kurz und ausreichend erklärt. Es ist einfacher, es auf einmal ein wenig auszufüllen, und es wird viel besser, wenn man grobe Entwürfe schreibt und später darauf zurückgreift, wenn bessere Erklärungen und Beispiele in den Sinn kommen.
  • Wenn Sie feststellen, dass ein Teil der API schwer zu dokumentieren ist, fragen Sie, ob dieser Teil der API Verbesserungspotenzial bietet. Könnte es einfacher sein? Regelmäßiger? Ist es zu allgemein? Zu spezialisiert? Könnte es bekanntere Namen verwenden?
  • Die docstrings können Argumenttypen mit strukturierten Kommentaren dokumentieren, die Tools überprüfen können. Ich habe noch keine echte Dokumentation dazu gefunden, aber die PyCharm-IDE hilft beim Erstellen dieser Dokumentzeichenfolgen und überprüft sofort die Argumenttypen, während Methodenaufrufe bearbeitet werden.
  • Apropos, PyCharm ist ein wunderbares Tool, um Entwicklerzeit zu sparen und die Codequalität zu verbessern. Es werden "Inspektionen" ausgeführt, um den Code zu überprüfen, während Sie ihn bearbeiten, z. B. Überprüfung der Typen, wenn dies möglich ist, Überprüfung auf fehlende und nicht verwendete Importe, doppelte Methoden, PEP 8-Stilfehler usw.
• Starten Sie das Schreiben von Komponententests mit pytest. Lange bevor Sie eine Veröffentlichung vornehmen, zahlen sich Komponententests in Ihrer eigenen Entwicklung aus, indem sie Fehler in Eckfällen aufdecken und die Gewissheit vermitteln, dass Codeänderungen nichts kaputt machten. Auch dies können Sie im Laufe der Zeit aufbauen. Es ist ziemlich einfach anzufangen.
• Durchsuchen Sie vorhandene Open Source-Bibliotheken (die ungefähr dieselbe Größe haben) auf GitHub, um zu sehen, wie sie die Dateien und Veröffentlichungen organisieren. Beobachten Sie, wie sie Bug- / Issue-Tracking- und Pull-Anfragen durchführen. Tragen Sie zu einem oder mehreren von ihnen bei, um Erfahrung mit diesen Projektorganisationsprozessen für mehrere Personen zu sammeln, wenn Sie dort keine Erfahrung haben. GitHub hat gute Werkzeuge für diese Prozesse. Es macht nette Dinge mit README.mdDokumentationsdateien auf der obersten Ebene und in einem beliebigen Verzeichnis sowie mit einer Lizenzdatei.
• Ziehen Sie in Betracht, einen Mitarbeiter zu engagieren, um Feedback zu Bibliothek, API und Dokumentation zu erhalten.
  • Wenn Sie freigeben, ist es hilfreich, einen oder mehrere Mitarbeiter zu haben, die im Urlaub Fehler beheben, Benutzerfragen beantworten und in der Zwischenzeit Pull-Requests mit Codeüberprüfungen durchführen, um die Aufgaben zur Freigabe von Bibliotheken aufzuteilen. und bringen zusätzliche Erfahrung mit Projektmanagement und Bibliotheksdesign ein.
• Bisher haben Sie einen linearen Git-Commit-Verlauf erstellt. Eventuell ist es nützlich, "Issue Branches" für bestimmte Korrekturen und Änderungen, "Release Branches" für den kontrollierten Hochlauf eines Releases und "Development Branches" für alle laufenden Arbeiten mit mehreren Personen zu verwenden, die nicht zur Zusammenführung bereit sind in den Master-Zweig. Nehmen Sie sich ein oder zwei Tage Zeit, um mehr darüber zu erfahren, und üben Sie sich darin, bevor Sie sich auf diese Git-Fähigkeiten verlassen müssen. Git ist sehr flexibel und nützlich, aber die Benutzeroberfläche kann voller Probleme sein .
  • Ein Ort, an dem Sie etwas über Git-Zweige und ihre Verwendung lesen können, ist das Pro Git-Buch . Beginnen Sie unter den vielen Möglichkeiten, Zweige zu verwenden, mit der Option "Zweige ausgeben".
  • Die GitHub Desktop App ist ein großartiges Tool zum Verwalten von Filialen. Es eignet sich auch hervorragend zum Ausführen von Commits, da das Schreiben der Commit-Nachricht beim Überprüfen aller Änderungen vereinfacht wird.