diff --git a/.gitignore b/.gitignore index 403fcc2997..f5edb89f0e 100644 --- a/.gitignore +++ b/.gitignore @@ -52,7 +52,7 @@ _build # Generated rst files ###################### genrst/ -autoapi/ +/autoapi/ # ctags and similar ################### diff --git a/Makefile b/Makefile index 1971076a38..842c18da5b 100644 --- a/Makefile +++ b/Makefile @@ -67,6 +67,7 @@ help: clean: rm -rf $(BUILDDIR)/* + rm -rf autoapi rm -rf $(STUBDIR) $(DISTDIR) *.egg-info html: stubs @@ -213,10 +214,10 @@ check-translate: locale/circuitpython.pot $(wildcard locale/*.po) $(PYTHON) tools/check_translations.py $^ stubs: - mkdir -p circuitpython-stubs - python tools/extract_pyi.py shared-bindings/ $(STUBDIR) - python tools/extract_pyi.py ports/atmel-samd/bindings $(STUBDIR) - python setup.py sdist + @mkdir -p circuitpython-stubs + @$(PYTHON) tools/extract_pyi.py shared-bindings/ $(STUBDIR) + @$(PYTHON) tools/extract_pyi.py ports/atmel-samd/bindings $(STUBDIR) + @$(PYTHON) setup.py -q sdist update-frozen-libraries: @echo "Updating all frozen libraries to latest tagged version." diff --git a/conf.py b/conf.py index aea84dd21d..ee65e39fb4 100644 --- a/conf.py +++ b/conf.py @@ -71,11 +71,13 @@ extensions.append('autoapi.extension') autoapi_type = 'python' # Uncomment this if debugging autoapi -# autoapi_keep_files = True -autoapi_dirs = ['circuitpython-stubs'] +autoapi_keep_files = True +autoapi_dirs = [os.path.join('circuitpython-stubs', x) for x in os.listdir('circuitpython-stubs')] +print(autoapi_dirs) autoapi_add_toctree_entry = False autoapi_options = ['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members', 'show-module-summary'] autoapi_template_dir = 'docs/autoapi/templates' +autoapi_python_use_implicit_namespaces = True # The encoding of source files. #source_encoding = 'utf-8-sig' diff --git a/docs/autoapi/templates/python/module.rst b/docs/autoapi/templates/python/module.rst new file mode 100644 index 0000000000..7ede6bdfdf --- /dev/null +++ b/docs/autoapi/templates/python/module.rst @@ -0,0 +1,93 @@ +{% if not obj.display %} +:orphan: + +{% endif %} +:mod:`{{ obj.name }}` +======={{ "=" * obj.name|length }} + +.. py:module:: {{ obj.name }} + +{% if obj.docstring %} +.. autoapi-nested-parse:: + + {{ obj.docstring|prepare_docstring|indent(3) }} + +{% endif %} + +{% block subpackages %} +{% set visible_subpackages = obj.subpackages|selectattr("display")|list %} +{% if visible_subpackages %} +.. toctree:: + :titlesonly: + :maxdepth: 3 + +{% for subpackage in visible_subpackages %} + {{ subpackage.short_name }}/index.rst +{% endfor %} + + +{% endif %} +{% endblock %} +{% block submodules %} +{% set visible_submodules = obj.submodules|selectattr("display")|list %} +{% if visible_submodules %} + +.. toctree:: + :titlesonly: + :maxdepth: 1 + +{% for submodule in visible_submodules %} + {{ submodule.short_name }}/index.rst +{% endfor %} + + +{% endif %} +{% endblock %} +{% block content %} +{% if obj.all is not none %} +{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %} +{% elif obj.type is equalto("package") %} +{% set visible_children = obj.children|selectattr("display")|list %} +{% else %} +{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %} +{% endif %} +{% if visible_children %} + +{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %} +{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %} +{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %} +{% block classes %} +{% if visible_classes %} +Classes +~~~~~~~ + +.. autoapisummary:: + +{% for klass in visible_classes %} + {{ klass.id }} +{% endfor %} + + +{% endif %} +{% endblock %} + +{% block functions %} +{% if visible_functions %} +Functions +~~~~~~~~~ + +.. autoapisummary:: + +{% for function in visible_functions %} + {{ function.id }} +{% endfor %} + + +{% endif %} +{% endblock %} +{% endif %} +{% for obj_item in visible_children %} +{{ obj_item.rendered|indent(0) }} +{% endfor %} +{% endif %} +{% endblock %} diff --git a/shared-bindings/math/__init__.c b/shared-bindings/math/__init__.c index 56155306ff..8226a08ecb 100644 --- a/shared-bindings/math/__init__.c +++ b/shared-bindings/math/__init__.c @@ -78,178 +78,170 @@ STATIC NORETURN void math_error(void) { // 1.442695040888963407354163704 is 1/_M_LN2 #define log2(x) (log(x) * 1.442695040888963407354163704) #endif - //| Constants - //| --------- - //| - //| e: Any = ... - //| """base of the natural logarithm""" - //| - //| pi: Any = ... - //| """the ratio of a circle's circumference to its diameter""" - //| - //| Functions - //| --------- - //| - //| def acos(x: Any) -> Any: - //| """Return the inverse cosine of ``x``.""" - //| ... - //| - //| def asin(x: Any) -> Any: - //| """Return the inverse sine of ``x``.""" - //| ... - //| - //| def atan(x: Any) -> Any: - //| """Return the inverse tangent of ``x``.""" - //| ... - //| - //| def atan2(y: Any, x: Any) -> Any: - //| """Return the principal value of the inverse tangent of ``y/x``.""" - //| ... - //| - //| def ceil(x: Any) -> Any: - //| """Return an integer, being ``x`` rounded towards positive infinity.""" - //| ... - //| - //| def copysign(x: Any, y: Any) -> Any: - //| """Return ``x`` with the sign of ``y``.""" - //| ... - //| - //| def cos(x: Any) -> Any: - //| """Return the cosine of ``x``.""" - //| ... - //| - //| def degrees(x: Any) -> Any: - //| """Return radians ``x`` converted to degrees.""" - //| ... - //| - //| def exp(x: Any) -> Any: - //| """Return the exponential of ``x``.""" - //| ... - //| - //| def fabs(x: Any) -> Any: - //| """Return the absolute value of ``x``.""" - //| ... - //| - //| def floor(x: Any) -> Any: - //| """Return an integer, being ``x`` rounded towards negative infinity.""" - //| ... - //| - //| def fmod(x: Any, y: Any) -> Any: - //| """Return the remainder of ``x/y``.""" - //| ... - //| - //| def frexp(x: Any) -> Any: - //| """Decomposes a floating-point number into its mantissa and exponent. - //| The returned value is the tuple ``(m, e)`` such that ``x == m * 2**e`` - //| exactly. If ``x == 0`` then the function returns ``(0.0, 0)``, otherwise - //| the relation ``0.5 <= abs(m) < 1`` holds.""" - //| ... - //| - //| def isfinite(x: Any) -> Any: - //| """Return ``True`` if ``x`` is finite.""" - //| ... - //| - //| def isinf(x: Any) -> Any: - //| """Return ``True`` if ``x`` is infinite.""" - //| ... - //| - //| def isnan(x: Any) -> Any: - //| """Return ``True`` if ``x`` is not-a-number""" - //| ... - //| - //| def ldexp(x: Any, exp: Any) -> Any: - //| """Return ``x * (2**exp)``.""" - //| ... - //| - //| def modf(x: Any) -> Any: - //| """Return a tuple of two floats, being the fractional and integral parts of - //| ``x``. Both return values have the same sign as ``x``.""" - //| ... - //| - //| def pow(x: Any, y: Any) -> Any: - //| """Returns ``x`` to the power of ``y``.""" - //| - //| def radians(x: Any) -> Any: - //| """Return degrees ``x`` converted to radians.""" - //| - //| def sin(x: Any) -> Any: - //| """Return the sine of ``x``.""" - //| ... - //| - //| def sqrt(x: Any) -> Any: - //| """Returns the square root of ``x``.""" - //| ... - //| - //| def tan(x: Any) -> Any: ... - //| """Return the tangent of ``x``.""" - //| ... - //| - //| def trunc(x: Any) -> Any: - //| """Return an integer, being ``x`` rounded towards 0.""" - //| ... - //| +//| e: Any = ... +//| """base of the natural logarithm""" +//| +//| pi: Any = ... +//| """the ratio of a circle's circumference to its diameter""" +//| + +//| def acos(x: Any) -> Any: +//| """Return the inverse cosine of ``x``.""" +//| ... +//| +//| def asin(x: Any) -> Any: +//| """Return the inverse sine of ``x``.""" +//| ... +//| +//| def atan(x: Any) -> Any: +//| """Return the inverse tangent of ``x``.""" +//| ... +//| +//| def atan2(y: Any, x: Any) -> Any: +//| """Return the principal value of the inverse tangent of ``y/x``.""" +//| ... +//| +//| def ceil(x: Any) -> Any: +//| """Return an integer, being ``x`` rounded towards positive infinity.""" +//| ... +//| +//| def copysign(x: Any, y: Any) -> Any: +//| """Return ``x`` with the sign of ``y``.""" +//| ... +//| +//| def cos(x: Any) -> Any: +//| """Return the cosine of ``x``.""" +//| ... +//| +//| def degrees(x: Any) -> Any: +//| """Return radians ``x`` converted to degrees.""" +//| ... +//| +//| def exp(x: Any) -> Any: +//| """Return the exponential of ``x``.""" +//| ... +//| +//| def fabs(x: Any) -> Any: +//| """Return the absolute value of ``x``.""" +//| ... +//| +//| def floor(x: Any) -> Any: +//| """Return an integer, being ``x`` rounded towards negative infinity.""" +//| ... +//| +//| def fmod(x: Any, y: Any) -> Any: +//| """Return the remainder of ``x/y``.""" +//| ... +//| +//| def frexp(x: Any) -> Any: +//| """Decomposes a floating-point number into its mantissa and exponent. +//| The returned value is the tuple ``(m, e)`` such that ``x == m * 2**e`` +//| exactly. If ``x == 0`` then the function returns ``(0.0, 0)``, otherwise +//| the relation ``0.5 <= abs(m) < 1`` holds.""" +//| ... +//| +//| def isfinite(x: Any) -> Any: +//| """Return ``True`` if ``x`` is finite.""" +//| ... +//| +//| def isinf(x: Any) -> Any: +//| """Return ``True`` if ``x`` is infinite.""" +//| ... +//| +//| def isnan(x: Any) -> Any: +//| """Return ``True`` if ``x`` is not-a-number""" +//| ... +//| +//| def ldexp(x: Any, exp: Any) -> Any: +//| """Return ``x * (2**exp)``.""" +//| ... +//| +//| def modf(x: Any) -> Any: +//| """Return a tuple of two floats, being the fractional and integral parts of +//| ``x``. Both return values have the same sign as ``x``.""" +//| ... +//| +//| def pow(x: Any, y: Any) -> Any: +//| """Returns ``x`` to the power of ``y``.""" +//| +//| def radians(x: Any) -> Any: +//| """Return degrees ``x`` converted to radians.""" +//| +//| def sin(x: Any) -> Any: +//| """Return the sine of ``x``.""" +//| ... +//| +//| def sqrt(x: Any) -> Any: +//| """Returns the square root of ``x``.""" +//| ... +//| +//| def tan(x: Any) -> Any: +//| """Return the tangent of ``x``.""" +//| ... +//| +//| def trunc(x: Any) -> Any: +//| """Return an integer, being ``x`` rounded towards 0.""" +//| ... +//| MATH_FUN_1_ERRCOND(sqrt, sqrt, (x < (mp_float_t)0.0)) MATH_FUN_2(pow, pow) MATH_FUN_1(exp, exp) #if MICROPY_PY_MATH_SPECIAL_FUNCTIONS -// Special functions -// ----------------- -// -// .. function:: expm1(x) -// -// Return ``exp(x) - 1``. -// +//| def expm1(x): +//| """Return ``exp(x) - 1``.""" +//| ... +//| MATH_FUN_1(expm1, expm1) -// .. function:: log2(x) -// -// Return the base-2 logarithm of ``x``. -// +//| def log2(x): +//| """Return the base-2 logarithm of ``x``.""" +//| ... +//| MATH_FUN_1_ERRCOND(log2, log2, (x <= (mp_float_t)0.0)) -// .. function:: log10(x) -// -// Return the base-10 logarithm of ``x``. -// +//| def log10(x): +//| """Return the base-10 logarithm of ``x``.""" +//| ... +//| MATH_FUN_1_ERRCOND(log10, log10, (x <= (mp_float_t)0.0)) -// .. function:: cosh(x) -// -// Return the hyperbolic cosine of ``x``. -// +//| def cosh(x): +//| """Return the hyperbolic cosine of ``x``.""" +//| ... +//| MATH_FUN_1(cosh, cosh) -// .. function:: sinh(x) -// -// Return the hyperbolic sine of ``x``. -// +//| def sinh(x): +//| """Return the hyperbolic sine of ``x``.""" +//| ... +//| MATH_FUN_1(sinh, sinh) -// .. function:: tanh(x) -// -// Return the hyperbolic tangent of ``x``. -// +//| def tanh(x): +//| """Return the hyperbolic tangent of ``x``.""" +//| ... +//| MATH_FUN_1(tanh, tanh) -// .. function:: acosh(x) -// -// Return the inverse hyperbolic cosine of ``x``. -// +//| def acosh(x): +//| """Return the inverse hyperbolic cosine of ``x``.""" +//| ... +//| MATH_FUN_1(acosh, acosh) -// .. function:: asinh(x) -// -// Return the inverse hyperbolic sine of ``x``. -// +//| def asinh(x): +//| """Return the inverse hyperbolic sine of ``x``.""" +//| ... +//| MATH_FUN_1(asinh, asinh) -// .. function:: atanh(x) -// -// Return the inverse hyperbolic tangent of ``x``. -// +//| def atanh(x): +//| """Return the inverse hyperbolic tangent of ``x``.""" +//| ... +//| MATH_FUN_1(atanh, atanh) #endif @@ -288,28 +280,28 @@ MATH_FUN_1_TO_INT(trunc, trunc) MATH_FUN_2(ldexp, ldexp) #if MICROPY_PY_MATH_SPECIAL_FUNCTIONS -// .. function:: erf(x) -// -// Return the error function of ``x``. -// +//| def erf(x): +//| """Return the error function of ``x``.""" +//| ... +//| MATH_FUN_1(erf, erf) -// .. function:: erfc(x) -// -// Return the complementary error function of ``x``. -// +//| def erfc(x): +//| """Return the complementary error function of ``x``.""" +//| ... +//| MATH_FUN_1(erfc, erfc) -// .. function:: gamma(x) -// -// Return the gamma function of ``x``. -// +//| def gamma(x): +//| """Return the gamma function of ``x``.""" +//| ... +//| MATH_FUN_1(gamma, tgamma) -// .. function:: lgamma(x) -// -// Return the natural logarithm of the gamma function of ``x``. -// +//| def lgamma(x): +//| """Return the natural logarithm of the gamma function of ``x``.""" +//| ... +//| MATH_FUN_1(lgamma, lgamma) #endif //TODO: factorial, fsum diff --git a/shared-bindings/ulab/__init__.pyi b/shared-bindings/ulab/__init__.pyi index d2ff7eb80b..e5de1391b6 100644 --- a/shared-bindings/ulab/__init__.pyi +++ b/shared-bindings/ulab/__init__.pyi @@ -1,9 +1,4 @@ - -:mod:`ulab` --- Manipulate numeric data similar to numpy -======================================================== - -.. module:: ulab - :synopsis: Manipulate numeric data similar to numpy +"""Manipulate numeric data similar to numpy `ulab` is a numpy-like module for micropython, meant to simplify and speed up common mathematical operations on arrays. The primary goal was to @@ -17,507 +12,158 @@ https://micropython-ulab.readthedocs.io/en/latest/ `ulab` is modeled after numpy, and aims to be a compatible subset where possible. Numpy's documentation can be found at -https://docs.scipy.org/doc/numpy/index.html - -.. contents:: - -.. attribute:: __version__ - -The closest corresponding version of micropython-ulab - -ulab.array -- 1- and 2- dimensional array ------------------------------------------ - -.. class:: ulab.array(values, \*, dtype=float) - - :param sequence values: Sequence giving the initial content of the array. - :param dtype: The type of array values, ``int8``, ``uint8``, ``int16``, ``uint16``, or ``float`` - - The `values` sequence can either be another ~ulab.array, sequence of numbers - (in which case a 1-dimensional array is created), or a sequence where each - subsequence has the same length (in which case a 2-dimensional array is - created). - - Passing a ~ulab.array and a different dtype can be used to convert an array - from one dtype to another. - - In many cases, it is more convenient to create an array from a function - like `zeros` or `linspace`. - - `ulab.array` implements the buffer protocol, so it can be used in many - places an `array.array` can be used. - - .. attribute:: shape - - The size of the array, a tuple of length 1 or 2 - - .. attribute:: size - - The number of elements in the array - - .. attribute:: itemsize - - The number of elements in the array - - .. method:: flatten(\*, order='C') - - :param order: Whether to flatten by rows ('C') or columns ('F') - - Returns a new `ulab.array` object which is always 1 dimensional. - If order is 'C' (the default", then the data is ordered in rows; - If it is 'F', then the data is ordered in columns. "C" and "F" refer - to the typical storage organization of the C and Fortran languages. - - .. method:: sort(\*, axis=1) - - :param axis: Whether to sort elements within rows (0), columns (1), or elements (None) - - .. method:: transpose() - - Swap the rows and columns of a 2-dimensional array - - .. method:: __add__() - - Adds corresponding elements of the two arrays, or adds a number to all - elements of the array. If both arguments are arrays, their sizes must match. - - .. method:: __sub__() - - Subtracts corresponding elements of the two arrays, or adds a number to all - elements of the array. If both arguments are arrays, their sizes must match. - - .. method:: __mul__() - - Multiplies corresponding elements of the two arrays, or multiplies - all elements of the array by a number. If both arguments are arrays, - their sizes must match. - - .. method:: __div__() - - Multiplies corresponding elements of the two arrays, or divides - all elements of the array by a number. If both arguments are arrays, - their sizes must match. - - .. method:: __pow__() - - Computes the power (x**y) of corresponding elements of the the two arrays, - or one number and one array. If both arguments are arrays, their sizes - must match. - - .. method:: __getitem__() - - Retrieve an element of the array. - - .. method:: __setitem__() - - Set an element of the array. - -Array type codes ----------------- -.. attribute:: int8 - - Type code for signed integers in the range -128 .. 127 inclusive, like the 'b' typecode of `array.array` - -.. attribute:: int16 - - Type code for signed integers in the range -32768 .. 32767 inclusive, like the 'h' typecode of `array.array` - -.. attribute:: float - - Type code for floating point values, like the 'f' typecode of `array.array` - -.. attribute:: uint8 - - Type code for unsigned integers in the range 0 .. 255 inclusive, like the 'H' typecode of `array.array` - -.. attribute:: uint16 - - Type code for unsigned integers in the range 0 .. 65535 inclusive, like the 'h' typecode of `array.array` +https://docs.scipy.org/doc/numpy/index.html""" -Basic Array defining functions ------------------------------- +class array: + """1- and 2- dimensional array""" + def __init__(self, values, *, dtype=float): + """:param sequence values: Sequence giving the initial content of the array. + :param dtype: The type of array values, ``int8``, ``uint8``, ``int16``, ``uint16``, or ``float`` -.. method:: ones(shape, \*, dtype=float) + The `values` sequence can either be another ~ulab.array, sequence of numbers + (in which case a 1-dimensional array is created), or a sequence where each + subsequence has the same length (in which case a 2-dimensional array is + created). - .. param: shape - Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) + Passing a ~ulab.array and a different dtype can be used to convert an array + from one dtype to another. - .. param: dtype - Type of values in the array + In many cases, it is more convenient to create an array from a function + like `zeros` or `linspace`. - Return a new array of the given shape with all elements set to 1. + `ulab.array` implements the buffer protocol, so it can be used in many + places an `array.array` can be used.""" + ... -.. method:: zeros + shape: tuple = ... + """The size of the array, a tuple of length 1 or 2""" - .. param: shape - Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) + size: int = ... + """The number of elements in the array""" - .. param: dtype - Type of values in the array + itemsize: int = ... + """The number of elements in the array""" - Return a new array of the given shape with all elements set to 0. + def flatten(self, *, order='C'): + """:param order: Whether to flatten by rows ('C') or columns ('F') + + Returns a new `ulab.array` object which is always 1 dimensional. + If order is 'C' (the default", then the data is ordered in rows; + If it is 'F', then the data is ordered in columns. "C" and "F" refer + to the typical storage organization of the C and Fortran languages.""" + ... + + def sort(self, *, axis=1): + """:param axis: Whether to sort elements within rows (0), columns (1), or elements (None)""" + ... + + def transpose(self): + """Swap the rows and columns of a 2-dimensional array""" + ... + + def __add__(self): + """Adds corresponding elements of the two arrays, or adds a number to all + elements of the array. If both arguments are arrays, their sizes must match.""" + ... + + def __sub__(self): + """Subtracts corresponding elements of the two arrays, or adds a number to all + elements of the array. If both arguments are arrays, their sizes must match.""" + ... + + def __mul__(self): + """Multiplies corresponding elements of the two arrays, or multiplies + all elements of the array by a number. If both arguments are arrays, + their sizes must match.""" + ... + + def __div__(self): + """Multiplies corresponding elements of the two arrays, or divides + all elements of the array by a number. If both arguments are arrays, + their sizes must match.""" + ... + + def __pow__(): + """Computes the power (x**y) of corresponding elements of the the two arrays, + or one number and one array. If both arguments are arrays, their sizes + must match.""" + ... + + def __getitem__(): + """Retrieve an element of the array.""" + ... + + def __setitem__(): + """Set an element of the array.""" + ... + +int8 = ... +"""Type code for signed integers in the range -128 .. 127 inclusive, like the 'b' typecode of `array.array`""" + +int16 = ... +"""Type code for signed integers in the range -32768 .. 32767 inclusive, like the 'h' typecode of `array.array`""" + +float = ... +"""Type code for floating point values, like the 'f' typecode of `array.array`""" + +uint8 = ... +"""Type code for unsigned integers in the range 0 .. 255 inclusive, like the 'H' typecode of `array.array`""" + +uint16 = ... +"""Type code for unsigned integers in the range 0 .. 65535 inclusive, like the 'h' typecode of `array.array`""" + +def ones(shape, *, dtype=float): + """ + .. param: shape + Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) + + .. param: dtype + Type of values in the array + + Return a new array of the given shape with all elements set to 1.""" + ... + +def zeros(shape, *, dtype): + """ + .. param: shape + Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) + + .. param: dtype + Type of values in the array + + Return a new array of the given shape with all elements set to 0.""" + ... -.. method:: eye(size, \*, dtype=float) +def eye(size, *, dtype=float): + """Return a new square array of size, with the diagonal elements set to 1 + and the other elements set to 0.""" + ... - Return a new square array of size, with the diagonal elements set to 1 - and the other elements set to 0. - -.. method:: linspace(start, stop, \*, dtype=float, num=50, endpoint=True) - - .. param: start +def linspace(start, stop, *, dtype=float, num=50, endpoint=True): + """ + .. param: start First value in the array - .. param: stop + .. param: stop Final value in the array - .. param int: num + .. param int: num Count of values in the array - .. param: dtype + .. param: dtype Type of values in the array - .. param bool: endpoint + .. param bool: endpoint Whether the ``stop`` value is included. Note that even when endpoint=True, the exact ``stop`` value may not be included due to the inaccuracy of floating point arithmetic. - Return a new 1-D array with ``num`` elements ranging from ``start`` to ``stop`` linearly. - - -:mod:`ulab.compare` --- Comparison functions -============================================ - -.. module::ulab.compare - -.. method:: clip(x1, x2, x3) - - Constrain the values from ``x1`` to be between ``x2`` and ``x3``. - ``x2`` is assumed to be less than or equal to ``x3``. - - Arguments may be ulab arrays or numbers. All array arguments - must be the same size. If the inputs are all scalars, a 1-element - array is returned. - - Shorthand for ``ulab.maximum(x2, ulab.minimum(x1, x3))`` - -.. method:: maximum(x1, x2) - - Compute the element by element maximum of the arguments. - - Arguments may be ulab arrays or numbers. All array arguments - must be the same size. If the inputs are both scalars, a number is - returned - -.. method:: minimum(x1, x2) - - Compute the element by element minimum of the arguments. - - Arguments may be ulab arrays or numbers. All array arguments - must be the same size. If the inputs are both scalars, a number is - returned - - -:mod:`ulab.vector` --- Element-by-element functions -=================================================== - -.. module:: ulab.vector - -These functions can operate on numbers, 1-D arrays, or 2-D arrays by -applying the function to every element in the array. This is typically -much more efficient than expressing the same operation as a Python loop. - -.. method:: acos - - Computes the inverse cosine function - -.. method:: acosh - - Computes the inverse hyperbolic cosine function - -.. method:: asin - - Computes the inverse sine function - -.. method:: asinh - - Computes the inverse hyperbolic sine function - -.. method:: around(a, \*, decimals) - - Returns a new float array in which each element is rounded to - ``decimals`` places. - -.. method:: atan - - Computes the inverse tangent function; the return values are in the - range [-pi/2,pi/2]. - -.. method:: atan2(y,x) - - Computes the inverse tangent function of y/x; the return values are in - the range [-pi, pi]. - -.. method:: atanh - - Computes the inverse hyperbolic tangent function - -.. method:: ceil - - Rounds numbers up to the next whole number - -.. method:: cos - - Computes the cosine function - -.. method:: erf - - Computes the error function, which has applications in statistics - -.. method:: erfc - - Computes the complementary error function, which has applications in statistics - -.. method:: exp - - Computes the exponent function. - -.. method:: expm1 - - Computes $e^x-1$. In certain applications, using this function preserves numeric accuracy better than the `exp` function. - -.. method:: floor - - Rounds numbers up to the next whole number - -.. method:: gamma - - Computes the gamma function - -.. method:: lgamma - - Computes the natural log of the gamma function - -.. method:: log - - Computes the natural log - -.. method:: log10 - - Computes the log base 10 - -.. method:: log2 - - Computes the log base 2 - -.. method:: sin - - Computes the sine - -.. method:: sinh - - Computes the hyperbolic sine - -.. method:: sqrt - - Computes the square root - -.. method:: tan - - Computes the tangent - -.. method:: tanh - - Computes the hyperbolic tangent - -:mod:`ulab.linalg` - Linear algebra functions -============================================= - -.. module:: ulab.linalg - -.. method:: cholesky(A) - - :param ~ulab.array A: a positive definite, symmetric square matrix - :return ~ulab.array L: a square root matrix in the lower triangular form - :raises ValueError: If the input does not fulfill the necessary conditions - - The returned matrix satisfies the equation m=LL* - -.. method:: det - - :param: m, a square matrix - :return float: The determinant of the matrix - - Computes the eigenvalues and eigenvectors of a square matrix - -.. method:: dot(m1, m2) - - :param ~ulab.array m1: a matrix - :param ~ulab.array m2: a matrix - - Computes the matrix product of two matrices - - **WARNING:** Unlike ``numpy``, this function cannot be used to compute the dot product of two vectors - -.. method:: eig(m) - - :param m: a square matrix - :return tuple (eigenvectors, eigenvalues): - - Computes the eigenvalues and eigenvectors of a square matrix - -.. method:: inv(m) - - :param ~ulab.array m: a square matrix - :return: The inverse of the matrix, if it exists - :raises ValueError: if the matrix is not invertible - - Computes the inverse of a square matrix - -.. method:: size(array) - - Return the total number of elements in the array, as an integer. - -.. method:: trace(m) - - :param m: a square matrix - - Compute the trace of the matrix, the sum of its diagonal elements. - -:mod:`ulab.filter` --- Filtering functions -========================================== - -.. module:: ulab.filter - -.. method:: convolve(r, c=None) - - :param ulab.array a: - :param ulab.array v: - - Returns the discrete, linear convolution of two one-dimensional sequences. - The result is always an array of float. Only the ``full`` mode is supported, - and the ``mode`` named parameter of numpy is not accepted. Note that all other - modes can be had by slicing a ``full`` result. - - Convolution filters can implement high pass, low pass, band pass, etc., - filtering operations. Convolution filters are typically constructed ahead - of time. This can be done using desktop python with scipy, or on web pages - such as https://fiiir.com/ - - Convolution is most time-efficient when both inputs are of float type. - -:mod:`ulab.fft` --- Frequency-domain functions -============================================== - -.. module:: ulab.fft - -.. method:: fft(r, c=None) - - :param ulab.array r: A 1-dimension array of values whose size is a power of 2 - :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value - :return tuple (r, c): The real and complex parts of the FFT - - Perform a Fast Fourier Transform from the time domain into the frequency domain - - See also ~ulab.extras.spectrum, which computes the magnitude of the fft, - rather than separately returning its real and imaginary parts. - -.. method:: ifft(r, c=None) - - :param ulab.array r: A 1-dimension array of values whose size is a power of 2 - :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value - :return tuple (r, c): The real and complex parts of the inverse FFT - - Perform an Inverse Fast Fourier Transform from the frequeny domain into the time domain - -:mod:`ulab.numerical` --- Numerical and Statistical functions -============================================================= - -.. module:: ulab.numerical - -Most of these functions take an "axis" argument, which indicates whether to -operate over the flattened array (None), rows (0), or columns (1). - -.. method:: argmax(array, \*, axis=None) - - Return the index of the maximum element of the 1D array - -.. method:: argmin(array, \*, axis=None) - - Return the index of the minimum element of the 1D array - -.. method:: argsort(array, \*, axis=None) - - Returns an array which gives indices into the input array from least to greatest. - -.. method:: diff(array, \*, axis=1) - - Return the numerical derivative of successive elements of the array, as - an array. axis=None is not supported. - -.. method:: flip(array, \*, axis=None) - - Returns a new array that reverses the order of the elements along the - given axis, or along all axes if axis is None. - -.. method:: max(array, \*, axis=None) - - Return the maximum element of the 1D array - -.. method:: mean(array, \*, axis=None) - - Return the mean element of the 1D array, as a number if axis is None, otherwise as an array. - -.. method:: min(array, \*, axis=None) - - Return the minimum element of the 1D array - -.. method:: roll(array, distance, \*, axis=None) - - Shift the content of a vector by the positions given as the second - argument. If the ``axis`` keyword is supplied, the shift is applied to - the given axis. The array is modified in place. - -.. method:: std(array, \*, axis=None) - - Return the standard deviation of the array, as a number if axis is None, otherwise as an array. - -.. method:: sum(array, \*, axis=None) - - Return the sum of the array, as a number if axis is None, otherwise as an array. - -.. method:: sort(array, \*, axis=0) - - Sort the array along the given axis, or along all axes if axis is None. - The array is modified in place. - -:mod:`ulab.poly` --- Polynomial functions -========================================= - -.. module:: ulab.poly - -.. method:: polyfit([x, ] y, degree) - - Return a polynomial of given degree that approximates the function - f(x)=y. If x is not supplied, it is the range(len(y)). - -.. method:: polyval(p, x) - - Evaluate the polynomial p at the points x. x must be an array. - -:mod:`ulab.extras` --- Additional functions not in numpy -======================================================== - -.. method:: spectrum(r): - - :param ulab.array r: A 1-dimension array of values whose size is a power of 2 - - Computes the spectrum of the input signal. This is the absolute value of the (complex-valued) fft of the signal. - - This function is similar to scipy's ``scipy.signal.spectrogram``. + Return a new 1-D array with ``num`` elements ranging from ``start`` to ``stop`` linearly.""" + ... diff --git a/shared-bindings/ulab/compare/__init__.pyi b/shared-bindings/ulab/compare/__init__.pyi new file mode 100644 index 0000000000..00a9eae1e6 --- /dev/null +++ b/shared-bindings/ulab/compare/__init__.pyi @@ -0,0 +1,30 @@ +"""Comparison functions""" + +def clip(x1, x2, x3): + """ + Constrain the values from ``x1`` to be between ``x2`` and ``x3``. + ``x2`` is assumed to be less than or equal to ``x3``. + + Arguments may be ulab arrays or numbers. All array arguments + must be the same size. If the inputs are all scalars, a 1-element + array is returned. + + Shorthand for ``ulab.maximum(x2, ulab.minimum(x1, x3))``""" + ... + +def maximum(x1, x2): + """ + Compute the element by element maximum of the arguments. + + Arguments may be ulab arrays or numbers. All array arguments + must be the same size. If the inputs are both scalars, a number is + returned""" + ... + +def minimum(x1, x2): + """Compute the element by element minimum of the arguments. + + Arguments may be ulab arrays or numbers. All array arguments + must be the same size. If the inputs are both scalars, a number is + returned""" + ... diff --git a/shared-bindings/ulab/extras/__init__.pyi b/shared-bindings/ulab/extras/__init__.pyi new file mode 100644 index 0000000000..4da56a5822 --- /dev/null +++ b/shared-bindings/ulab/extras/__init__.pyi @@ -0,0 +1,10 @@ +"""Additional functions not in numpy""" + +def spectrum(r): + """ + :param ulab.array r: A 1-dimension array of values whose size is a power of 2 + + Computes the spectrum of the input signal. This is the absolute value of the (complex-valued) fft of the signal. + + This function is similar to scipy's ``scipy.signal.spectrogram``.""" + ... diff --git a/shared-bindings/ulab/fft/__init__.pyi b/shared-bindings/ulab/fft/__init__.pyi new file mode 100644 index 0000000000..401ecb6445 --- /dev/null +++ b/shared-bindings/ulab/fft/__init__.pyi @@ -0,0 +1,22 @@ +"""Frequency-domain functions""" + +def fft(r, c=None): + """ + :param ulab.array r: A 1-dimension array of values whose size is a power of 2 + :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value + :return tuple (r, c): The real and complex parts of the FFT + + Perform a Fast Fourier Transform from the time domain into the frequency domain + + See also ~ulab.extras.spectrum, which computes the magnitude of the fft, + rather than separately returning its real and imaginary parts.""" + ... + +def ifft(r, c=None): + """ + :param ulab.array r: A 1-dimension array of values whose size is a power of 2 + :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value + :return tuple (r, c): The real and complex parts of the inverse FFT + + Perform an Inverse Fast Fourier Transform from the frequeny domain into the time domain""" + ... diff --git a/shared-bindings/ulab/filter/__init__.pyi b/shared-bindings/ulab/filter/__init__.pyi new file mode 100644 index 0000000000..fff404300b --- /dev/null +++ b/shared-bindings/ulab/filter/__init__.pyi @@ -0,0 +1,19 @@ +"""Filtering functions""" + +def convolve(r, c=None): + """ + :param ulab.array a: + :param ulab.array v: + + Returns the discrete, linear convolution of two one-dimensional sequences. + The result is always an array of float. Only the ``full`` mode is supported, + and the ``mode`` named parameter of numpy is not accepted. Note that all other + modes can be had by slicing a ``full`` result. + + Convolution filters can implement high pass, low pass, band pass, etc., + filtering operations. Convolution filters are typically constructed ahead + of time. This can be done using desktop python with scipy, or on web pages + such as https://fiiir.com/ + + Convolution is most time-efficient when both inputs are of float type.""" + ... diff --git a/shared-bindings/ulab/linalg/__init__.pyi b/shared-bindings/ulab/linalg/__init__.pyi new file mode 100644 index 0000000000..d16e61807b --- /dev/null +++ b/shared-bindings/ulab/linalg/__init__.pyi @@ -0,0 +1,57 @@ +"""Linear algebra functions""" + + +def cholesky(A): + """ + :param ~ulab.array A: a positive definite, symmetric square matrix + :return ~ulab.array L: a square root matrix in the lower triangular form + :raises ValueError: If the input does not fulfill the necessary conditions + + The returned matrix satisfies the equation m=LL*""" + ... + +def det(): + """ + :param: m, a square matrix + :return float: The determinant of the matrix + + Computes the eigenvalues and eigenvectors of a square matrix""" + ... + +def dot(m1, m2): + """ + :param ~ulab.array m1: a matrix + :param ~ulab.array m2: a matrix + + Computes the matrix product of two matrices + + **WARNING:** Unlike ``numpy``, this function cannot be used to compute the dot product of two vectors""" + ... + +def eig(m): + """ + :param m: a square matrix + :return tuple (eigenvectors, eigenvalues): + + Computes the eigenvalues and eigenvectors of a square matrix""" + ... + +def inv(m): + """ + :param ~ulab.array m: a square matrix + :return: The inverse of the matrix, if it exists + :raises ValueError: if the matrix is not invertible + + Computes the inverse of a square matrix""" + ... + +def size(array): + """Return the total number of elements in the array, as an integer.""" + ... + +def trace(m): + """ + :param m: a square matrix + + Compute the trace of the matrix, the sum of its diagonal elements.""" + ... diff --git a/shared-bindings/ulab/numerical/__init__.pyi b/shared-bindings/ulab/numerical/__init__.pyi new file mode 100644 index 0000000000..7596789218 --- /dev/null +++ b/shared-bindings/ulab/numerical/__init__.pyi @@ -0,0 +1,57 @@ +"""Numerical and Statistical functions + +Most of these functions take an "axis" argument, which indicates whether to +operate over the flattened array (None), rows (0), or columns (1).""" + +def argmax(array, *, axis=None): + """Return the index of the maximum element of the 1D array""" + ... + +def argmin(array, *, axis=None): + """Return the index of the minimum element of the 1D array""" + ... + +def argsort(array, *, axis=None): + """Returns an array which gives indices into the input array from least to greatest.""" + ... + +def diff(array, *, axis=1): + """Return the numerical derivative of successive elements of the array, as + an array. axis=None is not supported.""" + ... + +def flip(array, *, axis=None): + """Returns a new array that reverses the order of the elements along the + given axis, or along all axes if axis is None.""" + ... + +def max(array, *, axis=None): + """Return the maximum element of the 1D array""" + ... + +def mean(array, *, axis=None): + """Return the mean element of the 1D array, as a number if axis is None, otherwise as an array.""" + ... + +def min(array, *, axis=None): + """Return the minimum element of the 1D array""" + ... + +def roll(array, distance, *, axis=None): + """Shift the content of a vector by the positions given as the second + argument. If the ``axis`` keyword is supplied, the shift is applied to + the given axis. The array is modified in place.""" + ... + +def std(array, *, axis=None): + """Return the standard deviation of the array, as a number if axis is None, otherwise as an array.""" + ... + +def sum(array, *, axis=None): + """Return the sum of the array, as a number if axis is None, otherwise as an array.""" + ... + +def sort(array, *, axis=0): + """Sort the array along the given axis, or along all axes if axis is None. + The array is modified in place.""" + ... diff --git a/shared-bindings/ulab/poly/__init__.pyi b/shared-bindings/ulab/poly/__init__.pyi new file mode 100644 index 0000000000..d051bbded4 --- /dev/null +++ b/shared-bindings/ulab/poly/__init__.pyi @@ -0,0 +1,10 @@ +"""Polynomial functions""" + +def polyfit(x, y, degree): + """Return a polynomial of given degree that approximates the function + f(x)=y. If x is not supplied, it is the range(len(y)).""" + ... + +def polyval(p, x): + """Evaluate the polynomial p at the points x. x must be an array.""" + ... diff --git a/shared-bindings/ulab/vector/__init__.pyi b/shared-bindings/ulab/vector/__init__.pyi new file mode 100644 index 0000000000..2c7a804463 --- /dev/null +++ b/shared-bindings/ulab/vector/__init__.pyi @@ -0,0 +1,108 @@ +"""Element-by-element functions + +These functions can operate on numbers, 1-D arrays, or 2-D arrays by +applying the function to every element in the array. This is typically +much more efficient than expressing the same operation as a Python loop.""" + +def acos(): + """Computes the inverse cosine function""" + ... + +def acosh(): + """Computes the inverse hyperbolic cosine function""" + ... + +def asin(): + """Computes the inverse sine function""" + ... + +def asinh(): + """Computes the inverse hyperbolic sine function""" + ... + +def around(a, *, decimals): + """Returns a new float array in which each element is rounded to + ``decimals`` places.""" + ... + +def atan(): + """Computes the inverse tangent function; the return values are in the + range [-pi/2,pi/2].""" + ... + +def atan2(y,x): + """Computes the inverse tangent function of y/x; the return values are in + the range [-pi, pi].""" + ... + +def atanh(): + """Computes the inverse hyperbolic tangent function""" + ... + +def ceil(): + """Rounds numbers up to the next whole number""" + ... + +def cos(): + """Computes the cosine function""" + ... + +def erf(): + """Computes the error function, which has applications in statistics""" + ... + +def erfc(): + """Computes the complementary error function, which has applications in statistics""" + ... + +def exp(): + """Computes the exponent function.""" + ... + +def expm1(): + """Computes $e^x-1$. In certain applications, using this function preserves numeric accuracy better than the `exp` function.""" + ... + +def floor(): + """Rounds numbers up to the next whole number""" + ... + +def gamma(): + """Computes the gamma function""" + ... + +def lgamma(): + """Computes the natural log of the gamma function""" + ... + +def log(): + """Computes the natural log""" + ... + +def log10(): + """Computes the log base 10""" + ... + +def log2(): + """Computes the log base 2""" + ... + +def sin(): + """Computes the sine""" + ... + +def sinh(): + """Computes the hyperbolic sine""" + ... + +def sqrt(): + """Computes the square root""" + ... + +def tan(): + """Computes the tangent""" + ... + +def tanh(): + """Computes the hyperbolic tangent""" + ... diff --git a/tools/extract_pyi.py b/tools/extract_pyi.py index 95370f7619..f15f15ba67 100644 --- a/tools/extract_pyi.py +++ b/tools/extract_pyi.py @@ -6,47 +6,47 @@ import traceback top_level = sys.argv[1].strip("/") stub_directory = sys.argv[2] -if top_level.count("/") == 1: - top_level, module = top_level.split("/") - modules = [module] -else: - modules = os.listdir(top_level) - modules = sorted(modules) - -ok = 0 -total = 0 -for module in modules: - module_path = os.path.join(top_level, module) - if not os.path.isdir(module_path): - continue +def convert_folder(top_level, stub_directory): + print(top_level, stub_directory) + ok = 0 + total = 0 + filenames = sorted(os.listdir(top_level)) pyi_lines = [] - classes = os.listdir(module_path) - classes = [x for x in sorted(classes) if x.endswith(".c")] - if classes and classes[-1] == "__init__.c": - classes.insert(0, classes.pop()) - for class_file in classes: - class_path = os.path.join(module_path, class_file) - with open(class_path, "r") as f: - for line in f: - if line.startswith("//|"): - if line[3] == " ": - line = line[4:] - elif line[3] == "\n": - line = line[3:] - else: - continue - pyi_lines.append(line) + for filename in filenames: + full_path = os.path.join(top_level, filename) + file_lines = [] + if os.path.isdir(full_path): + mok, mtotal = convert_folder(full_path, os.path.join(stub_directory, filename)) + ok += mok + total += mtotal + elif filename.endswith(".c"): + with open(full_path, "r") as f: + for line in f: + if line.startswith("//|"): + if line[3] == " ": + line = line[4:] + elif line[3] == "\n": + line = line[3:] + else: + continue + file_lines.append(line) + elif filename.endswith(".pyi"): + with open(full_path, "r") as f: + file_lines.extend(f.readlines()) - raw_stubs = [x for x in sorted(classes) if x.endswith(".pyi")] - if raw_stubs and raw_stubs[-1] == "__init__.pyi": - raw_stubs.insert(0, raw_stubs.pop()) - for raw_stub in raw_stubs: - raw_stub_path = os.path.join(module_path, raw_stub) - with open(raw_stub_path, "r") as f: - pyi_lines.extend(f.readlines()) - stub_filename = os.path.join(stub_directory, module + ".pyi") + # Always put the contents from an __init__ first. + if filename.startswith("__init__."): + pyi_lines = file_lines + pyi_lines + else: + pyi_lines.extend(file_lines) + + if not pyi_lines: + return ok, total + + stub_filename = os.path.join(stub_directory, "__init__.pyi") print(stub_filename) stub_contents = "".join(pyi_lines) + os.makedirs(stub_directory, exist_ok=True) with open(stub_filename, "w") as f: f.write(stub_contents) @@ -59,6 +59,9 @@ for module in modules: e = e.__cause__ traceback.print_exception(type(e), e, e.__traceback__) print() + return ok, total + +ok, total = convert_folder(top_level, stub_directory) print(f"{ok} ok out of {total}")