Added Search Configuration to IMAP Sensor

[mwegner]

The IMAP sensor currently only counts unread emails in a folder. By exposing the IMAP search parameter, the sensor can be used to count other results:

• All emails in an inbox
• Emails sent from an address
• Emails matching a subject
• Other advanced searches, especially with vendor-specific extensions. Gmail in particular supports X-GM-RAW, which lets you use any Gmail search directly ("emails with X label older than 14 days with", etc)

For my use case, I just wanted total emails in a folder, to show an "X/Y" counter for total/unread. I started work on a one-off script to throw the data in, but figured I'd try to extend Home Assistant more directly, especially since this IMAP sensor correctly handles servers that push data. This is my first Home Assistant contribution, so apologies in advance if something is out of place! It's a pretty minimal modification.

Description:

Related issue (if applicable): N/A

Pull request in home-assistant.io with documentation (if applicable): home-assistant/home-assistant.io#8034

Example entry for configuration.yaml (if applicable):

# Example configuration.yaml entry
sensor:
  - platform: imap
    server: imap.gmail.com
    port: 993
    username: YOUR_USERNAME
    password: YOUR_PASSWORD
    search: ALL

Checklist:

• The code change is tested and works locally.
• Local tests pass with tox. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated in home-assistant.io

If the code communicates with devices, web services, or third-party tools:

• New dependencies have been added to the REQUIREMENTS variable (example).
• New dependencies are only imported inside functions that use them (example).
• New or updated dependencies have been added to requirements_all.txt by running script/gen_requirements_all.py.
• New files were added to .coveragerc.

If the code does not interact with devices:

• Tests have been added to verify that the new code works.

[homeassistant]

Hi @mwegner,

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

[dgomes]

What happens if the user fills in an invalid search string ?

[mwegner]

Good question! I figured the underlying library would throw an exception, but looks like it doesn't. I added some basic checking to look for the "OK" result before parsing the count. Previous code counts spaces--the result is a list of IDs--so an error would actually result in a state value of 4.

You could see the bad server result with debug logging turned on, but now it throws a warning into the logger with the search text and full server result. Shows up as:

2019-01-03 15:18:36 WARNING (MainThread) [homeassistant.components.sensor.imap] Can't parse IMAP server response to search 'ASDAFTEST': BAD / Could not parse command

[dgomes]

I would go one step ahead and make it an ERROR, there is no point in a sensor that can't do its purpose.

[mwegner]

Good point! I'm not sure offhand how regularly IMAP servers barf--I think the silent errors in the library might be there in case connectivity or other issues are acting up. I would guess hiccups with something like Gmail is probably rare, but maybe less rare with an in-house company email server.

I'll get that changed over and fix up the linting when I get a sec.

[amelchio]

I like this 👍

Fun fact, my own first contribution to Home Assistant was to modify the IMAP search string (#6395) :)

[amelchio]

Looks good!