update docs

Author: ofabel

docs/pages/conf.py

@@ -5,11 +5,26 @@
 base = pathlib.Path(__file__).parent.parent.parent
 root = base.__str__()
 flipperzero = base.joinpath('flipperzero').__str__()
-now = datetime.datetime.now()
 
 sys.path.append(root)
 sys.path.append(flipperzero)
 
+def copy_dict(source, target):
+    for key, value in source.__dict__.items():
+        target.__dict__[key] = value
+
+import flipperzero.logging
+import logging
+
+copy_dict(flipperzero.logging, logging)
+
+import flipperzero.io
+import io
+
+copy_dict(flipperzero.io, io)
+
+now = datetime.datetime.now()
+
 project = 'uPython'
 copyright = str(now.year) + ', Oliver Fabel'
 author = 'Oliver Fabel'

docs/pages/reference.rst

@@ -416,25 +416,84 @@ Classes
 ~~~~~~~
 
 .. autoclass:: flipperzero.UART
-   :members: read, readline, readlines, write, flush
+   :members: read, readline, readlines, write, flush, close, __enter__, __exit__, __del__
+
+Logging
+-------
+
+Log messages to the Flipper's own logging backend.
+Check out the `Flipper Zero docs <https://docs.flipper.net/development/cli#_yZ2E>`_ on how to reveal them in the CLI.
+Be aware, that you can't change Flipper's global log level from within your script.
+Change the `corresponding settings <https://docs.flipper.net/basics/settings#d5TAt>`_ instead or use the **log** command in the CLI with the desired log level as the first argument.
+
+Levels
+~~~~~~
+
+.. autodata:: logging.TRACE
+.. autodata:: logging.DEBUG
+.. autodata:: logging.INFO
+.. autodata:: logging.WARN
+.. autodata:: logging.ERROR
+.. autodata:: logging.NONE
+.. autodata:: logging.level
+
+Functions
+~~~~~~~~~
+
+.. autofunction:: logging.setLevel
+.. autofunction:: logging.getEffectiveLevel
+.. autofunction:: logging.trace
+.. autofunction:: logging.debug
+.. autofunction:: logging.info
+.. autofunction:: logging.warn
+.. autofunction:: logging.error
+.. autofunction:: logging.log
+
+I/O
+---
+
+Constants
+~~~~~~~~~
+
+.. autodata:: io.SEEK_SET
+.. autodata:: io.SEEK_CUR
+.. autodata:: io.SEEK_END
+
+Functions
+~~~~~~~~~
+
+.. autofunction:: io.open
+
+Classes
+~~~~~~~
+
+.. autoclass:: io.BinaryFileIO
+   :members: name, read, readline, readlines, readable, writable, write, flush, seek, tell, close, __enter__, __exit__, __del__
+
+.. autoclass:: io.TextFileIO
+   :members: name, read, readline, readlines, readable, writable, write, flush, seek, tell, close, __enter__, __exit__, __del__
 
 Built-In
 --------
 
 The functions in this section are `not` part of the ``flipperzero`` module.
 They're members of the global namespace instead.
 
-.. py:function:: print(*objects, sep=' ', end='\n', file=None, flush=False) -> None
+.. py:function:: print(*objects, sep=' ', end='\n') -> None
 
    The standard Python `print <https://docs.python.org/3/library/functions.html#print>`_ function.
+   Where the output of this function will be redirected depends on how the script is invoked:
+
+      * When invoked from the UI, the output will be sent to the Flipper's log buffer.
+        Check out the `Flipper Zero docs <https://docs.flipper.net/development/cli#_yZ2E>`_ on how to view them in the CLI interface.
+      * In the REPL, the output will be sent to the standard output buffer.
+      * When invoked by the **py** command, the output will be sent to the standard output buffer.
 
    :param objects: The objects to print (mostly a single string).
    :param sep: The separator to use between the objects.
    :param end: The line terminator character to use.
 
    .. versionadded:: 1.0.0
+   .. versionchanged:: 1.5.0
 
-   .. attention::
-      
-      This function prints to the internal log buffer.
-      Check out the `Flipper Zero docs <https://docs.flipper.net/development/cli#_yZ2E>`_ on how to reveal them in the CLI interface.
+      Output redirection, based on script invocation.

flipperzero/_uart.py

@@ -29,6 +29,15 @@ class UART:
 
         with f0.open(f0.UART_MODE_USART, 115200) as uart:
             lines = [line for line in uart]
+    
+    An :class:`UART` instance can be used with a `context manager <https://docs.python.org/3/reference/datamodel.html#with-statement-context-managers>`_:
+
+    .. code-block::
+
+        import flipperzero as f0
+
+        with f0.open(f0.UART_MODE_USART, 115200) as uart:
+            ...
 
     .. hint::
 
@@ -94,6 +103,44 @@ def flush(self) -> None:
         '''
         Flush the transmission buffer to the underlying UART connection.
         This method blocks until all data is sent.
+
+        .. versionadded:: 1.5.0
+        '''
+        pass
+
+    def close(self) -> None:
+        '''
+        Close the UART connection.
+
+        .. versionadded:: 1.5.0
+        '''
+        pass
+
+    def __enter__(self) -> 'UART':
+        '''
+        This method is invoked, when the instance enters a runtime context.
+
+        :returns: The :class:`UART` connection.
+
+        .. versionadded:: 1.5.0
+        '''
+        pass
+
+    def __exit__(self, *args, **kwargs) -> None:
+        '''
+        This method is invoked, when the instance leavs a runtime context.
+        This basically calls :meth:`close` on the instance.
+
+        .. versionadded:: 1.5.0
+        '''
+        pass
+
+    def __del__(self) -> None:
+        '''
+        This method is invoked, when the garbage collector removes the object.
+        This basically calls :meth:`close` on the instance.
+
+        .. versionadded:: 1.5.0
         '''
         pass