A library for querying custom and third party web address blacklists and whitelists.

• client classes for Google Safe Browsing Lookup API and hpHosts services
• support for custom DNSBL service clients
• preconfigured clients for SURBL, Spamhaus ZEN and Spamhaus DBL
• support for querying and populating custom host whitelists and blacklists
• combining multiple URL testers into a composite tester
• optional querying for redirect URL addresses when using a composite URL tester
• support for Python 2 and 3

Simple test for membership of a host value in a host blacklist:

>>> from spam_lists import SPAMHAUS_DBL
>>> 'dbltest.com' in SPAMHAUS_DBL
True

lookup(host_value) method returns a named tuple containing:

• a listed host that is a parent of a searched domain, or a listed ip address equal to one searched in the blacklist
• source of the returned information as an instance of the client used to search for the value
• a set of classificiation terms associated with the value

>>> SPAMHAUS_DBL.lookup('dbltest.com')
AddressListItem(value=u'dbltest.com', ...)

Testing if there is any spam URL in a sequence:

>>> urls_to_test = (
'http://google.com',
'http://wikipedia.org',
'http://dbltest.com'
)
>>> SPAMHAUS_DBL.any_match(urls_to_test)
True

Filtering recognized spam URLs out of a sequence of values returns a generator object that yields the spam URLs:

>>> result = SPAMHAUS_DBL.filter_matching(urls_to_test)
>>> result
<generator object <genexpr> at 0xb4f60a7c>
>>> list(result)
['http://dbltest.com']

Calling lookup_matching(urls) returns a generator object yielding instances of the AddressListItem named tuple for matching URLs:

>>> result = SPAMHAUS_DBL.lookup_matching(urls_to_test)
>>> result
<generator object lookup_matching at 0xb4f60e3c>
>>> list(result)
[AddressListItem(value=u'dbltest.com', ...)]

For further information, read spam_lists package docstring.

Install using pip:

$ pip install spam-lists

To be able to run tests, install test extras:

$ pip install spam-lists[test]