Skip to content

Commit b8468ff

Browse files
committed
docstrings
1 parent bd6ec2b commit b8468ff

File tree

2 files changed

+99
-7
lines changed

2 files changed

+99
-7
lines changed

src/textual/color.py

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
"""
2-
This module contains a powerful Color class which Textual uses to expose colors.
2+
This module contains a powerful [Color][textual.color.Color] class which Textual uses to manipulate colors.
33
44
## Named colors
55
66
The following named colors are used by the [parse][textual.color.Color.parse] method.
77
8+
89
```{.rich columns="80" title="colors"}
910
from textual._color_constants import COLOR_NAME_TO_RGB
1011
from textual.color import Color
@@ -41,8 +42,6 @@
4142
from rich.color import Color as RichColor
4243
from rich.color import ColorType
4344
from rich.color_triplet import ColorTriplet
44-
from rich.style import Style
45-
from rich.text import Text
4645
from typing_extensions import Final
4746

4847
from textual.css.scalar import percentage_string_to_float
@@ -143,6 +142,22 @@ class Color(NamedTuple):
143142
Colors are stored as three values representing the degree of red, green, and blue in a color, and a
144143
fourth "alpha" value which defines where the color lies on a gradient of opaque to transparent.
145144
145+
Example:
146+
```python
147+
>>> from textual.color import Color
148+
>>> color = Color.parse("red")
149+
>>> color
150+
Color(255, 0, 0)
151+
>>> color.darken(0.5)
152+
Color(98, 0, 0)
153+
>>> color + Color.parse("green")
154+
Color(0, 128, 0)
155+
>>> color_with_alpha = Color(100, 50, 25, 0.5)
156+
>>> color_with_alpha
157+
Color(100, 50, 25, a=0.5)
158+
>>> color + color_with_alpha
159+
Color(177, 25, 12)
160+
```
146161
147162
"""
148163

@@ -185,7 +200,12 @@ def from_hsl(cls, h: float, s: float, l: float) -> Color:
185200

186201
@property
187202
def inverse(self) -> Color:
188-
"""The inverse of this color."""
203+
"""The inverse of this color.
204+
205+
Returns:
206+
Inverse color.
207+
208+
"""
189209
r, g, b, a = self
190210
return Color(255 - r, 255 - g, 255 - b, a)
191211

@@ -242,6 +262,9 @@ def hsl(self) -> HSL:
242262
243263
HSL color is an alternative way of representing a color, which can be used in certain color calculations.
244264
265+
Returns:
266+
Color encoded in HSL format.
267+
245268
"""
246269
r, g, b = self.normalized
247270
h, l, s = rgb_to_hls(r, g, b)
@@ -295,7 +318,12 @@ def css(self) -> str:
295318

296319
@property
297320
def monochrome(self) -> Color:
298-
"""A monochrome version of this color."""
321+
"""A monochrome version of this color.
322+
323+
Returns:
324+
The monochrome (black and white) version of this color.
325+
326+
"""
299327
r, g, b, a = self
300328
gray = round(r * 0.2126 + g * 0.7152 + b * 0.0722)
301329
return Color(gray, gray, gray, a)

src/textual/geometry.py

Lines changed: 66 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,21 @@ class Offset(NamedTuple):
6161
6262
Textual prefers the names `x` and `y`, but you could consider `x` to be the _column_ and `y` to be the _row_.
6363
64+
Offsets support addition, subtraction, multiplication, and negation.
65+
66+
Example:
67+
```python
68+
>>> from textual.geometry import Offset
69+
>>> offset = Offset(3, 2)
70+
>>> offset
71+
Offset(x=3, y=2)
72+
>>> offset += Offset(10, 0)
73+
>>> offset
74+
Offset(x=13, y=2)
75+
>>> -offset
76+
Offset(x=-13, y=-2)
77+
```
78+
6479
"""
6580

6681
x: int = 0
@@ -139,7 +154,21 @@ def get_distance_to(self, other: Offset) -> float:
139154

140155

141156
class Size(NamedTuple):
142-
"""The dimensions of a rectangular region."""
157+
"""The dimensions (width and height) of a rectangular region.
158+
159+
Example:
160+
```python
161+
>>> from textual.geometry import Size
162+
>>> size = Size(2, 3)
163+
>>> size
164+
Size(width=2, height=3)
165+
>>> size.area
166+
6
167+
>>> size + Size(10, 20)
168+
Size(width=12, height=23)
169+
```
170+
171+
"""
143172

144173
width: int = 0
145174
"""The width in cells."""
@@ -237,6 +266,24 @@ class Region(NamedTuple):
237266
◀─────── width ──────▶
238267
```
239268
269+
Example:
270+
```python
271+
>>> from textual.geometry import Region
272+
>>> region = Region(4, 5, 20, 10)
273+
>>> region
274+
Region(x=4, y=5, width=20, height=10)
275+
>>> region.area
276+
200
277+
>>> region.size
278+
Size(width=20, height=10)
279+
>>> region.offset
280+
Offset(x=4, y=5)
281+
>>> region.contains(1, 2)
282+
False
283+
>>> region.contains(10, 8)
284+
True
285+
```
286+
240287
"""
241288

242289
x: int = 0
@@ -831,7 +878,24 @@ def split_horizontal(self, cut: int) -> tuple[Region, Region]:
831878

832879

833880
class Spacing(NamedTuple):
834-
"""The spacing around a renderable."""
881+
"""The spacing around a renderable, such as padding and border
882+
883+
Spacing is defined by four integers for the space at the top, right, bottom, and left of a region,
884+
885+
Example:
886+
```python
887+
>>> from textual.geometry import Region, Spacing
888+
>>> region = Region(2, 3, 20, 10)
889+
>>> spacing = Spacing(1, 2, 3, 4)
890+
>>> region.grow(spacing)
891+
Region(x=-2, y=2, width=26, height=14)
892+
>>> region.shrink(spacing)
893+
Region(x=6, y=4, width=14, height=6)
894+
>>> spacing.css
895+
'1 2 3 4'
896+
```
897+
898+
"""
835899

836900
top: int = 0
837901
"""Space from the top of a region."""

0 commit comments

Comments
 (0)