Document extract

docs/references/utils.md

@@ -0,0 +1 @@
+::: urlscan.utils

src/urlscan/client.py

@@ -17,7 +17,7 @@
 from .error import APIError, ItemError, RateLimitError, RateLimitRemainingError
 from .iterator import SearchIterator
 from .types import ActionType, SearchDataSource, VisibilityType
-from .utils import _compact, parse_datetime
+from .utils import _compact, _parse_datetime
 
 logger = logging.getLogger("urlscan-python")
 
@@ -249,7 +249,7 @@ def _send_request(
             if remaining and reset:
                 self._rate_limit_memo[action] = RateLimit(
                     remaining=int(remaining),
-                    reset=parse_datetime(reset),
+                    reset=_parse_datetime(reset),
                 )
 
         return res

src/urlscan/utils.py

@@ -19,21 +19,30 @@ def _merge(d: dict, kwargs: dict[str, Any]) -> dict:
     result = d.copy()
     for k, v in kwargs.items():
         if k in result:
-            raise ValueError(f"Recived multiple values for key: {k}")
+            raise ValueError(f"Received multiple values for key: {k}")
 
         result[k] = v
 
     return result
 
 
-def parse_datetime(s: str) -> datetime.datetime:
+def _parse_datetime(s: str) -> datetime.datetime:
     """Parse an ISO 8601 datetime string to a datetime object."""
     dt = datetime.datetime.strptime(s, "%Y-%m-%dT%H:%M:%S.%fZ")
     return dt.replace(tzinfo=datetime.timezone.utc)
 
 
 def extract(path: StrOrBytesPath, outdir: StrOrBytesPath):
-    """Extract a compressed file to the specified output directory."""
+    """Extract a compressed file to the specified output directory.
+
+    Args:
+        path (StrOrBytesPath): The path to the compressed file.
+        outdir (StrOrBytesPath): The directory to extract the files to.
+
+    Returns:
+        None
+
+    """
     basename = os.path.basename(str(path))
     if basename.endswith(".tar.gz"):
         with tarfile.open(path, mode="r:*", ignore_zeros=True) as tar:

tests/unit/test_utils.py

@@ -4,7 +4,7 @@
 
 import pytest
 
-from urlscan.utils import _merge, extract, parse_datetime
+from urlscan.utils import _merge, _parse_datetime, extract
 
 
 def test_merge():
@@ -32,7 +32,7 @@ def inner(**kwargs):
     ],
 )
 def test_parse_datetime(input_str: str, expected: datetime.datetime):
-    result = parse_datetime(input_str)
+    result = _parse_datetime(input_str)
     assert result == expected