period

Author: lsbardel

ccy/dates/period.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Self
 
 
 def period(pstr: str = "") -> Period:
@@ -31,7 +31,7 @@ def __init__(self, months: int = 0, days: int = 0) -> None:
         self._days = days
 
     @classmethod
-    def make(cls, data: Any) -> Period:
+    def make(cls, data: Any) -> Self:
         if isinstance(data, cls):
             return data
         elif isinstance(data, str):
@@ -110,7 +110,7 @@ def simple(self) -> str:
         else:
             return ""
 
-    def add_tenure(self, pstr: str) -> Period:
+    def add_tenure(self, pstr: str) -> Self:
         if isinstance(pstr, self.__class__):
             self._months += pstr._months
             self._days += pstr._days
@@ -141,18 +141,18 @@ def add_tenure(self, pstr: str) -> Period:
                 st = st[ip:]
         return self
 
-    def __add__(self, other: Any) -> Period:
+    def __add__(self, other: Any) -> Self:
         p = self.make(other)
         return self.__class__(self._months + p._months, self._days + p._days)
 
-    def __radd__(self, other: Any) -> Period:
+    def __radd__(self, other: Any) -> Self:
         return self + other
 
-    def __sub__(self, other: Any) -> Period:
+    def __sub__(self, other: Any) -> Self:
         p = self.make(other)
         return self.__class__(self._months - p._months, self._days - p._days)
 
-    def __rsub__(self, other: Any) -> Period:
+    def __rsub__(self, other: Any) -> Self:
         return self.make(other) - self
 
     def __gt__(self, other: Any) -> bool:

docs/dates.md

@@ -1,26 +1,49 @@
 # Dates & Periods
 
-The module is shipped with a `date` module for manipulating time periods and
-converting dates between different formats. The *period* function can be used
-to create `Period` instances:
+The `Period` class represents a calendar period composed of months and days.
+Use the `period` factory function to create instances from a period string.
+
+## Period strings
+
+A period string combines one or more components, each a number followed by a unit letter:
+
+| Unit | Meaning |
+|------|---------|
+| `Y`  | Years   |
+| `M`  | Months  |
+| `W`  | Weeks   |
+| `D`  | Days    |
+
+Examples: `"1Y"`, `"6M"`, `"2W"`, `"3D"`, `"1Y6M"`, `"2W3D"`.
+
+## Usage
 
 ```python
 import ccy
-p = ccy.period("1m")
-p
-```
 
-```python
-p += "2w"
-p
+p = ccy.period("1Y6M")
+str(p)       # "1Y6M"
+p.years      # 1
+p.months     # 6
+p.totaldays  # 390
 ```
 
+Arithmetic with strings or other `Period` objects:
+
 ```python
-p += "3m"
-p
+p = ccy.period("1M")
+p += "2W"    # Period("1M2W")
+p += "3M"    # Period("4M2W")
+p -= "1W"    # Period("4M1W")
 ```
 
+Comparison:
+
 ```python
-p -= "1w"
-p
+ccy.period("1Y") > ccy.period("6M")   # True
+ccy.period("12M") == ccy.period("1Y") # True
 ```
+
+## Class reference
+
+::: ccy.dates.period.Period