Example Usage

BlackRed features a very simple and intuitive API. Go to API documentation.

Simple Use

With everything in defaults (Host is localhost, port is 6379 and so on), you can use BlackRed right out of the box:

import blackred

def login(username, password, request_ip):
    br = blackred.BlackRed()
    if br.is_blocked(request_ip):
        return False
    if not authenticate(username, password):
        br.log_fail(request_ip)
        return False
    return True

The BlackRed constructor offers a wide range of on-the-fly settings for the new instance. To keep your code nice and clean when you use the same settings most of the time, you can use the Settings Predefinition.

Item Selection

For a web or network based application, a good item to check and block is the client IP address of the requestor.

In other environments, you might choose anything else that identifies a request source uniqually. Most important: The item must be represented by a str.

Settings Predefinition

To make the using of BlackRed easier, you can change the default settings for new instances by changing the values of the attributes of the BlackRed.Settings class. Changes are only valid for new instances created after the changes. Already existing instances are not changed.

Note

BlackRed versions before 0.3.0 had a different settings approach. Settings where separated into global settings and settings for new instances. With 0.3.0, all settings are only valid for new instances. Keep that in mind when upgrading from an older version.

Example: Enable Anonymization by default:

import blackred

blackred.BlackRed.Settings.ANONYMIZATION = True

def login(username, password, request_ip):
    br = blackred.BlackRed()
    if br.is_blocked(request_ip):
        return False
    if not authenticate(username, password):
        br.log_fail(request_ip)
        return False
    return True

Use Unix Socket instead of TCP/IP connection

If you want to use a unix socket to connect, set the redis_use_socket constructor parameter to True and provide the absolute path to the socket with the redis_host parameter, example:

import blackred

br = blackred.BlackRed(redis_host='/var/run/redis/redis.sock', redis_use_socket=True)

As always, those settings can be predefined (see Settings Predefinition) as defaults for all new instances:

import blackred

blackred.BlackRed.Settings.REDIS_USE_SOCKET = True
blackred.BlackRed.Settings.REDIS_HOST = '/var/run/redis/redis.sock'

Anonymization

Sometimes it’s necessary to hash the item’s values to ensure privacy of the requester. BlackRed can easily support you. Just set the ANONYMIZATION attribute to True:

import blackred

blackred.BlackRed.Settings.ANONYMIZATION = True

Use a Redis password (aka Redis AUTH feature)

To activate authentication, you can use the redis_auth parameter of the constructor:

import blackred

br = blackred.BlackRed(redis_auth='my_password')

As always, this settings can be predefined (see Settings Predefinition) as default for all new instances:

import blackred

blackred.BlackRed.Settings.REDIS_AUTH = 'my_password'