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 pip
znalazł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.
Odpowiedzi:
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.
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.
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.
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.
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:
Wyjaśnij, czy Twoja biblioteka współpracuje z Pythonem 2, 3 lub z obydwoma.
Jeśli biblioteka nie działa w systemie Windows, powiedz tak.
Upewnij się, że korzystasz z oficjalnych konwencji (użyj pep8, aby to sprawdzić). Jeśli nie, wyjaśnij to wyraźnie lub napraw.
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.
źródło
How can I tell which one I should invest in learning for my project?
- ty nie. Spędzasz trochę czasu, wybierając taki, który wydaje się rozsądny, i rzucasz nim. Jako programista javascript, w którym masz 40 opcji dla każdej decyzji, obiecuję, że to właściwa decyzja :)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).
źródło
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:
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).
źródło
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.
źródło
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
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.
źródło
To są świetne pytania.
O ważnych konkretnych krokach w kierunku biblioteki, którą można wydać:
../library
dopóki nie przejdziesz do etapu pakowania pip i kroków trybu programowania.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.README.md
plikami dokumentacji na najwyższym poziomie, w dowolnym katalogu oraz z plikiem licencji.źródło