Skip to content

Commit a9e52d0

Browse files
jimmojimmo
committed
top: Update top-level docs.
* Add instructions for how to use micropython-lib. * Add a terminology guide and use consistent terminology (package/module/library). * Improve code conventions and contributor guidelines. * Misc readme updates. This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
1 parent 8d653e9 commit a9e52d0

File tree

7 files changed

+229
-51
lines changed

7 files changed

+229
-51
lines changed

‎CODEOFCONDUCT.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Please see the [MicroPython Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md).

‎CONTRIBUTING.md‎

Lines changed: 70 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,71 @@
1-
If you submit a pull request, please adhere to Contributor Guidelines:
1+
## Contributor's Guidelines & Code Conventions
22

3-
https://github.com/micropython/micropython-lib/wiki/ContributorGuidelines
3+
micropython-lib follows the same general conventions as the [main MicroPython
4+
repository](https://github.com/micropython/micropython). Please see
5+
[micropython/CONTRIBUTING.md](https://github.com/micropython/micropython/blob/master/CONTRIBUTING.md)
6+
and [micropython/CODECONVENTIONS.md](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md).
7+
8+
### Raising issues
9+
10+
Please include enough information for someone to reproduce the issue you are
11+
describing. This will typically include:
12+
13+
* The version of MicroPython you are using (e.g. the firmware filename, git
14+
hash, or version info printed by the startup message).
15+
* What board/device you are running MicroPython on.
16+
* Which package you have installed, how you installed it, and what version.
17+
When installed via `mip`, all packages will have a `__version__`
18+
attribute.
19+
* A simple code snippet that demonstrates the issue.
20+
21+
If you have a how-to question or are looking for help with using MicroPython
22+
or packages from micropython-lib, please post at the
23+
[discussion forum](https://github.com/orgs/micropython/discussions) instead.
24+
25+
### Pull requests
26+
27+
The same rules for commit messages, signing-off commits, and commit structure
28+
apply as for the main MicroPython repository. All Python code is formatted
29+
using `black`. See [`tools/codeformat.py`](tools/codeformat.py) to apply
30+
`black` automatically before submitting a PR.
31+
32+
There are some specific conventions and guidelines for micropython-lib:
33+
34+
* The first line of the commit message should start with the name of the
35+
package, followed by a short description of the commit. Package names are
36+
globally unique in the micropython-lib directory structure.
37+
38+
For example: `shutil: Add disk_usage function.`
39+
40+
* Although we encourage keeping the code short and minimal, please still use
41+
comments in your code. Typically, packages will be installed via
42+
`mip` and so they will be compiled to bytecode where comments will
43+
_not_ contribute to the installed size.
44+
45+
* All packages must include a `manifest.py`, including a `metadata()` line
46+
with at least a description and a version.
47+
48+
* Prefer to break larger packages up into smaller chunks, so that just the
49+
required functionality can be installed. The way to do this is to have a
50+
base package, e.g. `mypackage` containing `mypackage/__init__.py`, and then
51+
an "extension" package, e.g. `mypackage-ext` containing additional files
52+
e.g. `mypackage/ext.py`. See
53+
[`collections-defaultdict`](python-stdlib/collections-defaultdict) as an
54+
example.
55+
56+
* If you think a package might be extended in this way in the future, prefer
57+
to create a package directory with `package/__init__.py`, rather than a
58+
single `module.py`.
59+
60+
* Packages in the python-stdlib directory should be CPython compatible and
61+
implement a subset of the CPython equivalent. Avoid adding
62+
MicroPython-specific extensions. Please include a link to the corresponding
63+
CPython docs in the PR.
64+
65+
* Include tests (ideally using the `unittest` package) as `test_*.py`.
66+
Otherwise, provide examples as `example_*.py`. When porting CPython
67+
packages, prefer to use the existing tests rather than writing new ones
68+
from scratch.
69+
70+
* When porting an existing third-party package, please ensure that the source
71+
license is compatible.

‎README.md‎

Lines changed: 130 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,141 @@
1-
micropython-lib
2-
===============
1+
# micropython-lib
32

4-
This is a repository of libraries designed to be useful for writing
5-
MicroPython applications.
3+
This is a repository of packages designed to be useful for writing MicroPython
4+
applications.
65

7-
The libraries here fall into four categories corresponding to the four top-level directories:
6+
The packages here fall into categories corresponding to the four top-level
7+
directories:
88

9-
* **python-stdlib**: Compatible versions of modules from the [Python Standard Library](https://docs.python.org/3/library/). These should be drop-in replacements for the Python libraries, although many have reduced functionality or missing methods or classes (which may not be an issue for many most cases).
9+
* **python-stdlib**: Compatible versions of modules from [The Python Standard
10+
Library](https://docs.python.org/3/library/). These should be drop-in
11+
replacements for the corresponding Python modules, although many have
12+
reduced functionality or missing methods or classes (which may not be an
13+
issue for most cases).
1014

11-
* **python-ecosys**: Compatible, but reduced-functionality versions of modules from the larger Python ecosystem, for example that might be found in the [Python Package Index](https://pypi.org/).
15+
* **python-ecosys**: Compatible, but reduced-functionality versions of
16+
packages from the wider Python ecosystem. For example, a package that
17+
might be found in the [Python Package Index](https://pypi.org/).
1218

13-
* **micropython**: MicroPython-specific modules that do not have equivalents in other Python environments. These are typically hardware drivers or highly-optimised alternative implementations of functionality available in other Python modules.
19+
* **micropython**: MicroPython-specific packages that do not have equivalents
20+
in other Python environments. This includes drivers for hardware
21+
(e.g. sensors, peripherals, or displays), libraries to work with
22+
embedded functionality (e.g. bluetooth), or MicroPython-specific
23+
packages that do not have equivalents in CPython.
1424

15-
* **unix-ffi**: These modules are specifically for the MicroPython Unix port and provide access to operating-system and third-party libraries via FFI.
25+
* **unix-ffi**: These packages are specifically for the MicroPython Unix port
26+
and provide access to operating-system and third-party libraries via FFI,
27+
or functionality that is not useful for non-Unix ports.
1628

17-
Usage
18-
-----
29+
## Usage
1930

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 `python-stdlib/base64/base64.py` to the `lib`
23-
directory on your device.
31+
To install a micropython-lib package, there are four main options. For more
32+
information see the [Package management documentation](https://docs.micropython.org/en/latest/reference/packages.html)
33+
documentation.
2434

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.
35+
### On a network-enabled device
2636

27-
Future plans (and new contributor ideas)
28-
----------------------------------------
37+
As of MicroPython v1.20 (and nightly builds since October 2022), boards
38+
with WiFi and Ethernet support include the `mip` package manager.
39+
40+
```py
41+
>>> import mip
42+
>>> mip.install("package-name")
43+
```
44+
45+
### Using `mpremote` from your PC
46+
47+
`mpremote` is the officially-supported tool for interacting with a MicroPython
48+
device and, since v0.4.0, support for installing micropython-lib packages is
49+
provided by using the `mip` command.
50+
51+
```bash
52+
$ mpremote connect /dev/ttyUSB0 mip install package-name
53+
```
54+
55+
See the [mpremote documentation](https://docs.micropython.org/en/latest/reference/mpremote.html).
56+
57+
### Freeze into your firmware
58+
59+
If you are building your own firmware, all packages in this repository include
60+
a `manifest.py` that can be included into your board manifest via the
61+
`require()` command. See [Manifest files](https://docs.micropython.org/en/latest/reference/manifest.html#require) for
62+
more information.
63+
64+
### Copy the files manually
65+
66+
Many micropython-lib packages are just single-file modules, and you can
67+
quickly get started by copying the relevant Python file to your device. For
68+
example, to add the `base64` library, you can directly copy
69+
`python-stdlib/base64/base64.py` to the `lib` directory on your device.
70+
71+
This can be done using `mpremote`, for example:
72+
73+
```bash
74+
$ mpremote connect /dev/ttyUSB0 cp python-stdlib/base64/base64.py :/lib
75+
```
76+
77+
For packages that are implemented as a package directory, you'll need to copy
78+
the directory instead. For example, to add `collections.defaultdict`, copy
79+
`collections/collections/__init__.py` and
80+
`collections-defaultdict/collections/defaultdict.py` to a directory named
81+
`lib/collections` on your device.
82+
83+
Note that unlike the other three approaches based on `mip` or `manifest.py`,
84+
you will need to manually resolve dependencies. You can inspect the relevant
85+
`manifest.py` file to view the list of dependencies for a given package.
86+
87+
## Contributing
88+
89+
We use [GitHub Discussions](https://github.com/micropython/micropython/discussions)
90+
as our forum, and [Discord](https://micropython.org/discord) for chat. These
91+
are great places to ask questions and advice from the community or to discuss your
92+
MicroPython-based projects.
93+
94+
The [MicroPython Wiki](https://github.com/micropython/micropython/wiki) is
95+
also used for micropython-lib.
96+
97+
For bugs and feature requests, please [raise an issue](https://github.com/micropython/micropython-lib/issues/new).
98+
99+
We welcome pull requests to add new packages, fix bugs, or add features.
100+
Please be sure to follow the
101+
[Contributor's Guidelines & Code Conventions](CONTRIBUTING.md). Note that
102+
MicroPython is licensed under the [MIT license](LICENSE) and all contributions
103+
should follow this license.
104+
105+
### Future plans (and new contributor ideas)
106+
107+
* Develop a set of example programs using these packages.
108+
* Develop more MicroPython packages for common tasks.
109+
* Expand unit testing coverage.
110+
* Add support for referencing remote/third-party repositories.
111+
112+
## Notes on terminology
113+
114+
The terms *library*, *package*, and *module* are overloaded and lead to some
115+
confusion. The interpretation used in by the MicroPython project is that:
116+
117+
A *library* is a collection of installable packages, e.g. [The Python Standard
118+
Library](https://docs.python.org/3/library/), or micropython-lib.
119+
120+
A *package* can refer to two things. The first meaning, "library package", is
121+
something that can be installed from a library, e.g. via `mip` (or `pip` in
122+
CPython/PyPI). Packages provide *modules* that can be imported. The ambiguity
123+
here is that the module provided by the package does not necessarily have to
124+
have the same name, e.g. the `pyjwt` package provides the `jwt` module. In
125+
CPython, the `pyserial` package providing the `serial` module is another
126+
common example.
127+
128+
A *module* is something that can be imported. For example, "the *os* module".
129+
130+
A module can be implemented either as a single file, typically also called
131+
a *module* or "single-file module", or as a *package* (the second meaning),
132+
which in this context means a directory containing multiple `.py` files
133+
(usually at least an `__init__.py`).
134+
135+
In micropython-lib, we also have the concept of an *extension package* which
136+
is a library package that extends the functionality of another package, by
137+
adding additional files to the same package directory. These packages have
138+
hyphenated names. For example, the `collections-defaultdict` package extends
139+
the `collections` package to add the `defaultdict` class to the `collections`
140+
module.
29141

30-
* Develop a set of example programs using these libraries.
31-
* Develop more MicroPython libraries for common tasks.

‎micropython/README.md‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,9 @@
1-
MicroPython-specific libraries
2-
==============================
1+
## MicroPython-specific packages
32

4-
These are libraries that have been written specifically for use on MicroPython.
3+
These are packages that have been written specifically for use on MicroPython.
54

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.
5+
Packages in this directory should not have the same name as modules from the Python Standard Library.
76

8-
Other libraries have been written specifically for MicroPython use cases.
7+
### Future plans
98

10-
Future plans
11-
------------
12-
13-
* More organised directory structure based on library purpose (e.g. drivers, network, etc).
9+
* More organised directory structure based on purpose (e.g. drivers, network, etc).

‎python-ecosys/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
## Python-ecosystem packages
2+
3+
These MicroPython versions of common Python packages, typically found on PyPI.
4+
5+
If a package has the same name as a PyPI package, then it should match at
6+
least some subset of the functionality.
7+
8+
### Future plans
9+
10+
* More organised directory structure based on library purpose (e.g. drivers, network, etc).

‎python-stdlib/README.md‎

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,18 @@
1-
CPython standard libraries
2-
==========================
1+
## CPython Standard Library
32

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.
3+
The packages in this directory aim to provide compatible implementations of
4+
modules from the Python Standard Library, with the goal of allowing existing
5+
Python code to run un-modified on MicroPython.
76

8-
Implementation
9-
--------------
7+
### Implementation
108

11-
Many libraries are implemented in pure Python, often based on the original
9+
Many packages are implemented in pure Python, often based on the original
1210
CPython implementation. (e.g. `collections.defaultdict`)
1311

14-
Some libraries are based on or extend from the built-in "micro" modules in the
12+
Some packages are based on or extend from the built-in "micro" modules in the
1513
MicroPython firmware, providing additional functionality that didn't need to
1614
be written in C (e.g. `collections`, `socket`, `struct`).
1715

18-
19-
Future plans (ideas for contributors):
20-
--------------------------------------
16+
### Future plans (ideas for contributors):
2117

2218
* Add README.md to each library explaining compatibility and limitations.

‎unix-ffi/README.md‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,14 @@
1-
Unix-specific libraries
2-
=======================
1+
## Unix-specific packages
32

4-
These are libraries that will only run on the Unix port of MicroPython, or are
3+
These are packages that will only run on the Unix port of MicroPython, or are
54
too big to be used on microcontrollers. There is some limited support for the
65
Windows port too.
76

87
**Note:** This directory is unmaintained.
98

10-
Background
11-
----------
9+
### Background
1210

13-
The libraries in this directory provide additional CPython compatibility using
11+
The packages in this directory provide additional CPython compatibility using
1412
the host operating system's native libraries.
1513

1614
This is implemented either by accessing the libraries directly via libffi, or
@@ -19,8 +17,7 @@ by using built-in modules that are only available on the Unix port.
1917
In theory, this allows you to use MicroPython as a more complete drop-in
2018
replacement for CPython.
2119

22-
Usage
23-
-----
20+
### Usage
2421

2522
To use a unix-specific library, pass `unix_ffi=True` to `require()` in your
2623
manifest file.

0 commit comments

Comments
 (0)