Metadata-Version: 1.1
Name: picoredis
Version: 0.1.1
Summary: A very minimal Python Redis client library (not only) for MicroPython
Home-page: https://github.com/SpotlightKid/picoredis
Author: Christopher Arndt
Author-email: chris@chrisarndt.de
License: MIT
Description: PicoRedis
        =========
        
        Overview
        --------
        
        **PicoRedis** is a very minimal Redis client (not only) for MicroPython.
        
        What is does
        ~~~~~~~~~~~~
        
        -  Support the **RE**\ dis **S**\ erialization **P**\ rotocol
           (`RESP <https://redis.io/topics/protocol>`__).
        -  Connect to a Redis server via TCP.
        -  Send `Redis commands <https://redis.io/commands>`__ and receive and
           parse the response in a simple, blocking fashion.
        -  Support MicroPython (unix and bare-metal ports with ``usocket`` and
           ``uselect`` module), CPython and PyPy (3.4+, 2.7+ untested).
        
        What it does not
        ~~~~~~~~~~~~~~~~
        
        -  Parse the response beyond de-serialization of the basic RESP types
           (``simple string``, ``error``, ``bulk string``, ``integer`` and
           ``array``).
        -  Decode response byte strings, except error messages.
        -  Support the subscribe / publish protocol.
        -  Support SSL / TLS (yet).
        -  Async I/O.
        
        Usage
        -----
        
        .. code:: python
        
            >>> from picoredis import Redis
            >>> redis = Redis()  # server defaults to 127.0.0.1 port 6379
            >>> redis.do_cmd('PING', 'Hello World!')
            b'Hello World!'
        
        Instead of using the ``do_cmd`` method, ``Redis`` instances can be
        called directly:
        
        .. code:: python
        
            >>> redis('SET', 'foo', 'bar')
            b'OK'
            >>> redis('GET', 'foo')
            b'bar'  # string responses are always byte strings
        
        Or you can call arbitrary methods on the ``Redis`` instance, and the
        method name will be used as the Redis command:
        
        .. code:: python
        
            >>> redis.hset('myhash', 'key1', 42)
            1
            >>> redis.hkeys('myhash')
            [b'key1']
        
        You can use any method name consisting of *only* letters, except
        ``connect``, ``close``, ``debug`` (and ``do_cmd``), which are already
        used as instance attribute or method names. If the name does not
        correspond to a valid Redis command, the server will return an error and
        a ``RedisError`` exception will be raised:
        
        .. code:: python
        
            >>> redis.bogus('spam!')
            Traceback (most recent call last):
              File "<stdin>", line 1, in <module>
              File "picoredis.py", line 72, in <lambda>
              File "picoredis.py", line 66, in do_cmd
              File "picoredis.py", line 82, in _read_response
            RedisError: ('ERR', "unknown command 'bogus'")
        
        Connection
        ~~~~~~~~~~
        
        When you create a ``Redis`` instance, it immediatly tries to open a
        connecting to the Redis server. The default host and port are
        ``127.0.0.1`` and ``6379`` respectively.
        
        You can set the host name or IP address and port number of the Redis
        server to connect with the ``host`` and ``port`` keyword arguments:
        
        .. code:: python
        
            >>> redis = Redis('192.168.1.100')
            >>> redis = Redis(port=6380)
            >>> redis = Redis('192.168.1.100', 6380)
            >>> redis = Redis(host='192.168.1.100')
            >>> redis = Redis(host='192.168.1.100', port=6380)
        
        You can set the TCP socket timeout with the ``timeout`` keyword argument
        in milliseconds (default 3000):
        
        .. code:: python
        
            >>> redis = Redis(timeout=10000)
        
        If a response is read from the server and the server doesn’t return any
        data within the timeout, a ``RedisTimeout`` exception is raised.
        
        To close the connection to the server, use the ``close()`` method:
        
        .. code:: python
        
            >>> redis.close()
            >>> redis.ping()
            Traceback (most recent call last):
              File "<stdin>", line 1, in <module>
              File "picoredis.py", line 89, in <lambda>
              File "picoredis.py", line 75, in do_cmd
            RedisError: Not connected: use 'connect()' to connect to Redis server.
        
        To open a new connection again, use the ``connect`` method. You can pass
        a different host name and / or port number and they will overwrite the
        ones given when the instance was created:
        
        .. code:: python
        
            >>> redis.connect('redis.myserver.com')
            >>> redis._host
            'redis.myserver.com'
        
        Debug Output
        ~~~~~~~~~~~~
        
        To turn on printing of raw messages sent to and received from the Redis
        server pass ``debug=True`` when creating the instance or set its
        ``debug`` attribute to ``True``:
        
        .. code:: python
        
            >>> redis = Redis(debug=True)
            >>> redis.hkeys('myhash')
            SEND: '*2\r\n$5\r\nhkeys\r\n$6\r\nmyhash\r\n'
            RECV: b'*1\r\n'
            RECV: b'$4\r\n'
            RECV: b'key1\r\n'
            [b'key1']
        
        Tips
        ~~~~
        
        If you need to further parse the response to a Redis command regularly,
        just add a wrapper method in a sub-class. For example, here is how to
        get the list of commands supported by the Redis server as a list of
        strings:
        
        .. code:: python
        
            >>> class MyRedis(Redis):
            ...     def command_list(self):
            ...         return sorted([cmd[0].decode('utf-8')
            ...                        for cmd in self.do_cmd('command')])
            >>> redis = MyRedis()
            >>> redis.command_list()
            ['append', 'asking', 'auth', 'bgrewriteaof', 'bgsave', 'bitcount', 'bitfield',
             ..., 'zunionstore']
        
        **Warning:** The response to this command sent be the Redis server will
        be fairly big and probably cause a ``MemoryError``, when you run it on a
        memory-constrained device like an ESP8266-based board.
        
        Installation
        ------------
        
        On CPython and PyPy use ``pip`` to install as usual:
        
        ::
        
            $ pip install picoredis
        
        On MicroPython, just download the
        `picoredis.py <https://raw.githubusercontent.com/SpotlightKid/picoredis/master/picoredis/picoredis.py>`__
        file from the repository and, for the unix port, put it into your
        MICROPYPATH directory (normally ``~/.micropython/lib``), or for
        base-metal ports (*esp8266*, *stm32*, *wipy*, etc.) upload it to the
        flash storage of your MicroPython board, for example using
        `ampy <https://github.com/adafruit/ampy>`__:
        
        ::
        
            $ curl -O https://raw.githubusercontent.com/SpotlightKid/picoredis/master/picoredis/picoredis.py
            $ ampy -p /dev/ttyUSB0 put picoredis.py
        
        You can also compile the ``picoredis.py`` module with
        `mpy-cross <https://github.com/micropython/micropython/tree/master/mpy-cross>`__
        and use the resulting ``picoredis.mpy`` file as a drop-in replacement
        for the pure Python version. This will save you a good bit of memory on
        your MicroPython board, because the byte-code compilation step, that
        normally happens when you import the module, can be skipped:
        
        ::
        
            $ mpy-cross picoredis.py
            $ ampy -p /dev/ttyUSB0 put picoredis.mpy
        
        License
        -------
        
        **PicoRedis** was written and is copyrighted by Christopher Arndt, 2017.
        
        It is distributed under the terms of the `MIT
        license <http://opensource.org/licenses/MIT>`__, **PicoRedis** is free
        and open source software.
        
        Acknowledgements
        ----------------
        
        Some inspiration and code ideas were taken from these projects:
        
        -  `micropython-redis <https://github.com/dwighthubbard/micropython-redis>`__
           by Dwight Hubbard
        -  `redis_protocol <https://github.com/wayhome/redis_protocol>`__ by
           Young King
        
Keywords: database,micropython,redis,network
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Other Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: MicroPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Database
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
