Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 56603ed

Browse files
committed
all: Update READMEs.
1 parent f271ec9 commit 56603ed

File tree

5 files changed

+99
-64
lines changed

5 files changed

+99
-64
lines changed

‎LICENSE‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
micropython-lib consists of multiple modules from different sources and
2-
authors. Each module comes under its own licensing terms. Short name of
3-
a license can be found in a file within a module directory (usually
4-
metadata.txt or setup.py). Complete text of each license used is provided
5-
below. Files not belonging to a particular module a provided under MIT
2+
authors. Each module comes under its own licensing terms. The short name of
3+
a license can be found in a file within the module directory (usually
4+
metadata.txt or setup.py). The complete text of each license used is provided
5+
below. Files not belonging to a particular module are provided under the MIT
66
license, unless explicitly stated otherwise.
77

88
=============== MIT License ===============

‎README.md‎

Lines changed: 35 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,48 @@
11
micropython-lib
22
===============
3-
micropython-lib is a project to develop a non-monolothic standard library
4-
for "advanced" MicroPython fork (https://github.com/pfalcon/micropython).
5-
Each module or package is available as a separate distribution package from
6-
PyPI. Each module comes from one of the following sources (and thus each
7-
module has its own licensing terms):
83

9-
* written from scratch specifically for MicroPython
10-
* ported from CPython
11-
* ported from some other Python implementation, e.g. PyPy
12-
* some modules actually aren't implemented yet and are dummy
4+
This is a repository of libraries designed to be useful for writing
5+
MicroPython applications.
136

14-
Note that the main target of micropython-lib is a "Unix" port of the
15-
aforementioned fork of MicroPython. Actual system requirements vary per
16-
module. Majority of modules are compatible with the upstream MicroPython,
17-
though some may require additional functionality/optimizations present in
18-
the "advanced" fork. Modules not related to I/O may also work without
19-
problems on bare-metal ports, not just on "Unix" port (e.g. pyboard).
7+
The libraries here fall into roughly four categories:
208

9+
* 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).
2110

22-
Usage
23-
-----
24-
micropython-lib packages are published on PyPI (Python Package Index),
25-
the standard Python community package repository: https://pypi.org/ .
26-
On PyPI, you can search for MicroPython related packages and read
27-
additional package information. By convention, all micropython-lib package
28-
names are prefixed with "micropython-" (the reverse is not true - some
29-
package starting with "micropython-" aren't part of micropython-lib and
30-
were released by 3rd parties).
31-
32-
Browse available packages [via this
33-
URL](https://pypi.org/search/?q=&o=&c=Programming+Language+%3A%3A+Python+%3A%3A+Implementation+%3A%3A+MicroPython).
34-
35-
To install packages from PyPI for usage on your local system, use the
36-
`upip` tool, which is MicroPython's native package manager, similar to
37-
`pip`, which is used to install packages for CPython. `upip` is bundled
38-
with MicroPython "Unix" port (i.e. if you build "Unix" port, you
39-
automatically have `upip` tool). Following examples assume that
40-
`micropython` binary is available on your `PATH`:
41-
42-
~~~~
43-
$ micropython -m upip install micropython-pystone
44-
...
45-
$ micropython
46-
>>> import pystone
47-
>>> pystone.main()
48-
Pystone(1.2) time for 50000 passes = 0.534
49-
This machine benchmarks at 93633 pystones/second
50-
~~~~
11+
* "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.
5112

52-
Run `micropython -m upip --help` for more information about `upip`.
13+
* MicroPython-specific libraries. These include drivers and other libraries targeted at running Python on hardware or embedded systems.
5314

15+
* 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).
5416

55-
Development
56-
-----------
57-
To install modules during development, use `make install`. By default, all
58-
available packages will be installed. To install a specific module, add the
59-
`MOD=<module>` parameter to the end of the `make install` command.
60-
61-
62-
Links
17+
Usage
6318
-----
64-
If you would like to trace evolution of MicroPython packaging support,
65-
you may find following links useful (note that they may contain outdated
66-
information):
6719

68-
* https://github.com/micropython/micropython/issues/405
69-
* http://forum.micropython.org/viewtopic.php?f=5&t=70
20+
Many libraries are self contained modules, and you can quickly get started by
21+
copying the relevant Python file to your device. For example, to add the
22+
`base64` library, you can directly copy `base64/base64.py` to the `lib`
23+
directory on your device.
7024

71-
Guidelines for packaging MicroPython modules for PyPI:
25+
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.
7226

73-
* https://github.com/micropython/micropython/issues/413
27+
For devices that have network connectivity (e.g. PYBD, ESP8266, ESP32), they
28+
will have the `upip` module installed.
29+
30+
```
31+
>>> import upip
32+
>>> upip.install('micropython-base64')
33+
>>> upip.install('micropython-collections.defaultdict')
34+
...
35+
>>> import base64
36+
>>> base64.b64decode('aGVsbG8sIG1pY3JvcHl0aG9u')
37+
b'hello, micropython'
38+
>>> from collections import defaultdict
39+
>>> d = defaultdict(int)
40+
>>> d[a] += 1
41+
```
42+
43+
Future plans (and new contributor ideas)
44+
----------------------------------------
45+
46+
* Provide compiled .mpy distributions.
47+
* Develop a set of example programs using these libraries.
48+
* Develop more MicroPython libraries for common tasks.

‎micropython/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
MicroPython-specific libraries
2+
==============================
3+
4+
These are libraries that have been written specifically for use on MicroPython.
5+
6+
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.
7+
8+
Other libraries have been written specifically for MicroPython use cases.
9+
10+
Future plans
11+
------------
12+
13+
* More organised directory structure based on library purpose (e.g. drivers, network, etc).

‎python-stdlib/README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
CPython standard libraries
2+
==========================
3+
4+
The libraries in this directory aim to provide compatible implementations of
5+
standard libraries to allow existing Python code to run un-modified on
6+
MicroPython.
7+
8+
Compatibility ranges from:
9+
10+
* Many commonly-used methods and classes are provided with identical runtime semantics.
11+
* A subset of methods and classes, with identical semantics for most use cases.
12+
* Additional constants not provided in the main firmware (to keep size down).
13+
* Stub methods and classes required to make code load without error, but may lead to runtime errors.
14+
15+
16+
Implementation
17+
--------------
18+
19+
Many libraries are implemented in pure Python, often based on the original
20+
CPython implementation. (e.g. `collections.defaultdict`)
21+
22+
Some libraries are based on or extend from the built-in "micro" modules in the
23+
MicroPython firmware, providing additional functionality that didn't need to
24+
be written in C. (e.g. `socket`, `struct`)
25+
26+
27+
Future plans (ideas for contributors):
28+
--------------------------------------
29+
30+
* Add README.md to each library explaining compatibility and limitations.

‎unix-ffi/README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Unix-specific libraries
2+
=======================
3+
4+
These are libraries that will only run on the Unix port of MicroPython. There is some limited support for the Windows port too.
5+
6+
**Note:** This directory is largely unmaintained, although large breaking changes are not expected.
7+
8+
Background
9+
----------
10+
11+
The libraries in this directory provide additional CPython compatibility using
12+
the host operating system's native libraries.
13+
14+
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.
15+
16+
In theory, this allows you to use MicroPython as a more complete drop-in
17+
replacement for CPython.

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /