add and move ts functions to helpers

twarc/client2.py

@@ -9,7 +9,6 @@
 import json
 import logging
 import requests
-import datetime
 import time
 
 from oauthlib.oauth2 import BackendApplicationClient
@@ -121,9 +120,9 @@ def _search(
         if until_id:
             params["until_id"] = until_id
         if start_time:
-            params["start_time"] = _ts(start_time)
+            params["start_time"] = ts(start_time)
         if end_time:
-            params["end_time"] = _ts(end_time)
+            params["end_time"] = ts(end_time)
 
         count = 0
         made_call = time.monotonic()
@@ -487,9 +486,9 @@ def _timeline(
         if until_id:
             params["until_id"] = until_id
         if start_time:
-            params["start_time"] = _ts(start_time)
+            params["start_time"] = ts(start_time)
         if end_time:
-            params["end_time"] = _ts(end_time)
+            params["end_time"] = ts(end_time)
 
         count = 0
         for response in self.get_paginated(url, params=params):
@@ -757,6 +756,6 @@ def _append_metadata(result, url):
     result["__twarc"] = {
                     "url": url,
                     "version": version,
-                    "retrieved_at": _utcnow()
+                    "retrieved_at": utcnow()
                 }
     return result

twarc/helpers.py

@@ -1,8 +1,10 @@
 """
 Useful functions for converting things into different types
 """
+import datetime
 
-def _ts(dt):
+
+def ts(dt):
     """
     Return ISO 8601 / RFC 3339 datetime in UTC. If no timezone is specified it
     is assumed to be in UTC. The Twitter API does not accept microseconds.
@@ -17,15 +19,40 @@ def _ts(dt):
         dt = dt.astimezone(datetime.timezone.utc)
     else:
         dt = dt.replace(tzinfo=datetime.timezone.utc)
-    return dt.isoformat(timespec='seconds')
+    return dt.isoformat(timespec="seconds")
+
 
-def _utcnow():
+def utcnow():
     """
     Return _now_ in ISO 8601 / RFC 3339 datetime in UTC.
 
     Returns:
         datetime: Current timestamp in UTC.
     """
-    return datetime.datetime.now(datetime.timezone.utc).isoformat(
-        timespec='seconds'
-    )
+    return datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds")
+
+
+def _snowflake2millis(snowflake_id):
+    return (snowflake_id >> 22) + 1288834974657
+
+
+def _millis2snowflake(milliseconds):
+    return (int(milliseconds) - 1288834974657) << 22
+
+
+def _get_millis(ms):
+    return ms % 1000
+
+
+def _sample_windows(start_ts, end_ts, sample_type):
+    """
+    todo: Generate tuples of start and end snowflake ids between two timestamps
+    
+    sample_type - type of random sample and millisecond range:
+        _1% "Spritzer" Sample   [657-666]
+        10% "Gardenhose" Sample [657-756]
+        10% "Enterprise" Sample [*0*]
+        _1% v2 Sample           [?]
+        _N% v2 Sample           [?]
+    """
+    pass

twarc/version.py

@@ -1 +1 @@
-version = '2.0.12'
+version = '2.0.13'