kopia lustrzana https://github.com/micropython/micropython-lib
all: Update READMEs.
Jim Mussared
rodzic
1a28fe84e8
commit
af3e1aff9e
8
LICENSE
8
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 ===============
|
||||
|
|
|
|||
93
README.md
93
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=<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
|
||||
* Provide compiled .mpy distributions.
|
||||
* Develop a set of example programs using these libraries.
|
||||
* Develop more MicroPython libraries for common tasks.
|
||||
|
|
|
|||
|
|
@ -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