diff --git a/LICENSE b/LICENSE index 87095e2..0e9e41d 100644 --- a/LICENSE +++ b/LICENSE @@ -1,8 +1,8 @@ micropython-lib consists of multiple modules from different sources and -authors. Each module comes under its own licensing terms. Short name of -a license can be found in a file within a module directory (usually -metadata.txt or setup.py). Complete text of each license used is provided -below. Files not belonging to a particular module a provided under MIT +authors. Each module comes under its own licensing terms. The short name of +a license can be found in a file within the module directory (usually +metadata.txt or setup.py). The complete text of each license used is provided +below. Files not belonging to a particular module are provided under the MIT license, unless explicitly stated otherwise. =============== MIT License =============== diff --git a/README.md b/README.md index 88d00ca..a38a226 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,48 @@ micropython-lib =============== -micropython-lib is a project to develop a non-monolothic standard library -for "advanced" MicroPython fork (https://github.com/pfalcon/micropython). -Each module or package is available as a separate distribution package from -PyPI. Each module comes from one of the following sources (and thus each -module has its own licensing terms): -* written from scratch specifically for MicroPython -* ported from CPython -* ported from some other Python implementation, e.g. PyPy -* some modules actually aren't implemented yet and are dummy +This is a repository of libraries designed to be useful for writing +MicroPython applications. -Note that the main target of micropython-lib is a "Unix" port of the -aforementioned fork of MicroPython. Actual system requirements vary per -module. Majority of modules are compatible with the upstream MicroPython, -though some may require additional functionality/optimizations present in -the "advanced" fork. Modules not related to I/O may also work without -problems on bare-metal ports, not just on "Unix" port (e.g. pyboard). +The libraries here fall into roughly four categories: + * Compatible ports of CPython standard libraries. These should be drop-in replacements for the CPython libraries, although many have reduced functionality or missing methods or classes (which may not be an issue for many use cases). + + * "Micro" versions of CPython standard libraries with limited compatibility. These can often provide the same functionality, but might require some code changes compared to the CPython version. + + * MicroPython-specific libraries. These include drivers and other libraries targeted at running Python on hardware or embedded systems. + + * MicroPython-on-Unix-specific libraries. These extend the functionality of the Unix port to allow access to operating-system level functionality (which allows more CPython compatibility). Usage ----- -micropython-lib packages are published on PyPI (Python Package Index), -the standard Python community package repository: https://pypi.org/ . -On PyPI, you can search for MicroPython related packages and read -additional package information. By convention, all micropython-lib package -names are prefixed with "micropython-" (the reverse is not true - some -package starting with "micropython-" aren't part of micropython-lib and -were released by 3rd parties). -Browse available packages [via this -URL](https://pypi.org/search/?q=&o=&c=Programming+Language+%3A%3A+Python+%3A%3A+Implementation+%3A%3A+MicroPython). +Many libraries are self contained modules, and you can quickly get started by +copying the relevant Python file to your device. For example, to add the +`base64` library, you can directly copy `base64/base64.py` to the `lib` +directory on your device. -To install packages from PyPI for usage on your local system, use the -`upip` tool, which is MicroPython's native package manager, similar to -`pip`, which is used to install packages for CPython. `upip` is bundled -with MicroPython "Unix" port (i.e. if you build "Unix" port, you -automatically have `upip` tool). Following examples assume that -`micropython` binary is available on your `PATH`: +Other libraries are packages, in which case you'll need to copy the directory instead. For example, to add `collections.defaultdict`, copy `collections/collections/__init__.py` and `collections.defaultdict/collections/defaultdict.py` to a directory named `lib/collections` on your device. -~~~~ -$ micropython -m upip install micropython-pystone +For devices that have network connectivity (e.g. PYBD, ESP8266, ESP32), they +will have the `upip` module installed. + +``` +>>> import upip +>>> upip.install('micropython-base64') +>>> upip.install('micropython-collections.defaultdict') ... -$ micropython ->>> import pystone ->>> pystone.main() -Pystone(1.2) time for 50000 passes = 0.534 -This machine benchmarks at 93633 pystones/second -~~~~ +>>> import base64 +>>> base64.b64decode('aGVsbG8sIG1pY3JvcHl0aG9u') +b'hello, micropython' +>>> from collections import defaultdict +>>> d = defaultdict(int) +>>> d[a] += 1 +``` -Run `micropython -m upip --help` for more information about `upip`. +Future plans (and new contributor ideas) +---------------------------------------- - -Development ------------ -To install modules during development, use `make install`. By default, all -available packages will be installed. To install a specific module, add the -`MOD=` parameter to the end of the `make install` command. - - -Links ------ -If you would like to trace evolution of MicroPython packaging support, -you may find following links useful (note that they may contain outdated -information): - - * https://github.com/micropython/micropython/issues/405 - * http://forum.micropython.org/viewtopic.php?f=5&t=70 - -Guidelines for packaging MicroPython modules for PyPI: - - * https://github.com/micropython/micropython/issues/413 +* Provide compiled .mpy distributions. +* Develop a set of example programs using these libraries. +* Develop more MicroPython libraries for common tasks. diff --git a/micropython/README.md b/micropython/README.md new file mode 100644 index 0000000..2df5de4 --- /dev/null +++ b/micropython/README.md @@ -0,0 +1,13 @@ +MicroPython-specific libraries +============================== + +These are libraries that have been written specifically for use on MicroPython. + +In some cases, the libraries are inspired by or based on equivalent CPython standard libraries, but compatibility varies. The libraries are often named with a "u" prefix. + +Other libraries have been written specifically for MicroPython use cases. + +Future plans +------------ + +* More organised directory structure based on library purpose (e.g. drivers, network, etc). diff --git a/python-stdlib/README.md b/python-stdlib/README.md new file mode 100644 index 0000000..ed7d347 --- /dev/null +++ b/python-stdlib/README.md @@ -0,0 +1,30 @@ +CPython standard libraries +========================== + +The libraries in this directory aim to provide compatible implementations of +standard libraries to allow existing Python code to run un-modified on +MicroPython. + +Compatibility ranges from: + + * Many commonly-used methods and classes are provided with identical runtime semantics. + * A subset of methods and classes, with identical semantics for most use cases. + * Additional constants not provided in the main firmware (to keep size down). + * Stub methods and classes required to make code load without error, but may lead to runtime errors. + + +Implementation +-------------- + +Many libraries are implemented in pure Python, often based on the original +CPython implementation. (e.g. `collections.defaultdict`) + +Some libraries are based on or extend from the built-in "micro" modules in the +MicroPython firmware, providing additional functionality that didn't need to +be written in C. (e.g. `socket`, `struct`) + + +Future plans (ideas for contributors): +-------------------------------------- + +* Add README.md to each library explaining compatibility and limitations. diff --git a/unix-ffi/README.md b/unix-ffi/README.md new file mode 100644 index 0000000..ae58362 --- /dev/null +++ b/unix-ffi/README.md @@ -0,0 +1,17 @@ +Unix-specific libraries +======================= + +These are libraries that will only run on the Unix port of MicroPython. There is some limited support for the Windows port too. + +**Note:** This directory is largely unmaintained, although large breaking changes are not expected. + +Background +---------- + +The libraries in this directory provide additional CPython compatibility using +the host operating system's native libraries. + +This is implemented either by accessing the libraries directly via libffi, or by using built-in modules that are only available on the Unix port. + +In theory, this allows you to use MicroPython as a more complete drop-in +replacement for CPython.