python-abp 0.2.0

安装

先决条件

• Linux, Mac OS X 或 Windows (任何现代Unix也应该可以工作)，

• Python (2.7 或 3.5+),

• pip.

要安装

$ pip install --upgrade python-abp

渲染过滤列表

过滤器列表最初是按相对较小的部分编写的，专注于特定类型的过滤器，与特定主题相关或与特定地理区域相关。我们称这些部分为过滤器列表片段（或简称片段），以区别于由Adblock Plus等广告拦截软件消费的完整过滤器列表。

渲染是一个将过滤器列表片段组合成过滤器列表的过程。它从一个可以包括其他片段的片段开始。生成的过滤器列表带有版本和时间戳。

Python-abp 包含一个名为 flrender 的脚本，可以完成这项工作

$ flrender fragment.txt filterlist.txt

这将从 fragment.txt 中的顶级片段开始，渲染它并将其保存到 filterlist.txt 中。

flrender 脚本也可以仅通过指定 fragment.txt

$ flrender fragment.txt

来使用，在这种情况下，渲染结果将被发送到 stdout。此外，当它没有位置参数运行时

$ flrender

它将读取 stdin 并将结果发送到 stdout。

片段可能引用其他应该包含在内的片段。引用有两种形式：http(s) 包含和本地包含

%include http://www.server.org/dir/list.txt%
%include easylist:easylist/easylist_general_block.txt%

http 包含包含一个URL，该URL将在引用点获取并插入。本地包含包含easylist存储库内的路径。 flrender 需要能够在本地文件系统上找到一个存储库的副本。我们使用 -i 选项来指定正确的目录

$ flrender -i easylist=/home/abc/easylist input.txt output.txt

现在上述引用的本地包含将解析为：/home/abc/easylist/easylist/easylist_general_block.txt，并将从该文件加载片段。

在渲染过程中使用的过滤器列表片段包含的目录称为来源。它们通常是包含过滤器列表片段的存储库的工作副本。每个来源都有一个名称：这是包含指令中“:”之前的部分，它应该与 -i 选项中的“=”之前的部分相同。

常用来源通常有普遍接受的名字。例如，主EasyList存储库被称为 easylist。如果您不知道渲染某些列表所需的所有来源名称，只需运行 flrender，它将报告缺少的内容

$ flrender easylist.txt output/easylist.txt
Unknown source: 'easylist' when including 'easylist:easylist/easylist_gener
al_block.txt' from 'easylist.txt'

您可以将必要的存储库克隆到本地目录中，并相应地添加 -i 选项。

生成差异

差异允许运行Adblock Plus等广告拦截软件的客户增量更新过滤器列表，而不是在每次更新时下载完整列表的新副本。这是为了减少更新过滤器列表时使用的资源量（例如网络数据、内存使用、电池消耗等），允许客户使用更少的资源更频繁地更新列表。

python-abp 包含一个名为 fldiff 的脚本，可以找到最新过滤器列表与任何数量的先前过滤器列表之间的差异

$ fldiff -o diffs/easylist/ easylist.txt archive/*

其中 -o diffs/easylist/ 是一个可选的输出目录，diffs 将被写入该目录，easylist.txt 是最新的过滤列表版本，而 archive/* 是包含所有存档过滤列表的目录。当以这种方式调用时，shell 应该自动展开 archive/* 目录，将每个文件名分别传递给脚本。

在上面的例子中，每个存档的 list[版本].txt 的输出将被写入到 diffs/diff[版本].txt。如果省略输出参数，diffs 将被写入当前目录。

脚本生成三种类型的行，如技术规范所述。

• 形式为 ! <name>:[ <value>] 的特殊注释

• 形式为 + <filter-text> 的添加过滤规则

• 形式为 - <filter-text> 的移除过滤规则

库API

python-abp 也可以用作解析过滤列表的库。例如，要读取一个过滤列表（这里我们使用 Python 3 语法，但 API 是相同的）

from abp.filters import parse_filterlist

with open('filterlist.txt') as filterlist:
    for line in parse_filterlist(filterlist):
        print(line)

如果 filterlist.txt 包含这个过滤列表

[Adblock Plus 2.0]
! Title: Example list

abc.com,cdf.com##div#ad1
abc.com/ad$image
@@/abc\.com/

输出将类似于

Header(version='Adblock Plus 2.0')
Metadata(key='Title', value='Example list')
EmptyLine()
Filter(text='abc.com,cdf.com##div#ad1', selector={'type': 'css', 'value': 'div#ad1'}, action='hide', options=[('domain', [('abc .com', True), ('cdf.com', True)])])
Filter(text='abc.com/ad$image', selector={'type': 'url-pattern', 'value': 'abc.com/ad'}, action='block', options=[('image', True)])
Filter(text='@@/abc\\.com/', selector={'type': 'url-regexp', 'value': 'abc\\.com'}, action='allow', options=[])

abp.filters 模块还导出了解析过滤列表单个行的低级别函数：parse_line。它返回一个解析行对象，就像由 parse_filterlist 返回的迭代器中的项一样。

有关库 API 的更多信息，请在交互式 Python 会话中使用 help() 来查看 abp.filters 及其内容，阅读文档字符串，或查看测试用例以获取一些用法示例。

from abp.filters import parse_filterlist
from abp.filters.blocks import to_blocks

with open(fl_path) as f:
    for block in to_blocks(parse_filterlist(f)):
        print(json.dumps(block.to_dict(), indent=2))

测试

python-abp 的单元测试位于 /tests 目录。在开发过程中使用 Pytest 快速运行测试。使用 Tox 在不同的环境中进行测试（Python 2.7，Python 3.5+ 和 PyPy）以及代码质量报告。

使用 tox 来获取单元测试和测试覆盖率的综合报告

$ tox

开发

在添加新功能时，为其添加测试（最好先添加测试）。如果某些代码在 Python 的某个版本中将永远不会被访问，可以通过添加注释来将其从覆盖率测试中免除，例如 # pragma: no py2 cover。

所有公共函数、类和方法都应该有符合 NumPy/SciPy 文档指南 的文档字符串。一个例外是用户不需要实例化的类的构造函数（例如异常）。

使用R语言与库结合使用

$ pip install -U python-abp

$ pip install -U /path/to/python-abp

$ virtualenv env

$ python3 -m venv env

$ env/bin/pip install -U python-abp

> library(reticulate)
> use_virtualenv("~/path/to/env", required=TRUE)  # If using virtualenv
> abp <- import("abp.filters.rpy")