kopia lustrzana https://github.com/micropython/micropython-lib
all: Update READMEs.
rodzic
1a28fe84e8
commit
af3e1aff9e
8
LICENSE
8
LICENSE
|
@ -1,8 +1,8 @@
|
||||||
micropython-lib consists of multiple modules from different sources and
|
micropython-lib consists of multiple modules from different sources and
|
||||||
authors. Each module comes under its own licensing terms. Short name of
|
authors. Each module comes under its own licensing terms. The short name of
|
||||||
a license can be found in a file within a module directory (usually
|
a license can be found in a file within the module directory (usually
|
||||||
metadata.txt or setup.py). Complete text of each license used is provided
|
metadata.txt or setup.py). The complete text of each license used is provided
|
||||||
below. Files not belonging to a particular module a provided under MIT
|
below. Files not belonging to a particular module are provided under the MIT
|
||||||
license, unless explicitly stated otherwise.
|
license, unless explicitly stated otherwise.
|
||||||
|
|
||||||
=============== MIT License ===============
|
=============== MIT License ===============
|
||||||
|
|
93
README.md
93
README.md
|
@ -1,73 +1,48 @@
|
||||||
micropython-lib
|
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
|
This is a repository of libraries designed to be useful for writing
|
||||||
* ported from CPython
|
MicroPython applications.
|
||||||
* ported from some other Python implementation, e.g. PyPy
|
|
||||||
* some modules actually aren't implemented yet and are dummy
|
|
||||||
|
|
||||||
Note that the main target of micropython-lib is a "Unix" port of the
|
The libraries here fall into roughly four categories:
|
||||||
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).
|
|
||||||
|
|
||||||
|
* 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
|
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
|
Many libraries are self contained modules, and you can quickly get started by
|
||||||
URL](https://pypi.org/search/?q=&o=&c=Programming+Language+%3A%3A+Python+%3A%3A+Implementation+%3A%3A+MicroPython).
|
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
|
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.
|
||||||
`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`:
|
|
||||||
|
|
||||||
~~~~
|
For devices that have network connectivity (e.g. PYBD, ESP8266, ESP32), they
|
||||||
$ micropython -m upip install micropython-pystone
|
will have the `upip` module installed.
|
||||||
|
|
||||||
|
```
|
||||||
|
>>> import upip
|
||||||
|
>>> upip.install('micropython-base64')
|
||||||
|
>>> upip.install('micropython-collections.defaultdict')
|
||||||
...
|
...
|
||||||
$ micropython
|
>>> import base64
|
||||||
>>> import pystone
|
>>> base64.b64decode('aGVsbG8sIG1pY3JvcHl0aG9u')
|
||||||
>>> pystone.main()
|
b'hello, micropython'
|
||||||
Pystone(1.2) time for 50000 passes = 0.534
|
>>> from collections import defaultdict
|
||||||
This machine benchmarks at 93633 pystones/second
|
>>> d = defaultdict(int)
|
||||||
~~~~
|
>>> d[a] += 1
|
||||||
|
```
|
||||||
|
|
||||||
Run `micropython -m upip --help` for more information about `upip`.
|
Future plans (and new contributor ideas)
|
||||||
|
----------------------------------------
|
||||||
|
|
||||||
|
* Provide compiled .mpy distributions.
|
||||||
Development
|
* Develop a set of example programs using these libraries.
|
||||||
-----------
|
* Develop more MicroPython libraries for common tasks.
|
||||||
To install modules during development, use `make install`. By default, all
|
|
||||||
available packages will be installed. To install a specific module, add the
|
|
||||||
`MOD=<module>` 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
|
|
||||||
|
|
|
@ -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).
|
|
@ -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.
|
|
@ -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.
|
Ładowanie…
Reference in New Issue