{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "reference:arrays.dtypes", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A data type object (an instance of " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.dtype", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy:dtype" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " class) describes how the bytes in the fixed-size block of memory corresponding to an array item should be interpreted. It describes the following aspects of the data:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Type of the data (integer, float, Python object, etc.)" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Size of the data (how many bytes is in " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "e.g." } ] }, { "__type": "Text", "__tag": 4046, "value": " the integer)" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Byte order of the data (" }, { "__type": "InlineCode", "__tag": 4051, "value": "little-endian" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "big-endian" }, { "__type": "Text", "__tag": 4046, "value": ")" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the data type is " }, { "__type": "InlineCode", "__tag": 4051, "value": "structured data type" }, { "__type": "Text", "__tag": 4046, "value": ", an aggregate of other data types, (" }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "e.g." } ] }, { "__type": "Text", "__tag": 4046, "value": ", describing an array item consisting of an integer and a float)," } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "what are the names of the \"" }, { "__type": "InlineCode", "__tag": 4051, "value": "fields " }, { "__type": "Text", "__tag": 4046, "value": "\" of the structure, by which they can be " }, { "__type": "CrossRef", "__tag": 4002, "value": "accessed", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "user:basics.indexing" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": "," } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "what is the data-type of each " }, { "__type": "InlineCode", "__tag": 4051, "value": "field" }, { "__type": "Text", "__tag": 4046, "value": ", and" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "which part of the memory block each field takes." } ] } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the data type is a sub-array, what is its shape and data type." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To describe the type of scalar data, there are several " }, { "__type": "CrossRef", "__tag": 4002, "value": "built-in scalar types", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:arrays.scalars" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " in NumPy for various precision of integers, floating-point numbers, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "etc" } ] }, { "__type": "Text", "__tag": 4046, "value": ". An item extracted from an array, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "e.g." } ] }, { "__type": "Text", "__tag": 4046, "value": ", by indexing, will be a Python object whose type is the scalar type associated with the data type of the array." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that the scalar types are not " }, { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " objects, even though they can be used in place of one whenever a data type specification is needed in NumPy." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Structured data types are formed by creating a data type whose " }, { "__type": "InlineCode", "__tag": 4051, "value": "field" }, { "__type": "Text", "__tag": 4046, "value": " contain other data types. Each field has a name by which it can be " }, { "__type": "CrossRef", "__tag": 4002, "value": "accessed", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "user:basics.indexing" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": ". The parent data type should be of sufficient size to contain all its fields; the parent is nearly always based on the " }, { "__type": "InlineRole", "__tag": 4003, "value": "void", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " type which allows an arbitrary item size. Structured data types may also contain nested structured sub-array data types in their fields." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Finally, a data type can describe items that are themselves arrays of items of another data type. These sub-arrays must, however, be of a fixed size." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If an array is created using a data-type describing a sub-array, the dimensions of the sub-array are appended to the shape of the array when the array is created. Sub-arrays in a field of a structured type behave differently, see " }, { "__type": "CrossRef", "__tag": 4002, "value": "arrays.indexing.fields", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "user:basics.indexing" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sub-arrays always have a C-contiguous memory layout." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A simple data type containing a 32-bit big-endian integer: (see " }, { "__type": "CrossRef", "__tag": 4002, "value": "arrays.dtypes.constructing", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:arrays.dtypes" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " for details on construction)" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The corresponding array scalar type is " }, { "__type": "InlineRole", "__tag": 4003, "value": "int32", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A structured data type containing a 16-character string (in field 'name') and a sub-array of two 64-bit floating-point number (in field 'grades'):" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Items of an array of this data type are wrapped in an " }, { "__type": "CrossRef", "__tag": 4002, "value": "array scalar", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:arrays.scalars" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " type that also has two fields:" } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Data type objects (" }, { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ")" } ], "level": 0, "target": "arrays.dtypes" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whenever a data-type is required in a NumPy function or method, either a " }, { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " object or something that can be converted to one can be supplied. Such conversions are done by the " }, { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " constructor:" } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n dtype", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "What can be converted to a data-type object is described below:" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " object" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Used as-is." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "None" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The default data type: " }, { "__type": "InlineRole", "__tag": 4003, "value": "float64", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array-scalar types" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The 24 built-in " }, { "__type": "CrossRef", "__tag": 4002, "value": "array scalar type objects", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:arrays.scalars" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " all convert to an associated data-type object. This is true for their sub-classes as well." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that not all data-type information can be supplied with a type-object: for example, " }, { "__type": "InlineRole", "__tag": 4003, "value": "flexible", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " data-types have a default " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "itemsize" } ] }, { "__type": "Text", "__tag": 4046, "value": " of 0, and require an explicitly given size to be useful." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Generic types" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The generic hierarchical type objects convert to corresponding type objects according to the associations:" } ] }, { "__type": "Code", "__tag": 4050, "value": "===================================================== ===================\n:class:`number`, :class:`inexact`, :class:`floating` :class:`float64`\n:class:`complexfloating` :class:`complex128`\n:class:`integer`, :class:`signedinteger` :class:`int\\_`\n:class:`unsignedinteger` :class:`uint`\n:class:`generic`, :class:`flexible` :class:`void`\n===================================================== ===================", "execution_status": null }, { "__type": "Admonition", "__tag": 4056, "kind": "deprecated", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "deprecated 1.19" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This conversion of generic scalar types is deprecated." } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is because it can be unexpected in a context such as " }, { "__type": "InlineCode", "__tag": 4051, "value": "arr.astype(dtype=np.floating)" }, { "__type": "Text", "__tag": 4046, "value": ", which casts an array of " }, { "__type": "InlineCode", "__tag": 4051, "value": "float32" }, { "__type": "Text", "__tag": 4046, "value": " to an array of " }, { "__type": "InlineCode", "__tag": 4051, "value": "float64" }, { "__type": "Text", "__tag": 4046, "value": ", even though " }, { "__type": "InlineCode", "__tag": 4051, "value": "float32" }, { "__type": "Text", "__tag": 4046, "value": " is a subdtype of " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.floating" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ] } ] } ] }, { "__type": "Target", "__tag": 4061, "label": "dtype-constructing-from-python-types" }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Built-in Python types" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Several Python types are equivalent to a corresponding array scalar when used to generate a " }, { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " object:" } ] }, { "__type": "Code", "__tag": 4050, "value": "=================== ===============\nPython type NumPy type\n=================== ===============\n:class:`int` :class:`int\\_`\n:class:`bool` :class:`bool\\_`\n:class:`float` :class:`float64`\n:class:`complex` :class:`complex128`\n:class:`bytes` :class:`bytes\\_`\n:class:`str` :class:`str\\_`\n:class:`memoryview` :class:`void`\n(all others) :class:`object_`\n=================== ===============", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that " }, { "__type": "InlineCode", "__tag": 4051, "value": "str_" }, { "__type": "Text", "__tag": 4046, "value": " corresponds to UCS4 encoded unicode strings." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note " } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "All other types map to " }, { "__type": "InlineCode", "__tag": 4051, "value": "object_" }, { "__type": "Text", "__tag": 4046, "value": " for convenience. Code should expect" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "that such types may map to a specific (new) dtype in the future." } ] } ] } ] } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Types with " }, { "__type": "InlineCode", "__tag": 4051, "value": ".dtype" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Any type object with a " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype" }, { "__type": "Text", "__tag": 4046, "value": " attribute: The attribute will be accessed and used directly. The attribute must return something that is convertible into a dtype object." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Several kinds of strings can be converted. Recognized strings can be prepended with " }, { "__type": "InlineCode", "__tag": 4051, "value": "'>'" }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "InlineCode", "__tag": 4051, "value": "big-endian" }, { "__type": "Text", "__tag": 4046, "value": "), " }, { "__type": "InlineCode", "__tag": 4051, "value": "'<'" }, { "__type": "Text", "__tag": 4046, "value": " (" }, { "__type": "InlineCode", "__tag": 4051, "value": "little-endian" }, { "__type": "Text", "__tag": 4046, "value": "), or " }, { "__type": "InlineCode", "__tag": 4051, "value": "'='" }, { "__type": "Text", "__tag": 4046, "value": " (hardware-native, the default), to specify the byte order." } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "One-character strings" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Each built-in data-type has a character code (the updated Numeric typecodes), that uniquely identifies it." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array-protocol type strings (see " }, { "__type": "CrossRef", "__tag": 4002, "value": "arrays.interface", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:arrays.interface" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": ")" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The first character specifies the kind of data and the remaining characters specify the number of bytes per item, except for Unicode, where it is interpreted as the number of characters, and except " }, { "__type": "InlineCode", "__tag": 4051, "value": "b1" }, { "__type": "Text", "__tag": 4046, "value": " which represents boolean. The item size must correspond to an existing type, or an error will be raised. The supported kinds are" } ] }, { "__type": "Code", "__tag": 4050, "value": "================= ========================\n``'?'``, ``'b1'`` boolean\n``'b'`` (signed) byte\n``'B'`` unsigned byte\n``'i'`` (signed) integer\n``'u'`` unsigned integer\n``'f'`` floating-point\n``'c'`` complex-floating point\n``'m'`` timedelta\n``'M'`` datetime\n``'O'`` (Python) objects\n``'S'``, ``'a'`` zero-terminated bytes (not recommended)\n``'U'`` Unicode string\n``'V'`` raw data (:class:`void`)\n================= ========================", "execution_status": null }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] }, { "__type": "Target", "__tag": 4061, "label": "string-dtype-note" }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note on string types" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For backward compatibility with existing code originally written to support" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Python 2, " }, { "__type": "InlineCode", "__tag": 4051, "value": "S" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": " typestrings are zero-terminated bytes. For unicode strings, use " }, { "__type": "InlineCode", "__tag": 4051, "value": "U" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.str_", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy:str_" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ". For signed bytes that do not need zero-termination " }, { "__type": "InlineCode", "__tag": 4051, "value": "b" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "i1" }, { "__type": "Text", "__tag": 4046, "value": " can be used." } ] } ] } ] } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "String with comma-separated fields" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A short-hand notation for specifying the format of a structured data type is a comma-separated string of basic formats." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A basic format in this context is an optional shape specifier followed by an array-protocol type string. Parenthesis are required on the shape if it has more than one dimension. NumPy allows a modification on the format in that any string that can uniquely identify the type can be used to specify the data-type in a field. The generated data-type fields are named " }, { "__type": "InlineCode", "__tag": 4051, "value": "'f0'" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "'f1'" }, { "__type": "Text", "__tag": 4046, "value": ", ..., " }, { "__type": "InlineCode", "__tag": 4051, "value": "'f'" }, { "__type": "Text", "__tag": 4046, "value": " where N (>1) is the number of comma-separated basic formats in the string. If the optional shape specifier is provided, then the data-type for the corresponding field describes a sub-array." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Type strings" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Any string name of a NumPy dtype, e.g.:" } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] } ] } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "(flexible_dtype, itemsize)" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The first argument must be an object that is converted to a zero-sized flexible data-type object, the second argument is an integer providing the desired itemsize." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "(fixed_dtype, shape)" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The first argument is any object that can be converted into a fixed-size data-type object. The second argument is the desired shape of this type. If the shape parameter is 1, then the data-type object used to be equivalent to fixed dtype. This behaviour is deprecated since NumPy 1.17 and will raise an error in the future. If " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "shape" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a tuple, then the new dtype defines a sub-array of the given shape." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] } ] } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "[(field_name, field_dtype, field_shape), ...]" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "obj" } ] }, { "__type": "Text", "__tag": 4046, "value": " should be a list of fields where each field is described by a tuple of length 2 or 3. (Equivalent to the " }, { "__type": "InlineCode", "__tag": 4051, "value": "descr" }, { "__type": "Text", "__tag": 4046, "value": " item in the " }, { "__type": "InlineRole", "__tag": 4003, "value": "~object.__array_interface__", "domain": null, "role": "obj", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " attribute.)" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The first element, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "field_name" } ] }, { "__type": "Text", "__tag": 4046, "value": ", is the field name (if this is " }, { "__type": "InlineCode", "__tag": 4051, "value": "''" }, { "__type": "Text", "__tag": 4046, "value": " then a standard field name, " }, { "__type": "InlineCode", "__tag": 4051, "value": "'f#'" }, { "__type": "Text", "__tag": 4046, "value": ", is assigned). The field name may also be a 2-tuple of strings where the first string is either a \"title\" (which may be any string or unicode string) or meta-data for the field which can be any object, and the second string is the \"name\" which must be a valid Python identifier." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The second element, " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "field_dtype" } ] }, { "__type": "Text", "__tag": 4046, "value": ", can be anything that can be interpreted as a data-type." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The optional third element " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "field_shape" } ] }, { "__type": "Text", "__tag": 4046, "value": " contains the shape if this field represents an array of the data-type in the second element. Note that a 3-tuple with a third argument equal to 1 is equivalent to a 2-tuple." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This style does not accept " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "align" } ] }, { "__type": "Text", "__tag": 4046, "value": " in the " }, { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " constructor as it is assumed that all of the memory is accounted for by the array interface description." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] } ] } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "{'names': ..., 'formats': ..., 'offsets': ..., 'titles': ..., 'itemsize': ...}" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This style has two required and three optional keys. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "names" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "formats" } ] }, { "__type": "Text", "__tag": 4046, "value": " keys are required. Their respective values are equal-length lists with the field names and the field formats. The field names must be strings and the field formats can be any object accepted by " }, { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " constructor." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When the optional keys " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "offsets" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "titles" } ] }, { "__type": "Text", "__tag": 4046, "value": " are provided, their values must each be lists of the same length as the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "names" } ] }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "formats" } ] }, { "__type": "Text", "__tag": 4046, "value": " lists. The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "offsets" } ] }, { "__type": "Text", "__tag": 4046, "value": " value is a list of byte offsets (limited to " }, { "__type": "CrossRef", "__tag": 4002, "value": "ctypes.c_int", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "ctypes", "version": "*", "kind": "api", "path": "ctypes:c_int" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ") for each field, while the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "titles" } ] }, { "__type": "Text", "__tag": 4046, "value": " value is a list of titles for each field (" }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " can be used if no title is desired for that field). The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "titles" } ] }, { "__type": "Text", "__tag": 4046, "value": " can be any object, but when a " }, { "__type": "InlineRole", "__tag": 4003, "value": "str", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " object will add another entry to the fields dictionary keyed by the title and referencing the same field tuple which will contain the title as an additional tuple member." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "itemsize" } ] }, { "__type": "Text", "__tag": 4046, "value": " key allows the total size of the dtype to be set, and must be an integer large enough so all the fields are within the dtype. If the dtype being constructed is aligned, the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "itemsize" } ] }, { "__type": "Text", "__tag": 4046, "value": " must also be divisible by the struct alignment. Total dtype " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "itemsize" } ] }, { "__type": "Text", "__tag": 4046, "value": " is limited to " }, { "__type": "CrossRef", "__tag": 4002, "value": "ctypes.c_int", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "ctypes", "version": "*", "kind": "api", "path": "ctypes:c_int" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "{'field1': ..., 'field2': ..., ...}" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This usage is discouraged, because it is ambiguous with the other dict-based construction method. If you have a field called 'names' and a field called 'formats' there will be a conflict." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This style allows passing in the " }, { "__type": "InlineRole", "__tag": 4003, "value": "fields ", "domain": null, "role": "attr", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " attribute of a data-type object." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "obj" } ] }, { "__type": "Text", "__tag": 4046, "value": " should contain string or unicode keys that refer to " }, { "__type": "InlineCode", "__tag": 4051, "value": "(data-type, offset)" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "(data-type, offset, title)" }, { "__type": "Text", "__tag": 4046, "value": " tuples." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "(base_dtype, new_dtype)" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In NumPy 1.7 and later, this form allows " }, { "__type": "InlineRole", "__tag": 4003, "value": "base_dtype", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " to be interpreted as a structured dtype. Arrays created with this dtype will have underlying dtype " }, { "__type": "InlineRole", "__tag": 4003, "value": "base_dtype", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " but will have fields and flags taken from " }, { "__type": "InlineRole", "__tag": 4003, "value": "new_dtype", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". This is useful for creating custom structured dtypes, as done in " }, { "__type": "CrossRef", "__tag": 4002, "value": "record arrays", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:arrays.classes" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This form also makes it possible to specify struct dtypes with overlapping fields, functioning like the 'union' type in C. This usage is discouraged, however, and the union mechanism is preferred." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Both arguments must be convertible to data-type objects with the same total size." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Specifying and constructing data types" } ], "level": 1, "target": "arrays.dtypes.constructing" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When checking for a specific data type, use " }, { "__type": "InlineCode", "__tag": 4051, "value": "==" }, { "__type": "Text", "__tag": 4046, "value": " comparison." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "As opposed to Python types, a comparison using " }, { "__type": "InlineCode", "__tag": 4051, "value": "is" }, { "__type": "Text", "__tag": 4046, "value": " should not be used." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "First, NumPy treats data type specifications (everything that can be passed to the " }, { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " constructor) as equivalent to the data type object itself. This equivalence can only be handled through " }, { "__type": "InlineCode", "__tag": 4051, "value": "==" }, { "__type": "Text", "__tag": 4046, "value": ", not through " }, { "__type": "InlineCode", "__tag": 4051, "value": "is" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Second, there is no guarantee that data type objects are singletons." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "admonition", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "Example" } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Checking the data type" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "NumPy data type descriptions are instances of the " }, { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " class." } ] } ], "title": [ { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": "class", "inventory": null } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The type of the data is described by the following " }, { "__type": "InlineRole", "__tag": 4003, "value": "dtype", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " attributes:" } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n dtype.type\n dtype.kind\n dtype.char\n dtype.num\n dtype.str", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Size of the data is in turn described by:" } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n dtype.name\n dtype.itemsize", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Endianness of this data:" } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n dtype.byteorder", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Information about sub-data-types in a " }, { "__type": "InlineCode", "__tag": 4051, "value": "structured data type" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n dtype.fields\n dtype.names", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For data types that describe sub-arrays:" } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n dtype.subdtype\n dtype.shape", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Attributes providing additional information:" } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n dtype.hasobject\n dtype.flags\n dtype.isbuiltin\n dtype.isnative\n dtype.descr\n dtype.alignment\n dtype.base", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Metadata attached by the user:" } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n\n dtype.metadata\n", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Attributes" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Data types have the following method for changing the byte order:" } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n dtype.newbyteorder", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The following methods implement the pickle protocol:" } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n dtype.__reduce__\n dtype.__setstate__", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Utility method for typing:" } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n dtype.__class_getitem__", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Comparison operations:" } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n dtype.__ge__\n dtype.__gt__\n dtype.__le__\n dtype.__lt__", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Methods" } ], "level": 2, "target": null } ], "local_refs": [] }