Adding aspect ratio handling to images and video objects. Aspect rat… (#19)

* Adding aspect ratio handling to images and video objects.  Aspect ratio can now be provided manually or will be automatically determined

Author: dmoggles

pyproject.toml

@@ -8,7 +8,7 @@ name = "blueskysocial"
 
 
 dependencies = [
-    "requests","BeautifulSoup4"
+    "requests","BeautifulSoup4","pillow==11.2.1","opencv-python==4.11.0.86"
 ]
 [project.optional-dependencies]
 dev = [

setup.cfg

@@ -23,6 +23,8 @@ python_requires = >=3.11
 install_requires =
     requests
     BeautifulSoup4
+    pillow==11.2.1
+    opencv-python==4.11.0.86
 
 [options.extras_require]
 dev =

src/blueskysocial/errors.py

@@ -113,3 +113,15 @@ class InvalidAttachmentsError(Exception):
     Attributes:
         None
     """
+
+
+class UnknownAspectRatioError(Exception):
+    """
+    Exception raised when the aspect ratio of an image is unknown.
+
+    This error is intended to be used when an operation requires a known aspect ratio,
+    but the aspect ratio of the provided image cannot be determined.
+
+    Attributes:
+        None
+    """

src/blueskysocial/image.py

@@ -39,12 +39,16 @@
     post = Post("Check this out!", with_attachments=image)
 """
 
-from typing import Union, Optional, List, cast
+from typing import Union, List, cast, Optional, Tuple, Callable, Dict
 from io import BytesIO
 import requests
 from blueskysocial.api_endpoints import UPLOAD_BLOB, RPC_SLUG, IMAGES_TYPE
 from blueskysocial.post_attachment import PostAttachment
-from blueskysocial.utils import get_auth_header
+from blueskysocial.utils import (
+    get_auth_header,
+    get_image_aspect_ratio_spec,
+    provide_aspect_ratio,
+)
 from blueskysocial.errors import ImageIsTooLargeError
 from blueskysocial.typedefs import ApiPayloadType, PostProtocol, as_str
 
@@ -120,7 +124,13 @@ class Image(PostAttachment):
         post = Post("Photo gallery!", with_attachments=images)
     """
 
-    def __init__(self, image: Union[str, BytesIO], alt_text: str) -> None:
+    def __init__(
+        self,
+        image: Union[str, BytesIO],
+        alt_text: str,
+        aspect_ratio: Optional[Tuple[int, int]] = None,
+        require_aspect_ratio: bool = False,
+    ) -> None:
         """
         Initialize an Image attachment with source and alternative text.
 
@@ -159,7 +169,9 @@ def __init__(self, image: Union[str, BytesIO], alt_text: str) -> None:
                 image = Image(buffer, alt_text="Chart showing sales data")
         """
         self._alt_text = alt_text
-        self._image: Optional[bytes] = self._set_image(image)
+        self._image = self._set_image(image)
+        self._aspect_ratio = aspect_ratio
+        self._require_aspect_ratio = require_aspect_ratio
 
     @property
     def alt_text(self) -> str:
@@ -380,7 +392,10 @@ def attach_to_post(self, post: PostProtocol, session: ApiPayloadType) -> None:
             #     ]
             # }
         """
+        aspect_ratio = provide_aspect_ratio(self)
         img_dict: ApiPayloadType = {"alt": self.alt_text, "image": self.build(session)}
+        if aspect_ratio:
+            img_dict["aspectRatio"] = aspect_ratio
         post.embed["$type"] = IMAGES_TYPE
         if "images" not in post.embed:
             post.embed["images"] = [img_dict]
@@ -444,7 +459,66 @@ def build(self, session: ApiPayloadType) -> ApiPayloadType:
         resp = requests.post(
             RPC_SLUG + UPLOAD_BLOB,
             headers=headers,
-            data=self._image,
+            data=self.data_accessor,
         )
         resp.raise_for_status()
         return cast(ApiPayloadType, resp.json()["blob"])
+
+    @property
+    def data_accessor(self) -> bytes:
+        """
+        Get the raw image data in bytes.
+
+
+        Returns:
+            bytes: The raw image data in PNG format ready for upload
+
+        Examples:
+            image = Image("photo.jpg", alt_text="A beautiful sunset")
+            raw_data = image.data_accessor
+            # raw_data contains the bytes of the image
+        """
+        return self._image
+
+    @property
+    def aspect_ratio(self) -> Optional[Tuple[int, int]]:
+        """
+        Get the aspect ratio of the image if available.
+
+        Returns the aspect ratio tuple (width, height) if it was provided during
+        initialization or calculated. If no aspect ratio is set, returns None.
+
+        Returns:
+            Optional[Tuple[int, int]]: The aspect ratio of the image as a tuple
+                                       of (width, height) or None if not set.
+
+        """
+        return self._aspect_ratio
+
+    @property
+    def require_aspect_ratio(self) -> bool:
+        """
+        Check if the image requires an aspect ratio.
+
+        Returns True if the image requires an aspect ratio to be provided,
+        otherwise returns False. This is used to determine if aspect ratio
+        validation should be enforced during post attachment.
+
+        Returns:
+            bool: True if aspect ratio is required, False otherwise.
+        """
+        return self._require_aspect_ratio
+
+    @property
+    def aspect_ratio_function(self) -> Callable[[bytes], Optional[Dict[str, int]]]:
+        """
+        Get the function to provide aspect ratio for the image.
+
+        Returns a callable that returns the aspect ratio of the image if available.
+        This allows dynamic aspect ratio retrieval based on the current image state.
+
+        Returns:
+            callable: A function that returns the aspect ratio tuple (width, height)
+                      or None if not set.
+        """
+        return get_image_aspect_ratio_spec

src/blueskysocial/typedefs/__init__.py

@@ -2,7 +2,12 @@
 Typing protocols and type definitions for BlueSky Social.
 """
 
-from .protocols import ConvoProtocol, DirectMessageProtocol, PostProtocol
+from .protocols import (
+    ConvoProtocol,
+    DirectMessageProtocol,
+    PostProtocol,
+    AspectRatioConsumerProtocol,
+)
 from ._types import RecursiveStrDict, DictStrOrInt, ApiPayloadType
 from .typecheck import as_str, as_bs4_tag, as_bool, as_int
 
@@ -17,4 +22,5 @@
     "as_bs4_tag",
     "as_bool",
     "as_int",
+    "AspectRatioConsumerProtocol",
 ]

src/blueskysocial/typedefs/protocols.py

@@ -2,7 +2,7 @@
 Protocol definitions for BlueSky Social types.
 """
 
-from typing import Protocol
+from typing import Protocol, Callable, Dict, Optional, Tuple, Any
 import datetime as dt
 from typing_extensions import runtime_checkable
 from blueskysocial.typedefs._types import ApiPayloadType
@@ -146,3 +146,53 @@ def embed(self) -> ApiPayloadType:
             Dict[str, str]: The embedded data.
         """
         ...
+
+
+class AspectRatioConsumerProtocol(Protocol):
+    """
+    Protocol defining the interface for an object that consumes aspect ratio data.
+
+    This protocol defines the expected attributes and methods that an object
+    should have to be compatible with aspect ratio specifications.
+    """
+
+    @property
+    def data_accessor(self) -> str | bytes:
+        """
+        The data accessor for the aspect ratio consumer.  Provides the data that can be used to determine the aspect ratio.
+
+        Returns:
+            str|bytes: The data accessor, which can be a string or bytes.
+        """
+        ...
+
+    @property
+    def aspect_ratio_function(self) -> Callable[[Any], Optional[Dict[str, int]]]:
+        """
+        The function used to calculate the aspect ratio from the data accessor.
+        This function should take the data accessor as input and return a dictionary
+        containing the width and height of the aspect ratio.
+        Returns:
+            Callable[[str|bytes], Dict[str, int]]: A function that takes the data accessor and returns a dictionary with width and height.
+        """
+        ...
+
+    @property
+    def aspect_ratio(self) -> Optional[Tuple[int, int]]:
+        """
+        The aspect ratio of the data accessor.
+
+        Returns:
+            Optional[Tuple[int, int]]: A tuple containing the width and height of the aspect ratio, or None if not applicable.
+        """
+        ...
+
+    @property
+    def require_aspect_ratio(self) -> bool:
+        """
+        Whether the aspect ratio is required for the consumer.
+
+        Returns:
+            bool: True if the aspect ratio is required, False otherwise.
+        """
+        ...

src/blueskysocial/utils.py

@@ -5,6 +5,11 @@
 from typing import Dict, Optional, Union
 from bs4 import Tag
 from bs4.element import NavigableString
+from PIL import Image
+from io import BytesIO
+import cv2
+from blueskysocial.typedefs import AspectRatioConsumerProtocol
+from blueskysocial.errors import UnknownAspectRatioError
 
 
 def parse_uri(uri: str) -> Dict[str, str]:
@@ -60,3 +65,94 @@ def bs4_tag_extract_content(tag: Optional[Union[Tag, NavigableString]]) -> str:
         content = tag.get("content")
         return str(content) if content is not None else ""
     return ""
+
+
+def get_image_aspect_ratio_spec(image: bytes) -> Optional[Dict[str, int]]:
+    """
+    Returns the width and height of an image from its byte content.
+    Args:
+        image (bytes): The image data in bytes.
+    Returns:
+        Optional[Dict[str, int]]: A dictionary containing the width and height of the image,
+        or None if the image cannot be opened or processed.
+    """
+
+    try:
+        with Image.open(BytesIO(image)) as img:
+            width, height = img.size
+            return {
+                "width": width,
+                "height": height,
+            }
+    except Exception:
+        return None
+
+
+def get_video_aspect_ratio_spec(path: str) -> Optional[Dict[str, int]]:
+    """
+    Get the aspect ratio specification (width and height) of a video file.
+    Args:
+        path (str): The file path to the video file.
+    Returns:
+        Optional[Dict[str, int]]: A dictionary containing 'width' and 'height' keys
+                                 with integer values representing the video dimensions,
+                                 or None if the video cannot be opened or an error occurs.
+    Raises:
+        ValueError: If the video file cannot be opened (caught internally and returns None).
+    Example:
+        >>> specs = get_video_aspect_ratio_spec("/path/to/video.mp4")
+        >>> if specs:
+        ...     print(f"Video dimensions: {specs['width']}x{specs['height']}")
+    """
+
+    try:
+        cap = cv2.VideoCapture(path)
+        if not cap.isOpened():
+            raise ValueError(f"Cannot open video: {path}")
+        width = cap.get(cv2.CAP_PROP_FRAME_WIDTH)
+        height = cap.get(cv2.CAP_PROP_FRAME_HEIGHT)
+        cap.release()
+        return {
+            "width": int(width),
+            "height": int(height),
+        }
+    except Exception:
+        return None
+
+
+def provide_aspect_ratio(
+    consumer: AspectRatioConsumerProtocol,
+) -> Optional[Dict[str, int]]:
+    """
+    Provide aspect ratio information for a consumer object.
+    This function attempts to retrieve aspect ratio information from a consumer object
+    by first checking if the consumer has a predefined aspect ratio, and if not,
+    calling the consumer's aspect ratio function to compute it dynamically.
+    Args:
+        consumer (AspectRatioConsumerProtocol): An object that implements the
+            AspectRatioConsumerProtocol, containing aspect ratio information or
+            methods to compute it.
+    Returns:
+        Optional[Dict[str, int]]: A dictionary containing 'width' and 'height'
+            keys with integer values representing the aspect ratio, or None if
+            the aspect ratio cannot be determined and is not required.
+    Raises:
+        UnknownAspectRatioError: If the aspect ratio cannot be determined and
+            the consumer requires an aspect ratio (consumer.require_aspect_ratio
+            is True).
+    Note:
+        The function prioritizes the consumer's predefined aspect_ratio attribute
+        over the computed aspect ratio from the aspect_ratio_function.
+    """
+
+    if consumer.aspect_ratio is not None:
+        return {"width": consumer.aspect_ratio[0], "height": consumer.aspect_ratio[1]}
+
+    aspect_ratio = consumer.aspect_ratio_function(consumer.data_accessor)
+    if aspect_ratio is None and consumer.require_aspect_ratio:
+        raise UnknownAspectRatioError(
+            f"{consumer.__class__.__name__} aspect ratio could not be determined. "
+            "Please provide a valid aspect ratio function or data accessor."
+            "or provide a valid aspect ratio at construction time using the aspect_ratio parameter."
+        )
+    return aspect_ratio