Skip to content

Commit 0b1aaaf

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 6fca45f commit 0b1aaaf

File tree

7 files changed

+218
-51
lines changed

7 files changed

+218
-51
lines changed

‎CODEOFCONDUCT.md

+1
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

+67-2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,68 @@
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+
[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[discussion forum]
23+
(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` to apply `black` automatically
30+
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. In most cases, packages will be installed via
42+
`mip`, which means that they will be compiled to bytecode, so 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 `collections-defaultdict` as an example.
53+
54+
* If you think a package might be extended in this way in the future, prefer
55+
to create a package directory with `package/__init__.py`, rather than a
56+
single `module.py`.
57+
58+
* Packages in the python-stdlib directory should be CPython compatible and
59+
implement a subset of the CPython equivalent. Avoid adding
60+
MicroPython-specific extensions.
61+
62+
* Include tests (ideally using the `unittest` package) as `test_*.py`.
63+
Otherwise, provide examples as `example_*.py`. When porting CPython
64+
packages, prefer to use the existing tests rather than writing new ones
65+
from scratch.
66+
67+
* When porting an existing third-party package, please ensure that the source
68+
license is compatible.

‎README.md

+122-20
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,133 @@
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 library 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 four categories corresponding to the four
7+
top-level 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 many 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 larger Python ecosystem, for example that might be
17+
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), or 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+
This is the officially-supported tool for interacting with a MicroPython
48+
device, and since v0.4.0 it supports installing packages using the `mip`
49+
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+
For packages that are implemented as a package directory, you'll need to copy
72+
the directory instead. For example, to add `collections.defaultdict`, copy
73+
`collections/collections/__init__.py` and
74+
`collections-defaultdict/collections/defaultdict.py` to a directory named
75+
`lib/collections` on your device.
76+
77+
Note that unlike the other three approaches based on `mip` or `manifest.py`,
78+
you will need to manually sort out dependencies. You can look at the
79+
`manifest.py` file to see which other packages a given package depends on.
80+
81+
## Contributing
82+
83+
We use [GitHub Discussions](https://github.com/micropython/micropython/discussions)
84+
as our forum, and [Discord](https://micropython.org/discord) for chat. These
85+
are great places to ask questions and advice from the community or to discuss your
86+
MicroPython-based projects.
87+
88+
The [MicroPython Wiki](https://github.com/micropython/micropython/wiki) is
89+
also used for micropython-lib.
90+
91+
For bugs and feature requests, please [raise an issue](https://github.com/micropython/micropython-lib/issues/new).
92+
93+
We welcome pull requests to add new packages, fix bugs, or add features.
94+
Please be sure to follow the [Contributor's Guidelines & Code Conventions](CONTRIBUTING.md). Note that MicroPython is licenced under the [MIT license](LICENSE), and all
95+
contributions should follow this license.
96+
97+
### Future plans (and new contributor ideas)
98+
99+
* Develop a set of example programs using these packages.
100+
* Develop more MicroPython packages for common tasks.
101+
* Expand unit testing coverage.
102+
* Add support for referencing remote/third-party repositories.
103+
104+
## Notes on terminology
105+
106+
The terms *library*, *package*, and *module* are overloaded and lead to some
107+
confusion. The interpretation used in by the MicroPython project is that:
108+
109+
A *library* is a collection of installable packages, e.g. [The Python Standard
110+
Library](https://docs.python.org/3/library/), or micropython-lib.
111+
112+
A *package* can refer to two things. The first meaning, "library package", is
113+
something that can be installed from a library, e.g. via `mip` (or `pip` in
114+
CPython/PyPI). Packages provide *modules* that can be imported. The ambiguity
115+
here is that the module provided by the package does not necessarily have to
116+
have the same name, e.g. the `pyjwt` package provides the `jwt` module. In
117+
CPython, the `pyseral` package providing the `serial` module is another
118+
common example.
119+
120+
A *module* is something that can be imported. For example, "the *os* module".
121+
122+
A module can be implemented either as a single file, typically also called
123+
a *module* or "single-file module", or as a *package* (the second meaning),
124+
which in this context means a directory containing multiple `.py` files
125+
(usually at least an `__init__.py`).
126+
127+
In micropython-lib, we also have the concept of an *extension package* which
128+
is a library package that extends the functionality of another package, by
129+
adding additional files to the same package directory. These packages have
130+
hyphenated names. For example, the `collections-defaultdict` package extends
131+
the `collections` package to add the `defaultdict` class to the `collections`
132+
module.
29133

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

‎micropython/README.md

+5-9
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

+10
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

+8-12
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

+5-8
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)