SciPy API#

Importieren aus SciPy#

In Python ist die Unterscheidung zwischen der öffentlichen API einer Bibliothek und privaten Implementierungsdetails nicht immer klar. Im Gegensatz zu anderen Sprachen wie Java ist es in Python möglich, auf „private“ Funktionen oder Objekte zuzugreifen. Gelegentlich kann dies praktisch sein, aber seien Sie sich bewusst, dass Ihr Code bei solchen Zugriffen ohne Vorwarnung in zukünftigen Versionen fehlschlagen kann. Einige allgemein verstandene Regeln für das, was in Python öffentlich und was nicht öffentlich ist, lauten:

  • Methoden / Funktionen / Klassen und Modulattribute, deren Namen mit einem führenden Unterstrich beginnen, sind privat.

  • Wenn ein Klassenname mit einem führenden Unterstrich beginnt, sind keine seiner Mitglieder öffentlich, unabhängig davon, ob sie mit einem führenden Unterstrich beginnen oder nicht.

  • Wenn ein Modulname in einem Paket mit einem führenden Unterstrich beginnt, sind keine seiner Mitglieder öffentlich, unabhängig davon, ob sie mit einem führenden Unterstrich beginnen oder nicht.

  • Wenn ein Modul oder Paket __all__ definiert, definiert dies maßgeblich die öffentliche Schnittstelle.

  • Wenn ein Modul oder Paket __all__ nicht definiert, dann sind alle Namen, die nicht mit einem führenden Unterstrich beginnen, öffentlich.

Hinweis

Beim Lesen der obigen Richtlinien könnte man zu dem Schluss kommen, dass jedes private Modul oder Objekt mit einem Unterstrich beginnt. Das ist nicht der Fall; die Anwesenheit von Unterstrichen markiert etwas als privat, aber die Abwesenheit von Unterstrichen markiert etwas nicht als öffentlich.

In SciPy gibt es Module, deren Namen nicht mit einem Unterstrich beginnen, die aber als privat betrachtet werden sollten. Um zu verdeutlichen, um welche Module es sich handelt, definieren wir im Folgenden, was die öffentliche API für SciPy ist, und geben einige Empfehlungen, wie Module/Funktionen/Objekte aus SciPy importiert werden sollten.

Richtlinien für den Import von Funktionen aus SciPy#

Alles in den Namespaces von SciPy-Untermodulen ist öffentlich. Im Allgemeinen wird in Python empfohlen, Namespaces zu nutzen. Zum Beispiel sollte die Funktion curve_fit (definiert in scipy/optimize/_minpack_py.py) wie folgt importiert werden

import scipy
result = scipy.optimize.curve_fit(...)

Alternativ könnte man das Untermodul als Namespace wie folgt verwenden

from scipy import optimize
result = optimize.curve_fit(...)

Hinweis

Für scipy.io ist die Verwendung von import scipy zu bevorzugen, da io auch der Name eines Moduls in der Python-Standardbibliothek ist.

In einigen Fällen ist die öffentliche API eine Ebene tiefer. Zum Beispiel ist das Modul scipy.sparse.linalg öffentlich, und die darin enthaltenen Funktionen sind nicht im Namespace scipy.sparse verfügbar. Manchmal kann es zu leichter verständlichem Code führen, wenn Funktionen von einer tieferen Ebene importiert werden. Zum Beispiel ist es in den folgenden Fällen sofort ersichtlich, dass lomax eine Verteilung ist, wenn die zweite Form gewählt wird

# first form
from scipy import stats
stats.lomax(...)

# second form
from scipy.stats import distributions
distributions.lomax(...)

In diesem Fall kann die zweite Form gewählt werden, **wenn** im nächsten Abschnitt dokumentiert ist, dass das betreffende Untermodul öffentlich ist. Natürlich können Sie immer noch verwenden

import scipy
scipy.stats.lomax(...)
# or
scipy.stats.distributions.lomax(...)

Hinweis

SciPy verwendet einen Lazy-Loading-Mechanismus, was bedeutet, dass Module erst dann in den Speicher geladen werden, wenn Sie versuchen, auf sie zuzugreifen.

API-Definition#

Jedes unten aufgeführte Untermodul ist öffentlich. Das bedeutet, dass diese Untermodule wahrscheinlich nicht umbenannt oder in einer inkompatiblen Weise geändert werden, und wenn dies notwendig ist, wird eine Deprecation-Warnung für eine SciPy-Version vor der Änderung ausgegeben.

SciPy-Struktur#

Alle SciPy-Module sollten den folgenden Konventionen folgen. Im Folgenden wird ein *SciPy-Modul* als ein Python-Paket, sagen wir yyy, definiert, das sich im Verzeichnis scipy/ befindet.

  • Idealerweise sollte jedes SciPy-Modul so eigenständig wie möglich sein. Das heißt, es sollte minimale Abhängigkeiten von anderen Paketen oder Modulen haben. Selbst Abhängigkeiten von anderen SciPy-Modulen sollten auf ein Minimum beschränkt werden. Eine Abhängigkeit von NumPy wird natürlich vorausgesetzt.

  • Verzeichnis yyy/ enthält

    • Eine Datei meson.build mit der Build-Konfiguration für das Untermodul.

    • Ein Verzeichnis tests/, das Dateien test_<name>.py enthält, die den Modulen yyy/<name>{.py,.so,/} entsprechen.

  • Private Module sollten mit einem Unterstrich _ beginnen, zum Beispiel yyy/_somemodule.py.

  • Benutzerfreundliche Funktionen sollten eine gute Dokumentation im Stil der NumPy-Dokumentation aufweisen.

  • Die __init__.py des Moduls sollte die Hauptreferenzdokumentation in seinem Docstring enthalten. Diese wird über die `automodule`-Direktive von Sphinx unter doc/ mit der Sphinx-Dokumentation verbunden.

    Die Referenzdokumentation sollte zuerst eine kategorisierte Liste des Modulinhalts mit autosummary::-Direktiven liefern und danach Punkte erläutern, die für das Verständnis der Modulnutzung wesentlich sind.

    Tutorial-artige Dokumentation mit ausführlichen Beispielen sollte separat unter doc/source/tutorial/ platziert werden.

Siehe die vorhandenen SciPy-Untermodule als Anleitung.