Skip to content
GitLab
Explore
Sign in
Register
Primary navigation
Search or go to…
Project
M
micropython
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Build
Pipelines
Jobs
Pipeline schedules
Artifacts
Deploy
Releases
Container registry
Model registry
Operate
Environments
Monitor
Incidents
Service Desk
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
GitLab community forum
Contribute to GitLab
Provide feedback
Terms and privacy
Keyboard shortcuts
?
Snippets
Groups
Projects
This is an archived project. Repository and other project resources are read-only.
Show more breadcrumbs
card10
micropython
Commits
1942f0ce
Commit
1942f0ce
authored
Jun 28, 2017
by
Paul Sokolovsky
Browse files
Options
Downloads
Patches
Plain Diff
docs/{framebuf,usocket}: Use markup adhering to the latest docs conventions.
parent
346f5d4c
No related branches found
No related tags found
No related merge requests found
Changes
2
Show whitespace changes
Inline
Side-by-side
Showing
2 changed files
docs/library/framebuf.rst
+12
-12
12 additions, 12 deletions
docs/library/framebuf.rst
docs/library/usocket.rst
+49
-46
49 additions, 46 deletions
docs/library/usocket.rst
with
61 additions
and
58 deletions
docs/library/framebuf.rst
+
12
−
12
View file @
1942f0ce
...
@@ -32,25 +32,25 @@ Constructors
...
@@ -32,25 +32,25 @@ Constructors
Construct a FrameBuffer object. The parameters are:
Construct a FrameBuffer object. The parameters are:
-
`
buffer
`
is an object with a buffer protocol which must be large
-
*
buffer
*
is an object with a buffer protocol which must be large
enough to contain every pixel defined by the width, height and
enough to contain every pixel defined by the width, height and
format of the FrameBuffer.
format of the FrameBuffer.
-
`
width
`
is the width of the FrameBuffer in pixels
-
*
width
*
is the width of the FrameBuffer in pixels
-
`
height
`
is the height of the FrameBuffer in pixels
-
*
height
*
is the height of the FrameBuffer in pixels
-
`
format
`
specifies the type of pixel used in the FrameBuffer;
-
*
format
*
specifies the type of pixel used in the FrameBuffer;
valid values are ``framebuf.MVLSB``, ``framebuf.RGB565``
valid values are ``framebuf.MVLSB``, ``framebuf.RGB565``
and ``framebuf.GS4_HMSB``. MVLSB is monochrome 1-bit color,
and ``framebuf.GS4_HMSB``. MVLSB is monochrome 1-bit color,
RGB565 is RGB 16-bit color, and GS4_HMSB is grayscale 4-bit color.
RGB565 is RGB 16-bit color, and GS4_HMSB is grayscale 4-bit color.
Where a color value c is passed to a method, c is a small integer
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.
with an encoding that is dependent on the format of the FrameBuffer.
-
`
stride
`
is the number of pixels between each horizontal line
-
*
stride
*
is the number of pixels between each horizontal line
of pixels in the FrameBuffer. This defaults to
`
width
`
but may
of pixels in the FrameBuffer. This defaults to
*
width
*
but may
need adjustments when implementing a FrameBuffer within another
need adjustments when implementing a FrameBuffer within another
larger FrameBuffer or screen. The
`
buffer
`
size must accommodate
larger FrameBuffer or screen. The
*
buffer
*
size must accommodate
an increased step size.
an increased step size.
One must specify valid
`
buffer
`
,
`
width
`
,
`
height
`
,
`
format
`
and
One must specify valid
*
buffer
*
,
*
width
*
,
*
height
*
,
*
format
*
and
optionally
`
stride
`
. Invalid
`
buffer
`
size or dimensions may lead to
optionally
*
stride
*
. Invalid
*
buffer
*
size or dimensions may lead to
unexpected errors.
unexpected errors.
Drawing primitive shapes
Drawing primitive shapes
...
@@ -64,8 +64,8 @@ The following methods draw shapes onto the FrameBuffer.
...
@@ -64,8 +64,8 @@ The following methods draw shapes onto the FrameBuffer.
.. method:: FrameBuffer.pixel(x, y[, c])
.. method:: FrameBuffer.pixel(x, y[, c])
If
`c`
is not given, get the color value of the specified pixel.
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.
If
*c*
is given, set the specified pixel to the given color.
.. method:: FrameBuffer.hline(x, y, w, c)
.. method:: FrameBuffer.hline(x, y, w, c)
.. method:: FrameBuffer.vline(x, y, h, c)
.. method:: FrameBuffer.vline(x, y, h, c)
...
@@ -106,7 +106,7 @@ Other methods
...
@@ -106,7 +106,7 @@ Other methods
.. method:: FrameBuffer.blit(fbuf, x, y[, key])
.. method:: FrameBuffer.blit(fbuf, x, y[, key])
Draw another FrameBuffer on top of the current one at the given coordinates.
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
If
*
key
*
is specified then it should be a color integer and the
corresponding color will be considered transparent: all pixels with that
corresponding color will be considered transparent: all pixels with that
color value will not be drawn.
color value will not be drawn.
...
...
This diff is collapsed.
Click to expand it.
docs/library/usocket.rst
+
49
−
46
View file @
1942f0ce
...
@@ -14,14 +14,14 @@ for comparison.
...
@@ -14,14 +14,14 @@ for comparison.
:class: attention
:class: attention
CPython used to have a ``socket.error`` exception which is now deprecated,
CPython used to have a ``socket.error`` exception which is now deprecated,
and is an alias of OSError. In MicroPython, use OSError directly.
and is an alias of
`
OSError
`
. In MicroPython, use
`
OSError
`
directly.
.. admonition:: Difference to CPython
.. admonition:: Difference to CPython
:class: attention
:class: attention
For efficiency and consistency, socket objects in MicroPython implement a stream
For efficiency and consistency, socket objects in MicroPython implement a stream
(file-like) interface directly. In CPython, you need to convert a socket to
(file-like) interface directly. In CPython, you need to convert a socket to
a file-like object using
`
`makefile()`
`
method. This method is still supported
a file-like object using `makefile()` method. This method is still supported
by MicroPython (but is a no-op), so where compatibility with CPython matters,
by MicroPython (but is a no-op), so where compatibility with CPython matters,
be sure to use it.
be sure to use it.
...
@@ -29,19 +29,19 @@ Socket address format(s)
...
@@ -29,19 +29,19 @@ Socket address format(s)
------------------------
------------------------
The functions below which expect a network address, accept it in the format of
The functions below which expect a network address, accept it in the format of
`
(ipv4_address, port)
`
, where
`
ipv4_address
`
is a string with dot-notation numeric
*
(ipv4_address, port)
*
, where
*
ipv4_address
*
is a string with dot-notation numeric
IPv4 address, e.g. ``"8.8.8.8"``, and port is integer port number in the range
IPv4 address, e.g. ``"8.8.8.8"``, and port is integer port number in the range
1-65535. Note the domain names are not accepted as
`
ipv4_address
`
, they should be
1-65535. Note the domain names are not accepted as
*
ipv4_address
*
, they should be
resolved first using `
`
socket.getaddrinfo()`
`
.
resolved first using `
u
socket.getaddrinfo()`.
Functions
Functions
---------
---------
.. function:: socket
.socket(socket.
AF_INET,
socket.
SOCK_STREAM,
socket.
IPPROTO_TCP)
.. function:: socket
(af=
AF_INET,
type=
SOCK_STREAM,
proto=
IPPROTO_TCP)
Create a new socket using the given address family, socket type and protocol number.
Create a new socket using the given address family, socket type and protocol number.
.. function::
socket.
getaddrinfo(host, port)
.. function:: getaddrinfo(host, port)
Translate the host/port argument into a sequence of 5-tuples that contain all the
Translate the host/port argument into a sequence of 5-tuples that contain all the
necessary arguments for creating a socket connected to that service. The list of
necessary arguments for creating a socket connected to that service. The list of
...
@@ -57,11 +57,11 @@ Functions
...
@@ -57,11 +57,11 @@ Functions
.. admonition:: Difference to CPython
.. admonition:: Difference to CPython
:class: attention
:class: attention
CPython raises a ``socket.gaierror`` exception (OSError subclass) in case
CPython raises a ``socket.gaierror`` exception (
`
OSError
`
subclass) in case
of error in this function. MicroPython doesn't have ``socket.gaierror``
of error in this function. MicroPython doesn't have ``socket.gaierror``
and raises OSError directly. Note that error numbers of
`
`getaddrinfo()`
`
and raises OSError directly. Note that error numbers of `getaddrinfo()`
form a separate namespace and may not match error numbers from
form a separate namespace and may not match error numbers from
`
`uerrno`
`
module. To distinguish
`
`getaddrinfo()`
`
errors, they are
`uerrno` module. To distinguish `getaddrinfo()` errors, they are
represented by negative numbers, whereas standard system errors are
represented by negative numbers, whereas standard system errors are
positive numbers (error numbers are accessible using ``e.args[0]`` property
positive numbers (error numbers are accessible using ``e.args[0]`` property
from an exception object). The use of negative values is a provisional
from an exception object). The use of negative values is a provisional
...
@@ -70,32 +70,34 @@ Functions
...
@@ -70,32 +70,34 @@ Functions
Constants
Constants
---------
---------
.. data::
socket.
AF_INET
.. data:: AF_INET
socket.
AF_INET6
AF_INET6
Address family types. Availability depends on a particular board.
Address family types. Availability depends on a particular board.
.. data::
socket.
SOCK_STREAM
.. data:: SOCK_STREAM
socket.
SOCK_DGRAM
SOCK_DGRAM
Socket types.
Socket types.
.. data::
socket.
IPPROTO_UDP
.. data:: IPPROTO_UDP
socket.
IPPROTO_TCP
IPPROTO_TCP
IP protocol numbers.
IP protocol numbers.
.. data:: socket.SOL_*
.. data::
u
socket.SOL_*
Socket option levels (an argument to ``setsockopt()``). The exact inventory depends on a board.
Socket option levels (an argument to `setsockopt()`). The exact
inventory depends on a MicroPython port.
.. data:: socket.SO_*
.. data::
u
socket.SO_*
Socket options (an argument to ``setsockopt()``). The exact inventory depends on a board.
Socket options (an argument to `setsockopt()`). The exact
inventory depends on a MicroPython port.
Constants specific to WiPy:
Constants specific to WiPy:
.. data::
socket.
IPPROTO_SEC
.. data:: IPPROTO_SEC
Special protocol value to create SSL-compatible socket.
Special protocol value to create SSL-compatible socket.
...
@@ -105,21 +107,22 @@ class socket
...
@@ -105,21 +107,22 @@ class socket
Methods
Methods
-------
-------
.. method:: socket.close
.. method:: socket.close
()
Mark the socket closed. Once that happens, all future operations on the socket
Mark the socket closed and release all resources. Once that happens, all future operations
object will fail. The remote end will receive no more data (after queued data is flushed).
on the socket object will fail. The remote end will receive EOF indication if
supported by protocol.
Sockets are automatically closed when they are garbage-collected, but it is recommended
Sockets are automatically closed when they are garbage-collected, but it is recommended
to close() them explicitly
, or to use a with statement around
them.
to
`
close()
`
them explicitly
as soon you finished working with
them.
.. method:: socket.bind(address)
.. method:: socket.bind(address)
Bind the socket to address. The socket must not already be bound.
Bind the socket to
*
address
*
. The socket must not already be bound.
.. method:: socket.listen([backlog])
.. method:: socket.listen([backlog])
Enable a server to accept connections. If backlog is specified, it must be at least 0
Enable a server to accept connections. If
*
backlog
*
is specified, it must be at least 0
(if it's lower, it will be set to 0); and specifies the number of unaccepted connections
(if it's lower, it will be set to 0); and specifies the number of unaccepted connections
that the system will allow before refusing new connections. If not specified, a default
that the system will allow before refusing new connections. If not specified, a default
reasonable value is chosen.
reasonable value is chosen.
...
@@ -133,7 +136,7 @@ Methods
...
@@ -133,7 +136,7 @@ Methods
.. method:: socket.connect(address)
.. method:: socket.connect(address)
Connect to a remote socket at address.
Connect to a remote socket at
*
address
*
.
.. method:: socket.send(bytes)
.. method:: socket.send(bytes)
...
@@ -144,11 +147,11 @@ Methods
...
@@ -144,11 +147,11 @@ Methods
.. method:: socket.sendall(bytes)
.. method:: socket.sendall(bytes)
Send all data to the socket. The socket must be connected to a remote socket.
Send all data to the socket. The socket must be connected to a remote socket.
Unlike
`
`send()`
`
, this method will try to send all of data, by sending data
Unlike `send()`, this method will try to send all of data, by sending data
chunk by chunk consecutively.
chunk by chunk consecutively.
The behavior of this method on non-blocking sockets is undefined. Due to this,
The behavior of this method on non-blocking sockets is undefined. Due to this,
on MicroPython, it's recommended to use
`
`write()`
`
method instead, which
on MicroPython, it's recommended to use `write()` method instead, which
has the same "no short writes" policy for blocking sockets, and will return
has the same "no short writes" policy for blocking sockets, and will return
number of bytes sent on non-blocking sockets.
number of bytes sent on non-blocking sockets.
...
@@ -160,25 +163,25 @@ Methods
...
@@ -160,25 +163,25 @@ Methods
.. method:: socket.sendto(bytes, address)
.. method:: socket.sendto(bytes, address)
Send data to the socket. The socket should not be connected to a remote socket, since the
Send data to the socket. The socket should not be connected to a remote socket, since the
destination socket is specified by
`
address
`
.
destination socket is specified by
*
address
*
.
.. method:: socket.recvfrom(bufsize)
.. method:: socket.recvfrom(bufsize)
Receive data from the socket. The return value is a pair (bytes, address) where bytes is a
Receive data from the socket. The return value is a pair
*
(bytes, address)
*
where
*
bytes
*
is a
bytes object representing the data received and address is the address of the socket sending
bytes object representing the data received and
*
address
*
is the address of the socket sending
the data.
the data.
.. method:: socket.setsockopt(level, optname, value)
.. method:: socket.setsockopt(level, optname, value)
Set the value of the given socket option. The needed symbolic constants are defined in the
Set the value of the given socket option. The needed symbolic constants are defined in the
socket module (SO_* etc.). The value can be an integer or a bytes-like object representing
socket module (SO_* etc.). The
*
value
*
can be an integer or a bytes-like object representing
a buffer.
a buffer.
.. method:: socket.settimeout(value)
.. method:: socket.settimeout(value)
Set a timeout on blocking socket operations. The value argument can be a nonnegative floating
Set a timeout on blocking socket operations. The value argument can be a nonnegative floating
point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations
point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations
will raise an
`
`OSError`
`
exception if the timeout period value has elapsed before the operation has
will raise an `OSError` exception if the timeout period value has elapsed before the operation has
completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket
completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket
is put in blocking mode.
is put in blocking mode.
...
@@ -186,7 +189,7 @@ Methods
...
@@ -186,7 +189,7 @@ Methods
:class: attention
:class: attention
CPython raises a ``socket.timeout`` exception in case of timeout,
CPython raises a ``socket.timeout`` exception in case of timeout,
which is an
`
`OSError`
`
subclass. MicroPython raises an OSError directly
which is an `OSError` subclass. MicroPython raises an OSError directly
instead. If you use ``except OSError:`` to catch the exception,
instead. If you use ``except OSError:`` to catch the exception,
your code will work both in MicroPython and CPython.
your code will work both in MicroPython and CPython.
...
@@ -195,7 +198,7 @@ Methods
...
@@ -195,7 +198,7 @@ Methods
Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking,
Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking,
else to blocking mode.
else to blocking mode.
This method is a shorthand for certain
`
`settimeout()`
`
calls:
This method is a shorthand for certain `settimeout()` calls:
* ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)``
* ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)``
* ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0)``
* ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0)``
...
@@ -204,12 +207,12 @@ Methods
...
@@ -204,12 +207,12 @@ Methods
Return a file object associated with the socket. The exact returned type depends on the arguments
Return a file object associated with the socket. The exact returned type depends on the arguments
given to makefile(). The support is limited to binary modes only ('rb', 'wb', and 'rwb').
given to makefile(). The support is limited to binary modes only ('rb', 'wb', and 'rwb').
CPython's arguments:
``
encoding
``, ``
errors
``
and
``
newline
``
are not supported.
CPython's arguments:
*
encoding
*, *
errors
*
and
*
newline
*
are not supported.
.. admonition:: Difference to CPython
.. admonition:: Difference to CPython
:class: attention
:class: attention
As MicroPython doesn't support buffered streams, values of
``
buffering
``
As MicroPython doesn't support buffered streams, values of
*
buffering
*
parameter is ignored and treated as if it was 0 (unbuffered).
parameter is ignored and treated as if it was 0 (unbuffered).
.. admonition:: Difference to CPython
.. admonition:: Difference to CPython
...
@@ -220,19 +223,19 @@ Methods
...
@@ -220,19 +223,19 @@ Methods
.. method:: socket.read([size])
.. method:: socket.read([size])
Read up to size bytes from the socket. Return a bytes object. If
``
size
``
is not given, it
Read up to size bytes from the socket. Return a bytes object. If
*
size
*
is not given, it
reads all data available from the socket until
``
EOF
``
; as such the method will not return until
reads all data available from the socket until EOF; as such the method will not return until
the socket is closed. This function tries to read as much data as
the socket is closed. This function tries to read as much data as
requested (no "short reads"). This may be not possible with
requested (no "short reads"). This may be not possible with
non-blocking socket though, and then less data will be returned.
non-blocking socket though, and then less data will be returned.
.. method:: socket.readinto(buf[, nbytes])
.. method:: socket.readinto(buf[, nbytes])
Read bytes into the
``
buf
``
. If
``
nbytes
``
is specified then read at most
Read bytes into the
*
buf
*
. If
*
nbytes
*
is specified then read at most
that many bytes. Otherwise, read at most
``
len(buf)
``
bytes. Just as
that many bytes. Otherwise, read at most
*
len(buf)
*
bytes. Just as
`
`read()`
`
, this method follows "no short reads" policy.
`read()`, this method follows "no short reads" policy.
Return value: number of bytes read and stored into
``
buf
``
.
Return value: number of bytes read and stored into
*
buf
*
.
.. method:: socket.readline()
.. method:: socket.readline()
...
@@ -245,6 +248,6 @@ Methods
...
@@ -245,6 +248,6 @@ Methods
Write the buffer of bytes to the socket. This function will try to
Write the buffer of bytes to the socket. This function will try to
write all data to a socket (no "short writes"). This may be not possible
write all data to a socket (no "short writes"). This may be not possible
with a non-blocking socket though, and returned value will be less than
with a non-blocking socket though, and returned value will be less than
the length of
``
buf
``
.
the length of
*
buf
*
.
Return value: number of bytes written.
Return value: number of bytes written.
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment