PyBloomfilter API

PyBloomfilter API

可以使用的平台：Windows Unix

BloomFilter类

class pybloomfilter.BloomFilter(capacity : int, error_rate : float, filename : string)

capacity：给定的容量

error_rate：给定的错误率

filename：用于记录的mmap file，如果不给定，则记录在内存中，不进行保存

BloomFilter类的静态方法

static BloomFilter.open(filename)

用于打开一个已经存在的Bloomfilter文件

static BloomFilter.from_base64(filename, input[, perm = 0755])

Create a new BloomFilter object on filename from the input base64 string

根据输入的base64字符串在制定的文件名filename上创建一个新的BloomFilter

例如：

>>> bf = BloomFilter.from_base64("/tmp/mike.bf",
     "eJwFwcuWgiAAANC9v+JCx7By0QKt0GHEbKSknflAQ9QmTyRfP/fW5E9XTRSX"
     "qcLlqGNXphAqcfVH\nRoNv0n4JlTpIvAP0e1+RyXX6I637ggA+VPZnTYR1A4"
     "Um5s9geYaZZLiT208JIiG3iwhf3Fwlzb3Y\n5NRL4uNQS6/d9OvTDJbnZMnR"
     "zcrplOX5kmsVIkQziM+vw4hCDQ3OkN9m3WVfPWzGfaTeRftMCLws\nPnzEzs"
     "gjAW60xZTBbj/bOAgYbK50PqjdzvgHZ6FHZw==\n")
>>> "MIKE" in bf
True

BloomFilter类的实例属性

BloomFilter.capacity

这个Bloomfilter的给定容量

BloomFilter.error_rate

这个Bloomfilter的给定错误率

BloomFilter.hash_seeds
测试打印结果为：
array('I', [2785341594L, 3729606536L, 2913499975L, 1863476974L, 2030843148L, 1054553351L, 2664834384L, 2503334711L, 892242853L])

The integer seeds used for the random hashing 用于做hashing的int型数种子

BloomFilter.name

存储BloomFilter信息的文件的文件名

BloomFilter.num_bits

在BloomFilter用作存储的位数bits

BloomFilter.num_hashes

在BloomFilter中使用的hash函数的个数

BloomFilter类的实例方法

BloomFilter.add(item) → Boolean

功能：添加一个item到filter中

参数：item：做hash的对象

返回值类型：Boolean，（true 如果item已经在filter中）

BloomFilter.clear_all()

功能：一次性移除bloomfilter中所有的item

BloomFilter.copy(filename) → BloomFilter

功能：Copies the current BloomFilter object to another object with new filename.

经测试，应该是将当前的BloomFilter的对象复制一份给新的BloomFilter对象，并且新的对象对应的文件名为给定的filename。

参数：filename，给定的文件路径，新的BloomFilter对象对应的文件名

返回值类型：一个新的BloomFilter对象

BloomFilter.copy_template(filename[, perm=0755]) → BloomFilter

使用相同的参数创建一个新的BloomFilter对象，即相同的hash seeds，相同的大小，就是一切参数。执行此操作后，两个BloomFilter具有可比性，因此可以执行逻辑运算符操作。

参数与返回值类型与 BloomFilter.copy()相同

BloomFilter.sync()

强制同步BloomFilter对象信息到对应的mmap file文件中，这用于在复制文件时希望保证绝对的正确。

BloomFilter.to_base64() → string

功能：创建BloomFilter的压缩base64编码版本。 由于BloomFilter在文件系统上有效地是二进制的，因此这可能不太有用。 我发现它对调试很有用，所以我可以将过滤器从一个终端复制到另一个终端 。

返回值类型：Base64压缩编码后代表BloomFilter的字符串

BloomFilter.update(iterable)

在该iterable上所有的items，均调用add()。即将所有的items都一次性加入到BloomFilter中。

参数：iterable：通过测试发现可以是list，（估计是其他形式的也可以）

测试代码与结果如下：

#! /usr/bin/env python
# -*- coding:utf-8 -*-

import os
import sys
reload(sys)
sys.setdefaultencoding('utf-8')
import random
from pybloomfilter import BloomFilter
# 创建一个capacity等于100万，error rate等于0.001的bloomfilter对象
bfilter = BloomFilter(1000000,0.001,'bf_test.bloom')

for x in xrange(10):
    bfilter.add(str(x))
# 与mmap文件同步
bfilter.sync()

print "2" in bfilter
print "20" in bfilter
print "21" in bfilter
print "22" in bfilter

iterable = ["20", "21", "22"]
print iterable

bfilter.update(iterable)
print "2" in bfilter
print "20" in bfilter
print "21" in bfilter
print "22" in bfilter

结果：
True
False
False
False
['20', '21', '22']
True
True
True
True

BloomFilter.union(filter) → BloomFilter

功能：当前BloomFilter对象和另一个comparable*** 的BloomFilter对象进行OR（或）操作，获取comparable 的BloomFilter对象的唯一方法是调用上面所说的copy_template* 方法

参数：filter：另一个comparable 的BloomFilter对象

返回值类型：BloomFilter对象

注意事项：调用此方法后，无法使用对应的 len() 方法

BloomFilter.intersection(filter) → BloomFilter

功能：当前BloomFilter对象和另一个comparable*** 的BloomFilter对象进行AND（且）操作，获取comparable 的BloomFilter对象的唯一方法是调用上面所说的copy_template* 方法

参数：filter：另一个comparable 的BloomFilter对象

返回值类型：BloomFilter对象

注意事项：调用此方法后，无法使用对应的 len() 方法

BloomFilter类的魔法方法

python魔法方法小结：https://blog.csdn.net/LToddy/article/details/80467235

据说，Python的对象天生拥有一些神奇的方法，它们总被双下划线所包围，他们是面向对象的 Python 的一切。 他们是可以给你的类增加魔力的特殊方法，如果你的对象实现（重载）了这些方法中的某一个，那么这个方法就会在特殊的情况下被 Python 所调用，你可以定义自己想要的行为，而这一切都是自动发生的。

Python的魔术方法非常强大，然而随之而来的则是责任。每个魔法方法都是在对内建方法的重写，和做像装饰器一样的行为。

Python的魔法方法大概就是一些固定的，很方便使用的，固定格式且可以自定义的方法，有点类似于C++的运算符重载，范围比那个更加宽广一些。

BloomFilter类实现的魔法方法

BloomFilter.__len__(item) → Integer

功能：返回已经添加到BloomFilter中的不同item的数量，但是不一定是精确的，这取决于给定的error_rate。

参数：给定的应该是filter对象，调用形式应该是 len(BloomFilter)，具体例子如下：

>>> bf = BloomFilter(100, 0.1, '/tmp/fruit.bloom')
>>> bf.add("Apple")
>>> bf.add('Apple')
>>> bf.add('orange')
>>> len(bf)
2
>>> bf2 = bf.copy_template('/tmp/new.bloom')
>>> bf2 |= bf
>>> len(bf2)
Traceback (most recent call last):
  ...
pybloomfilter.IndeterminateCountError: Length of BloomFilter object is unavailable after intersection or union called.

注意：进行或操作后，不能使用 len() 函数。

返回值类型：Int型整数

BloomFilter.__in__(item) → Boolean

功能：检查一个item是否已经存在于filter中，同样不一定精确，这要看给定的错误率。

参数：传入的是一个item，形式为 item in filter，这是一个逻辑表达式，在执行时调用了该函数，如果存在，则返回True，不存在则返回False。

返回值类型：一个Boolean类型的值，表示该元素是否存在于filter中。

BloomFilter.__ior__(filter) → BloomFilter

使用方式有所区别，应该是 |=，具体功能同上述union(filter)

BloomFilter.__iand__(filter) → BloomFilter

使用方式有所区别，应该是 &=，具体功能同上述intersection(filter)

BloomFilter类的异常处理类

class pybloomfilter.IndeterminateCountError(message)

这个异常被抛出，当 len() 函数被一个使用过 |=， &= ，intersection()，union() 的对象调用时，具体例子如上所述。

message：抛出的异常信息