Add last_clean_details to return information from the last clean (#395)

* Add last_clean_details to return information from the last clean

This involves also refactoring clean_details() to return the results unwrapped.
For the time being the default behavior will remain the same as it was (wrapped),
but a deprecation warning will be raised.

I'm expecting that we can flip the toggle after a while, and remove the warning
at that point, too.

* try to fix the indent, return the full list instead of a single entry when return_list=True

miio/vacuum.py

@@ -6,7 +6,7 @@
 import os
 import pathlib
 import time
-from typing import List
+from typing import List, Optional, Union
 
 import click
 import pytz
@@ -184,17 +184,39 @@ def clean_history(self) -> CleaningSummary:
         """Return generic cleaning history."""
         return CleaningSummary(self.send("get_clean_summary"))
 
+    @command()
+    def last_clean_details(self) -> CleaningDetails:
+        """Return details from the last cleaning."""
+        last_clean_id = self.clean_history().ids.pop()
+        return self.clean_details(last_clean_id, return_list=False)
+
     @command(
         click.argument("id_", type=int, metavar="ID"),
+        click.argument("return_list", type=bool, default=False)
     )
-    def clean_details(self, id_: int) -> List[CleaningDetails]:
+    def clean_details(self, id_: int, return_list=True) -> Union[
+            List[CleaningDetails],
+            Optional[CleaningDetails]]:
         """Return details about specific cleaning."""
         details = self.send("get_clean_record", [id_])
 
-        res = list()
-        for rec in details:
-            res.append(CleaningDetails(rec))
+        if not details:
+            _LOGGER.warning("No cleaning record found for id %s" % id_)
+            return None
+
+        if return_list:
+            _LOGGER.warning("This method will be returning the details "
+                            "without wrapping them into a list in the "
+                            "near future. The current behavior can be "
+                            "kept by passing return_list=True and this "
+                            "warning will be removed when the default gets "
+                            "changed.")
+            return [CleaningDetails(entry) for entry in details]
+
+        if len(details) > 1:
+            _LOGGER.warning("Got multiple clean details, returning the first")
 
+        res = CleaningDetails(details.pop())
         return res
 
     @command()

miio/vacuum_cli.py

@@ -418,15 +418,15 @@ def cleaning_history(vac: miio.Vacuum):
                                                   res.total_area))
     click.echo()
     for idx, id_ in enumerate(res.ids):
-        for e in vac.clean_details(id_):
-            color = "green" if e.complete else "yellow"
-            click.echo(click.style(
-                "Clean #%s: %s-%s (complete: %s, error: %s)" % (
-                    idx, e.start, e.end, e.complete, e.error),
-                bold=True, fg=color))
-            click.echo("  Area cleaned: %s m²" % e.area)
-            click.echo("  Duration: (%s)" % e.duration)
-            click.echo()
+        details = vac.clean_details(id_, return_list=False)
+        color = "green" if details.complete else "yellow"
+        click.echo(click.style(
+            "Clean #%s: %s-%s (complete: %s, error: %s)" % (
+                idx, details.start, details.end, details.complete, details.error),
+            bold=True, fg=color))
+        click.echo("  Area cleaned: %s m²" % details.area)
+        click.echo("  Duration: (%s)" % details.duration)
+        click.echo()
 
 
 @cli.command()