help(), pydoc rt(f)m Dokumentation für (built-in) Methoden

Wenn du dir nicht sicher bist, in welchem der anderen Foren du die Frage stellen sollst, dann bist du hier im Forum für allgemeine Fragen sicher richtig.
Antworten
oqwolq
User
Beiträge: 2
Registriert: Dienstag 12. April 2011, 11:39

Hallo,
ich bin relativ neu mit Python und hätte ein oder zwei grundsätzliche Fragen zur offline-Dokumentation.

Wie es scheint, sind die help() bzw. pydoc Dokus nicht das erste Mittel der Wahl für die meisten Programmierer, was mich etwas wundert. Sind diese offiziellen Dokus einfach so unbrauchbar? - oder haben die Leute mit der Zeit einfach selbst besser rausbekommen als die Python-Entwickler, wie Python arbeitet, so dass man irgendwo im Netz einfacher zur Lösung kommt als im Handbuch?

Konrekt wäre die Frage folgende: Wie gehe ich vor, wenn ich nur den Namen z.B. einer Methode, z.B. sort() kenne und nachlesen möchte, wie die genau funktioniert, ohne zu wissen, zu welchem Modul diese gehört?

Die Online-Doku sagt dazu: "The argument to pydoc can be the name of a function, module, or package, or a dotted reference to a class, method, or function within a module or module in a package."

Ähnlich hierzu ist das Problem, dass ich (als Neuling) zwar von der ein oder anderen Funktion oder Methode gehört habe und diese mit etwas Glück auch verwenden könnte, allerdings nicht in jedem Fall weiss, welches Paket dafür zu importieren ist.

Python kann ja z.B. auflisten dir() welche Methoden auf einen string möglich sind. Kann man nicht auch abfragen, zu welchem Modul bzw. Paket eine Methode gehört :?:
Benutzeravatar
cofi
Python-Forum Veteran
Beiträge: 4432
Registriert: Sonntag 30. März 2008, 04:16
Wohnort: RGFybXN0YWR0

Willkommen im Forum und zu Python,

wegen der ganzen Ramblings verstehe ich nicht so recht was du willst. Suchst du ein Tool, dass dir bei einem Namen die entsprechende Doku anzeigt, unabhaengig davon in welchem Modul und wie tief es darin steht?

Code: Alles auswählen

pydoc open
soll also nicht nur `__builtins__.open`, sondern auch `os.open`, `os.path.os.open`, `shelve.open` etc anzeigt?

Vielleicht interessiert dich pylookup, im Grunde ein glorified grep: https://github.com/tsgates/pylookup
BlackJack

@oqwolq: Wenn man nur den Namen kennt, dann schaut man am besten in den Index von der Dokumentation. Zum Beispiel unter O wenn man `open` sucht: http://docs.python.org/genindex-O.html
Benutzeravatar
noisefloor
User
Beiträge: 4262
Registriert: Mittwoch 17. Oktober 2007, 21:40
Wohnort: WW
Kontaktdaten:

Hallo,
Konrekt wäre die Frage folgende: Wie gehe ich vor, wenn ich nur den Namen z.B. einer Methode, z.B. sort() kenne und nachlesen möchte, wie die genau funktioniert, ohne zu wissen, zu welchem Modul diese gehört?
Prinzipiell könnte es auch sein, dass verschiedene Module gleichnamige Methoden haben. Bei open() ist die z.B. der Fall AFAIK.

Von daher fährst du, wie BlackJack schon sagt, mit einer Online Suche in der Regel besser.
Sind diese offiziellen Dokus einfach so unbrauchbar?
Nein, sind sie nicht. :-) Bis jetzt habe ich jedenfalls noch keine unbrauchbare gefunden. Die mitgelieferten Module sind eigentlich alle gut dokumentiert - was aber nicht heißt, das die Doku im Internet nicht doch besser ist.

Eine sehr gute externe Seite mit vielen Beispielen für die Python Standardmodule ist übrigens Module of the Week von Doug Hellmann. Gibt's auch als Buch für die Offline Lektüre. ;-)

Gruß, noisefloor
sma
User
Beiträge: 3018
Registriert: Montag 19. November 2007, 19:57
Wohnort: Kiel

Ich finde `help` zusammen mit der REPL (dem interaktiven Modus) eigentlich sehr brauchbar. Ruft man `help(open)` oder für sonst eine Funktion, einen Typ oder ein Modul auf, steht in der ersten Zeile immer das Modul. So lerne ich aus

Code: Alles auswählen

Help on built-in function open in module __builtin__
das `open` eine eingebaute Funktion aus dem speziellen Modul `__builtin__` ist. Wenn man in diesem speziellen Fall nun weiß, dass dieses Modul an den Namen `__builtins__` (mit zusätzlichem s) gebunden ist, kann man mit `help(__builtins__)` an eine Übersicht aller Funktionen, Typen, usw. dieses Moduls kommen.

Eigentlich hat auch alles bei Python ein Attribut `__module__`, das man abfragen kann, um den Namen eines Moduls einer Funktion, usw. zu erfragen, wenn einem `help()` aus irgendeinem Grund nicht gefällt. Selbst wenn man sich einfach nur mal das Objekt selbst anzeigen lässt, lernt man schon etwas:

Code: Alles auswählen

<built-in function open>
Bei `sort`, etwa für Listen, kann man mit `help(list.sort)` leider nur

Code: Alles auswählen

Help on method_descriptor:

sort(...)
    L.sort(cmp=None, key=None, reverse=False) -- stable sort *IN PLACE*;
    cmp(x, y) -> -1, 0, 1
als schlechtes Beispiel für eine zu knappe Beschreibung sehen. Aus einem Grund, der mir gerade nicht klar ist, ist `sort` ein bisschen spezieller, sodass hier nicht zu sehen ist, dass das eine Methode von list ist, wie man erfährt, wenn man einfach mal `list.sort` anzeigen lässt, und auch die Erklärung ist vielleicht ein bisschen zu kurz geraten.

Generell hilft einem aber IMHO die Erklärung von `help` schon weiter.

Stefan
oqwolq
User
Beiträge: 2
Registriert: Dienstag 12. April 2011, 11:39

Schönen Dank für die Antworten!

@cofi
pylookup klingt interessant; falls ich einmal auf emacs umsteige wäre dran zu denken.

@BlackJack
Wenn ich in den Index der Dokumentation unter s schaue, findet sich dort leider nur eine sort() Methode im Zusammenhang mit IMAP. (Wüsste ich, dass die Methode zu List gehört, würde ich unter "List" (hier docs.python.org/glossary.html#term-list) Verschiedenes zu min(), max() usw. sehen, auch die Methode list.sort() wird hier erwähnt, aber nicht erklärt.)

Gebe ich "list.sort()" in die Suchfunktion der Dokumentation ein, gibt es auch kein Ergebnis.

@noisefloor
Module of the Week ist abonniert...

@Stefan
Tatsächlich findet sich über help(__builtins__) auch der Eintrag sort() und lässt sich einem list(object) zuordnen.

Problem gelöst!

Trotzdem finde ich die offline-Doku nach wie vor seltsam. Liegt das eher daran, dass meine Frage sich einem Fortgeschrittenern nicht stellen würde, oder ist die Doku einfach nicht besonders durchdacht, da sowieso meistens google gefragt wird?
Benutzeravatar
cofi
Python-Forum Veteran
Beiträge: 4432
Registriert: Sonntag 30. März 2008, 04:16
Wohnort: RGFybXN0YWR0

oqwolq hat geschrieben:@cofi
pylookup klingt interessant; falls ich einmal auf emacs umsteige wäre dran zu denken.
Es gibt auch ein Terminal "Interface", wenn dein Terminal-Emulator Links unterstuetzt ist das auch praktikabel.
Im Index findet sich auch der Link zu `list.sort`, direkt unter der IMAP4 Methode; zugegeben die Formatierung ist gewoehnungsbeduerftig (pylookup leidet auch unter der Trennung von `list.sort` in `sort` (list method)).

Ob die Frage sich einem Fortgeschrittenen nicht stellt kann ich nicht sagen, aber ich hab sie mir nie gestellt. Wie schon ein paar mal aufgetaucht ist: Ein Name ist nicht eindeutig (`open` hat ueber 20 Eintraege!), darum ist es nicht sonderlich sinnvoll nur davon zu sprechen, sondern nur zusammen mit dem Modul, der Klasse, dem Paket etc. und dann weiss man wieder wo man suchen muss.

Der Fall `list` ist hier aber Besonders haarig, da die Dokumentation `list` nur als Funktion und nicht als Typ fuerht und man sich erst zu http://docs.python.org/library/stdtypes.html#typesseq durchschlagen muss. Das ist wirklich verbesserungswuerdig.t
BlackJack

@oqwolq: Also wenn ich im Index der Dokumentation unter http://docs.python.org/genindex-S.html nach `sort()` schaue dann finde ich *zwei* Einträge. Und einer davon führt zu `list.sort()`.

Die integrierte Dokumentation hat halt keinen Index oder irgendeine Ahnung was es alles gibt, sondern es handelt sich um die Dokumentation die an den einzelnen Objekten existiert. Um ein Objekt nach seiner Dokumentation fragen zu können, muss man es also erst einmal „in der Hand“ haben. Das ist dazu gedacht Objekte „live“ zu erforschen und soll keine umfassende Dokumentation ersetzen.

Die Begriffe On- und Offline finde ich hier übrigens ein wenig irreführend, denn die Python-Dokumentation von http://docs.python.org/ kann man in verschiedenen Formaten herunterladen. Auf der anderen Seite wird Dokumentation die in einem Programm integriert ist, auch oft als Online-Dokumentation bezeichnet.
Benutzeravatar
cofi
Python-Forum Veteran
Beiträge: 4432
Registriert: Sonntag 30. März 2008, 04:16
Wohnort: RGFybXN0YWR0

Ich bin gerade auf pydoc-info gestossen, fuer Emacs-Nutzer, die keine Info Abneigung haben ist das evtl ganz praktisch.
Antworten