Why Adblock-to-Polipo Filter Conversion Needs More Than Regex

A converter must preserve what a rule means, as well as translate its characters. A browser filtering list can depend on the page loading a resource, the resource type and exception rules. A URL-only blocklist has less information.

For an existing Polipo installation, its manual defines forbiddenFile entries as domain names or POSIX extended regular expressions. A regex produced for Python’s engine is therefore not automatically valid in that file.

Start with a declared subset

• Translate unconditional URL blocking patterns only after defining their anchors and separator behavior.
• Preserve exception rules beginning with @@. Appending their patterns to a deny file reverses their meaning.
• Keep rules with context options, such as script or domain restrictions, out of a URL-only conversion unless the target can represent those conditions.
• Exclude element-hiding rules: selecting a page’s DOM elements requires a different mechanism.

Deleting an unsupported option can broaden a conditional rule into an unconditional block. Report those skipped rules instead of silently claiming a complete conversion.

The historical adblockparser package can parse and evaluate a subset of Adblock Plus rules. Its README documents ignored element-hiding rules, option-dependent matching and other limitations; its repository was archived on June 24, 2026. Treat its output as something to assess against the target engine, rather than a promise of faithful whole-list conversion.

Account for the proxy’s view

For ordinary HTTPS tunnels, Polipo’s tunnel filtering sees hostname and port, not the encrypted URL path. Its forbiddenTunnelsFile is a separate policy surface. A perfectly translated path expression still cannot match content that the proxy never sees.

Document the retained subset and check both intended blocks and intended exceptions when evaluating a conversion. “The file loaded” establishes syntax acceptance, not equivalent filtering.