Overview of MicroPython Differences from Standard Python
=========================================================

MicroPython does not support the entire Python standard library. If a
module is missing it will be due to the in-applicability of that
module for use in an embedded controller. High memory consumption
(e.g. sqlite3) or a lack of a certain required hardware feature (e.g.
multiprocessing) are reasons that some modules can not be implemented
for some microcontrollers. The full list of standard python libraries
can be found here: `Python 3.4 standard lib`_

There are several differences between CPython3 (considered to be a
reference implementation of the Python3 language) and MicroPython.
These differences are classified into 3 categories, each category
having a different status regarding the possibility that items
belonging to it will change.


Differences By Design
---------------------

MicroPython is intended for constrained environments, in particular,
microcontrollers, which have orders of magnitude less performance and
memory than "desktop" systems on which CPython3 runs. This means that
MicroPython must be designed with this constrained environment in
mind, leaving out features which simply won't fit, or won't scale,
with target systems. "By design" differences are unlikely to change.


#. MicroPython does not ship with an extensive standard library of
   modules. It's not possible and does not make sense, to provide the
   complete CPython3 library. Many modules are not usable or useful in
   the context of embedded systems, and there is not enough memory to
   deploy the entire library on small devices. So MicroPython takes the
   minimalist approach - only core datatypes (plus modules specific to
   particular hardware) are included with the interpreter, and all the
   rest is left as 3rd-party dependencies for particular user
   applications. The `micropython-lib`_ project provides a non-monolithic
   standard library for MicroPython (`forum`_)
#. Unlike CPython3, which uses reference-counting, MicroPython uses
   garbage collection as the primary means of memory management.
#. MicroPython does not implement complete CPython object data model,
   but only a subset of it. Advanced usages of multiple inheritance,
   `__new__` method may not work. Method resolution order is different
   (#525). Metaclasses are not supported (at least yet).
#. MicroPython design is not based around descriptor objects. So far,
   we were able to implement all native Python features (like properties)
   without explicit descriptors. Descriptors are considered "overdynamic"
   feature, and conflicts with the aim of being fast and efficient.
   However, simplified support for descriptors is now implemented, as an
   opt-in feature.
#. By virtue of being "micro", MicroPython implements only subset of
   functionality and parameters of particular functions and classes. Each
   specific issue may be treated as "implementation difference" and
   resolved, but there unlikely will ever be 100% coverage of CPython
   features.
#. By virtue of being "micro", MicroPython supports only minimal
   subset of introspection and reflection features (such as object names,
   docstrings, etc.). Each specific feature may be treated as
   "implementation difference" and resolved, but there unlikely will ever
   be 100% coverage of CPython features.
#. print() function does not check for recursive data structures in
   the same way CPython does. There's however checks for stack usage, so
   printing recursive data structure won't lead to crash due to stack
   overflow. Note that it's possible to implement more CPython-like
   handling of recursive data structures on the Python application level.
   Do this by writing a function which keeps the history of each object
   visited, and override the builtin print() with your custom function.
   Such an implementation may of course use a lot of memory, which is why
   it's not implemented at the MicroPython level.
#. MicroPython optimizes local variable handling and does not record
   or provide any introspection info for them, e.g. locals() doesn't have
   entries for locals.


Implementation Differences
--------------------------

Some features don't cater for constrained systems, and at the same
time are not easy to implement efficiently, or at all. Such features
are known as "implementation differences" and some of them are
potentially the subject for future development (after corresponding
discussion and consideration). Note that many of them would affect the
size and performance of any given MicroPython implementation, so
sometimes not implementing a specific feature is identified by
MicroPython's target usage.


#. Unicode support is work in progress. It is based on internal
   representation using UTF-8. Strings containing Unicode escapes in the
   \xNN, \uNNNN, and \U000NNNNN forms are fully supported; \N{...} is not
   supported. `#695`_.
#. Subclassing of builtin types is partially implemented, but there
   may be various differences and compatibility issues with CPython.
   `#401`_
#. Buffered I/O streams (io.TextIOWrapper and superclasses) are not
   supported.
#. `async def` keyword is implemented with the following
   simplifications: there's no separate "coroutine" object type, `async
   def` just defines a generator function without requirement for "yield"
   or "yield from" to appear in function body. Usage of "yield" or "yield
   from" in `async def` function is not detected or banned.
#. `async with` should be equivalent to `PEP492 description`_.
#. `async for` should be equivalent to `PEP492 description`_.
#. There's no support for "Future-like objects" with `__await__`
   method. `await` can be used only on coroutines and generators (not
   "Future-like objects"). It's also just a syntactic sugar for "yield
   from" and thus accepts iterables and iterators, which are not allowed
   in CPython.
#. Instance `__dict__` support is optional (disabled in many ports)
   and read-only, so `foo.__dict__['bar'] = 23` or
   `foo.__dict__.update({'bar': 23})` does not work. `#1757`_ `#2139`_



Known Issues
------------

Known issues are essentially bugs, misfeatures, and omissions
considered such, and scheduled to be fixed. So, ideally any entry here
should be accompanied by bug ticket reference. But note that these
known issues will have different priorities, especially within wider
development process. So if you are actually affected by some issue,
please add details of your case to the ticket (or open it if does not
yet exist) to help planning. Submitting patches is even more
productive. (Please note that the list of not implemented
modules/classes include only those which are considered very important
to implement; per the above, MicroPython does not provide full
standard library in general.)


#. Currently, it's not possible to override sys.stdin, sys.stdout,
   sys.stderr (for efficiency, they are stored in read-only memory).
#. str.format() may miss few advanced/obscure features (but otherwise
   almost completely implemented). `#407`_, `#574`_
#. Instead of `re` module, minimified "ure" module is provided is
   subset of functionality. micropython-lib also offers more complete
   implementation based on PCRE engine, for "unix" port `#13`_
#. Only beginning of `io` module and class hierarchy exists so far.
#. `collections.deque` class is not implemented.
#. Container slice assignment/deletion is only partially implemented.
   `#509`_
#. 3-argument slicing is only partially implemented.
#. Only basic support for `__new__` method is available `#606`_,
   `#622`_.

.. _Python 3.4 standard lib: https://docs.python.org/3.4/library/index.html
.. _micropython-lib: https://github.com/micropython/micropython-lib
.. _forum: http://forum.micropython.org/viewtopic.php?f=5&t=70
.. _#695: https://github.com/micropython/micropython/issues/695
.. _#245: https://github.com/micropython/micropython/issues/245
.. _#401: https://github.com/micropython/micropython/issues/401
.. _PEP492 description: https://www.python.org/dev/peps/pep-0492/#asynchronous-context-managers-and-async-with
.. _#1757: https://github.com/micropython/micropython/issues/1757
.. _#2139: https://github.com/micropython/micropython/issues/2139
.. _#407: https://github.com/micropython/micropython/issues/407
.. _#574: https://github.com/micropython/micropython/issues/574
.. _#13: https://github.com/micropython/micropython/issues/13
.. _#509: https://github.com/micropython/micropython/issues/509
.. _#606: https://github.com/micropython/micropython/issues/606
.. _#622: https://github.com/micropython/micropython/issues/622