Commit 12e03550 authored by Pierre Augier's avatar Pierre Augier
Browse files

Update doc to describe typing

parent cd044adff5b4
......@@ -227,6 +227,9 @@ signatures using in Transonic type variables and/or Pythran types in strings
Moreover, it is possible to mix type hints and :code:`# transonic def`
commands.
See also our API to define types in `transonic.typing
<https://transonic.readthedocs.io/en/latest/generated/transonic.typing.html>`_.
More information when targetting Cython
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......
Short term (Milestones for 0.4.0)
---------------------------------
Full support of https://pythran.readthedocs.io/en/latest/MANUAL.html#concerning-pythran-specifications
- Tuple
- mem_layout for arrays (C, F, C_or_F, strided)
- fixed dimension for arrays
- alternative make_header_from_fdef_annotations for Cython
setup.py & more than one backend at runtime
-------------------------------------------
......@@ -21,6 +16,15 @@ Good example: https://github.com/martibosch/pylandstats/pull/1
- ``TRANSONIC_BACKEND`` changes only ``backend_default``
- Examples setup.py in documentation
More typing
-----------
Full support of https://pythran.readthedocs.io/en/latest/MANUAL.html#concerning-pythran-specifications
- fixed dimension for arrays
Specify backend in code
-----------------------
......
......@@ -16,6 +16,12 @@ Moreover, you can write:
Yes, this one is neat!
.. note::
Note that the array types ``A`` and ``A1`` are bound. When ``A.ndim == 1``,
then ``A1.ndim == 2``, and when ``A.ndim == 3``, then ``A1.ndim == 4``. No
signatures are produced for ``A.ndim == 1``, ``A1.ndim == 4``.
Note that one can also just write Pythran type-string in type annotations::
@boost
......@@ -33,9 +39,26 @@ Which has actually the same effect as::
A = "float[:, :, :]"
But, one can also specify the memory layout, for example for a C-order array
and a strided array::
A = Array[float, "3d", "C"]
A_strided = Array[float, "3d", "strided"]
Oh, and you can also write::
import numpy as np
from transonic import str2type, typeof
T = str2type("(int, float)") # a tuple
A = typeof(np.empty((2, 2)))
There is also an ``Union`` "type" that can be used similarly as `typing.Union
<https://docs.python.org/3/library/typing.html#typing.Union>`__::
from transonic import Array, Union
U = Union[float, Array[float, "3d"]]
All Transonic types are defined in the module :mod:`transonic.typing`.
......@@ -6,11 +6,9 @@ User API
.. autoclass:: Type
:members:
:private-members:
.. autoclass:: NDim
:members:
:private-members:
.. autoclass:: Array
:members:
......@@ -20,10 +18,18 @@ User API
:members:
:private-members:
.. autoclass:: Tuple
:members:
:private-members:
.. autoclass:: Dict
:members:
:private-members:
.. autoclass:: Set
:members:
:private-members:
.. autoclass:: Union
:members:
:private-members:
......@@ -130,7 +136,12 @@ class TemplateVar:
class Type(TemplateVar):
"""Template variable representing the dtype of an array"""
"""Template variable representing the dtype of an array.
As a user, it is useful only for fused types.
>>> T = Type(int, float)
"""
def __repr__(self):
return self.__name__
......@@ -151,7 +162,14 @@ class Type(TemplateVar):
class NDim(TemplateVar):
"""Template variable representing the number of dimension of an array"""
"""Template variable representing the number of dimension of an array.
As a user, it is useful only for fused types.
>>> N = NDim(1, 2)
>>> N1 = N + 1
"""
_type_values = int
_letter = "N"
......@@ -198,11 +216,15 @@ class NDim(TemplateVar):
class UnionVar(TemplateVar):
"""TemplateVar used for the Union type"""
_type_values = type
_letter = "U"
class Meta(type):
"""Type of the Transonic types (used to create metaclasses)"""
def __call__(cls, *args, **kwargs):
raise RuntimeError("Transonic types are not meant to be instantiated")
......@@ -218,7 +240,7 @@ class MemLayout(Enum):
class ArrayMeta(Meta):
"""Metaclass for the Array class used for type hinname_calling_module"""
"""Metaclass for the Array class"""
def __getitem__(self, parameters):
......@@ -370,7 +392,19 @@ class ArrayMeta(Meta):
class Array(metaclass=ArrayMeta):
"""Represent a Numpy array in type hinname_calling_module"""
"""Represent a Numpy array.
>>> Array[int, "2d"]
>>> Array[int, "2d", "C"]
>>> Array[int, "2d", "F"]
>>> Array[int, "2d", "strided"]
Fused types:
>>> Array[Type(int, float), "1d"]
>>> Array[float, NDim(2, 3)]
"""
class UnionMeta(Meta):
......@@ -582,6 +616,9 @@ class Tuple(metaclass=TupleMeta):
def format_type_as_backend_type(type_, backend_type_formatter, **kwargs):
"""Format a Transonic type as a backend (Pythran, Cython, ...) type
"""
if isinstance(type_, str):
type_ = str2type(type_)
......@@ -614,6 +651,13 @@ def analyze_array_type(str_type):
def str2type(str_type):
"""Compute a Transonic type from a string
>>> str2type("int[:,:]")
>>> str2type("int or float[]")
>>> str2type("(int, float[:, :])")
"""
str_type = str_type.strip()
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment