Docs lack examples for "any-of" and "all-of" topic filters

[veox]

• web3.py version: 3.8.1 (web3[gevent])
• node: geth 1.6.5-stable, local (via IPC)
• Python: 3.5
• OS: Ubuntu 16.04.2 LTS

What seems wrong?

Retrieving past log events while specifying 'topics' gives an empty list, if value of 'topics' is a list with more than one element.

I was under the impression that the filter will match any event that's in 'topics'. This seems not to be the case - EDIT: perhaps it's all?..

Details

Using these variables:

> # common vars
> import cancelot
> cancelot.enslaunchblock
3648565
> cancelot.registrar
'0x6090a6e47849629b7245dfa1ca21d94cd15878ef'
> list(cancelot.handlers.keys())
['0x7b6c4b278d165a6b33958f8ea5dfb00c8c9d4d0acf1985bef5d10786898bc3e7',
 '0xb556ff269c1b6714f432c36431e2041d28436a73b6c3f19c021827bbdc6bfc29']

Not specifying 'topics' does give a list of events (dicts), as expected:

> # filter for past events, without topics
> filtall =  web3.eth.filter({
    'fromBlock': cancelot.enslaunchblock,
    'toBlock': cancelot.enslaunchblock + 1000,
    'address': cancelot.registrar
    })
> evs = filtall.get(only_changes = False)
> len(evs)
80
> evs[0]
{'address': '0x6090a6e47849629b7245dfa1ca21d94cd15878ef',
 'blockHash': '0x3a2c9e10de45a86d39f52eeaa2beef514d8b0a19ddf6bd231a6d97bca79988b8',
 'blockNumber': 3648565,
 'data': '0x000000000000000000000000000000000000000000000000002386f26fc10000',
 'logIndex': 4,
 'removed': False,
 'topics': ['0xb556ff269c1b6714f432c36431e2041d28436a73b6c3f19c021827bbdc6bfc29',
  '0x1f0e90602b7ed7fe12cd293824cccad3966e676d067df11da128793f5ad97ac3',
  '0x0000000000000000000000000904dac3347ea47d208f3fd67402d039a3b99859'],
 'transactionHash': '0x6e032eed213f1a641af8cdb7fd3770984010a38c04f6c06e393b03dfca30a80d',
 'transactionIndex': 40}

The above shows that the topic 0xb556.., which is part of list(cancelot.handlers.keys()), is present as the first event log entry.

Giving a list of topics, though, doesn't work:

> # same filter, with topics
> filttop = web3.eth.filter({
    'fromBlock': cancelot.enslaunchblock,
    'toBlock': cancelot.enslaunchblock + 1000,
    'address': cancelot.registrar,
    'topics': list(cancelot.handlers.keys())
    })
> filttop.get(only_changes = False)
[]

Providing topics manually

I know that the 0xb556.. topic is present for sure (it's the ENS NewBid event):

> # topic known to be present
> filtnew = web3.eth.filter({
    'fromBlock': cancelot.enslaunchblock,
    'toBlock': cancelot.enslaunchblock + 1000,
    'address': cancelot.registrar,
    'topics': ['0xb556ff269c1b6714f432c36431e2041d28436a73b6c3f19c021827bbdc6bfc29']
    })
> len(filtnew.get(False))
31

And 0x7b6c.. is for sure not present (ENS BidRevealed event):

> # topic known to be not present
> filtrev = web3.eth.filter({
    'fromBlock': cancelot.enslaunchblock,
    'toBlock': cancelot.enslaunchblock + 1000,
    'address': cancelot.registrar,
    'topics': ['0x7b6c4b278d165a6b33958f8ea5dfb00c8c9d4d0acf1985bef5d10786898bc3e7']
    })
> len(filtrev.get(False))
0

Specifying both results in empty list behaviour:

> # both topics
> filtboth = web3.eth.filter({'fromBlock': cancelot.enslaunchblock,
    'toBlock': cancelot.enslaunchblock + 1000,
    'address': cancelot.registrar,
    'topics': ['0x7b6c4b278d165a6b33958f8ea5dfb00c8c9d4d0acf1985bef5d10786898bc3e7', '0xb556ff269c1b6714f432c36431e2041d28436a73b6c3f19c021827bbdc6bfc29']
    })
> len(filtboth.get(False))
0

Cute Animal Picture

Puffer fish can't believe it (via some random article):

[veox]

Perhaps I misunderstood the functionality, and the filter matches messages with all of the specified topics, not any.

This is also probably node-dependent.

If so, OK to close.

[veox]

Re-read the docs:

topics: list of 32 byte strings or null - (optional) Array of topics that should be used for filtering. Topics are order-dependent. This parameter can also be a list of topic lists in which case filtering will match any of the provided topic arrays.

So, perhaps what I needed was

[['<topic1>'], ['<topic2>'], ['<topic3>']]

instead of

['<topic1>', '<topic2>', '<topic3>']

Even if this is dependent on the node backend, it may be useful to clarify that dense passage in the docs with an example.

[pipermerriam]

Even if this is dependent on the node backend, it may be useful to clarify that dense passage in the docs with an example.

I think this would be a good idea. Docs could use a lot more examples surrounding filtering.