diff --git a/docs/array.rst b/docs/array.rst new file mode 100644 index 000000000..c49ad8d64 --- /dev/null +++ b/docs/array.rst @@ -0,0 +1,29 @@ +:mod:`array` -- arrays of numeric data +====================================== + +.. module:: array + :synopsis: efficient arrays of numeric data + +|see_cpython_module| :mod:`python:array`. + +Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``, +``L``, ``q``, ``Q``, ``f``, ``d`` (the latter 2 depending on the +floating-point support). + +Classes +------- + +.. class:: array.array(typecode, [iterable]) + + Create array with elements of given type. Initial contents of the + array are given by *iterable*. If it is not provided, an empty + array is created. + + .. method:: append(val) + + Append new element *val* to the end of array, growing it. + + .. method:: extend(iterable) + + Append new elements as contained in *iterable* to the end of + array, growing it. \ No newline at end of file diff --git a/docs/builtins.rst b/docs/builtins.rst new file mode 100644 index 000000000..365248dc7 --- /dev/null +++ b/docs/builtins.rst @@ -0,0 +1,199 @@ +Builtin functions and exceptions +================================ + +All builtin functions and exceptions are described here. They are also +available via ``builtins`` module. + +Functions and types +------------------- + +.. function:: abs() + +.. function:: all() + +.. function:: any() + +.. function:: bin() + +.. class:: bool() + +.. class:: bytearray() + +.. class:: bytes() + + |see_cpython| `python:bytes`. + +.. function:: callable() + +.. function:: chr() + +.. function:: classmethod() + +.. function:: compile() + +.. class:: complex() + +.. function:: delattr(obj, name) + + The argument *name* should be a string, and this function deletes the named + attribute from the object given by *obj*. + +.. class:: dict() + +.. function:: dir() + +.. function:: divmod() + +.. function:: enumerate() + +.. function:: eval() + +.. function:: exec() + +.. function:: filter() + +.. class:: float() + +.. class:: frozenset() + +.. function:: getattr() + +.. function:: globals() + +.. function:: hasattr() + +.. function:: hash() + +.. function:: hex() + +.. function:: id() + +.. function:: input() + +.. class:: int() + + .. classmethod:: from_bytes(bytes, byteorder) + + In MicroPython, `byteorder` parameter must be positional (this is + compatible with CPython). + + .. method:: to_bytes(size, byteorder) + + In MicroPython, `byteorder` parameter must be positional (this is + compatible with CPython). + +.. function:: isinstance() + +.. function:: issubclass() + +.. function:: iter() + +.. function:: len() + +.. class:: list() + +.. function:: locals() + +.. function:: map() + +.. function:: max() + +.. class:: memoryview() + +.. function:: min() + +.. function:: next() + +.. class:: object() + +.. function:: oct() + +.. function:: open() + +.. function:: ord() + +.. function:: pow() + +.. function:: print() + +.. function:: property() + +.. function:: range() + +.. function:: repr() + +.. function:: reversed() + +.. function:: round() + +.. class:: set() + +.. function:: setattr() + +.. class:: slice() + + The *slice* builtin is the type that slice objects have. + +.. function:: sorted() + +.. function:: staticmethod() + +.. class:: str() + +.. function:: sum() + +.. function:: super() + +.. class:: tuple() + +.. function:: type() + +.. function:: zip() + + +Exceptions +---------- + +.. exception:: AssertionError + +.. exception:: AttributeError + +.. exception:: Exception + +.. exception:: ImportError + +.. exception:: IndexError + +.. exception:: KeyboardInterrupt + +.. exception:: KeyError + +.. exception:: MemoryError + +.. exception:: NameError + +.. exception:: NotImplementedError + +.. exception:: OSError + + |see_cpython| `python:OSError`. MicroPython doesn't implement ``errno`` + attribute, instead use the standard way to access exception arguments: + ``exc.args[0]``. + +.. exception:: RuntimeError + +.. exception:: StopIteration + +.. exception:: SyntaxError + +.. exception:: SystemExit + + |see_cpython| `python:SystemExit`. + +.. exception:: TypeError + + |see_cpython| `python:TypeError`. + +.. exception:: ValueError + +.. exception:: ZeroDivisionError diff --git a/docs/gc.rst b/docs/gc.rst new file mode 100644 index 000000000..c823aed3e --- /dev/null +++ b/docs/gc.rst @@ -0,0 +1,66 @@ +:mod:`gc` -- control the garbage collector +========================================== + +.. module:: gc + :synopsis: control the garbage collector + +|see_cpython_module| :mod:`python:gc`. + +Functions +--------- + +.. function:: enable() + + Enable automatic garbage collection. + +.. function:: disable() + + Disable automatic garbage collection. Heap memory can still be allocated, + and garbage collection can still be initiated manually using :meth:`gc.collect`. + +.. function:: collect() + + Run a garbage collection. + +.. function:: mem_alloc() + + Return the number of bytes of heap RAM that are allocated. + + .. admonition:: Difference to CPython + :class: attention + + This function is MicroPython extension. + +.. function:: mem_free() + + Return the number of bytes of available heap RAM, or -1 if this amount + is not known. + + .. admonition:: Difference to CPython + :class: attention + + This function is MicroPython extension. + +.. function:: threshold([amount]) + + Set or query the additional GC allocation threshold. Normally, a collection + is triggered only when a new allocation cannot be satisfied, i.e. on an + out-of-memory (OOM) condition. If this function is called, in addition to + OOM, a collection will be triggered each time after *amount* bytes have been + allocated (in total, since the previous time such an amount of bytes + have been allocated). *amount* is usually specified as less than the + full heap size, with the intention to trigger a collection earlier than when the + heap becomes exhausted, and in the hope that an early collection will prevent + excessive memory fragmentation. This is a heuristic measure, the effect + of which will vary from application to application, as well as + the optimal value of the *amount* parameter. + + Calling the function without argument will return the current value of + the threshold. A value of -1 means a disabled allocation threshold. + + .. admonition:: Difference to CPython + :class: attention + + This function is a MicroPython extension. CPython has a similar + function - ``set_threshold()``, but due to different GC + implementations, its signature and semantics are different. diff --git a/docs/math.rst b/docs/math.rst new file mode 100644 index 000000000..a6f13d48c --- /dev/null +++ b/docs/math.rst @@ -0,0 +1,185 @@ +:mod:`math` -- mathematical functions +===================================== + +.. module:: math + :synopsis: mathematical functions + +|see_cpython_module| :mod:`python:math`. + +The ``math`` module provides some basic mathematical functions for +working with floating-point numbers. + +*Note:* On the pyboard, floating-point numbers have 32-bit precision. + +Availability: not available on WiPy. Floating point support required +for this module. + +Functions +--------- + +.. function:: acos(x) + + Return the inverse cosine of ``x``. + +.. function:: acosh(x) + + Return the inverse hyperbolic cosine of ``x``. + +.. function:: asin(x) + + Return the inverse sine of ``x``. + +.. function:: asinh(x) + + Return the inverse hyperbolic sine of ``x``. + +.. function:: atan(x) + + Return the inverse tangent of ``x``. + +.. function:: atan2(y, x) + + Return the principal value of the inverse tangent of ``y/x``. + +.. function:: atanh(x) + + Return the inverse hyperbolic tangent of ``x``. + +.. function:: ceil(x) + + Return an integer, being ``x`` rounded towards positive infinity. + +.. function:: copysign(x, y) + + Return ``x`` with the sign of ``y``. + +.. function:: cos(x) + + Return the cosine of ``x``. + +.. function:: cosh(x) + + Return the hyperbolic cosine of ``x``. + +.. function:: degrees(x) + + Return radians ``x`` converted to degrees. + +.. function:: erf(x) + + Return the error function of ``x``. + +.. function:: erfc(x) + + Return the complementary error function of ``x``. + +.. function:: exp(x) + + Return the exponential of ``x``. + +.. function:: expm1(x) + + Return ``exp(x) - 1``. + +.. function:: fabs(x) + + Return the absolute value of ``x``. + +.. function:: floor(x) + + Return an integer, being ``x`` rounded towards negative infinity. + +.. function:: fmod(x, y) + + Return the remainder of ``x/y``. + +.. function:: frexp(x) + + 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. + +.. function:: gamma(x) + + Return the gamma function of ``x``. + +.. function:: isfinite(x) + + Return ``True`` if ``x`` is finite. + +.. function:: isinf(x) + + Return ``True`` if ``x`` is infinite. + +.. function:: isnan(x) + + Return ``True`` if ``x`` is not-a-number + +.. function:: ldexp(x, exp) + + Return ``x * (2**exp)``. + +.. function:: lgamma(x) + + Return the natural logarithm of the gamma function of ``x``. + +.. function:: log(x) + + Return the natural logarithm of ``x``. + +.. function:: log10(x) + + Return the base-10 logarithm of ``x``. + +.. function:: log2(x) + + Return the base-2 logarithm of ``x``. + +.. function:: modf(x) + + Return a tuple of two floats, being the fractional and integral parts of + ``x``. Both return values have the same sign as ``x``. + +.. function:: pow(x, y) + + Returns ``x`` to the power of ``y``. + +.. function:: radians(x) + + Return degrees ``x`` converted to radians. + +.. function:: sin(x) + + Return the sine of ``x``. + +.. function:: sinh(x) + + Return the hyperbolic sine of ``x``. + +.. function:: sqrt(x) + + Return the square root of ``x``. + +.. function:: tan(x) + + Return the tangent of ``x``. + +.. function:: tanh(x) + + Return the hyperbolic tangent of ``x``. + +.. function:: trunc(x) + + Return an integer, being ``x`` rounded towards 0. + +Constants +--------- + +.. data:: e + + base of the natural logarithm + +.. data:: pi + + the ratio of a circle's circumference to its diameter diff --git a/docs/sys.rst b/docs/sys.rst new file mode 100644 index 000000000..d3cc308d8 --- /dev/null +++ b/docs/sys.rst @@ -0,0 +1,142 @@ +:mod:`sys` -- system specific functions +======================================= + +.. module:: sys + :synopsis: system specific functions + +|see_cpython_module| :mod:`python:sys`. + +Functions +--------- + +.. function:: exit(retval=0) + + Terminate current program with a given exit code. Underlyingly, this + function raise as `SystemExit` exception. If an argument is given, its + value given as an argument to `SystemExit`. + +.. function:: atexit(func) + + Register *func* to be called upon termination. *func* must be a callable + that takes no arguments, or ``None`` to disable the call. The ``atexit`` + function will return the previous value set by this function, which is + initially ``None``. + + .. admonition:: Difference to CPython + :class: attention + + This function is a MicroPython extension intended to provide similar + functionality to the :mod:`atexit` module in CPython. + +.. function:: print_exception(exc, file=sys.stdout) + + Print exception with a traceback to a file-like object *file* (or + `sys.stdout` by default). + + .. admonition:: Difference to CPython + :class: attention + + This is simplified version of a function which appears in the + ``traceback`` module in CPython. Unlike ``traceback.print_exception()``, + this function takes just exception value instead of exception type, + exception value, and traceback object; *file* argument should be + positional; further arguments are not supported. CPython-compatible + ``traceback`` module can be found in `micropython-lib`. + +Constants +--------- + +.. data:: argv + + A mutable list of arguments the current program was started with. + +.. data:: byteorder + + The byte order of the system (``"little"`` or ``"big"``). + +.. data:: implementation + + Object with information about the current Python implementation. For + MicroPython, it has following attributes: + + * *name* - string "micropython" + * *version* - tuple (major, minor, micro), e.g. (1, 7, 0) + + This object is the recommended way to distinguish MicroPython from other + Python implementations (note that it still may not exist in the very + minimal ports). + + .. admonition:: Difference to CPython + :class: attention + + CPython mandates more attributes for this object, but the actual useful + bare minimum is implemented in MicroPython. + +.. data:: maxsize + + Maximum value which a native integer type can hold on the current platform, + or maximum value representable by MicroPython integer type, if it's smaller + than platform max value (that is the case for MicroPython ports without + long int support). + + This attribute is useful for detecting "bitness" of a platform (32-bit vs + 64-bit, etc.). It's recommended to not compare this attribute to some + value directly, but instead count number of bits in it:: + + bits = 0 + v = sys.maxsize + while v: + bits += 1 + v >>= 1 + if bits > 32: + # 64-bit (or more) platform + ... + else: + # 32-bit (or less) platform + # Note that on 32-bit platform, value of bits may be less than 32 + # (e.g. 31) due to peculiarities described above, so use "> 16", + # "> 32", "> 64" style of comparisons. + +.. data:: modules + + Dictionary of loaded modules. On some ports, it may not include builtin + modules. + +.. data:: path + + A mutable list of directories to search for imported modules. + +.. data:: platform + + The platform that MicroPython is running on. For OS/RTOS ports, this is + usually an identifier of the OS, e.g. ``"linux"``. For baremetal ports it + is an identifier of a board, e.g. ``"pyboard"`` for the original MicroPython + reference board. It thus can be used to distinguish one board from another. + If you need to check whether your program runs on MicroPython (vs other + Python implementation), use `sys.implementation` instead. + +.. data:: stderr + + Standard error `stream`. + +.. data:: stdin + + Standard input `stream`. + +.. data:: stdout + + Standard output `stream`. + +.. data:: version + + Python language version that this implementation conforms to, as a string. + +.. data:: version_info + + Python language version that this implementation conforms to, as a tuple of ints. + + .. admonition:: Difference to CPython + :class: attention + + Only the first three version numbers (major, minor, micro) are supported and + they can be referenced only by index, not by name. diff --git a/docs/ucollections.rst b/docs/ucollections.rst new file mode 100644 index 000000000..b833842c1 --- /dev/null +++ b/docs/ucollections.rst @@ -0,0 +1,82 @@ +:mod:`ucollections` -- collection and container types +===================================================== + +.. module:: ucollections + :synopsis: collection and container types + +|see_cpython_module| :mod:`python:collections`. + +This module implements advanced collection and container types to +hold/accumulate various objects. + +Classes +------- + +.. function:: deque(iterable, maxlen[, flags]) + + Deques (double-ended queues) are a list-like container that support O(1) + appends and pops from either side of the deque. New deques are created + using the following arguments: + + - *iterable* must be the empty tuple, and the new deque is created empty. + + - *maxlen* must be specified and the deque will be bounded to this + maximum length. Once the deque is full, any new items added will + discard items from the opposite end. + + - The optional *flags* can be 1 to check for overflow when adding items. + + As well as supporting `bool` and `len`, deque objects have the following + methods: + + .. method:: deque.append(x) + + Add *x* to the right side of the deque. + Raises IndexError if overflow checking is enabled and there is no more room left. + + .. method:: deque.popleft() + + Remove and return an item from the left side of the deque. + Raises IndexError if no items are present. + +.. function:: namedtuple(name, fields) + + This is factory function to create a new namedtuple type with a specific + name and set of fields. A namedtuple is a subclass of tuple which allows + to access its fields not just by numeric index, but also with an attribute + access syntax using symbolic field names. Fields is a sequence of strings + specifying field names. For compatibility with CPython it can also be a + a string with space-separated field named (but this is less efficient). + Example of use:: + + from ucollections import namedtuple + + MyTuple = namedtuple("MyTuple", ("id", "name")) + t1 = MyTuple(1, "foo") + t2 = MyTuple(2, "bar") + print(t1.name) + assert t2.name == t2[1] + +.. function:: OrderedDict(...) + + ``dict`` type subclass which remembers and preserves the order of keys + added. When ordered dict is iterated over, keys/items are returned in + the order they were added:: + + from ucollections import OrderedDict + + # To make benefit of ordered keys, OrderedDict should be initialized + # from sequence of (key, value) pairs. + d = OrderedDict([("z", 1), ("a", 2)]) + # More items can be added as usual + d["w"] = 5 + d["b"] = 3 + for k, v in d.items(): + print(k, v) + + Output:: + + z 1 + a 2 + w 5 + b 3 diff --git a/docs/ustruct.rst b/docs/ustruct.rst new file mode 100644 index 000000000..a6f13d48c --- /dev/null +++ b/docs/ustruct.rst @@ -0,0 +1,185 @@ +:mod:`math` -- mathematical functions +===================================== + +.. module:: math + :synopsis: mathematical functions + +|see_cpython_module| :mod:`python:math`. + +The ``math`` module provides some basic mathematical functions for +working with floating-point numbers. + +*Note:* On the pyboard, floating-point numbers have 32-bit precision. + +Availability: not available on WiPy. Floating point support required +for this module. + +Functions +--------- + +.. function:: acos(x) + + Return the inverse cosine of ``x``. + +.. function:: acosh(x) + + Return the inverse hyperbolic cosine of ``x``. + +.. function:: asin(x) + + Return the inverse sine of ``x``. + +.. function:: asinh(x) + + Return the inverse hyperbolic sine of ``x``. + +.. function:: atan(x) + + Return the inverse tangent of ``x``. + +.. function:: atan2(y, x) + + Return the principal value of the inverse tangent of ``y/x``. + +.. function:: atanh(x) + + Return the inverse hyperbolic tangent of ``x``. + +.. function:: ceil(x) + + Return an integer, being ``x`` rounded towards positive infinity. + +.. function:: copysign(x, y) + + Return ``x`` with the sign of ``y``. + +.. function:: cos(x) + + Return the cosine of ``x``. + +.. function:: cosh(x) + + Return the hyperbolic cosine of ``x``. + +.. function:: degrees(x) + + Return radians ``x`` converted to degrees. + +.. function:: erf(x) + + Return the error function of ``x``. + +.. function:: erfc(x) + + Return the complementary error function of ``x``. + +.. function:: exp(x) + + Return the exponential of ``x``. + +.. function:: expm1(x) + + Return ``exp(x) - 1``. + +.. function:: fabs(x) + + Return the absolute value of ``x``. + +.. function:: floor(x) + + Return an integer, being ``x`` rounded towards negative infinity. + +.. function:: fmod(x, y) + + Return the remainder of ``x/y``. + +.. function:: frexp(x) + + 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. + +.. function:: gamma(x) + + Return the gamma function of ``x``. + +.. function:: isfinite(x) + + Return ``True`` if ``x`` is finite. + +.. function:: isinf(x) + + Return ``True`` if ``x`` is infinite. + +.. function:: isnan(x) + + Return ``True`` if ``x`` is not-a-number + +.. function:: ldexp(x, exp) + + Return ``x * (2**exp)``. + +.. function:: lgamma(x) + + Return the natural logarithm of the gamma function of ``x``. + +.. function:: log(x) + + Return the natural logarithm of ``x``. + +.. function:: log10(x) + + Return the base-10 logarithm of ``x``. + +.. function:: log2(x) + + Return the base-2 logarithm of ``x``. + +.. function:: modf(x) + + Return a tuple of two floats, being the fractional and integral parts of + ``x``. Both return values have the same sign as ``x``. + +.. function:: pow(x, y) + + Returns ``x`` to the power of ``y``. + +.. function:: radians(x) + + Return degrees ``x`` converted to radians. + +.. function:: sin(x) + + Return the sine of ``x``. + +.. function:: sinh(x) + + Return the hyperbolic sine of ``x``. + +.. function:: sqrt(x) + + Return the square root of ``x``. + +.. function:: tan(x) + + Return the tangent of ``x``. + +.. function:: tanh(x) + + Return the hyperbolic tangent of ``x``. + +.. function:: trunc(x) + + Return an integer, being ``x`` rounded towards 0. + +Constants +--------- + +.. data:: e + + base of the natural logarithm + +.. data:: pi + + the ratio of a circle's circumference to its diameter