MOD: Improve path validation for timeseries

Author: nmacholl

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 #### Bug Fixes
 - Fixed and issue where the `end` parameter in `timeseries.get_range_async` did not support a value of `None`
+- Fixed an issue where `timeseries.get_range` requests would begin with an invalid `path` parameter
 
 ## 0.15.1 - 2023-07-06
 

databento/common/dbnstore.py

@@ -37,6 +37,7 @@
 from databento.common.data import STRUCT_MAP
 from databento.common.error import BentoError
 from databento.common.symbology import InstrumentIdMappingInterval
+from databento.common.validation import validate_file_write_path
 from databento.common.validation import validate_maybe_enum
 from databento.live import DBNRecord
 
@@ -978,10 +979,20 @@ def to_file(self, path: Path | str) -> None:
         path : str
             The file path to write to.
 
+        Raises
+        ------
+        IsADirectoryError
+            If path is a directory.
+        FileExistsError
+            If path exists.
+        PermissionError
+            If path is not writable.
+
         """
-        with open(path, mode="xb") as f:
+        file_path = validate_file_write_path(path, "path")
+        with open(file_path, mode="xb") as f:
             f.write(self._data_source.reader.read())
-        self._data_source = FileDataSource(path)
+        self._data_source = FileDataSource(file_path)
 
     def to_json(
         self,

databento/common/validation.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 from enum import Enum
 from os import PathLike
 from pathlib import Path
@@ -27,6 +28,11 @@ def validate_path(value: PathLike[str] | str, param: str) -> Path:
     Path
         A valid path.
 
+    Raises
+    ------
+    TypeError
+        If value is not a valid path.
+
     """
     try:
         return Path(value)
@@ -37,6 +43,42 @@ def validate_path(value: PathLike[str] | str, param: str) -> Path:
         ) from None
 
 
+def validate_file_write_path(value: PathLike[str] | str, param: str) -> Path:
+    """
+    Validate whether the given value is a valid path to a writable file.
+
+    Parameters
+    ----------
+    value: PathLike or str
+        The value to validate.
+    param : str
+        The name of the parameter being validated (for any error message).
+
+    Returns
+    -------
+    Path
+        A valid path to a writable file.
+
+    Raises
+    ------
+    IsADirectoryError
+        If path is a directory.
+    FileExistsError
+        If path exists.
+    PermissionError
+        If path is not writable.
+
+    """
+    path_valid = validate_path(value, param)
+    if not os.access(path_valid.parent, os.W_OK):
+        raise PermissionError(f"The file `{value}` is not writable.")
+    if path_valid.is_dir():
+        raise IsADirectoryError(f"The `{param}` was not a path to a file.")
+    if path_valid.is_file():
+        raise FileExistsError(f"The file `{value}` already exists.")
+    return path_valid
+
+
 def validate_enum(
     value: object,
     enum: type[E],

databento/historical/api/timeseries.py

@@ -15,6 +15,7 @@
 from databento.common.parsing import optional_datetime_to_string
 from databento.common.parsing import optional_symbols_list_to_list
 from databento.common.validation import validate_enum
+from databento.common.validation import validate_file_write_path
 from databento.common.validation import validate_semantic_string
 from databento.historical.api import API_VERSION
 from databento.historical.http import BentoHttpAPI
@@ -79,7 +80,7 @@ def get_range(
         limit : int, optional
             The maximum number of records to return. If `None` then no limit.
         path : PathLike or str, optional
-            The path to stream the data to on disk (will then return a `DBNStore`).
+            The file path to stream the data to on disk (will then return a `DBNStore`).
 
         Returns
         -------
@@ -115,6 +116,8 @@ def get_range(
             data["limit"] = str(limit)
         if end is not None:
             data["end"] = end_valid
+        if path is not None:
+            path = validate_file_write_path(path, "path")
 
         return self._stream(
             url=self._base_url + ".get_range",
@@ -174,7 +177,7 @@ async def get_range_async(
         limit : int, optional
             The maximum number of records to return. If `None` then no limit.
         path : PathLike or str, optional
-            The path to stream the data to on disk (will then return a `DBNStore`).
+            The file path to stream the data to on disk (will then return a `DBNStore`).
 
         Returns
         -------
@@ -210,6 +213,8 @@ async def get_range_async(
             data["limit"] = str(limit)
         if end is not None:
             data["end"] = end_valid
+        if path is not None:
+            path = validate_file_write_path(path, "path")
 
         return await self._stream_async(
             url=self._base_url + ".get_range",

tests/test_common_validation.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 from enum import Enum
+from pathlib import Path
 from typing import Any
 
 import pytest
 from databento.common.validation import validate_enum
+from databento.common.validation import validate_file_write_path
 from databento.common.validation import validate_gateway
 from databento.common.validation import validate_maybe_enum
 from databento.common.validation import validate_path
@@ -26,6 +28,29 @@ def test_validate_path_given_wrong_types_raises_type_error(
     with pytest.raises(TypeError):
         validate_path(value, "param")
 
+def test_validate_file_write_path(
+    tmp_path: Path,
+) -> None:
+    # Arrange, Act, Assert
+    test_file = tmp_path / "test.file"
+    validate_file_write_path(test_file, "param")
+
+def test_validate_file_write_path_is_dir(
+    tmp_path: Path,
+) -> None:
+    # Arrange, Act, Assert
+    with pytest.raises(IsADirectoryError):
+        validate_file_write_path(tmp_path, "param")
+
+def test_validate_file_write_path_exists(
+    tmp_path: Path,
+) -> None:
+    # Arrange, Act, Assert
+    test_file = tmp_path / "test.file"
+    test_file.touch()
+    with pytest.raises(FileExistsError):
+        validate_file_write_path(test_file, "param")
+
 @pytest.mark.parametrize(
     "value, enum",
     [