Anatomy of a Python Package

Over the course of several past months and years I was coding in Python, I’ve created quite a few Python packages: both open source and for private projects. Even though their most important part was always the code, there are numerous additional files that are necessary for the package to correctly serve its purpose. Rather than part of the Python language, they are more closely related to the Python platform.

But if you look for any definite, systemic info about them, you will at best find some scattered pieces of knowledge in various unrelated places. At worst, the only guidance would come in the form of a multitude of existing Python package sources, available on GitHub and similar sites. Parroting them is certainly an option, although I believe it’s much more advantageous to acquire firm understanding of how those different cogs fit together. Without it, following the modern Python’s best development practices – which are all hugely beneficial – is largely impossible.

So, I want to fill this void by outlining the structure of a Python package, as completely as possible. You can follow it as a step-by-step guide when creating your next project. Or just skim through it to see what you’re missing, and whether it’d be worthwhile to address such gaps. Any additional element or file will usually provide some tangible benefit, but of course not every project requires all bells and whistles.

Without further ado, let’s see what’s necessary for a complete Python software bundle.

License It, Please

In a blog relayed to my news reader today via Slashdot, I found this bit about providing licenses to the open source code you publish. Or, more specifically, about not providing them:

If some ‘no license’ sharing is a quiet rejection of the permission culture, the lawyer’s solution (make everyone use a license, for their own good!) starts to look bad. This is because once an author has used a standard license, their immediate interests are protected – but the political content of not choosing a license is lost. [emphasis mine]

I admire how the author goes all post-modernistic by bringing up fuzzy terms like “permission culture”. It’s a serious skill, to muddy such a clear-cut issue by making so many onerous assumptions per square inch of text. The alleged existence of some “political content” involved in not choosing any license – as opposed to, say, negligence or lack of knowledge – is easily my favorite here.

On more serious note: what a load of manure. I won’t even grace the premise with speculation on how likely it is to have anything to do with reality – that is, how big a percentage of the ‘no license’ projects is made so by the conscious choice of their authors. No, I will be insanely generous and assume that it actually holds water. Doesn’t matter; the claim that this practice should be encouraged and that something valuable is lost if software project has a license is still sheer lunacy.

If you don’t explicitly renounce some rights to your code – by providing a license, as the most common way – they are all reserved to you. Regardless of what political or cultural weight you may want to associate with this fact, the practical one is implied by law. And it’s very simple: no one can safely do anything with that code of yours, for there is always a risk you will exercise your rights through prosecution.

Of course I know you wouldn’t do anything so clearly evil. But that’s no guarantee for many parties that treat the issues of copyright and liability very seriously: from solo freelancers to the biggest of companies, and from lone hackers to the most influential software foundations. If you care about your code being widely used and solving problems for as many people as possible, this is also something you should pay attention to.
Otherwise it may happen that for someone, your work is just the perfect piece of puzzle – but they cannot use it safely. They might ask you to fix your oversight, of course, but they might also go somewhere else.

And that is typically the “immediate interest” that you protect by licensing: letting others actually use your code. If you ask me, that sounds like something totally worthy of protection.

Nietypowe licencje

Programy – zwłaszcza te do znalezienia w Internecie – są dostępne na wielu różnych rodzajach licencji. Do tych najbardziej znanych należą chociażby wszelakie licencje typu open source (na czele ze znaną i (nie)lubianą GNU GPL), freeware i shareware. Ale hakerska wyobraźnia nie zna granic i nawet w tak “poważnym” temacie pojawiły się żartobliwe wynalazki.
Wśród takich zdecydowanie nieszablonowych licencji mamy na przykład:

• postcardware, wedle której użytkownik może korzystać z programu pod warunkiem, że prześle autorowi kartkę pocztową ze swojego miasta. W innych wariantach może to być też e-mail, chociaż osobiście uważam, że możliwość pochwalenia się imponującą kolekcją pocztówek jest o wiele bardziej zachęcająca niż perspektywa zapychającej się skrzynki mailowej :)
• guiltware, charakteryzująca się tym, że program co jakiś czas wyświetla komunikat o tym, jak wiele wysiłku autor włożył w tworzenie danej aplikacji. Rzeczony komunikat ma wywołać w użytkowniku poczucie winy (stąd nazwa) i spowodować przesłanie autorowi drobnej sumy pieniędzy. To oczywiście dość drastyczna forma donationware i wydaje mi się, że skutek, jaki by odniosła, byłby raczej odwrotny do zamierzonego ;]
• linkware, zakładającą że użytkownicy powinni w widocznym miejscu zamieścić link do strony internetowej autora. Jak nietrudno się domyślić, ten typ licencji stosuje się głównie do bibliotek programistycznych lub do treści możliwych do zamieszczenia na stronach WWW (np. obrazków), i generalnie nie wydaje się specjalnie dolegliwy.
• beerware, która jest prawdopodobnie najlepsza z nich wszystkich :) Otóż według niej użytkownik w zasadzie może bez ograniczeń korzystać z programu – pod jednym warunkiem. Jeśli mianowicie kiedyś zdarzy mu się spotkać jego autora, ma kategoryczny obowiązek… postawić mu piwo :D Inne wersje zakładają wręcz wysłanie autorowi skrzynki chmielowego napoju lub tylko wypicie za jego zdrowie. No cóż, na pewno jest to praktyczniejsze niż wysyłanie pocztówek, a przy odrobinie szczęścia też może zostać pamiątka w postaci podstawki lub w ostateczności butelki ;]
• otherware to z kolei cała masa różnych rodzajów “licencji” (cudzysłów jest tu już chyba uzasadniony), które proszą użytkownika o różne rzeczy nieprzynoszące żadnych bezpośrednich korzyści autorowi. Są to przykładowo:
  • careware (charityware) – użytkownik powinien wpłacić drobną (lub niekoniecznie drobną) sumę pieniędzy na konto wskazanej organizacji charytatywnej. Przykładem programu, który o to prosi, jest edytor vim.
  • greenware – tutaj w zamian za możliwość korzystania z programu, user jest zobowiązany zadbać jakoś o środowisko naturalne, a więc np. zacząć segregować śmieci, przestać używać jednorazowych opakowań, korzystać ze środku transportu publicznego, itd.

  

  • catware -w tym wariancie możliwe jest bezpłatne korzystanie z programu, o ile jego użytkownik poświęci przynajmniej jedną godzinę na… zabawę z jednym lub kilkoma kotami, niekoniecznie własnymi. Zapewne gdyby ta licencja była powszechnie stosowana, spowodowałoby to protesty właścicieli psów i chomików :)

Wniosek z tej listy jest taki, że określanie swoich programów jako po prostu freeware to marnotrawienie wielkiej okazji, aby zrobić coś dobrego. Nie mówię już nawet o wspomaganiu pożytecznych organizacji czy propagowaniu ekologii. Pomyślmy raczej o kotach! ;))