Get tile

hvpy/api_groups/screenshots/get_tile.py

@@ -0,0 +1,80 @@
+from typing import Optional
+from datetime import datetime
+
+from pydantic import validator
+
+from hvpy.io import HvpyParameters, OutputType
+from hvpy.utils import convert_date_to_isoformat
+
+
+class getTileInputParameters(HvpyParameters):
+    """
+    Handles the input parameters of the ``getTile`` API.
+
+    Attributes
+    ----------
+    {Shared}
+    id
+        Unique image identifier.
+    x
+        Tile x-coordinate.
+    y
+        Tile y-coordinate.
+    imageScale
+        Image scale in arcseconds per pixel.
+    difference
+        Specify image type difference.
+
+            ``0`` - Display regular image
+
+            ``1`` - Running difference image
+
+            ``2`` - Base difference image
+
+        Default is `None`, optional.
+
+    diffCount
+        Used to display Running difference image. Work with “diffTime” parameter and set amount of time to use in time period.
+        Default is `None`, optional.
+    diffTime
+        Select Running difference time period:
+
+            ``1`` - Minutes
+
+            ``2`` - Hours
+
+            ``3`` - Days
+
+            ``4`` - Weeks
+
+            ``5`` - Month
+
+            ``6`` - Years
+
+        Default is `None`, optional.
+    baseDiffTime
+        Date/Time string for Base difference images.
+        Default is `None`, optional.
+
+    References
+    ----------
+    * `<https://api.helioviewer.org/docs/v2/api/api_groups/official_clients.html#gettile>`__
+    {Shared}
+    """
+
+    id: int
+    x: int
+    y: int
+    imageScale: int
+    difference: Optional[int] = None
+    diffCount: Optional[int] = None
+    diffTime: Optional[int] = None
+    baseDiffTime: Optional[datetime] = None
+
+    _date_vaidator = validator("baseDiffTime", allow_reuse=True)(convert_date_to_isoformat)
+
+    def get_output_type(self) -> OutputType:
+        """
+        Returns the output type of the API call.
+        """
+        return OutputType.RAW

hvpy/api_groups/screenshots/tests/test_get_tile.py

@@ -0,0 +1,51 @@
+import pytest
+
+from hvpy import getTile
+from hvpy.api_groups.screenshots.get_tile import getTileInputParameters
+
+
+def test_getTile():
+    response = getTile(
+        id=36275490,
+        x=-1,
+        y=-1,
+        imageScale=2,
+    )
+    assert isinstance(response, bytes)
+
+
+def test_error_handling():
+    with pytest.raises(TypeError, match="missing 1 required positional argument: 'id'"):
+        getTile(
+            x=-1,
+            y=-1,
+            imageScale=2,
+        )
+    with pytest.raises(TypeError, match="missing 1 required positional argument: 'x'"):
+        getTile(
+            id=36275490,
+            y=-1,
+            imageScale=2,
+        )
+    with pytest.raises(TypeError, match="missing 1 required positional argument: 'y'"):
+        getTile(
+            id=36275490,
+            x=-1,
+            imageScale=2,
+        )
+    with pytest.raises(TypeError, match="missing 1 required positional argument: 'imageScale'"):
+        getTile(
+            id=36275490,
+            x=-1,
+            y=-1,
+        )
+
+
+def test_url_property():
+    params = getTileInputParameters(
+        id=36275490,
+        x=-1,
+        y=-1,
+        imageScale=2,
+    )
+    assert params.url == "https://api.beta.helioviewer.org/v2/getTile/"

hvpy/facade.py

@@ -21,6 +21,7 @@
     "downloadMovie",
     "getNewsFeed",
     "shortenURL",
+    "getTile",
 ]
 
 
@@ -522,3 +523,47 @@ def shortenURL(
         callback=callback,
     )
     return execute_api_call(input_parameters=params)
+
+
+@add_shared_docstring(getTileInputParameters)
+def getTile(
+    id: int,
+    x: int,
+    y: int,
+    imageScale: int,
+    difference: Optional[int] = None,
+    diffCount: Optional[int] = None,
+    diffTime: Optional[int] = None,
+    baseDiffTime: Optional[datetime] = None,
+) -> Union[bytes, str, Dict[str, Any]]:
+    """
+    Request a single image tile to be used in the Helioviewer.org Viewport.
+    Tiles are 512x512 pixel PNG images, generated for a given image scale from
+    the intermediary JPEG2000 image files.
+
+    Use the ``getClosestImage`` API endpoint to obtain the desired image identifier for the id parameter.
+
+    Parameters
+    ----------
+    {Insert}
+    Examples
+    --------
+    >>> from hvpy import getTile
+    >>> getTile(id=36275490,
+    ...         x=-1,
+    ...         y=-1,
+    ...         imageScale=2,
+    ...         )
+    b'...'
+    """
+    params = getTileInputParameters(
+        id=id,
+        x=x,
+        y=y,
+        imageScale=imageScale,
+        difference=difference,
+        diffCount=diffCount,
+        diffTime=diffTime,
+        baseDiffTime=baseDiffTime,
+    )
+    return execute_api_call(input_parameters=params)

hvpy/parameters.py

@@ -12,6 +12,7 @@
 from hvpy.api_groups.official_clients.get_closest_image import getClosestImageInputParameters
 from hvpy.api_groups.official_clients.get_data_sources import getDataSourcesInputParameters
 from hvpy.api_groups.screenshots.download_screenshot import downloadScreenshotInputParameters
+from hvpy.api_groups.screenshots.get_tile import getTileInputParameters
 from hvpy.api_groups.screenshots.take_screenshot import takeScreenshotInputParameters
 
 __all__ = [
@@ -30,4 +31,5 @@
     "downloadMovieInputParameters",
     "getNewsFeedInputParameters",
     "shortenURLInputParameters",
+    "getTileInputParameters",
 ]