API SciPy

Импорт из SciPy

В Python различие между публичным API библиотеки и приватными деталями реализации не всегда ясно. В отличие от других языков, таких как Java, в Python возможно обращаться к "приватным" функциям или объектам. Иногда это может быть удобно, но имейте в виду, что если вы это сделаете, ваш код может сломаться без предупреждения в будущих выпусках. Некоторые широко принятые правила о том, что является публичным, а что нет в Python:

• Методы / функции / классы и атрибуты модуля, имена которых начинаются с ведущего подчёркивания, являются приватными.

• Если имя класса начинается с подчёркивания, ни один из его членов не является публичным, независимо от того, начинаются ли они с подчёркивания.

• Если имя модуля в пакете начинается с подчёркивания, ни один из его членов не является публичным, независимо от того, начинаются ли они с подчёркивания.

• Если модуль или пакет определяет __all__, который авторитетно определяет публичный интерфейс.

• Если модуль или пакет не определяет __all__, тогда все имена, которые не начинаются с подчёркивания, являются публичными.

Примечание

Читая приведенные выше рекомендации, можно сделать вывод, что каждый частный модуль или объект начинается с подчеркивания. Это не так; наличие подчеркиваний действительно отмечает что-то как частное, но отсутствие подчеркиваний не отмечает что-то как публичное.

В SciPy есть модули, имена которых не начинаются с подчеркивания, но которые следует считать приватными. Чтобы уточнить, какие это модули, мы определяем ниже, что является публичным API для SciPy, и даем некоторые рекомендации по импорту модулей/функций/объектов из SciPy.

Рекомендации по импорту функций из SciPy

Всё в пространствах имён подмодулей SciPy является публичным. В целом в Python рекомендуется использовать пространства имён. Например, функция curve_fit (определено в scipy/optimize/_minpack_py.py) следует импортировать так:

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

Или, как вариант, можно использовать подмодуль как пространство имён следующим образом:

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

Примечание

Для scipy.io предпочитают использование import scipy потому что io также является именем модуля в стандартной библиотеке Python.

В некоторых случаях публичный API находится на один уровень глубже. Например, scipy.sparse.linalg модуль является публичным, и содержащиеся в нем функции не доступны в scipy.sparse пространство имён. Иногда код может быть более понятным, если функции импортируются на один уровень глубже. Например, в следующем примере сразу понятно, что lomax является распределением, если выбран второй вид:

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

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

В этом случае можно выбрать вторую форму if в следующем разделе документировано, что рассматриваемый подмодуль является публичным. Конечно, вы всё ещё можете использовать:

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

Примечание

SciPy использует механизм ленивой загрузки, что означает, что модули загружаются в память только при первой попытке доступа к ним.

Определение API

Все перечисленные ниже подмодули являются публичными. Это означает, что эти подмодули вряд ли будут переименованы или изменены несовместимым образом, и если это необходимо, предупреждение об устаревании будет выдано в течение одного выпуска SciPy перед внесением изменений.

• scipy

• scipy.cluster

  • scipy.cluster.vq

  • scipy.cluster.hierarchy

• scipy.constants

• scipy.datasets

• scipy.differentiate

• scipy.fft

• scipy.fftpack

• scipy.integrate

• scipy.interpolate

• scipy.io

  • scipy.io.arff

  • scipy.io.matlab

  • scipy.io.wavfile

• scipy.linalg

  • scipy.linalg.blas

  • scipy.linalg.cython_blas

  • scipy.linalg.lapack

  • scipy.linalg.cython_lapack

  • scipy.linalg.interpolative

• scipy.ndimage

• scipy.odr

• scipy.optimize

  • scipy.optimize.cython_optimize

• scipy.signal

  • scipy.signal.windows

• scipy.sparse

  • scipy.sparse.linalg

  • scipy.sparse.csgraph

• scipy.spatial

  • scipy.spatial.distance

  • scipy.spatial.transform

• scipy.special

• scipy.stats

  • scipy.stats.contingency

  • scipy.stats.distributions

  • scipy.stats.mstats

  • scipy.stats.qmc

  • scipy.stats.sampling

Структура SciPy

Все модули SciPy должны следовать следующим соглашениям. В следующем, a Модуль SciPy определяется как пакет Python, например, yyy, который находится в директории scipy/.

• В идеале каждый модуль SciPy должен быть максимально самодостаточным. То есть он должен иметь минимальные зависимости от других пакетов или модулей. Даже зависимости от других модулей SciPy должны быть сведены к минимуму. Зависимость от NumPy, конечно, предполагается.

• Директория yyy/ содержит:

  • Файл meson.build с конфигурацией сборки для подмодуля.

  • Каталог tests/ который содержит файлы test_.py соответствующие модулям yyy/{.py,.so,/}.

• Приватные модули должны иметь префикс с подчеркиванием _, например yyy/_somemodule.py.

• Функции, видимые пользователю, должны иметь хорошую документацию, следующую Стиль документации NumPy.

• The __init__.py модуля должен содержать основную справочную документацию в своей строке документации. Это связано с документацией Sphinx под doc/ через директиву automodule Sphinx.

  Справочная документация должна сначала давать категоризированный список содержимого модуля, используя autosummary:: директивы, и после этого объяснить моменты, важные для понимания использования модуля.

  Учебная документация с обширными примерами должна быть отдельной и размещена под doc/source/tutorial/.

Смотрите существующие подмодули SciPy для руководства.