"""Redis Key Commands Mixin"""
from tornado import concurrent

# Python 2 support for ascii()
if 'ascii' not in dir(__builtins__):  # pragma: nocover
    from tredis.compat import ascii


class KeysMixin(object):
    """Redis Key Commands Mixin"""

    def delete(self, *keys):
        """Removes the specified keys. A key is ignored if it does not exist.
        Returns :data:`True` if all keys are removed.

        .. note::

           **Time complexity**: ``O(N)`` where ``N`` is the number of keys that
           will be removed. When a key to remove holds a value other than a
           string, the individual complexity for this key is ``O(M)`` where
           ``M`` is the number of elements in the list, set, sorted set or
           hash. Removing a single key that holds a string value is ``O(1)``.

        :param keys: One or more keys to remove
        :type keys: :class:`str`, :class:`bytes`
        :rtype: bool
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'DEL'] + list(keys), len(keys))

    def dump(self, key):
        """Serialize the value stored at key in a Redis-specific format and
        return it to the user. The returned value can be synthesized back into
        a Redis key using the :meth:`~tredis.RedisClient.restore` command.

        The serialization format is opaque and non-standard, however it has a
        few semantic characteristics:

          - It contains a 64-bit checksum that is used to make sure errors
            will be detected. The :meth:`~tredis.RedisClient.restore` command
            makes sure to check the checksum before synthesizing a key using
            the serialized value.
          - Values are encoded in the same format used by RDB.
          - An RDB version is encoded inside the serialized value, so that
            different Redis versions with incompatible RDB formats will
            refuse to process the serialized value.
          - The serialized value does NOT contain expire information. In
            order to capture the time to live of the current value the
            :meth:`~tredis.RedisClient.pttl` command should be used.

        If key does not exist :data:`None` is returned.

        .. note::

           **Time complexity**: ``O(1)`` to access the key and additional
           ``O(N*M)`` to serialized it, where N is the number of Redis objects
           composing the value and ``M`` their average size. For small string
           values the time complexity is thus ``O(1)+O(1*M)`` where ``M`` is
           small, so simply ``O(1)``.

        :param key: The key to dump
        :type key: :class:`str`, :class:`bytes`
        :rtype: bytes, None

        """
        return self._execute([b'DUMP', key])

    def exists(self, key):
        """Returns :data:`True` if the key exists.

        .. note::

           **Time complexity**: ``O(1)``

        **Command Type**: String

        :param key: One or more keys to check for
        :type key: :class:`str`, :class:`bytes`
        :rtype: bool
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'EXISTS', key], 1)

    def expire(self, key, timeout):
        """Set a timeout on key. After the timeout has expired, the key will
        automatically be deleted. A key with an associated timeout is often
        said to be volatile in Redis terminology.

        The timeout is cleared only when the key is removed using the
        :meth:`~tredis.RedisClient.delete` method or overwritten using the
        :meth:`~tredis.RedisClient.set` or :meth:`~tredis.RedisClient.getset`
        methods. This means that all the operations that conceptually alter the
        value stored at the key without replacing it with a new one will leave
        the timeout untouched. For instance, incrementing the value of a key
        with :meth:`~tredis.RedisClient.incr`, pushing a new value into a
        list with :meth:`~tredis.RedisClient.lpush`, or altering the field
        value of a hash with :meth:`~tredis.RedisClient.hset` are all
        operations that will leave the timeout untouched.

        The timeout can also be cleared, turning the key back into a persistent
        key, using the :meth:`~tredis.RedisClient.persist` method.

        If a key is renamed with :meth:`~tredis.RedisClient.rename`,
        the associated time to live is transferred to the new key name.

        If a key is overwritten by :meth:`~tredis.RedisClient.rename`, like in
        the case of an existing key ``Key_A`` that is overwritten by a call
        like ``client.rename(Key_B, Key_A)`` it does not matter if the original
        ``Key_A`` had a timeout associated or not, the new key ``Key_A`` will
        inherit all the characteristics of ``Key_B``.

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to set an expiration for
        :type key: :class:`str`, :class:`bytes`
        :param int timeout: The number of seconds to set the timeout to
        :rtype: bool
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute(
            [b'EXPIRE', key, ascii(timeout).encode('ascii')], 1)

    def expireat(self, key, timestamp):
        """:meth:`~tredis.RedisClient.expireat` has the same effect and
        semantic as :meth:`~tredis.RedisClient.expire`, but instead of
        specifying the number of seconds representing the TTL (time to live),
        it takes an absolute Unix timestamp (seconds since January 1, 1970).

        Please for the specific semantics of the command refer to the
        documentation of :meth:`~tredis.RedisClient.expire`.

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to set an expiration for
        :type key: :class:`str`, :class:`bytes`
        :param int timestamp: The UNIX epoch value for the expiration
        :rtype: bool
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute(
            [b'EXPIREAT', key,
             ascii(timestamp).encode('ascii')], 1)

    def keys(self, pattern):
        """Returns all keys matching pattern.

        While the time complexity for this operation is ``O(N)``, the constant
        times are fairly low. For example, Redis running on an entry level
        laptop can scan a 1 million key database in 40 milliseconds.

        .. warning:: Consider :meth:`~tredis.RedisClient.keys` as a
           command that should only be used in production environments with
           extreme care. It may ruin performance when it is executed against
           large databases. This command is intended for debugging and special
           operations, such as changing your keyspace layout. Don't use
           :meth:`~tredis.RedisClient.keys` in your regular application code.
           If you're looking for a way to find keys in a subset of your
           keyspace, consider using :meth:`~tredis.RedisClient.scan` or sets.

        Supported glob-style patterns:

         - ``h?llo`` matches ``hello``, ``hallo`` and ``hxllo``
         - ``h*llo`` matches ``hllo`` and ``heeeello``
         - ``h[ae]llo`` matches ``hello`` and ``hallo``, but not ``hillo``
         - ``h[^e]llo`` matches ``hallo``, ``hbllo``, but not ``hello``
         - ``h[a-b]llo`` matches ``hallo`` and ``hbllo``

        Use a backslash (``\``) to escape special characters if you want to
        match them verbatim.

        .. note::

           **Time complexity**: ``O(N)``

        :param pattern: The pattern to use when looking for keys
        :type pattern: :class:`str`, :class:`bytes`
        :rtype: list
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'KEYS', pattern])

    def migrate(self,
                host,
                port,
                key,
                destination_db,
                timeout,
                copy=False,
                replace=False):
        """Atomically transfer a key from a source Redis instance to a
        destination Redis instance. On success the key is deleted from the
        original instance and is guaranteed to exist in the target instance.

        The command is atomic and blocks the two instances for the time
        required to transfer the key, at any given time the key will appear to
        exist in a given instance or in the other instance, unless a timeout
        error occurs.

        .. note::

           **Time complexity**: This command actually executes a DUMP+DEL in
           the source instance, and a RESTORE in the target instance. See the
           pages of these commands for time complexity. Also an ``O(N)`` data
           transfer between the two instances is performed.

        :param host: The host to migrate the key to
        :type host: bytes, str
        :param int port: The port to connect on
        :param key: The key to migrate
        :type key: bytes, str
        :param int destination_db: The database number to select
        :param int timeout: The maximum idle time in milliseconds
        :param bool copy: Do not remove the key from the local instance
        :param bool replace: Replace existing key on the remote instance
        :rtype: bool
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        command = [
            b'MIGRATE', host,
            ascii(port).encode('ascii'), key,
            ascii(destination_db).encode('ascii'),
            ascii(timeout).encode('ascii')
        ]
        if copy is True:
            command.append(b'COPY')
        if replace is True:
            command.append(b'REPLACE')
        return self._execute(command, b'OK')

    def move(self, key, db):
        """Move key from the currently selected database (see
        :meth:`~tredis.RedisClient.select`) to the specified destination
        database. When key already exists in the destination database, or it
        does not exist in the source database, it does nothing. It is possible
        to use :meth:`~tredis.RedisClient.move` as a locking primitive because
        of this.

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to move
        :type key: :class:`str`, :class:`bytes`
        :param int db: The database number
        :rtype: bool
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'MOVE', key, ascii(db).encode('ascii')], 1)

    def object_encoding(self, key):
        """Return the kind of internal representation used in order to store
        the value associated with a key

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to get the encoding for
        :type key: :class:`str`, :class:`bytes`
        :rtype: bytes
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'OBJECT', b'ENCODING', key])

    def object_idle_time(self, key):
        """Return the number of seconds since the object stored at the
        specified key is idle (not requested by read or write operations).
        While the value is returned in seconds the actual resolution of this
        timer is 10 seconds, but may vary in future implementations of Redis.

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to get the idle time for
        :type key: :class:`str`, :class:`bytes`
        :rtype: int
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'OBJECT', b'IDLETIME', key])

    def object_refcount(self, key):
        """Return the number of references of the value associated with the
        specified key. This command is mainly useful for debugging.

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to get the refcount for
        :type key: :class:`str`, :class:`bytes`
        :rtype: int
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'OBJECT', b'REFCOUNT', key])

    def persist(self, key):
        """Remove the existing timeout on key, turning the key from volatile
        (a key with an expire set) to persistent (a key that will never expire
        as no timeout is associated).

         .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to move
        :type key: :class:`str`, :class:`bytes`
        :rtype: bool
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'PERSIST', key], 1)

    def pexpire(self, key, timeout):
        """This command works exactly like :meth:`~tredis.RedisClient.pexpire`
        but the time to live of the key is specified in milliseconds instead of
        seconds.

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to set an expiration for
        :type key: :class:`str`, :class:`bytes`
        :param int timeout: The number of milliseconds to set the timeout to
        :rtype: bool
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute(
            [b'PEXPIRE', key, ascii(timeout).encode('ascii')], 1)

    def pexpireat(self, key, timestamp):
        """:meth:`~tredis.RedisClient.pexpireat` has the same effect and
        semantic as :meth:`~tredis.RedisClient.expireat`, but the Unix time
        at which the key will expire is specified in milliseconds instead of
        seconds.

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to set an expiration for
        :type key: :class:`str`, :class:`bytes`
        :param int timestamp: The expiration UNIX epoch value in milliseconds
        :rtype: bool
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute(
            [b'PEXPIREAT', key,
             ascii(timestamp).encode('ascii')], 1)

    def pttl(self, key):
        """Like :meth:`~tredis.RedisClient.ttl` this command returns the
        remaining time to live of a key that has an expire set, with the sole
        difference that :meth:`~tredis.RedisClient.ttl` returns the amount of
        remaining time in seconds while :meth:`~tredis.RedisClient.pttl`
        returns it in milliseconds.

        In Redis 2.6 or older the command returns ``-1`` if the key does not
        exist or if the key exist but has no associated expire.

        Starting with Redis 2.8 the return value in case of error changed:

         - The command returns ``-2`` if the key does not exist.
         - The command returns ``-1`` if the key exists but has no associated
           expire.

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to get the PTTL for
        :type key: :class:`str`, :class:`bytes`
        :rtype: int
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'PTTL', key])

    def randomkey(self):
        """Return a random key from the currently selected database.

        .. note::

           **Time complexity**: ``O(1)``

        :rtype: bytes
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'RANDOMKEY'])

    def rename(self, key, new_key):
        """Renames ``key`` to ``new_key``. It returns an error when the source
        and destination names are the same, or when ``key`` does not exist.
        If ``new_key`` already exists it is overwritten, when this happens
        :meth:`~tredis.RedisClient.rename` executes an implicit
        :meth:`~tredis.RedisClient.delete` operation, so if the deleted key
        contains a very big value it may cause high latency even if
        :meth:`~tredis.RedisClient.rename` itself is usually a constant-time
        operation.

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to rename
        :type key: :class:`str`, :class:`bytes`
        :param new_key: The key to rename it to
        :type new_key: :class:`str`, :class:`bytes`
        :rtype: bool
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'RENAME', key, new_key], b'OK')

    def renamenx(self, key, new_key):
        """Renames ``key`` to ``new_key`` if ``new_key`` does not yet exist.
        It returns an error under the same conditions as
        :meth:`~tredis.RedisClient.rename`.

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to rename
        :type key: :class:`str`, :class:`bytes`
        :param new_key: The key to rename it to
        :type new_key: :class:`str`, :class:`bytes`
        :rtype: bool
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'RENAMENX', key, new_key], 1)

    def restore(self, key, ttl, value, replace=False):
        """Create a key associated with a value that is obtained by
        deserializing the provided serialized value (obtained via
        :meth:`~tredis.RedisClient.dump`).

        If ``ttl`` is ``0`` the key is created without any expire, otherwise
        the specified expire time (in milliseconds) is set.

        :meth:`~tredis.RedisClient.restore` will return a
        ``Target key name is busy`` error when key already exists unless you
        use the :meth:`~tredis.RedisClient.restore` modifier (Redis 3.0 or
        greater).

        :meth:`~tredis.RedisClient.restore` checks the RDB version and data
        checksum. If they don't match an error is returned.

        .. note::

           **Time complexity**: ``O(1)`` to create the new key and additional
           ``O(N*M)`` to reconstruct the serialized value, where ``N`` is the
           number of Redis objects composing the value and ``M`` their average
           size. For small string values the time complexity is thus
           ``O(1)+O(1*M)`` where ``M`` is small, so simply ``O(1)``. However
           for sorted set values the complexity is ``O(N*M*log(N))`` because
           inserting values into sorted sets is ``O(log(N))``.

        :param key: The key to get the TTL for
        :type key: :class:`str`, :class:`bytes`
        :param int ttl: The number of seconds to set the timeout to
        :param value: The value to restore to the key
        :type value: :class:`str`, :class:`bytes`
        :param bool replace: Replace a pre-existing key
        :rtype: bool
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        command = [b'RESTORE', key, ascii(ttl).encode('ascii'), value]
        if replace:
            command.append(b'REPLACE')
        return self._execute(command, b'OK')

    def scan(self, cursor=0, pattern=None, count=None):
        """The :meth:`~tredis.RedisClient.scan` command and the closely related
        commands :meth:`~tredis.RedisClient.sscan`,
        :meth:`~tredis.RedisClient.hscan` and :meth:`~tredis.RedisClient.zscan`
        are used in order to incrementally iterate over a collection of
        elements.

        - :meth:`~tredis.RedisClient.scan` iterates the set of keys in the
          currently selected Redis database.
        - :meth:`~tredis.RedisClient.sscan` iterates elements of Sets types.
        - :meth:`~tredis.RedisClient.hscan` iterates fields of Hash types and
          their associated values.
        - :meth:`~tredis.RedisClient.zscan` iterates elements of Sorted Set
          types and their associated scores.

        **Basic usage**

        :meth:`~tredis.RedisClient.scan` is a cursor based iterator.
        This means that at every call of the command, the server returns an
        updated cursor that the user needs to use as the cursor argument in
        the next call.

        An iteration starts when the cursor is set to ``0``, and terminates
        when the cursor returned by the server is ``0``.

        For more information on :meth:`~tredis.RedisClient.scan`,
        visit the `Redis docs on scan <http://redis.io/commands/scan>`_.

        .. note::

           **Time complexity**: ``O(1)`` for every call. ``O(N)`` for a
           complete iteration, including enough command calls for the cursor to
           return back to ``0``. ``N`` is the number of elements inside the
           collection.

        :param int cursor: The server specified cursor value or ``0``
        :param pattern: An optional pattern to apply for key matching
        :type pattern: :class:`str`, :class:`bytes`
        :param int count: An optional amount of work to perform in the scan
        :rtype: int, list
        :returns: A tuple containing the cursor and the list of keys
        :raises: :exc:`~tredis.exceptions.RedisError`

        """

        def format_response(value):
            """Format the response from redis

            :param tuple value: The return response from redis
            :rtype: tuple(int, list)

            """
            return int(value[0]), value[1]

        command = [b'SCAN', ascii(cursor).encode('ascii')]
        if pattern:
            command += [b'MATCH', pattern]
        if count:
            command += [b'COUNT', ascii(count).encode('ascii')]
        return self._execute(command, format_callback=format_response)

    def sort(self,
             key,
             by=None,
             external=None,
             offset=0,
             limit=None,
             order=None,
             alpha=False,
             store_as=None):
        """Returns or stores the elements contained in the list, set or sorted
        set at key. By default, sorting is numeric and elements are compared by
        their value interpreted as double precision floating point number.

        The ``external`` parameter is used to specify the
        `GET <http://redis.io/commands/sort#retrieving-external-keys>_`
        parameter for retrieving external keys. It can be a single string
        or a list of strings.

        .. note::

           **Time complexity**: ``O(N+M*log(M))`` where ``N`` is the number of
           elements in the list or set to sort, and ``M`` the number of
           returned elements. When the elements are not sorted, complexity is
           currently ``O(N)`` as there is a copy step that will be avoided in
           next releases.

        :param key: The key to get the refcount for
        :type key: :class:`str`, :class:`bytes`

        :param by: The optional pattern for external sorting keys
        :type by: :class:`str`, :class:`bytes`
        :param external: Pattern or list of patterns to return external keys
        :type external: :class:`str`, :class:`bytes`, list
        :param int offset: The starting offset when using limit
        :param int limit: The number of elements to return
        :param order: The sort order - one of ``ASC`` or ``DESC``
        :type order: :class:`str`, :class:`bytes`
        :param bool alpha: Sort the results lexicographically
        :param store_as: When specified, the key to store the results as
        :type store_as: :class:`str`, :class:`bytes`, None
        :rtype: list|int
        :raises: :exc:`~tredis.exceptions.RedisError`
        :raises: :exc:`ValueError`

        """
        if order and order not in [b'ASC', b'DESC', 'ASC', 'DESC']:
            raise ValueError('invalid sort order "{}"'.format(order))

        command = [b'SORT', key]
        if by:
            command += [b'BY', by]
        if external and isinstance(external, list):
            for entry in external:
                command += [b'GET', entry]
        elif external:
            command += [b'GET', external]
        if limit:
            command += [
                b'LIMIT',
                ascii(offset).encode('utf-8'),
                ascii(limit).encode('utf-8')
            ]
        if order:
            command.append(order)
        if alpha is True:
            command.append(b'ALPHA')
        if store_as:
            command += [b'STORE', store_as]

        return self._execute(command)

    def ttl(self, key):
        """Returns the remaining time to live of a key that has a timeout.
        This introspection capability allows a Redis client to check how many
        seconds a given key will continue to be part of the dataset.

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to get the TTL for
        :type key: :class:`str`, :class:`bytes`
        :rtype: int
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'TTL', key])

    def type(self, key):
        """Returns the string representation of the type of the value stored at
        key. The different types that can be returned are: ``string``,
        ``list``, ``set``, ``zset``, and ``hash``.

        .. note::

           **Time complexity**: ``O(1)``

        :param key: The key to get the type for
        :type key: :class:`str`, :class:`bytes`
        :rtype: bytes
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        return self._execute([b'TYPE', key])

    def wait(self, num_slaves, timeout=0):
        """his command blocks the current client until all the previous write
        commands are successfully transferred and acknowledged by at least the
        specified number of slaves. If the timeout, specified in milliseconds,
        is reached, the command returns even if the specified number of slaves
        were not yet reached.

        The command will always return the number of slaves that acknowledged
        the write commands sent before the :meth:`~tredis.RedisClient.wait`
        command, both in the case where the specified number of slaves are
        reached, or when the timeout is reached.

        .. note::

           **Time complexity**: ``O(1)``

        :param int num_slaves: Number of slaves to acknowledge previous writes
        :param int timeout: Timeout in milliseconds
        :rtype: int
        :raises: :exc:`~tredis.exceptions.RedisError`

        """
        command = [
            b'WAIT',
            ascii(num_slaves).encode('ascii'),
            ascii(timeout).encode('ascii')
        ]
        return self._execute(command)
