pydoc — Dokumentationsgenerator och hjälpsystem online¶
Källkod: Lib/pydoc.py
Modulen pydoc genererar automatiskt dokumentation från Python-moduler. Dokumentationen kan presenteras som textsidor på konsolen, visas i en webbläsare eller sparas i HTML-filer.
För moduler, klasser, funktioner och metoder härleds den dokumentation som visas från objektets docstring (dvs. attributet __doc__) och rekursivt från dess dokumenterbara medlemmar. Om det inte finns någon docstring försöker pydoc hämta en beskrivning från blocket med kommentarsrader precis ovanför definitionen av klassen, funktionen eller metoden i källfilen, eller högst upp i modulen (se inspect.getcomments()).
Den inbyggda funktionen help() anropar onlinehjälpsystemet i den interaktiva tolken, som använder pydoc för att generera sin dokumentation som text på konsolen. Samma textdokumentation kan också visas utanför Python-tolken genom att köra pydoc som ett skript i operativsystemets kommandotolk. Till exempel körs
python -m pydoc sys
vid en skalprompt visar dokumentation om modulen sys på ett sätt som liknar de manualsidor som visas med Unix-kommandot man. Argumentet till pydoc kan vara namnet på en funktion, modul eller ett paket, eller en prickad referens till en klass, metod eller funktion i en modul eller modul i ett paket. Om argumentet till pydoc ser ut som en sökväg (det vill säga innehåller sökvägsseparatorn för ditt operativsystem, till exempel ett snedstreck i Unix) och hänvisar till en befintlig Python-källfil, produceras dokumentation för den filen.
Anteckning
För att hitta objekt och deras dokumentation importerar pydoc den eller de moduler som ska dokumenteras. Därför kommer all kod på modulnivå att exekveras vid det tillfället. Använd en if __name__ == '__main__': guard för att endast exekvera kod när en fil anropas som ett skript och inte bara importeras.
När utdata skrivs ut till konsolen försöker pydoc att paginera utdata för att underlätta läsningen. Om antingen miljövariabeln MANPAGER eller PAGER är inställd, kommer pydoc att använda dess värde som ett pagineringsprogram. När båda är inställda används MANPAGER.
Om du anger flaggan -w före argumentet skrivs HTML-dokumentationen ut till en fil i den aktuella katalogen i stället för att texten visas på konsolen.
Om du anger flaggan -k före argumentet kommer du att söka i synopsisraderna för alla tillgängliga moduler efter nyckelordet som anges som argument, återigen på ett sätt som liknar Unix-kommandot man. Synopsisraden för en modul är den första raden i dess dokumentationssträng.
Du kan också använda pydoc för att starta en HTTP-server på den lokala datorn som serverar dokumentationen till besökande webbläsare. python -m pydoc -p 1234 startar en HTTP-server på port 1234, så att du kan bläddra i dokumentationen på http://localhost:1234/ i den webbläsare du föredrar. Om du anger 0 som portnummer kommer en godtycklig oanvänd port att väljas.
python -m pydoc -n <hostname> startar servern som lyssnar på det angivna värdnamnet. Som standard är värdnamnet ”localhost”, men om du vill att servern ska kunna nås från andra maskiner kanske du vill ändra värdnamnet som servern svarar på. Under utveckling är detta särskilt användbart om du vill köra pydoc från en container.
python -m pydoc -b startar servern och öppnar dessutom en webbläsare till en modulindexsida. Varje serverad sida har ett navigeringsfält högst upp där du kan Få hjälp med ett enskilt objekt, Söka i alla moduler med ett nyckelord i synopsisraden och gå till sidorna Modulindex, Teman och Nyckelord.
När pydoc genererar dokumentation använder den den aktuella miljön och sökvägen för att hitta moduler. När du anropar pydoc spam dokumenteras alltså exakt den version av modulen som du skulle få om du startade Python-tolken och skrev import spam.
Moduldokument för kärnmoduler antas finnas i https://docs.python.org/X.Y/library/ där X och Y är Python-tolkens större och mindre versionsnummer. Detta kan åsidosättas genom att ställa in miljövariabeln PYTHONDOCS till en annan URL eller till en lokal katalog som innehåller bibliotekets referensmanualsidor.
Ändrad i version 3.2: Lagt till alternativet -b.
Ändrad i version 3.3: Kommandoradsalternativet -g har tagits bort.
Ändrad i version 3.4: pydoc använder nu inspect.signature() istället för inspect.getfullargspec() för att extrahera signaturinformation från anropbara filer.
Ändrad i version 3.7: Lagt till alternativet -n.