Przekształcanie osobistego projektu Python w dostępną bibliotekę

Jestem raczej naukowcem niż programistą i mam wieloletnie doświadczenie w pisaniu programów Python na własny użytek, aby wesprzeć moje badania. Mój najnowszy projekt może się przydać wielu innym osobom, a także mnie, i myślę o wydaniu go jako biblioteki Pythona typu open source.

Wydaje się jednak, że przejście od działającego projektu osobistego do biblioteki, która może być bezproblemowo zainstalowana i używana przez innych, wymaga wielu przeszkód. To pytanie dotyczy pierwszych kroków, które powinienem podjąć, aby rozpocząć pracę nad wydaniem publicznym.

Obecnie mam jedno repozytorium git, które zawiera mój kod, który korzysta zarówno z biblioteki, jak i samej biblioteki, i używam git jako awaryjnego przycisku cofania na wypadek, gdyby coś się zepsuło. Wszystko to działa dobrze dla jednego użytkownika, ale oczywiście nie jest odpowiednie, jeśli chcę je wydać. Chcę, aby moja biblioteka pipznalazła się w osobnym repozytorium i mogła być instalowana przez innych użytkowników oraz miała stabilny interfejs API.

Nauka używania setuptools itp. Prawdopodobnie nie jest tak trudna, kiedy chcę opublikować - moim problemem jest wiedzieć, jak powinienem pracować, aby dojść do tego punktu.

Moje pytanie brzmi: jakie są pierwsze kroki, aby rozpocząć przygotowywanie projektu biblioteki Python do publicznego użytku? Jak powinienem zreorganizować strukturę katalogów, repozytorium git itp., Aby rozpocząć pracę nad publicznym wydaniem biblioteki?

Mówiąc bardziej ogólnie, bardzo pomocne byłoby, gdyby istniały zasoby, o których wiadomo, że są pomocne przy pierwszej próbie. Bardzo pomocne byłyby również wskazówki dotyczące najlepszych praktyk i błędów, których należy unikać itp.

Pewne wyjaśnienie: obecne odpowiedzi odpowiadają na pytanie w stylu „w jaki sposób mogę uczynić moją bibliotekę Python dobrą dla innych?” Jest to przydatne, ale różni się od pytania, które chciałem zadać.

Jestem obecnie na początku długiej podróży w kierunku wydania mojego projektu. Rdzeń mojej implementacji działa (i działa naprawdę dobrze), ale czuję się przytłoczony ilością pracy przede mną i szukam wskazówek, jak nawigować po tym procesie. Na przykład:

• Mój kod biblioteki jest obecnie sprzężony z moim własnym kodem specyficznym dla domeny, który go używa. Żyje w podfolderze i dzieli to samo repozytorium git. W końcu będzie trzeba go przekształcić w samodzielną bibliotekę i umieścić we własnym repozytorium, ale wciąż zwlekam z tym, ponieważ nie wiem, jak to zrobić. (Ani jak zainstalować bibliotekę w „trybie programowania”, aby móc ją nadal edytować, ani jak zachować synchronizację dwóch repozytoriów git).

• Moje dokumenty są zwięzłe, ponieważ wiem, że w końcu będę musiał użyć Sfinksa lub innego narzędzia. Ale narzędzia te wydają się nie być łatwe do nauczenia, więc staje się to dużym podprojektem i ciągle go odkładam.

• W pewnym momencie muszę nauczyć się korzystać z setuptools lub innego narzędzia do pakowania i śledzenia zależności, które są dość złożone. Nie jestem pewien, czy muszę to zrobić teraz, czy nie, a dokumentacja jest absolutnym labiryntem dla nowego użytkownika, więc postanawiam to zrobić później.

• Nigdy nie musiałem przeprowadzać systematycznych testów, ale na pewno zrobię to dla tego projektu, więc muszę (i) nauczyć się wystarczająco dużo o testowaniu, aby wiedzieć, która metodologia jest odpowiednia dla mojego projektu; (ii) dowiedzieć się, jakie narzędzia są dostępne dla mojej wybranej metodologii; (iii) nauczyć się korzystać z mojego wybranego narzędzia; (iv) zaimplementuj pakiety testowe itp. dla mojego projektu. To jest projekt sam w sobie.

• Mogą być też inne rzeczy, które muszę zrobić. Na przykład jonrsharpe opublikował pomocny link, który wspomina o git-flow, tox, TravisCI, virtualenv i CookieCutter, o którym wcześniej nie słyszałem. (Stanowisko pochodzi z 2013 r., Więc muszę również popracować, aby dowiedzieć się, ile nadal jest aktualne).

Po złożeniu tego w całość jest to ogromna praca, ale jestem pewien, że mogę to wszystko zrobić, jeśli będę się starał to zatkać i nie będę się spieszył. Moim problemem jest umiejętność podzielenia go na wykonalne kroki, które można wykonać pojedynczo.

Innymi słowy, pytam, jakie są najważniejsze konkretne kroki, które mogę teraz podjąć, aby ostatecznie uzyskać produkt, który można wydać. Jeśli mam wolny weekend, na których z tych rzeczy powinienem się skupić? Które (jeśli w ogóle) można zrobić w oderwaniu od innych, abym mógł przynajmniej wykonać jeden krok bez konieczności robienia wszystkiego? Jaki jest najskuteczniejszy sposób na nauczenie się tych rzeczy, aby mieć czas na skupienie się na samym projekcie? (Pamiętając, że to wszystko jest w zasadzie projektem hobby, a nie moją pracą.) Czy jest coś takiego, czego tak naprawdę nie muszę robić , oszczędzając w ten sposób ogromną ilość czasu i wysiłku?

Wszystkie odpowiedzi są bardzo mile widziane, ale szczególnie chciałbym powitać odpowiedzi, które koncentrują się na tych aspektach zarządzania projektami, ze szczególnym odniesieniem do współczesnego rozwoju Pythona.

Dodanie pliku setup.py, choć jest konieczne, nie jest najważniejszym krokiem, jeśli chcesz korzystać z biblioteki. Ważniejsze jest dodawanie dokumentacji i reklamowanie biblioteki. Ponieważ drugi punkt silnie zależy od biblioteki, pozwól mi raczej skupić się na aspekcie dokumentacji.

1. Wiesz wszystko o swojej bibliotece. I to jest problematyczne. Wiesz już, jak zainstalować i jak z niego korzystać, więc wiele rzeczy może wydawać się intuicyjnych lub oczywistych. Niestety te same rzeczy mogą nie być ani oczywiste, ani intuicyjne dla użytkowników. Spróbuj spojrzeć na swoją bibliotekę tak, jakbyś nic o niej nie wiedział, a co ważniejsze, poproś innych ludzi, aby z niej korzystali i starali się dostrzec wszystkie trudności, jakie mieli.

2. Wyjaśnij, prostym językiem angielskim, o czym jest twoja biblioteka. Zbyt wiele bibliotek zakłada, że ​​wszyscy o nich wiedzą. Gdy tak nie jest, może być trudno zrozumieć, jaki jest cel biblioteki.

3. Napisz szczegółową dokumentację techniczną, ale nie zapomnij również o krótkich fragmentach kodu, które pokazują, jak wykonać niektóre zadania z biblioteką. Większość programistów spieszy się i jeśli będą musieli spędzić godziny próbując zrozumieć, jak zrobić podstawową rzecz, mogą przechodzić do innych bibliotek.

4. Podaj swoje dane kontaktowe. Jeśli Twoja biblioteka odniesie sukces (a moje własne doświadczenie pokazało, że dotyczy to również raczej nieznanych), ludzie napotkaliby na nią trudności: albo błędy, albo po prostu trudności ze zrozumieniem lub wykorzystaniem niektórych jej części. Często przydatne jest otrzymanie ich opinii w celu ulepszenia biblioteki: na każdą osobę, która zgłosiła problem, być może są setki osób, które napotykając go, wolą po prostu przejść do innej biblioteki.

Dodatkowo:

1. Wyjaśnij, czy Twoja biblioteka współpracuje z Pythonem 2, 3 lub z obydwoma.

2. Jeśli biblioteka nie działa w systemie Windows, powiedz tak.

3. Upewnij się, że korzystasz z oficjalnych konwencji (użyj pep8, aby to sprawdzić). Jeśli nie, wyjaśnij to wyraźnie lub napraw.

4. Zadbaj o obsługę skrzynek krawędziowych. Kiedy twoja biblioteka jest wywoływana z niewłaściwego typu lub z nieobsługiwaną wartością, powinna powiedzieć, po prostu po angielsku, co dokładnie jest nie tak. To, czego nie powinno robić, to podniesienie tajemniczego wyjątku o dziesięć poziomów w dół stosu i pozwolenie użytkownikowi dowiedzieć się, co poszło nie tak.

Korzystając z kilku mniej dojrzałych bibliotek przez lata, najważniejszą radą jest, gdy już wybierzesz swoje narzędzie do wdrażania, wykonaj następujące czynności: Czy twoja biblioteka robi coś naprawdę użytecznego, wokół czego możesz zbudować społeczność?

Zidentyfikuj zależności biblioteki.

Spróbuj wdrożyć w czystym środowisku albo kontener docket lub maszynę wirtualną. Uważam ten krok za kluczowy, ponieważ często w środowisku osobistym jest coś wyjątkowego, co powoduje problemy.

Zastanów się, kto będzie utrzymywał bibliotekę w przyszłości, nie ma nic bardziej frustrującego niż znalezienie biblioteki, która była czyimś projektem dla zwierząt domowych przez trzy lub cztery lata, a następnie nie otrzymała aktualizacji potrzebnych do utrzymania jej aktualności.

Zastanów się, czy Ty lub Twój zespół chcecie zobowiązać się do testowania i dokumentowania biblioteki (testy jednostkowe i potoki CI zaczynają być częścią równania).

Być może mógłbyś znaleźć dojrzały projekt OSS w swojej dziedzinie i wnieść swój kod do tego projektu? Może być kilka zalet, takich jak:

• Możesz zmaksymalizować swój wkład. Rzeczywiście wiele „hobby” projektów OSS jest potencjalnie cennych, ale społeczność ich nie wykorzystuje (por. Odpowiedź @ReaddyEddy). Wysoki wysiłek polega na tym, aby projekt najpierw zacząć od zera, a następnie utrzymać, reklamować, podawać odpowiednie przykłady i dokumentację itp.
• Wiele z wymienionych przez ciebie problemów technicznych zostałoby już rozwiązanych w dojrzałym projekcie.
• Jeśli twoja biblioteka wnosi wartość dodaną do projektu OSS, jej współautorzy mogą pomóc ci dostosować kod do standardów projektu. Możesz więc zaoszczędzić wysiłek i zdobyć doświadczenie. Otrzymasz również szczegółowe odpowiedzi na temat Sphinx, TravisCI, CookieCutter i innych aspektów technicznych.

Jeśli istnieje odpowiedni projekt OSS, który Ci się podoba i którego możesz użyć, dlaczego nie otworzyć problemu lub prośby ściągania lub w inny sposób skontaktować się z opiekunami? (Dobrym sposobem na rozpoczęcie może być rozwiązanie istniejącego problemu).

Jest 2019, zdecydowanie sugeruję zacząć od najnowocześniejszych narzędzi. Nie potrzebujesz setup.py, to jest coś, czego ludzie w społeczności Python chcą się pozbyć, i wierzę, że w końcu będą.

Spróbuj Poezji , nie pożałujesz.

To skomplikowane pytanie, które zadajesz i całkowicie zgadzam się z odpowiedzią Arseniego . Dobra dokumentacja jest bardzo ważnym aspektem. Jeśli nie uda mi się uruchomić twojej biblioteki za pomocą kilku prostych kroków, po prostu upuszczam ją w tym miejscu (chyba, że ​​naprawdę chcę ją wypróbować).

Niektóre rzeczy, które zdecydowanie rozważasz

• Pomyśl o tym, jak zamierzasz zaktualizować bibliotekę. Chcesz mieć do pewnego stopnia kompatybilność wsteczną, a także poprawki błędów na trasie. Przeczytaj o wersjach semantycznych
• Używasz git w stosunkowo liniowy sposób (aby cofnąć). Czy znasz rozgałęzianie w git . To naprawdę nie jest takie trudne i ułatwia życie. Po opanowaniu gałęzi. Dostosuj model rozgałęziający do swojego repozytorium. Wybierz części tego modelu rozgałęziającego, które uważasz za istotne. Porównaj to również z oddziałami z repozytoriów, których używasz.
• Licencjonowanie: powinieneś dostarczyć licencję na swoją bibliotekę. Nie jestem ekspertem prawnym w tej sprawie, więc mogę jedynie udostępnić link do tego porównania między zwykłymi licencjami . Nie bierz lekko tego wyboru.
• Bugtracker. Chcesz, aby użytkownik mógł dostarczyć Ci raporty o błędach. Pomaga to poprawić jakość kodu. Dla każdego rozwiązanego błędu dodaj test do swojej ramki testowej, co zapewni, że nie wyhamuje ona w przyszłości (testy regresyjne). System śledzenia błędów może być używany do żądań funkcji.
• Wkład użytkownika. Czy chcesz wkład użytkowników? Nie jestem pewien, jak to zwykle działa w przypadku produktów typu open source, ale mogę sobie wyobrazić, że możesz pozwolić użytkownikom na tworzenie gałęzi funkcji. Za pomocą github wydaje się, że możesz to kontrolować za pomocą żądań ściągania

Nie mam odpowiedniego doświadczenia z Pythonem, więc nie mogę dać ci żadnych wskazówek w tym kierunku. Możliwe jest jednak zautomatyzowanie wszystkich testów uruchamianych przez każde zatwierdzenie w zdalnym repozytorium (tj. Przy użyciu Jenkinsa ). Proponuję jednak odłożyć to na później, ponieważ konfiguracja bez wcześniejszego doświadczenia wymaga dużo pracy.

To są świetne pytania.

O ważnych konkretnych krokach w kierunku biblioteki, którą można wydać:

• Oddziel pliki, które staną się biblioteką od reszty projektu.
  • Biblioteka powinna przejść do własnego repozytorium git, ale może okazać się przydatnym pośrednim krokiem do umieszczenia go w osobnym katalogu najwyższego poziomu w bieżącym repozytorium. Po utworzeniu oddzielnego repozytorium przechowuj je obok reszty projektu, które mogą się do niego odwoływać, ../librarydopóki nie przejdziesz do etapu pakowania pip i kroków trybu programowania.
  • Wszystkie dostępy z pozostałej części projektu do tej biblioteki powinny przechodzić przez jej publiczny interfejs API. Możesz znaleźć pewne współzależności, które drażnią się od siebie.
• Pisz przyrostowo dokumenty w celu udokumentowania interfejsu API biblioteki.
  • Ostatecznie dokumenty zostaną wprowadzone do narzędzia dokumentacyjnego, ale ważną pracą jest napisanie tekstu, który wyjaśnia zwięźle i wystarczająco interfejs API innym osobom. Łatwiej jest wypełniać go od razu niż wszystkie naraz, a wyjdzie to znacznie lepiej, pisząc wstępne szkice i wracając do niego później, gdy przyjdą na myśl lepsze wyjaśnienia i przykłady.
  • Jeśli okaże się, że jakaś część interfejsu API jest trudna do udokumentowania, zapytaj, czy ta część interfejsu API wymaga poprawy. Czy to może być prostsze? Bardziej regularny? Czy to jest zbyt ogólne? Zbyt wyspecjalizowany? Czy może używać bardziej znanych nazw?
  • Dokumenty mogą dokumentować typy argumentów za pomocą uporządkowanych komentarzy, które narzędzia mogą sprawdzać. Nie znalazłem jeszcze prawdziwej dokumentacji na ten temat, ale IDC PyCharm pomoże skonstruować te dokumenty i natychmiast sprawdzi typy argumentów podczas edycji wywołań metod.
  • Mówiąc o tym, PyCharm jest wspaniałym narzędziem do oszczędzania czasu programisty i poprawy jakości kodu. Uruchomione zostaną „inspekcje”, aby sprawdzić kod podczas jego edycji, np. Sprawdzanie typów, kiedy to możliwe, sprawdzanie brakujących i nieużywanych importów, duplikowanie metod, błędy w stylu PEP 8 i tak dalej.
• Rozpocznij pisanie testów jednostkowych za pomocą pytest. Na długo przed wydaniem wydania testy jednostkowe przydadzą się w twoim własnym rozwoju, znajdując błędy w narożnych przypadkach i zapewniając pewność, że zmiany kodu nic nie zepsuły. Ponownie możesz to z czasem rozbudować. Rozpoczęcie jest dość łatwe.
• Przejrzyj istniejące biblioteki Open Source (które są mniej więcej tego samego rozmiaru) w GitHub, aby zobaczyć, jak organizują pliki i wydania. Zobacz, jak wykonują śledzenie błędów / problemów i ściągają żądania. Wnieś wkład w co najmniej jeden z nich, aby uzyskać doświadczenie w tych wieloosobowych procesach organizacji projektów, jeśli nie masz tam doświadczenia. GitHub ma dobre narzędzia do tych procesów. Robi dobre rzeczy z README.mdplikami dokumentacji na najwyższym poziomie, w dowolnym katalogu oraz z plikiem licencji.
• Rozważ zatrudnienie współpracownika, aby uzyskać informacje zwrotne na temat biblioteki, jej interfejsu API i dokumentacji.
  • Po wydaniu pomoże Ci mieć co najmniej jednego współpracownika, który naprawi błędy podczas wakacji, pomoże odpowiedzieć na pytania użytkowników, a tymczasem zaczniesz robić żądania ściągania z recenzjami kodu, aby podzielić zadania zwalniające bibliotekę, i wnoszą dodatkowe doświadczenie w zarządzaniu projektami i projektowaniu bibliotek.
• Do tej pory robiłeś historię liniowego zatwierdzania git. W końcu przydatne będzie użycie „gałęzi wydania” dla określonych poprawek i zmian, „gałęzi wydania” dla kontrolowanego uruchomienia do wydania oraz „gałęzi programistycznych” dla każdej trwającej wieloosobowej pracy, która nie jest gotowa do scalenia do głównej gałęzi. Więc poświęć dzień lub dwa po drodze, aby dowiedzieć się o tym i zacznij ćwiczyć z nim, zanim będziesz musiał polegać na tych umiejętnościach git. git jest bardzo elastyczny i użyteczny, ale interfejs użytkownika może się napełnić .
  • Jedno miejsce do przeczytania o gałęziach gita i ich zastosowaniu znajduje się w książce Pro Git . Spośród wielu sposobów korzystania z gałęzi, zacznij od „wydania gałęzi”.
  • Aplikacja GitHub Desktop to doskonałe narzędzie do zarządzania oddziałami. Jest również świetny do dokonywania zatwierdzeń, ponieważ ułatwia napisanie komunikatu zatwierdzenia podczas przeglądania wszystkich zmian.