From 4a579f7242935b9fac5b6f56c93d5ed3c01c9098 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Mon, 14 Aug 2023 12:34:00 -0400 Subject: [PATCH] fix doc build; reorganize placement of library docs --- conf.py | 2 +- docs/index.rst | 8 +- docs/library/binascii.rst | 2 +- docs/library/btree.rst | 161 ------------------------------------ docs/library/framebuf.rst | 170 -------------------------------------- docs/library/index.rst | 30 ++++--- 6 files changed, 26 insertions(+), 347 deletions(-) delete mode 100644 docs/library/btree.rst delete mode 100644 docs/library/framebuf.rst diff --git a/conf.py b/conf.py index 645961c457..29cf7981fc 100644 --- a/conf.py +++ b/conf.py @@ -441,7 +441,7 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"cpython": ('https://docs.python.org/3/', None), +intersphinx_mapping = {"python": ('https://docs.python.org/3/', None), "register": ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None), "typing": ('https://circuitpython.readthedocs.io/projects/adafruit-circuitpython-typing/en/latest/', None)} diff --git a/docs/index.rst b/docs/index.rst index e49b74b4e3..ba40d18ec4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,6 +19,7 @@ Full Table of Contents :caption: API and Usage ../shared-bindings/index.rst + library/index.rst supported_ports.rst troubleshooting.rst libraries.rst @@ -32,13 +33,12 @@ Full Table of Contents design_guide porting common_hal + reference/mpyfiles.rst + reference/glossary.rst .. toctree:: :maxdepth: 2 - :caption: MicroPython specific - - library/index.rst - reference/glossary.rst + :caption: Python stand .. toctree:: :maxdepth: 1 diff --git a/docs/library/binascii.rst b/docs/library/binascii.rst index 296a4e9d85..1eba46652d 100644 --- a/docs/library/binascii.rst +++ b/docs/library/binascii.rst @@ -35,7 +35,7 @@ Functions Encode binary data in base64 format, as in `RFC 3548 `_. Returns the encoded data - followed by a newline character if ``newline``is true, as a bytes object. + followed by a newline character if ``newline`` is true, as a bytes object. .. function:: crc32(data, value=0, /) diff --git a/docs/library/btree.rst b/docs/library/btree.rst deleted file mode 100644 index 3d58abae6c..0000000000 --- a/docs/library/btree.rst +++ /dev/null @@ -1,161 +0,0 @@ -:mod:`btree` -- simple BTree database -===================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: btree - :synopsis: simple BTree database - -The ``btree`` module implements a simple key-value database using external -storage (disk files, or in general case, a random-access `stream`). Keys are -stored sorted in the database, and besides efficient retrieval by a key -value, a database also supports efficient ordered range scans (retrieval -of values with the keys in a given range). On the application interface -side, BTree database work as close a possible to a way standard `dict` -type works, one notable difference is that both keys and values must -be `bytes` objects (so, if you want to store objects of other types, you -need to serialize them to `bytes` first). - -The module is based on the well-known BerkelyDB library, version 1.xx. - -Example:: - - import btree - - # First, we need to open a stream which holds a database - # This is usually a file, but can be in-memory database - # using io.BytesIO, a raw flash partition, etc. - # Oftentimes, you want to create a database file if it doesn't - # exist and open if it exists. Idiom below takes care of this. - # DO NOT open database with "a+b" access mode. - try: - f = open("mydb", "r+b") - except OSError: - f = open("mydb", "w+b") - - # Now open a database itself - db = btree.open(f) - - # The keys you add will be sorted internally in the database - db[b"3"] = b"three" - db[b"1"] = b"one" - db[b"2"] = b"two" - - # Assume that any changes are cached in memory unless - # explicitly flushed (or database closed). Flush database - # at the end of each "transaction". - db.flush() - - # Prints b'two' - print(db[b"2"]) - - # Iterate over sorted keys in the database, starting from b"2" - # until the end of the database, returning only values. - # Mind that arguments passed to values() method are *key* values. - # Prints: - # b'two' - # b'three' - for word in db.values(b"2"): - print(word) - - del db[b"2"] - - # No longer true, prints False - print(b"2" in db) - - # Prints: - # b"1" - # b"3" - for key in db: - print(key) - - db.close() - - # Don't forget to close the underlying stream! - f.close() - - -Functions ---------- - -.. function:: open(stream, *, flags=0, pagesize=0, cachesize=0, minkeypage=0) - - Open a database from a random-access `stream` (like an open file). All - other parameters are optional and keyword-only, and allow to tweak advanced - parameters of the database operation (most users will not need them): - - * *flags* - Currently unused. - * *pagesize* - Page size used for the nodes in BTree. Acceptable range - is 512-65536. If 0, a port-specific default will be used, optimized for - port's memory usage and/or performance. - * *cachesize* - Suggested memory cache size in bytes. For a - board with enough memory using larger values may improve performance. - Cache policy is as follows: entire cache is not allocated at once; - instead, accessing a new page in database will allocate a memory buffer - for it, until value specified by *cachesize* is reached. Then, these - buffers will be managed using LRU (least recently used) policy. More - buffers may still be allocated if needed (e.g., if a database contains - big keys and/or values). Allocated cache buffers aren't reclaimed. - * *minkeypage* - Minimum number of keys to store per page. Default value - of 0 equivalent to 2. - - Returns a BTree object, which implements a dictionary protocol (set - of methods), and some additional methods described below. - -Methods -------- - -.. method:: btree.close() - - Close the database. It's mandatory to close the database at the end of - processing, as some unwritten data may be still in the cache. Note that - this does not close underlying stream with which the database was opened, - it should be closed separately (which is also mandatory to make sure that - data flushed from buffer to the underlying storage). - -.. method:: btree.flush() - - Flush any data in cache to the underlying stream. - -.. method:: btree.__getitem__(key) - btree.get(key, default=None, /) - btree.__setitem__(key, val) - btree.__delitem__(key) - btree.__contains__(key) - - Standard dictionary methods. - -.. method:: btree.__iter__() - - A BTree object can be iterated over directly (similar to a dictionary) - to get access to all keys in order. - -.. method:: btree.keys([start_key, [end_key, [flags]]]) - btree.values([start_key, [end_key, [flags]]]) - btree.items([start_key, [end_key, [flags]]]) - - These methods are similar to standard dictionary methods, but also can - take optional parameters to iterate over a key sub-range, instead of - the entire database. Note that for all 3 methods, *start_key* and - *end_key* arguments represent key values. For example, `values()` - method will iterate over values corresponding to they key range - given. None values for *start_key* means "from the first key", no - *end_key* or its value of None means "until the end of database". - By default, range is inclusive of *start_key* and exclusive of - *end_key*, you can include *end_key* in iteration by passing *flags* - of `btree.INCL`. You can iterate in descending key direction - by passing *flags* of `btree.DESC`. The flags values can be ORed - together. - -Constants ---------- - -.. data:: INCL - - A flag for `keys()`, `values()`, `items()` methods to specify that - scanning should be inclusive of the end key. - -.. data:: DESC - - A flag for `keys()`, `values()`, `items()` methods to specify that - scanning should be in descending direction of keys. diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst deleted file mode 100644 index 421066b82d..0000000000 --- a/docs/library/framebuf.rst +++ /dev/null @@ -1,170 +0,0 @@ -:mod:`framebuf` --- frame buffer manipulation -============================================= - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: framebuf - :synopsis: Frame buffer manipulation - -This module provides a general frame buffer which can be used to create -bitmap images, which can then be sent to a display. - -class FrameBuffer ------------------ - -The FrameBuffer class provides a pixel buffer which can be drawn upon with -pixels, lines, rectangles, text and even other FrameBuffer's. It is useful -when generating output for displays. - -For example:: - - import framebuf - - # FrameBuffer needs 2 bytes for every RGB565 pixel - fbuf = framebuf.FrameBuffer(bytearray(100 * 10 * 2), 100, 10, framebuf.RGB565) - - fbuf.fill(0) - fbuf.text('MicroPython!', 0, 0, 0xffff) - fbuf.hline(0, 9, 96, 0xffff) - -Constructors ------------- - -.. class:: FrameBuffer(buffer, width, height, format, stride=width, /) - - Construct a FrameBuffer object. The parameters are: - - - *buffer* is an object with a buffer protocol which must be large - enough to contain every pixel defined by the width, height and - format of the FrameBuffer. - - *width* is the width of the FrameBuffer in pixels - - *height* is the height of the FrameBuffer in pixels - - *format* specifies the type of pixel used in the FrameBuffer; - permissible values are listed under Constants below. These set the - number of bits used to encode a color value and the layout of these - bits in *buffer*. - Where a color value c is passed to a method, c is a small integer - with an encoding that is dependent on the format of the FrameBuffer. - - *stride* is the number of pixels between each horizontal line - of pixels in the FrameBuffer. This defaults to *width* but may - need adjustments when implementing a FrameBuffer within another - larger FrameBuffer or screen. The *buffer* size must accommodate - an increased step size. - - One must specify valid *buffer*, *width*, *height*, *format* and - optionally *stride*. Invalid *buffer* size or dimensions may lead to - unexpected errors. - -Drawing primitive shapes ------------------------- - -The following methods draw shapes onto the FrameBuffer. - -.. method:: FrameBuffer.fill(c) - - Fill the entire FrameBuffer with the specified color. - -.. method:: FrameBuffer.pixel(x, y[, c]) - - If *c* is not given, get the color value of the specified pixel. - If *c* is given, set the specified pixel to the given color. - -.. method:: FrameBuffer.hline(x, y, w, c) -.. method:: FrameBuffer.vline(x, y, h, c) -.. method:: FrameBuffer.line(x1, y1, x2, y2, c) - - Draw a line from a set of coordinates using the given color and - a thickness of 1 pixel. The `line` method draws the line up to - a second set of coordinates whereas the `hline` and `vline` - methods draw horizontal and vertical lines respectively up to - a given length. - -.. method:: FrameBuffer.rect(x, y, w, h, c) -.. method:: FrameBuffer.fill_rect(x, y, w, h, c) - - Draw a rectangle at the given location, size and color. The `rect` - method draws only a 1 pixel outline whereas the `fill_rect` method - draws both the outline and interior. - -Drawing text ------------- - -.. method:: FrameBuffer.text(s, x, y[, c]) - - Write text to the FrameBuffer using the the coordinates as the upper-left - corner of the text. The color of the text can be defined by the optional - argument but is otherwise a default value of 1. All characters have - dimensions of 8x8 pixels and there is currently no way to change the font. - - -Other methods -------------- - -.. method:: FrameBuffer.scroll(xstep, ystep) - - Shift the contents of the FrameBuffer by the given vector. This may - leave a footprint of the previous colors in the FrameBuffer. - -.. method:: FrameBuffer.blit(fbuf, x, y, key=-1, palette=None) - - Draw another FrameBuffer on top of the current one at the given coordinates. - If *key* is specified then it should be a color integer and the - corresponding color will be considered transparent: all pixels with that - color value will not be drawn. - - The *palette* argument enables blitting between FrameBuffers with differing - formats. Typical usage is to render a monochrome or grayscale glyph/icon to - a color display. The *palette* is a FrameBuffer instance whose format is - that of the current FrameBuffer. The *palette* height is one pixel and its - pixel width is the number of colors in the source FrameBuffer. The *palette* - for an N-bit source needs 2**N pixels; the *palette* for a monochrome source - would have 2 pixels representing background and foreground colors. The - application assigns a color to each pixel in the *palette*. The color of the - current pixel will be that of that *palette* pixel whose x position is the - color of the corresponding source pixel. - -Constants ---------- - -.. data:: framebuf.MONO_VLSB - - Monochrome (1-bit) color format - This defines a mapping where the bits in a byte are vertically mapped with - bit 0 being nearest the top of the screen. Consequently each byte occupies - 8 vertical pixels. Subsequent bytes appear at successive horizontal - locations until the rightmost edge is reached. Further bytes are rendered - at locations starting at the leftmost edge, 8 pixels lower. - -.. data:: framebuf.MONO_HLSB - - Monochrome (1-bit) color format - This defines a mapping where the bits in a byte are horizontally mapped. - Each byte occupies 8 horizontal pixels with bit 7 being the leftmost. - Subsequent bytes appear at successive horizontal locations until the - rightmost edge is reached. Further bytes are rendered on the next row, one - pixel lower. - -.. data:: framebuf.MONO_HMSB - - Monochrome (1-bit) color format - This defines a mapping where the bits in a byte are horizontally mapped. - Each byte occupies 8 horizontal pixels with bit 0 being the leftmost. - Subsequent bytes appear at successive horizontal locations until the - rightmost edge is reached. Further bytes are rendered on the next row, one - pixel lower. - -.. data:: framebuf.RGB565 - - Red Green Blue (16-bit, 5+6+5) color format - -.. data:: framebuf.GS2_HMSB - - Grayscale (2-bit) color format - -.. data:: framebuf.GS4_HMSB - - Grayscale (4-bit) color format - -.. data:: framebuf.GS8 - - Grayscale (8-bit) color format diff --git a/docs/library/index.rst b/docs/library/index.rst index 48b87a7721..7fda1abd60 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -1,15 +1,13 @@ .. _micropython_lib: -MicroPython libraries -===================== +Standard Libraries +================== -Python standard libraries and micro-libraries ---------------------------------------------- +Python standard libraries +------------------------- -The libraries below are inherited from MicroPython. -They are similar to the standard Python libraries with the same name. -They implement a subset of or a variant of the corresponding -standard Python library. +The libraries below implement a subset of the corresponding +standard Python (CPython) library. They are implemented in C, not Python. CircuitPython's long-term goal is that code written in CircuitPython using Python standard libraries will be runnable on CPython without changes. @@ -38,10 +36,22 @@ These libraries are not currently enabled in any CircuitPython build, but may be ctypes.rst select.rst -Omitted functions in the ``string`` library -------------------------------------------- +Omitted ``string`` functions +---------------------------- A few string operations are not enabled on small builds due to limited flash memory: ``string.center()``, ``string.partition()``, ``string.splitlines()``, ``string.reversed()``. + + +CircuitPython/MicroPython-specific libraries +-------------------------------------------- + +Functionality specific to the CircuitPython/MicroPython implementations is available in +the following libraries. + +.. toctree:: + :maxdepth: 1 + + micropython.rst