Inesa/v1 enums and dataclasses docstrings

sdk/python/packages/flet/src/flet/controls/base_control.py

@@ -98,6 +98,10 @@ class BaseControl:
     _i: int = field(init=False)
     _c: str = field(init=False)
     data: Any = skip_field()
+    """
+    Arbitrary data that can be attached to a control.
+    """
+
     ref: InitVar[Optional[Ref["BaseControl"]]] = None
 
     def __post_init__(self, ref: Optional[Ref[Any]]):
@@ -121,6 +125,16 @@ def __hash__(self) -> int:
 
     @property
     def parent(self) -> Optional["BaseControl"]:
+        """
+        Points to the direct ancestor(parent) of this control.
+
+        It defaults to `None` and will only have a value when this control is mounted 
+        (added to the page tree).
+
+        The `Page` control (which is the root of the tree) is an exception - it always 
+        has `parent=None`.
+        """
+
         parent_ref = getattr(self, "_parent", None)
         return parent_ref() if parent_ref else None
 
@@ -142,6 +156,10 @@ def init(self):
         pass
 
     def before_update(self):
+        """
+        `before_update()` method is called every time when the control is being updated.
+        Make sure not to call `update()` method within `before_update()`.
+        """
         pass
 
     def before_event(self, e: ControlEvent):

sdk/python/packages/flet/src/flet/controls/box.py

@@ -43,15 +43,52 @@
 
 @dataclass
 class ColorFilter:
+    """
+    Defines a color filter that can be used with
+    [`Container.color_filter`](https://flet.dev/docs/controls/container#color_filter).
+    """
+
     color: OptionalColorValue = None
+    """
+    The [color](https://flet.dev/docs/reference/colors) to use when applying the filter.
+    """
+
     blend_mode: Optional[BlendMode] = None
+    """
+    The blend mode to apply to the color filter.
+
+    Value is of type [`BlendMode`](https://flet.dev/docs/reference/types/blendmode).
+    """
 
 
 class FilterQuality(Enum):
+    """
+    Quality levels for image sampling in Image and DecorationImage objects.
+    """
+
     NONE = "none"
+    """
+    The fastest filtering method, albeit also the lowest quality.
+    """
+
     LOW = "low"
+    """
+    Better quality than none, faster than medium.
+    """
+
     MEDIUM = "medium"
+    """
+    The best all around filtering method that is only worse than high at extremely 
+    large scale factors.
+    """
+
     HIGH = "high"
+    """
+    Best possible quality when scaling up images by scale factors larger than 5-10x.
+    When images are scaled down, this can be worse than medium for scales smaller than 
+    0.5x, or when animating the scale factor.
+    This option is also the slowest.
+    """
 
 
 class ShadowBlurStyle(Enum):
@@ -64,10 +101,40 @@ class ShadowBlurStyle(Enum):
 @dataclass
 class BoxShadow:
     spread_radius: OptionalNumber = None
+    """
+    The amount the box should be inflated prior to applying the blur.
+
+    Defaults to `0.0.`
+    """
+
     blur_radius: OptionalNumber = None
+    """
+    The standard deviation of the Gaussian to convolve with the shadow's shape.
+
+    Defaults to `0.0.`
+    """
+
     color: OptionalColorValue = None
+    """
+    [Color](https://flet.dev/docs/reference/colors) used to draw the shadow.
+    """
+
     offset: Optional[OffsetValue] = None
+    """
+    An instance of `Offset` class - the displacement of the shadow from the casting
+    element. Positive x/y offsets will shift the shadow to the right and down, while
+    negative offsets shift the shadow to the left and up. The offsets are relative to
+    the position of the element that is casting it.
+
+    Value is of type [`Offset`](https://flet.dev/docs/reference/types/offset) and
+    defaults to `Offset(0,0)`.
+    """
+
     blur_style: ShadowBlurStyle = ShadowBlurStyle.NORMAL
+    """
+    Value is of type [`ShadowBlurStyle`](https://flet.dev/docs/reference/types/shadowblurstyle)
+    and defaults to `ShadowBlurStyle.NORMAL`.
+    """
 
 
 ShadowValue = Union[BoxShadow, list[BoxShadow]]
@@ -91,39 +158,208 @@ class BoxFit(Enum):
 
 @dataclass
 class DecorationImage:
+    """
+    An image for a box decoration.
+    """
+
     src: Optional[str] = None
+    """
+    The image to paint.
+    """
+
     src_base64: Optional[str] = None
+    """
+    The base64-encoded image to paint.
+    """
+
     src_bytes: Optional[bytes] = None
+    """
+    TBD
+    """
+
     color_filter: Optional[ColorFilter] = None
+    """
+    A color filter to apply to the image before painting it.
+
+    Value is of type [`ColorFilter`](https://flet.dev/docs/reference/types/colorfilter).
+    """
+
     fit: Optional[ImageFit] = None
+    """
+    How the image should be inscribed into the box.
+
+    Value is of type [`ImageFit`](https://flet.dev/docs/reference/types/imagefit).
+    """
+
     alignment: Optional[Alignment] = None
+    """
+    The alignment of the image within its bounds.
+
+    Value is of type [`Alignment`](https://flet.dev/docs/reference/types/alignment) and 
+    defaults to `Alignment(0.0, 0.0)`.
+    """
+
     repeat: Optional[ImageRepeat] = None
+    """
+    How the image should be repeated to fill the box.
+
+    Value is of type [`ImageRepeat`](https://flet.dev/docs/reference/types/imagerepeat) 
+    and defaults to `ImageRepeat.NO_REPEAT`.
+    """
+
     match_text_direction: OptionalBool = None
+    """
+    Whether to paint the image in the direction of the TextDirection.
+
+    Value is of type `bool` and defaults to `False`.
+    """
+
     scale: OptionalNumber = None
+    """
+    The scale(image pixels to be shown per logical pixels) to apply to the image.
+
+    Value is of type `float` and defaults to `1.0`.
+    """
+
     opacity: OptionalNumber = None
+    """
+    The opacity of the image.
+
+    Value is of type `float` and defaults to `1.0`.
+    """
+
     filter_quality: Optional[FilterQuality] = None
+    """
+    The quality of the image filter.
+
+    Value is of type [`FilterQuality`](https://flet.dev/docs/reference/types/filterquality) 
+    and defaults to `FilterQuality.MEDIUM`.
+    """
+
     invert_colors: OptionalBool = None
+    """
+    Whether to invert the colors of the image while drawing.
+
+    Value is of type `bool` and defaults to `False`.
+    """
+
     anti_alias: OptionalBool = None
+    """
+    Whether to paint the image in anti-aliased quality.
+
+    Value is of type `bool` and defaults to `False`.
+    """
 
 
 @dataclass
 class BoxDecoration:
+    """
+    BoxDecoration provides a description of how to paint a box.
+    The box has a border, a body, and may cast a shadow.
+    """
+
     bgcolor: OptionalColorValue = None
+    """
+    The [color](https://flet.dev/docs/reference/colors) to fill in the background of 
+    the box.
+    """
+
     image: Optional[DecorationImage] = None
+    """
+    An image to paint above the background `color` or `gradient`.
+
+    Value is of type [`DecorationImage`](https://flet.dev/docs/reference/types/decorationimage).
+    """
+
     border: Optional[Border] = None
+    """
+    A border to draw above the background `color`, `gradient`, or `image`.
+
+    Value is of type [`Border`](https://flet.dev/docs/reference/types/border).
+    """
+
     border_radius: OptionalBorderRadiusValue = None
+    """
+    The border radius of the box.
+
+    Value is of type [`BorderRadius`](https://flet.dev/docs/reference/types/borderradius).
+    """
+
     shadow: Optional[ShadowValue] = None
+    """
+    A list of shadows cast by the box.
+
+    Value is of type [`List[BoxShadow]`](https://flet.dev/docs/reference/types/boxshadow).
+    """
+
     gradient: Optional[Gradient] = None
+    """
+    A gradient to use when filling the box.
+    """
+
     shape: Optional[BoxShape] = None
+    """
+    The shape to fill the `bgcolor`, `gradient`, and `image` into and to cast as the 
+    `shadow`.
+    """
+
     blend_mode: Optional[BlendMode] = None
+    """
+    The blend mode to apply to the background `color` or `gradient`.
+
+    Value is of type [`BlendMode`](https://flet.dev/docs/reference/types/blendmode).
+    """
 
 
 @dataclass
 class BoxConstraints:
+    """
+    Constraints that must be respected by a size of a box.
+
+    A Size respects a BoxConstraints if, and only if, all of the following relations 
+    hold:
+
+        min_width <= Size.width <= max_width
+        min_height <= Size.height <= max_height
+
+    Read more about BoxConstraints [here](https://api.flutter.dev/flutter/rendering/BoxConstraints-class.html).
+    """
+
     min_width: Number = 0
+    """
+    The minimum width that satisfies the constraints, such that
+    `0.0 <= min_width <= max_width`.
+
+    Value is of type [`Number`](https://flet.dev/docs/reference/types/aliases#number)
+    and defaults to `0.0`.
+    """
+
     min_height: Number = 0
+    """
+    The minimum height that satisfies the constraints, such that
+    `0.0 <= min_height <= max_height`.
+
+    Value is of type [`Number`](https://flet.dev/docs/reference/types/aliases#number)
+    and defaults to `0.0`.
+    """
+
     max_width: Number = float("inf")
+    """
+    The maximum width that satisfies the constraints, such that
+    `min_width <= max_width <= float("inf")`.
+
+    Value is of type [`Number`](https://flet.dev/docs/reference/types/aliases#number)
+    and defaults to `float("inf")` - infinity.
+    """
+
     max_height: Number = float("inf")
+    """
+    The maximum height that satisfies the constraints, such that
+    `min_height <= max_height <= float("inf")`.
+
+    Value is of type [`Number`](https://flet.dev/docs/reference/types/aliases#number)
+    and defaults to `float("inf")` - infinity.
+    """
 
     def __post_init__(self):
         assert 0 <= self.min_width <= self.max_width <= float("inf"), (