Avancerad handledning: Hur man skriver återanvändbara appar

Denna avancerade handledning börjar där Handledning 8 slutade. Vi kommer att förvandla vår webbenkät till ett fristående Python-paket som du kan återanvända i nya projekt och dela med andra människor.

Om du inte nyligen har slutfört Tutorials 1-8, uppmanar vi dig att gå igenom dessa så att ditt exempelprojekt överensstämmer med det som beskrivs nedan.

Återanvändbarhet är viktigt

Det är mycket arbete att designa, bygga, testa och underhålla en webbapplikation. Många Python- och Django-projekt delar gemensamma problem. Skulle det inte vara bra om vi kunde spara en del av detta upprepade arbete?

Återanvändbarhet är livsstilen i Python. Python Package Index (PyPI) har ett stort utbud av paket som du kan använda i dina egna Python-program. Kolla in Django Packages för befintliga återanvändbara appar som du kan införliva i ditt projekt. Django i sig är också ett normalt Python-paket. Det innebär att du kan ta befintliga Python-paket eller Django-appar och komponera dem till ditt eget webbprojekt. Du behöver bara skriva de delar som gör ditt projekt unikt.

Låt oss säga att du startar ett nytt projekt som behöver en app för opinionsundersökningar, som den vi har arbetat med. Hur gör du den här appen återanvändbar? Lyckligtvis, du är på god väg redan. I Tutorial 1 såg vi hur vi kunde frikoppla polls från URLconf på projektnivå med hjälp av en include. I den här handledningen tar vi ytterligare steg för att göra appen enkel att använda i nya projekt och redo att publicera så att andra kan installera och använda den.

Paket? App?

En Python package ger ett sätt att gruppera relaterad Python-kod för enkel återanvändning. Ett paket innehåller en eller flera filer med Python-kod (även kända som ”moduler”).

Ett paket kan importeras med import foo.bar eller from foo import bar. För att en katalog (som polls) ska utgöra ett paket måste den innehålla en speciell fil __init__.py, även om denna fil är tom.

En Django applikation är ett Python-paket som är specifikt avsett för användning i ett Django-projekt. En applikation kan använda vanliga Django-konventioner, till exempel att ha undermoduler för modeller, tester, urls och vyer.

Senare använder vi termen packaging för att beskriva processen att göra ett Python-paket enkelt för andra att installera. Vi vet att det kan vara lite förvirrande.

Ditt projekt och din återanvändbara app

Efter de tidigare handledningarna bör vårt projekt se ut så här:

djangotutorial/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py
    polls/
        __init__.py
        admin.py
        apps.py
        migrations/
            __init__.py
            0001_initial.py
        models.py
        static/
            polls/
                images/
                    background.png
                style.css
        templates/
            polls/
                detail.html
                index.html
                results.html
        tests.py
        urls.py
        views.py
    templates/
        admin/
            base_site.html

Du skapade djangotutorial/templates i :doc:Tutorial 7 </intro/tutorial07>`, och ``polls/templates i :doc:Tutorial 3 </intro/tutorial03>`. Nu kanske det är tydligare varför vi valde att ha separata mallkataloger för projektet och applikationen: allt som är en del av pollsapplikationen finns i ``polls. Det gör applikationen fristående och lättare att släppa in i ett nytt projekt.

Katalogen polls kan nu kopieras till ett nytt Django-projekt och omedelbart återanvändas. Den är dock inte riktigt redo att publiceras. För det måste vi paketera appen för att göra det enkelt för andra att installera den.

Installera vissa förutsättningar

Det nuvarande läget för Python-paketering är lite förvirrat med olika verktyg. För denna handledning kommer vi att använda setuptools för att bygga vårt paket. Det är det rekommenderade förpackningsverktyget (sammanslaget med distribute-gaffeln). Vi kommer också att använda pip för att installera och avinstallera det. Du bör installera dessa två paket nu. Om du behöver hjälp kan du läsa så här installerar du Django med pip. Du kan installera setuptools på samma sätt.

Paketera din app

Python packaging hänvisar till att förbereda din app i ett specifikt format som enkelt kan installeras och användas. Django själv är förpackat mycket på detta sätt. För en liten app som polls är denna process inte alltför svår.

1. Först skapar du en överordnad katalog för paketet, utanför ditt Django-projekt. Kalla den här katalogen django-polls.

   Välja ett namn för din app

   När du väljer ett namn för ditt paket, kontrollera PyPI för att undvika namnkonflikter med befintliga paket. Vi rekommenderar att du använder ett django--prefix för paketnamn, för att identifiera ditt paket som specifikt för Django, och ett motsvarande django_-prefix för ditt modulnamn. Till exempel innehåller paketet django-ratelimit modulen django_ratelimit.

   Applikationsetiketter (det vill säga den sista delen av den prickade sökvägen till applikationspaket) måste vara unika i INSTALLED_APPS. Undvik att använda samma etikett som någon av Django contrib-paketen, till exempel auth, admin eller messages.

2. Flytta katalogen polls till katalogen django-polls och döp om den till django_polls.

3. Redigera django_polls/apps.py så att name hänvisar till det nya modulnamnet och lägg till label för att ge ett kort namn på appen:

   django-polls/django_polls/apps.py

   from django.apps import AppConfig
   
   
   class PollsConfig(AppConfig):
       default_auto_field = "django.db.models.BigAutoField"
       name = "django_polls"
       label = "polls"
   

4. Skapa en fil django-polls/README.rst med följande innehåll:

   django-polls/README.rst

   ============
   django-polls
   ============
   
   django-polls is a Django app to conduct web-based polls. For each
   question, visitors can choose between a fixed number of answers.
   
   Detailed documentation is in the "docs" directory.
   
   Quick start
   -----------
   
   1. Add "polls" to your INSTALLED_APPS setting like this::
   
       INSTALLED_APPS = [
           ...,
           "django_polls",
       ]
   
   2. Include the polls URLconf in your project urls.py like this::
   
       path("polls/", include("django_polls.urls")),
   
   3. Run ``python manage.py migrate`` to create the models.
   
   4. Start the development server and visit the admin to create a poll.
   
   5. Visit the ``/polls/`` URL to participate in the poll.
   

5. Skapa en fil med namnet django-polls/LICENSE. Att välja en licens ligger utanför ramen för denna handledning, men det räcker med att säga att kod som släpps offentligt utan licens är användbar. Django och många Django-kompatibla appar distribueras under BSD-licensen; du är dock fri att välja din egen licens. Var bara medveten om att ditt licensval kommer att påverka vem som kan använda din kod.

6. Därefter skapar vi filen pyproject.toml som beskriver hur appen ska byggas och installeras. En fullständig förklaring av den här filen ligger utanför ramen för denna handledning, men Python Packaging User Guide har en bra förklaring. Skapa filen django-polls/pyproject.toml med följande innehåll:

   django-polls/pyproject.toml

   [build-system]
   requires = ["setuptools>=69.3"]
   build-backend = "setuptools.build_meta"
   
   [project]
   name = "django-polls"
   version = "0.1"
   dependencies = [
       "django>=X.Y",  # Replace "X.Y" as appropriate
   ]
   description = "A Django app to conduct web-based polls."
   readme = "README.rst"
   requires-python = ">= 3.10"
   authors = [
       {name = "Your Name", email = "[e-mail]"},
   ]
   classifiers = [
       "Environment :: Web Environment",
       "Framework :: Django",
       "Framework :: Django :: X.Y",  # Replace "X.Y" as appropriate
       "Intended Audience :: Developers",
       "License :: OSI Approved :: BSD License",
       "Operating System :: OS Independent",
       "Programming Language :: Python",
       "Programming Language :: Python :: 3",
       "Programming Language :: Python :: 3 :: Only",
       "Programming Language :: Python :: 3.10",
       "Programming Language :: Python :: 3.11",
       "Programming Language :: Python :: 3.12",
       "Programming Language :: Python :: 3.13",
       "Topic :: Internet :: WWW/HTTP",
       "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
   ]
   
   [project.urls]
   Homepage = "https://www.example.com/"
   

7. Många vanliga filer och Python-moduler och -paket ingår i paketet som standard. För att inkludera ytterligare filer måste vi skapa en fil MANIFEST.in. För att inkludera mallarna och de statiska filerna skapar du en fil django-polls/MANIFEST.in med följande innehåll:

   django-polls/MANIFEST.in

   recursive-include django_polls/static *
   recursive-include django_polls/templates *
   

8. Det är valfritt, men rekommenderas, att inkludera detaljerad dokumentation med din app. Skapa en tom katalog django-polls/docs för framtida dokumentation.

   Observera att katalogen docs inte kommer att ingå i ditt paket om du inte lägger till några filer i den. Många Django-appar tillhandahåller också sin dokumentation online via webbplatser som readthedocs.org.

   Många Python-projekt, inklusive Django och Python självt, använder Sphinx för att bygga sin dokumentation. Om du väljer att använda Sphinx kan du länka tillbaka till Djangos dokumentation genom att konfigurera Intersphinx och inkludera ett värde för Django i ditt projekts intersphinx_mapping värde:

   intersphinx_mapping = {
       # ...
       "django": (
           "https://docs.djangoproject.com/en/stable/",
           None,
       ),
   }
   

   Med det på plats kan du sedan korslänka till specifika poster, på samma sätt som i Django-dokumenten, till exempel ”:attr:`django.test.TransactionTestCase.databases`”.

9. Kontrollera att paketet build är installerat (python -m pip install build) och försök bygga ditt paket genom att köra python -m build inuti django-polls. Detta skapar en katalog som heter dist och bygger ditt nya paket till källkods- och binärformat, django_polls-0.1.tar.gz och django_polls-0.1-py3-none-any.whl.

Mer information om paketering finns i Pythons Tutorial on Packaging and Distributing Projects.

Använda ditt eget paket

Eftersom vi flyttade katalogen polls ut ur projektet fungerar den inte längre. Vi ska nu åtgärda detta genom att installera vårt nya paket django-polls.

Installera som ett användarbibliotek

Följande steg installerar django-polls som ett användarbibliotek. Installationer per användare har många fördelar jämfört med att installera paketet i hela systemet, till exempel att det kan användas på system där du inte har administratörsbehörighet samt att förhindra att paketet påverkar systemtjänster och andra användare av maskinen.

Observera att installationer per användare fortfarande kan påverka beteendet hos systemverktyg som körs som den användaren, så att använda en virtuell miljö är en mer robust lösning (se nedan).

1. För att installera paketet använder du pip (du har redan installerat det, eller hur?):

   python -m pip install --user django-polls/dist/django_polls-0.1.tar.gz
   

2. Uppdatera mysite/settings.py för att peka på det nya modulnamnet:

   INSTALLED_APPS = [
       "django_polls.apps.PollsConfig",
       ...,
   ]
   

3. Uppdatera mysite/urls.py för att peka på det nya modulnamnet:

   urlpatterns = [
       path("polls/", include("django_polls.urls")),
       ...,
   ]
   

4. Kör utvecklingsservern för att bekräfta att projektet fortsätter att fungera.

Publicera din app

Nu när vi har paketerat och testat django-polls, är det redo att dela med sig till världen! Om detta inte bara var ett exempel, kan du nu:

• Skicka paketet till en vän via e-post.

• Ladda upp paketet på din webbplats.

• Lägg upp paketet på ett offentligt arkiv, till exempel the Python Package Index (PyPI). packaging.python.org har en bra handledning för att göra detta.

Installera Python-paket med en virtuell miljö

Tidigare installerade vi django-polls som ett användarbibliotek. Detta har några nackdelar:

• Om du ändrar användarbiblioteken kan det påverka andra Python-program på ditt system.

• Du kommer inte att kunna köra flera versioner av det här paketet (eller andra med samma namn).

Vanligtvis uppstår dessa situationer först när du underhåller flera Django-projekt. När de gör det är den bästa lösningen att använda venv. Med det här verktyget kan du underhålla flera isolerade Python-miljöer, var och en med sin egen kopia av biblioteken och paketnamnrymden.