location: add all.py, using takeout/gpslogger/ip (#237)

* location: add all.py, using takeout/gpslogger/ip, update docs

my/ip/all.py

@@ -0,0 +1,29 @@
+"""
+An example all.py stub module that provides ip data
+
+To use this, you'd add IP providers that yield IPs to the 'ips' function
+
+For an example of how this could be used, see https://github.com/seanbreckenridge/HPI/tree/master/my/ip
+"""
+
+REQUIRES = ["git+https://github.com/seanbreckenridge/ipgeocache"]
+
+
+from typing import Iterator
+
+from my.core.common import Stats, warn_if_empty
+
+from .common import IP
+
+
+@warn_if_empty
+def ips() -> Iterator[IP]:
+    yield from ()
+
+
+def stats() -> Stats:
+    from my.core import stat
+
+    return {
+        **stat(ips),
+    }

my/ip/common.py

@@ -0,0 +1,39 @@
+"""
+Provides location/timezone data from IP addresses, using [[https://github.com/seanbreckenridge/ipgeocache][ipgeocache]]
+"""
+
+REQUIRES = ["git+https://github.com/seanbreckenridge/ipgeocache"]
+
+from my.core import __NOT_HPI_MODULE__
+
+import ipaddress
+from typing import NamedTuple, Iterator
+from datetime import datetime
+
+import ipgeocache
+
+from my.core import Json
+
+
+class IP(NamedTuple):
+    dt: datetime
+    addr: str  # an IP address
+
+    # TODO: could cache? not sure if it's worth it
+    def ipgeocache(self) -> Json:
+        return ipgeocache.get(self.addr)
+
+    @property
+    def tzname(self) -> str:
+        tz: str = self.ipgeocache()["timezone"]
+        return tz
+
+
+def drop_private(ips: Iterator[IP]) -> Iterator[IP]:
+    """
+    Helper function that can be used to filter out private IPs
+    """
+    for ip in ips:
+        if ipaddress.ip_address(ip.addr).is_private:
+            continue
+        yield ip