MicroPython V1.12官方文档：模块与扩展指南

需积分: 9 100 浏览量更新于2024-07-16 1 收藏 713KB PDF 举报

MicroPython官方文档V1.12详细介绍了该版本的特性与功能，发布日期为2020年4月12日。这份文档由Damien George和Paul Sokolovsky以及贡献者共同编撰，涵盖了MicroPython的核心库设计。微Python专注于提供一种轻量级的Python实现，特别适合嵌入式设备，它在标准Python功能集上进行了一定程度的精简和定制。该文档首先强调了MicroPython对标准Python模块的处理方式。为了便于扩展，MicroPython的标准模块通常带有“micro”前缀，这表明这些模块可能是核心功能，并可能不鼓励用户直接修改或扩展。然而，开发者可以根据需要对某些模块进行扩展，尤其是那些提供了Python接口的模块，允许用户通过编写Python代码来增强其功能。文档详细划分了模块的几个类别： 1. 不可扩展模块：这部分包含了标准Python功能的子集，它们作为预定义的功能，用户通常不需要对其进行扩展。 2. 可扩展模块：这些模块提供了一部分功能，预留接口供用户通过编写Python代码进行扩展。 3. MicroPython扩展模块：这些模块是专门为MicroPython平台设计的，扩展了标准Python库，使得MicroPython能够在特定领域提供更丰富的功能。 4. 端口特有模块：这类模块仅适用于特定的MicroPython版本或硬件平台，不具有跨平台的通用性。值得注意的是，文档还提到了模块的可用性和内容可能会因MicroPython的不同版本和移植而有所不同，因为资源限制和平台特性可能导致并非所有功能都能在所有情况下得到支持。阅读MicroPython V1.12的官方文档，开发者可以了解到如何充分利用内置模块，如何区分哪些模块可以直接使用，哪些可以扩展，以及如何处理与特定硬件平台相关的定制模块。这对于想要在嵌入式系统中使用MicroPython的开发人员来说，是一份不可或缺的参考资料。

MicroPython Documentation, Release 1.12

Classes

ucollections.deque(iterable, maxlen[, ﬂags ])

Deques (double-ended queues) are a list-like container that support O(1) appends and pops from either side of

the deque. New deques are created using the following arguments:

•iterable must be the empty tuple, and the new deque is created empty.

•maxlen must be speciﬁed and the deque will be bounded to this maximum length. Once the deque is full,

any new items added will discard items from the opposite end.

•The optional ﬂags can be 1 to check for overﬂow when adding items.

As well as supporting bool and len, deque objects have the following methods:

deque.append(x)

Add x to the right side of the deque. Raises IndexError if overﬂow checking is enabled and there is no

more room left.

deque.popleft()

Remove and return an item from the left side of the deque. Raises IndexError if no items are present.

ucollections.namedtuple(name, ﬁelds)

This is factory function to create a new namedtuple type with a speciﬁc name and set of ﬁelds. A namedtuple is

a subclass of tuple which allows to access its ﬁelds not just by numeric index, but also with an attribute access

syntax using symbolic ﬁeld names. Fields is a sequence of strings specifying ﬁeld names. For compatibility

with CPython it can also be a a string with space-separated ﬁeld named (but this is less efﬁcient). Example of

use:

from ucollections import namedtuple

MyTuple = namedtuple("MyTuple", ("id", "name"))

t1 = MyTuple(1, "foo")

t2 = MyTuple(2, "bar")

print(t1.name)

assert t2.name == t2[1]

ucollections.OrderedDict(...)

dict type subclass which remembers and preserves the order of keys added. When ordered dict is iterated over,

keys/items are returned in the order they were added:

from ucollections import OrderedDict

# To make benefit of ordered keys, OrderedDict should be initialized

# from sequence of (key, value) pairs.

d = OrderedDict([("z", 1), ("a", 2)])

# More items can be added as usual

d["w"] = 5

d["b"] = 3

for k, v in d.items():

print(k, v)

Output:

z 1

a 2

w 5

b 3

12 Chapter 1. MicroPython libraries

MicroPython Documentation, Release 1.12

1.1.9 uerrno – system error codes

This module implements a subset of the corresponding CPython module, as described below. For more information,

refer to the original CPython documentation: errno.

This module provides access to symbolic error codes for OSError exception. A particular inventory of codes depends

on MicroPython port.

Constants

EEXIST, EAGAIN, etc.

Error codes, based on ANSI C/POSIX standard. All error codes start with “E”. As mentioned above, inventory

of the codes depends on MicroPython port. Errors are usually accessible as exc.args[0] where exc

is an instance of OSError. Usage example:

try:

uos.mkdir("my_dir")

except OSError as exc:

if exc.args[0] == uerrno.EEXIST:

print("Directory already exists")

uerrno.errorcode

Dictionary mapping numeric error codes to strings with symbolic error code (see above):

>>> print(uerrno.errorcode[uerrno.EEXIST])

EEXIST

1.1.10 uhashlib – hashing algorithms

This module implements a subset of the corresponding CPython module, as described below. For more information,

refer to the original CPython documentation: hashlib.

This module implements binary data hashing algorithms. The exact inventory of available algorithms depends on a

board. Among the algorithms which may be implemented:

• SHA256 - The current generation, modern hashing algorithm (of SHA2 series). It is suitable for

cryptographically-secure purposes. Included in the MicroPython core and any board is recommended to provide

this, unless it has particular code size constraints.

• SHA1 - A previous generation algorithm. Not recommended for new usages, but SHA1 is a part of number of

Internet standards and existing applications, so boards targeting network connectivity and interoperability will

try to provide this.

• MD5 - A legacy algorithm, not considered cryptographically secure. Only selected boards, targeting interoper-

ability with legacy applications, will offer this.

Constructors

class uhashlib.sha256([data ])

Create an SHA256 hasher object and optionally feed data into it.

class uhashlib.sha1([data ])

Create an SHA1 hasher object and optionally feed data into it.

class uhashlib.md5([data ])

Create an MD5 hasher object and optionally feed data into it.

1.1. Python standard libraries and micro-libraries 13

MicroPython Documentation, Release 1.12

Methods

hash.update(data)

Feed more binary data into hash.

hash.digest()

Return hash for all data passed through hash, as a bytes object. After this method is called, more data cannot be

fed into the hash any longer.

hash.hexdigest()

This method is NOT implemented. Use ubinascii.hexlify(hash.digest()) to achieve a similar

effect.

1.1.11 uheapq – heap queue algorithm

This module implements a subset of the corresponding CPython module, as described below. For more information,

refer to the original CPython documentation: heapq.

This module implements the heap queue algorithm.

A heap queue is simply a list that has its elements stored in a certain way.

Functions

uheapq.heappush(heap, item)

Push the item onto the heap.

uheapq.heappop(heap)

Pop the ﬁrst item from the heap, and return it. Raises IndexError if heap is empty.

uheapq.heapify(x)

Convert the list x into a heap. This is an in-place operation.

1.1.12 uio – input/output streams

This module implements a subset of the corresponding CPython module, as described below. For more information,

refer to the original CPython documentation: io.

This module contains additional types of stream (ﬁle-like) objects and helper functions.

Conceptual hierarchy

Difference to CPython

Conceptual hierarchy of stream base classes is simpliﬁed in MicroPython, as described in this section.

(Abstract) base stream classes, which serve as a foundation for behavior of all the concrete classes, adhere to few

dichotomies (pair-wise classiﬁcations) in CPython. In MicroPython, they are somewhat simpliﬁed and made implicit

to achieve higher efﬁciencies and save resources.

An important dichotomy in CPython is unbuffered vs buffered streams. In MicroPython, all streams are currently

unbuffered. This is because all modern OSes, and even many RTOSes and ﬁlesystem drivers already perform buffering

on their side. Adding another layer of buffering is counter- productive (an issue known as “bufferbloat”) and takes

14 Chapter 1. MicroPython libraries

MicroPython Documentation, Release 1.12

precious memory. Note that there still cases where buffering may be useful, so we may introduce optional buffering

support at a later time.

But in CPython, another important dichotomy is tied with “bufferedness” - it’s whether a stream may incur short

read/writes or not. A short read is when a user asks e.g. 10 bytes from a stream, but gets less, similarly for writes. In

CPython, unbuffered streams are automatically short operation susceptible, while buffered are guarantee against them.

The no short read/writes is an important trait, as it allows to develop more concise and efﬁcient programs - something

which is highly desirable for MicroPython. So, while MicroPython doesn’t support buffered streams, it still provides

for no-short-operations streams. Whether there will be short operations or not depends on each particular class’ needs,

but developers are strongly advised to favor no-short-operations behavior for the reasons stated above. For example,

MicroPython sockets are guaranteed to avoid short read/writes. Actually, at this time, there is no example of a short-

operations stream class in the core, and one would be a port-speciﬁc class, where such a need is governed by hardware

peculiarities.

The no-short-operations behavior gets tricky in case of non-blocking streams, blocking vs non-blocking behavior

being another CPython dichotomy, fully supported by MicroPython. Non-blocking streams never wait for data either

to arrive or be written - they read/write whatever possible, or signal lack of data (or ability to write data). Clearly,

this conﬂicts with “no-short-operations” policy, and indeed, a case of non-blocking buffered (and this no-short-ops)

streams is convoluted in CPython - in some places, such combination is prohibited, in some it’s undeﬁned or just not

documented, in some cases it raises verbose exceptions. The matter is much simpler in MicroPython: non-blocking

stream are important for efﬁcient asynchronous operations, so this property prevails on the “no-short-ops” one. So,

while blocking streams will avoid short reads/writes whenever possible (the only case to get a short read is if end of

ﬁle is reached, or in case of error (but errors don’t return short data, but raise exceptions)), non-blocking streams may

produce short data to avoid blocking the operation.

The ﬁnal dichotomy is binary vs text streams. MicroPython of course supports these, but while in CPython text

streams are inherently buffered, they aren’t in MicroPython. (Indeed, that’s one of the cases for which we may

introduce buffering support.)

Note that for efﬁciency, MicroPython doesn’t provide abstract base classes corresponding to the hierarchy above, and

it’s not possible to implement, or subclass, a stream class in pure Python.

Functions

uio.open(name, mode=’r’, **kwargs)

Open a ﬁle. Builtin open() function is aliased to this function. All ports (which provide access to ﬁle system)

are required to support mode parameter, but support for other arguments vary by port.

Classes

class uio.FileIO(...)

This is type of a ﬁle open in binary mode, e.g. using open(name,"rb"). You should not instantiate this

class directly.

class uio.TextIOWrapper(...)

This is type of a ﬁle open in text mode, e.g. using open(name,"rt"). You should not instantiate this class

directly.

class uio.StringIO([string ])

class uio.BytesIO([string ])

In-memory ﬁle-like objects for input/output. StringIO is used for text-mode I/O (similar to a normal ﬁle

opened with “t” modiﬁer). BytesIO is used for binary-mode I/O (similar to a normal ﬁle opened with “b”

modiﬁer). Initial contents of ﬁle-like objects can be speciﬁed with string parameter (should be normal string

for StringIO or bytes object for BytesIO). All the usual ﬁle methods like read(), write(), seek(),

flush(), close() are available on these objects, and additionally, a following method:

1.1. Python standard libraries and micro-libraries 15

MicroPython Documentation, Release 1.12

getvalue()

Get the current contents of the underlying buffer which holds data.

class uio.StringIO(alloc_size)

class uio.BytesIO(alloc_size)

Create an empty StringIO/BytesIO object, preallocated to hold up to alloc_size number of bytes. That

means that writing that amount of bytes won’t lead to reallocation of the buffer, and thus won’t hit out-of-

memory situation or lead to memory fragmentation. These constructors are a MicroPython extension and are

recommended for usage only in special cases and in system-level libraries, not for end-user applications.

Difference to CPython

These constructors are a MicroPython extension.

1.1.13 ujson – JSON encoding and decoding

This module implements a subset of the corresponding CPython module, as described below. For more information,

refer to the original CPython documentation: json.

This modules allows to convert between Python objects and the JSON data format.

Functions

ujson.dump(obj, stream)

Serialise obj to a JSON string, writing it to the given stream.

ujson.dumps(obj)

Return obj represented as a JSON string.

ujson.load(stream)

Parse the given stream, interpreting it as a JSON string and deserialising the data to a Python object. The

resulting object is returned.

Parsing continues until end-of-ﬁle is encountered. A ValueError is raised if the data in stream is not correctly

formed.

ujson.loads(str)

Parse the JSON str and return an object. Raises ValueError if the string is not correctly formed.

1.1.14 uos – basic “operating system” services

This module implements a subset of the corresponding CPython module, as described below. For more information,

refer to the original CPython documentation: os.

The uos module contains functions for ﬁlesystem access and mounting, terminal redirection and duplication, and the

uname and urandom functions.

General functions

uos.uname()

Return a tuple (possibly a named tuple) containing information about the underlying machine and/or its operat-

ing system. The tuple has ﬁve ﬁelds in the following order, each of them being a string:

16 Chapter 1. MicroPython libraries

剩余204页未读，继续阅读

CHN悠远

粉丝: 53
资源: 37

MicroPython V1.12官方文档：模块与扩展指南

官方PyPI资源下载：django-online-docs-0.2.tar.gz

NVIDIA视频效果开发工具包-win-*.*.*.*版本介绍

ansible_autodoc-*.*.*.*-py3-none-any.whl文件下载与解压指南

Python库 | mypy-boto3-codestar-connections-1.12.3.0.tar.gz

PyPI 官网下载 | mypy-boto3-acm-pca-1.12.24.0.tar.gz

PyPI 官网下载 | mypy-boto3-license-manager-1.12.27.0.tar.gz

PyPI 官网下载 | mypy-boto3-codestar-notifications-1.12.35.0.tar.gz

PyPI 官网下载 | mypy-boto3-batch-1.12.39.1.tar.gz

PyPI 官网下载 | mypy-boto3-signer-1.12.39.0.tar.gz

PyPI 官网下载 | mypy-boto3-lambda-1.12.12.0.tar.gz

最新资源

NVIDIA视频效果开发工具包-win-...版本介绍

ansible_autodoc-...-py3-none-any.whl文件下载与解压指南