Скаляры

Python определяет только один тип данных определённого класса (существует только один тип целых чисел, один тип чисел с плавающей точкой и т.д.). Это может быть удобно в приложениях, которым не нужно беспокоиться обо всех способах представления данных в компьютере. Однако для научных вычислений зачастую требуется больший контроль.

В NumPy существует 24 новых фундаментальных типа Python для описания различных типов скаляров. Эти описатели типов в основном основаны на типах языка C, на котором написан CPython, с несколькими дополнительными типами, совместимыми с типами Python.

Скаляры массива имеют те же атрибуты и методы, что и ndarrays. [1] Это позволяет рассматривать элементы массива частично с той же точки зрения, что и массивы, сглаживая острые углы, возникающие при смешивании операций со скалярами и массивами.

Скаляры массива находятся в иерархии (см. рисунок ниже) типов данных. Их можно обнаружить, используя иерархию: например, isinstance(val, np.generic) вернёт True, если val является объектом скаляра массива. В качестве альтернативы, можно определить, какой тип скаляра массива присутствует, используя другие члены иерархии типов данных. Таким образом, например, isinstance(val, np.complexfloating) вернёт True, если val является типом со значениями комплексных чисел, в то время как isinstance(val, np.flexible) вернёт true, если val является одним из гибких типов массива с размером элементов (str_, bytes_, void).

../_images/dtype-hierarchy.png — **Рисунок:** Иерархия объектов типа, представляющих типы данных массивов. Не показаны два целочисленных типа `intp` и `uintp`, которые используются для индексирования (такие же, как и по умолчанию, начиная с NumPy 2).

Встроенные типы скаляров

Встроенные типы скаляров представлены ниже. C-подобные имена связаны с кодами символов, которые показаны в их описаниях. Тем не менее, использование кодов символов не рекомендуется.

Некоторые типы скаляров по сути эквивалентны фундаментальным типам Python и поэтому наследуют от них, а также от общего типа скаляра массива:

Тип скаляра массива	Соответствующий тип Python	Наследует?
`int_`	`int`	Только Python 2
`double`	`float`	да
`cdouble`	`complex`	да
`bytes_`	`bytes`	да
`str_`	`str`	да
`bool_`	`bool`	нет
`datetime64`	`datetime.datetime`	нет
`timedelta64`	`datetime.timedelta`	нет

Тип данных bool_ очень похож на Python bool, но не наследует от него, так как Python bool не позволяет наследоваться от себя, а на уровне C размер фактических данных bool не такой же, как у скаляра Python Boolean.

Предупреждение

Тип int_ не наследует от встроенного типа int в Python 3, так как тип int больше не является типом целых чисел фиксированной ширины.

Подсказка

Типом данных по умолчанию в NumPy является double.

classnumpy.generic[source]

Базовый класс для типов скаляров NumPy.

Класс, от которого происходит большинство (если не все) типов скаляров NumPy. Для согласованности, экспонирует тот же API, что и ndarray, несмотря на то, что многие последующие атрибуты являются либо только для чтения, либо совершенно нерелевантными. Это класс, от которого настоятельно рекомендуется пользователям получать пользовательские типы скаляров.

classnumpy.number[source]: Абстрактный базовый класс всех числовых типов скаляров.

Целочисленные типы

классnumpy.integer[source]: Абстрактный базовый класс всех целочисленных скалярных типов.

Примечание

Целочисленные типы NumPy имитируют поведение целочисленных типов языка C и, следовательно, могут быть подвержены ошибкам переполнения.

Типы целых со знаком

классnumpy.signedinteger[source]: Абстрактный базовый класс всех скалярных типов целых чисел со знаком.

классnumpy.byte[source]

Тип целого числа со знаком, совместимый с C char.

Код символа:: 'b'
Псевдоним на этой платформе (Darwin arm64):: numpy.int8: 8-битное целое число со знаком (-128 до 127).

классnumpy.short[source]

Тип целого числа со знаком, совместимый с C short.

Код символа:: 'h'
Псевдоним на этой платформе (Darwin arm64):: numpy.int16: 16-битное целое число со знаком (-32_768 до 32_767).

классnumpy.intc[source]

Тип целого числа со знаком, совместимый с C int.

Код символа:: 'i'
Псевдоним на этой платформе (Darwin arm64):: numpy.int32: 32-битное целое число со знаком (-2_147_483_648 до 2_147_483_647).

классnumpy.int_[source]

По умолчанию тип целого числа со знаком, 64-битный на 64-битных системах и 32-битный на 32-битных системах.

Код символа:: 'l'
Псевдоним на этой платформе (Darwin arm64):: numpy.int64: 64-битное целое число со знаком (-9_223_372_036_854_775_808 до 9_223_372_036_854_775_807).
Псевдоним на этой платформе (Darwin arm64):: numpy.intp: Целое число со знаком, достаточное для хранения указателя, совместимое с C intptr_t.

numpy.long[source]: Псевдоним для int_

классnumpy.longlong[source]

Тип целого числа со знаком, совместимый с C long long.

Код символа:: 'q'

Незнаковые целочисленные типы

классnumpy.unsignedinteger[source]: Абстрактный базовый класс всех незнаковых целочисленных скалярных типов.

классnumpy.ubyte[source]

Тип незнакового целого числа, совместимый с C unsigned char.

Символьный код:: 'B'
Псевдоним на этой платформе (Darwin arm64):: numpy.uint8: 8-битное незнаковое целое число (0 до 255).

классnumpy.ushort[source]

Тип незнакового целого числа, совместимый с C unsigned short.

Символьный код:: 'H'
Псевдоним на этой платформе (Darwin arm64):: numpy.uint16: 16-битное незнаковое целое число (0 до 65_535).

классnumpy.uintc[source]

Тип незнакового целого числа, совместимый с C unsigned int.

Символьный код:: 'I'
Псевдоним на этой платформе (Darwin arm64):: numpy.uint32: 32-битное незнаковое целое число (0 до 4_294_967_295).

классnumpy.uint[source]

Тип незнакового целого числа, 64-битный на 64-битных системах и 32-битный на 32-битных системах.

Символьный код:: 'L'
Псевдоним на этой платформе (Darwin arm64):: numpy.uint64: 64-битное незнаковое целое число (0 до 18_446_744_073_709_551_615).
Псевдоним на этой платформе (Darwin arm64):: numpy.uintp: Незнаковое целое число достаточной разрядности для хранения указателя, совместимое с C uintptr_t.

numpy.ulong[source]: Псевдоним uint

классnumpy.ulonglong[source]

Тип незнакового целого числа, совместимый с C unsigned long long.

Символьный код:: 'Q'

Неточные типы

классnumpy.inexact[source]: Абстрактный базовый класс всех числовых скалярных типов с (возможно) неточной представленностью значений в своём диапазоне, например, числа с плавающей точкой.

Примечание

Неточные скаляры выводятся с наименьшим количеством десятичных знаков, необходимых для различения их значения от других значений того же типа данных, путём разумного округления. См. параметр unique format_float_positional и format_float_scientific.

Это означает, что переменные с одинаковыми двоичными значениями, но с типами данных различной точности, могут отображаться по-разному:

>>> f16 = np.float16("0.1")
>>> f32 = np.float32(f16)
>>> f64 = np.float64(f32)
>>> f16 == f32 == f64
True
>>> f16, f32, f64
(0.1, 0.099975586, 0.0999755859375)

Обратите внимание, что ни одно из этих чисел с плавающей точкой не содержит точное значение \(\frac{1}{10}\); f16 печатается как 0.1 потому, что оно максимально близко к этому значению, в то время как другие типы не так близки, так как имеют большую точность и, следовательно, имеют более близкие значения.

Напротив, числа с плавающей точкой различной точности, приближающие одно и то же десятичное значение, могут сравниваться как неравные, несмотря на то, что они выводятся одинаково:

>>> f16 = np.float16("0.1")
>>> f32 = np.float32("0.1")
>>> f64 = np.float64("0.1")
>>> f16 == f32 == f64
False
>>> f16, f32, f64
(0.1, 0.1, 0.1)

Типы с плавающей точкой

классnumpy.floating[source]: Абстрактный базовый класс всех скалярных типов с плавающей точкой.

классnumpy.half[source]

Тип числа с плавающей точкой полуточной точности.

Код символа:: 'e'
Псевдоним на этой платформе (Darwin arm64):: numpy.float16: Тип числа с плавающей точкой 16-битной точности: бит знака, 5 бит экспоненты, 10 бит мантиссы.

классnumpy.single[source]

Тип числа с плавающей точкой одинарной точности, совместимый с C float.

Код символа:: 'f'
Псевдоним на этой платформе (Darwin arm64):: numpy.float32: Тип числа с плавающей точкой 32-битной точности: бит знака, 8 бит экспоненты, 23 бита мантиссы.

классnumpy.double(x=0, /)[source]

Тип числа с плавающей точкой двойной точности, совместимый с Python float и C double.

Код символа:: 'd'
Псевдоним на этой платформе (Darwin arm64):: numpy.float64: Тип числа с плавающей точкой 64-битной точности: бит знака, 11 бит экспоненты, 52 бита мантиссы.

классnumpy.longdouble[source]

Тип числа с плавающей точкой расширенной точности, совместимый с C long double, но необязательно с IEEE 754 четырёхкратной точности.

Код символа:: 'g'

Комплексные типы с плавающей точкой

классnumpy.complexfloating[source]: Абстрактный базовый класс всех скалярных типов комплексных чисел, состоящих из чисел с плавающей точкой.

классnumpy.csingle[source]

Тип комплексного числа, составленного из двух чисел с плавающей точкой одинарной точности.

Код символа:: 'F'
Псевдоним на этой платформе (Darwin arm64):: numpy.complex64: Тип комплексного числа, составленного из 2 чисел с плавающей точкой 32-битной точности.

классnumpy.cdouble(real=0, imag=0)[source]

Тип комплексного числа, составленного из двух чисел с плавающей точкой двойной точности, совместимый с Python complex.

Код символа:: 'D'
Псевдоним на этой платформе (Darwin arm64):: numpy.complex128: Тип комплексного числа, составленного из 2 чисел с плавающей точкой 64-битной точности.

классnumpy.clongdouble[source]

Тип комплексного числа, составленного из двух чисел с плавающей точкой расширенной точности.

Код символа:: 'G'

Другие типы

numpy.bool_[source]: псевдоним для bool

classnumpy.bool[source]

Булевый тип (True или False), хранится как байт.

Предупреждение

Тип bool не является подклассом типа int_ (тип bool даже не является числовым типом). Это отличается от стандартной реализации Python bool в качестве подкласса int.

Код символа:: '?'

classnumpy.datetime64[source]

Если создан из 64-битного целого числа, представляет смещение от 1970-01-01T00:00:00. Если создан из строки, строка может быть в формате даты или даты и времени ISO 8601.

При разборе строки для создания объекта даты и времени, если строка содержит временную зону (символ ‘Z’ или смещение временной зоны), временная зона будет отброшена, и будет выведено предупреждение пользователя.

Объекты datetime64 следует рассматривать как UTC и, следовательно, иметь смещение +0000.

>>> np.datetime64(10, 'Y')
numpy.datetime64('1980')
>>> np.datetime64('1980', 'Y')
numpy.datetime64('1980')
>>> np.datetime64(10, 'D')
numpy.datetime64('1970-01-11')

См. Даты и временные интервалы для получения дополнительной информации.

Код символа:: 'M'

classnumpy.timedelta64[source]

Временной интервал, хранящийся как 64-битное целое число.

См. Даты и временные интервалы для получения дополнительной информации.

Код символа:: 'm'

classnumpy.object_[source]

Любой объект Python.

Код символа:: 'O'

Примечание

Данные, фактически хранящиеся в массивах объектов (т. е., массивах с типом object_), являются ссылками на объекты Python, а не сами объекты. Следовательно, массивы объектов ведут себя больше как обычные Python-списки, в том смысле, что их содержимое не обязательно должно быть одного типа Python.

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

Следующие типы данных являются гибкими: у них нет предопределенного размера, и данные, которые они описывают, могут иметь разную длину в разных массивах. (В кодах символов # — целое число, обозначающее количество элементов, из которых состоит тип данных.)

classnumpy.flexible[source]: Абстрактный базовый класс всех скалярных типов без предопределенной длины. Фактический размер этих типов зависит от конкретной инстанциации numpy.dtype.

classnumpy.character[source]: Абстрактный базовый класс всех скалярных типов символьных строк.

classnumpy.bytes_[source]

Строка байтов.

При использовании в массивах этот тип удаляет завершающие нулевые байты.

Код символа:: 'S'

classnumpy.str_[source]

Строка Unicode.

Этот тип удаляет завершающие нулевые кодпоинты.

>>> s = np.str_("abc\x00")
>>> s
'abc'

В отличие от встроенного str, это поддерживает Протокол буфера, представляя своё содержимое как UCS4:

>>> m = memoryview(np.str_("abc"))
>>> m.format
'3w'
>>> m.tobytes()
b'a\x00\x00\x00b\x00\x00\x00c\x00\x00\x00'

Код символа:: 'U'

classnumpy.void(length_or_data, /, dtype=None)[source]

Создание нового скаляра типа void (структурированного или неструктурированного).

Параметры:

length_or_dataint, массив-подобный, байт-подобный, объект: Несколько значений (см. примечания). Длина или байтовые данные неструктурированного типа void. Или альтернативно, данные, которые должны быть сохранены в новом скаляре, когда предоставлен dtype. Это может быть массив-подобный объект, в этом случае может быть возвращён массив.
dtypedtype, необязательно: Если указано, тип данных нового скаляра. Этот тип данных должен быть типом «void» (т. е. структурированным или неструктурированным void, см. также Структурированные типы данных).

Введено в версии 1.24.

Примечания

По историческим причинам и потому что скаляры void могут представлять как произвольные байтовые данные, так и структурированные типы данных, конструктор void имеет три варианта вызова:

np.void(5) создаёт скаляр dtype="V5", заполненный пятью \0 байтами. 5 может быть целым числом Python или NumPy.
np.void(b"bytes-like") создаёт скаляр void из строки байтов. Размер элемента dtype будет соответствовать длине строки байтов, здесь "V10".
Когда передаётся dtype= вызов примерно такой же, как создание массива. Однако возвращается скаляр void, а не массив.

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

Примеры

>>> np.void(5)
np.void(b'\x00\x00\x00\x00\x00')
>>> np.void(b'abcd')
np.void(b'\x61\x62\x63\x64')
>>> np.void((3.2, b'eggs'), dtype="d,S5")
np.void((3.2, b'eggs'), dtype=[('f0', '<f8'), ('f1', 'S5')])
>>> np.void(3, dtype=[('x', np.int8), ('y', np.int8)])
np.void((3, 3), dtype=[('x', 'i1'), ('y', 'i1')])

Код символа:: 'V'

Предупреждение

См. Примечание по строковым типам.

Числовая совместимость: Если вы использовали старые символы типа в своём коде Numeric (что никогда не рекомендулось), вам нужно будет изменить некоторые из них на новые символы. В частности, необходимые изменения — c -> S1, b -> B, 1 -> b, s -> h, w -> H, и u -> I. Эти изменения делают соглашение о символах типа более согласованным с другими модулями Python, такими как модуль struct.

Типы с фиксированным размером

Наряду с их (в основном) именами, производными от C, целочисленные, плавающие и комплексные типы данных также доступны с использованием соглашения о ширине разряда, чтобы всегда гарантировать массив нужного размера. Также предоставлены два псевдонима (numpy.intp и numpy.uintp), указывающие на целочисленный тип, достаточно большой для хранения указателя C.

numpy.int8[source]

numpy.int16

numpy.int32

numpy.int64

Псевдонимы для целочисленных типов со знаком (один из numpy.byte, numpy.short, numpy.intc, numpy.int_, numpy.long и numpy.longlong) с указанным количеством битов.

Совместимы с C99 int8_t, int16_t, int32_t, и int64_t, соответственно.

numpy.uint8[source]

numpy.uint16

numpy.uint32

numpy.uint64

Псевдоним для целочисленных типов без знака (один из numpy.ubyte, numpy.ushort, numpy.uintc, numpy.uint, numpy.ulong и numpy.ulonglong) с указанным количеством битов.

Совместимы с C99 uint8_t, uint16_t, uint32_t, и uint64_t, соответственно.

numpy.intp[source]

Псевдоним для целочисленного типа со знаком (один из numpy.byte, numpy.short, numpy.intc, numpy.int_, numpy.long и numpy.longlong), который используется по умолчанию для целых чисел и индексирования.

Совместим с C Py_ssize_t.

Код символа:: 'n'

Изменено в версии 2.0: До NumPy 2 этот тип имел такой же размер, как указатель. На практике это почти всегда идентично, но код символа 'p' отображается в C intptr_t. Код символа 'n' был добавлен в NumPy 2.0.

numpy.uintp[source]

Псевдоним для целочисленного типа без знака, размер которого такой же, как у intp.

Совместим с C size_t.

Код символа:: 'N'

Изменено в версии 2.0: До NumPy 2 этот тип имел такой же размер, как указатель. На практике это почти всегда идентично, но код символа 'P' отображается в C uintptr_t. Код символа 'N' был добавлен в NumPy 2.0.

numpy.float16[source]: псевдоним half

numpy.float32[source]: псевдоним single

numpy.float64[source]: псевдоним double

numpy.float96
numpy.float128: Псевдоним для numpy.longdouble, название которого дано по размеру в битах. Существование этих псевдонимов зависит от платформы.

numpy.complex64[source]: псевдоним csingle

numpy.complex128[source]: псевдоним cdouble

numpy.complex192
numpy.complex256: Псевдоним для numpy.clongdouble, название которого дано по размеру в битах. Существование этих псевдонимов зависит от платформы.

Атрибуты

Массивные скалярные объекты имеют array priority значение NPY_SCALAR_PRIORITY (-1 000 000,0). У них также (пока) нет атрибута ctypes. В остальном, они обладают теми же атрибутами, что и массивы:

`generic.flags`	Целое значение флагов.
`generic.shape`	Кортеж размеров массива.
`generic.strides`	Кортеж шагов в байтах для каждой размерности.
`generic.ndim`	Количество размерностей массива.
`generic.data`	Указатель на начало данных.
`generic.size`	Количество элементов в типе.
`generic.itemsize`	Длина одного элемента в байтах.
`generic.base`	Атрибут скаляра, идентичный соответствующему атрибуту массива.
`generic.dtype`	Получение описателя типа данных массива.
`generic.real`	Вещественная часть скаляра.
`generic.imag`	Мнимая часть скаляра.
`generic.flat`	Одномерный вид скаляра.
`generic.T`	Атрибут скаляра, идентичный соответствующему атрибуту массива.
`generic.__array_interface__`	Протокол массива: сторона Python
`generic.__array_struct__`	Протокол массива: структура
`generic.__array_priority__`	Приоритет массива.
`generic.__array_wrap__`	sc.__array_wrap__(obj) возвращает скаляр из массива

Индексирование

См. также

Операции индексирования, Объекты типов данных (dtype)

Массивные скаляры могут быть индексированы как 0-мерные массивы: если x - массивный скаляр,

x[()] возвращает копию массивного скаляра
x[...] возвращает 0-мерный ndarray
x['field-name'] возвращает массивный скаляр в поле имя-поля. (x может иметь поля, например, когда он соответствует структурированному типу данных.)

Методы

Массивные скаляры имеют ровно те же методы, что и массивы. По умолчанию эти методы внутренне преобразуют скаляр в эквивалентный 0-мерный массив и вызывают соответствующий метод массива. Кроме того, математические операции с массивными скалярами определены так, что те же флаги аппаратного обеспечения устанавливаются и используются для интерпретации результатов, как и для ufunc, так что состояние ошибки, используемое для ufunc, также переносится на математику над массивными скалярами.

Исключения из вышеуказанных правил приведены ниже:

`generic.__array__`	sc.__array__(dtype) возвращает 0-мерный массив из скаляра с указанным dtype
`generic.__array_wrap__`	sc.__array_wrap__(obj) возвращает скаляр из массива
`generic.squeeze`	Метод скаляра, идентичный соответствующему атрибуту массива.
`generic.byteswap`	Метод скаляра, идентичный соответствующему атрибуту массива.
`generic.__reduce__`	Служебная функция для pickle.
`generic.__setstate__`
`generic.setflags`	Метод скаляра, идентичный соответствующему атрибуту массива.

Утилитарный метод для типизации:

number.__class_getitem__(item, /)

Возвращает параметризованную оболочку вокруг типа number.

Определение новых типов

Существует два способа эффективного определения нового типа массива-скаляра (кроме составления структурированных типов dtypes из встроенных скалярных типов): Один способ - просто унаследовать от ndarray и переопределить интересующие методы. Это в какой-то степени сработает, но внутри определенные поведения фиксируются типом данных массива. Чтобы полностью настроить тип данных массива, необходимо определить новый тип данных и зарегистрировать его в NumPy. Такие новые типы могут быть определены только на C, используя NumPy C-API.

© 2005–2024 NumPy Developers
Licensed under the 3-clause BSD License.
https://numpy.org/doc/2.0/reference/arrays.scalars.html