qutebrowser 广告拦截测试数据集：ublock-matches.tsv.gz 的生成、结构与用法

桌面应用【免费下载链接】qutebrowserA keyboard-driven, vim-like browser based on Python and Qt.项目地址https://gitcode.com/gh_mirrors/qu/qutebrowser点击查看免费下载导读本文围绕 qutebrowser 仓库中 tests/end2end/data/brave-adblock/README.md 所记录的测试数据集展开深入讲解ublock-matches.tsv.gz的来源、预处理流程、字段结构与资源类型映射并结合仓库源码说明它在 qutebrowser 广告拦截Brave adblocker单元测试与端到端测试中的实际消费方式。读完本文你将掌握这份真实世界广告请求数据集的完整生命周期并能在本地复现它的生成过程为理解 qutebrowser 的content.blocking.*广告拦截体系提供数据侧的支撑。一、数据集在 qutebrowser 测试体系中的定位qutebrowser 是一个基于 Python 与 Qt 的键盘驱动vim 风格浏览器其广告拦截功能支持两种引擎简单的 hosts 阻断器和基于 Braveadblock-rust的 ABP 风格Adblock Plus 语法拦截器后者通过可选的adblockPython 包接入见 qutebrowser/components/braveadblock.py。为了验证 Brave adblocker 在各种真实网络请求上不会误杀合法流量false positive测试需要一批真实世界中确实不应被拦截的请求样本。ublock-matches.tsv.gz正是为此准备的基准数据集——它取自 uBlock Origin 过滤器在实际浏览中的匹配记录作为assert_none_blocked类测试的负样本输入。该目录tests/end2end/data/brave-adblock/共包含四个文件文件作用README.md说明数据来源、生成方式与许可generate.py下载、过滤、压缩生成数据集的脚本ublock-matches.tsv.gz最终供测试使用的 gzip 压缩 TSV 数据LICENSE原始数据采用的 MPLv2 许可全文318 行二、数据来源Brave adblock-rust 的 ublock-matches.tsvREADME 明确指出ublock-matches.tsv文件下载自adblock-rust项目Brave 的 Rust 广告拦截库的数据目录随后由generate.py预处理并压缩最终产出ublock-matches.tsv.gz。generate.py中对应的下载地址常量印证了这一来源tests/end2end/data/brave-adblock/generate.py#L16URL https://raw.githubusercontent.com/brave/adblock-rust/master/data/ublock-matches.tsv该原始文件记录了 uBlock Origin 过滤器在真实浏览场景下的命中样本每条记录包含多个字段。qutebrowser 只关心其中用于构造测试请求的三个字段url被请求的资源 URL、sourceUrl发起请求的页面 URL、type请求的资源类型。三、generate.py 预处理流程详解generate.py是一个可直接运行的独立脚本tests/end2end/data/brave-adblock/generate.py执行后在工作目录产出ublock-matches.tsv.gz。其处理管线分为四个阶段1. 下载或复用缓存脚本优先检查系统临时目录中的缓存文件ublock-matches-cache.tsvCACHE_PATH pathlib.Path(tempfile.gettempdir(), ublock-matches-cache.tsv)见 generate.py#L17缓存存在直接读取避免重复下载缓存不存在通过urllib.request下载原始 TSV校验 HTTP 状态码为 200 后写入缓存再读入内存。2. 截取前 30 000 行并抽取三列ROWS_TO_USE 30_000 reader csv.DictReader(data, delimiter\t) rows list(itertools.islice(reader, ROWS_TO_USE))脚本只保留原始数据集的前 30000 行ROWS_TO_USE 30_000generate.py#L18并用csv.DictReader按 Tab 分隔符解析再输出到仅含url、source_url、type三列的字典写入器。这一截断策略既保证了测试样本量的充分性又控制了数据文件体积与测试运行时间。3. 资源类型重命名对齐 QtWebEngine 命名这是预处理中最关键的转换。原始数据使用的资源类型命名来自 Chromium/ABP 体系而 qutebrowser 的interceptor.ResourceTypeQtWebEngine 枚举命名不同因此type_rename()generate.py#L21-L31执行了如下映射原始类型重命名后处理otherunknown保留xmlhttprequestxhr保留fontfont_resource保留image/stylesheet/media/script/sub_frame原样保留保留其他类型—丢弃整行从源码注释Use the same resource type names as QtWebEngine可以看出这一步的目的是让测试数据中的type字段能直接被ResourceType[row[type]]反查为枚举成员见下文测试消费部分。无法识别的请求类型对应的行会被跳过不会进入最终数据集。4. gzip 压缩落盘过滤后的数据先写入内存中的io.StringIO再以最高压缩级别写盘with gzip.open(ublock-matches.tsv.gz, wb, compresslevel9) as gzip_f: gzip_f.write(uncompressed_f.read().encode(utf-8))compresslevel9表示最高压缩比以换取更小的仓库体积——这是为了将测试数据文件控制在 Git 仓库可接受的尺寸内。四、数据在测试中的消费方式1. 测试辅助函数解压读取tests/helpers/testutils.py#L246-L256 提供了统一的解压读取入口def _decompress_gzip_datafile(filename): path os.path.join(abs_datapath(), filename) yield from io.TextIOWrapper(gzip.open(path), encodingutf-8) def adblock_dataset_tsv(): return _decompress_gzip_datafile(brave-adblock/ublock-matches.tsv.gz)adblock_dataset_tsv()返回一个逐行迭代的文本流供单元测试按 CSV 格式解析。2. 单元测试逐条验证不误杀tests/unit/components/test_braveadblock.py#L88-L110 中run_function_on_dataset()将数据集逐行转换为测试用例def run_function_on_dataset(given_function): dataset testutils.adblock_dataset_tsv() reader csv.DictReader(dataset, delimiter\t) for row in reader: url QUrl(row[url]) source_url QUrl(row[source_url]) resource_type ResourceType[row[type]] given_function(url, source_url, resource_type)而assert_none_blocked()则对数据集中的每一条请求断言不应被拦截assert not ad_blocker._is_blocked(url, source_url, resource_type)。这正是数据集的用途核心这些是在真实世界中合法加载过的请求任何一条被 Brave adblocker 误拦截都说明引擎存在过度拦截false positive问题。此外该测试文件还在BUGGY_URLStest_braveadblock.py#L76-L85中记录了因上游adblock-rust已知缺陷而需要特殊处理的 URL对应上游 issue #146 及 qutebrowser issue #6000用于验证仓库内置的 workaround 逻辑仍然必要。3. 端到端测试与真实列表联动在 tests/end2end/test_adblock_e2e.py 中test_adblock参数化覆盖auto/hosts/adblock/both四种拦截方法both与adblock需要已安装adblock库否则通过pytest.mark.skipif跳过它配置content.blocking.hosts.lists与content.blocking.adblock.lists指向测试服务器上的本地列表tests/end2end/data/blocking/qutebrowser-adblock 内容为 ABP 规则|||qutebrowser.org^执行:adblock-update后打开data/blocking/external_logo.html并断言对应日志消息如Request to https://qutebrowser.org/icons/qutebrowser.svg blocked by ad blocker.。这套 e2e 测试与单元测试的数据集形成互补前者验证拦截器该拦的拦得住后者验证不该拦的不误杀。五、运行层面数据集对应的拦截引擎工作方式理解数据集的价值还需要知道它在运行时的对应物。Brave adblocker 在 qutebrowser 中的工作链路如下qutebrowser/components/braveadblock.py启动时通过hook.init()注册interceptor.register(ad_blocker.filter_request)braveadblock.py#L335-L352每个网络请求进入_is_blocked()调用self._engine.check_network_urls(request_url, first_party_url, resource_type_str)判定是否命中规则braveadblock.py#L203-L207命中后还会检查异常规则result.exception、important标记与白名单blockutils.is_whitelisted_url()最终决定是否info.block()。其中运行时的资源类型字符串映射_RESOURCE_TYPE_STRINGSbraveadblock.py#L77-L102与generate.py中的type_rename方向相反但逻辑呼应运行时把ResourceType枚举转换为 adblock 引擎认识的字符串如xhr、font、sub_frame而生成数据时把原始类型转换为ResourceType可解析的枚举名。两者共同保证了测试数据与真实拦截调用使用同一套类型语义。六、相关配置项数据测试背后的可配置面单元测试与 e2e 测试均通过配置项驱动拦截行为这些配置定义在 qutebrowser/config/configdata.ymlcontent.blocking.enabled默认true支持 URL pattern总开关content.blocking.method默认auto可选auto有 adblock 库则用 Brave 引擎否则退回 hosts、adblock、hosts、bothcontent.blocking.adblock.lists默认 EasyList EasyPrivacyABP 风格规则列表 URLcontent.blocking.hosts.lists默认 StevenBlack hostshosts 列表 URLcontent.blocking.whitelist豁免拦截的 URL 模式列表。需要说明的是auto模式只有在adblock依赖可用时才启用 Brave 引擎若依赖缺失或版本过旧braveadblock.py#L47-L74 的_possibly_show_missing_dependency_warning()会给出相应警告信息。七、许可与合规MPLv2 与 LICENSE 文件README 的第二个要点是许可声明原始ublock-matches.tsv由 Andrius Aucinas 以Mozilla Public License 2.0MPLv2发布许可副本存放于同目录的 LICENSE 文件中共 318 行含版权声明Copyright (c) 2019, Andrius Aucinas。在引入第三方测试数据时保留许可全文是开源仓库合规的重要实践——qutebrowser 本体为 GPL-3.0-or-later见generate.py的 SPDX 头而该数据集以 MPLv2 独立授权二者互不冲突地共存于仓库中。注意generate.py与测试源码采用 GPL-3.0-or-laterSPDX 标识见 generate.py#L2-L5与数据本身的 MPLv2 是两个独立的许可对象使用时应区分对待。八、本地复现重新生成数据集如需在本地重新生成ublock-matches.tsv.gz可在该目录下直接运行python tests/end2end/data/brave-adblock/generate.py脚本会依次输出以下日志整个过程无需任何第三方 Python 依赖仅用标准库Downloading https://raw.githubusercontent.com/brave/adblock-rust/master/data/ublock-matches.tsv ... Saving to cache file /tmp/ublock-matches-cache.tsv ... Reading rows into memory... Writing filtered file to memory... Compressing filtered file and saving to disk...注意事项首次运行需要联网下载原始 TSV约数 MB之后会复用/tmp/ublock-matches-cache.tsv缓存上游文件内容若发生变化重新生成的数据集与仓库中已提交的ublock-matches.tsv.gz可能存在差异可能影响零误杀断言的稳定性该脚本仅供数据维护者更新测试基准使用普通运行测试无需执行——仓库中已包含现成的压缩数据文件。小结ublock-matches.tsv.gz是 qutebrowser 广告拦截测试体系中一份小而关键的真实世界数据资产它从 Braveadblock-rust的 uBlock 匹配记录中截取 30000 条请求经generate.py完成资源类型归一化与 gzip 压缩后入库再由单元测试逐条断言不应误拦截与端到端测试的应当拦截断言共同构成完整的拦截器验证闭环。理解这份数据集的来源、结构与处理管线有助于深入把握 qutebrowser 的content.blocking.*广告拦截机制以及开源项目在引入第三方数据时对许可合规的处理范式。赞分享桌面应用【免费下载链接】qutebrowserA keyboard-driven, vim-like browser based on Python and Qt.项目地址https://gitcode.com/gh_mirrors/qu/qutebrowser点击查看免费下载相关推荐终结广告追踪uBlock Origin广告联盟识别与拦截全攻略终结广告追踪uBlock Origin广告联盟识别与拦截全攻略 你是否曾在浏览网页时被无处不在的广告追踪困扰从电商网站的浏览历史弹窗到社交媒体的定向推广网络安全应用安全uBlock Origin广告拦截效果测评主流网站拦截率对比uBlock Origin广告拦截效果测评主流网站拦截率对比 你是否还在忍受视频前90秒的广告轰炸是否为弹窗广告打断阅读而烦恼uBlock Origin网络安全应用安全上一篇HAMi 对 Sidecar 容器 GPU 资源核算的支持设计与实现解析下一篇如何使用 Python WebSocket 客户端快速实现实时通信的完整指南 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考