vibe coding

Author: lsbardel

.github/copilot-instructions.md

@@ -21,3 +21,4 @@ applyTo: '/**'
 * The documentation for ccy is available at `https://ccy.quantmid.com`
 * Documentation is built using [mkdocs](https://www.mkdocs.org/) and stored in the `docs/` directory. The documentation source files are written in markdown format.
 * Do not use em dashes (—) in documentation files or docstrings. Use colons, parentheses, or restructure the sentence instead.
+* To link to a class or function in documentation, use the mkdocstrings cross-reference notation: `[ClassName][module.path.ClassName]` (e.g. `[TradingCentre][ccy.tradingcentres.TradingCentre]`)

Makefile

@@ -38,7 +38,7 @@ docs:		## Build mkdocs site
 
 .PHONY: docs-serve
 docs-serve:	## Serve docs locally with live reload
-	uv run mkdocs serve
+	uv run mkdocs serve --livereload --watch ccy --watch docs
 
 .PHONY: publish-docs
 publish-docs:	## Publish docs to github pages

ccy/core/daycounter.py

@@ -17,17 +17,13 @@ class DayCounter(StrEnum):
     THIRTYE360 = "30E/360"
     ACTACT = "ACT/ACT"
 
-    def count(self, start: date, end: date) -> float:
-        """Count the number of days between 2 dates"""
-        return date_diff(end, start).total_seconds() / 86400
-
     def dcf(self, start: date, end: date) -> float:
         """Day count fraction between 2 dates"""
         match self:
             case DayCounter.ACT360:
-                return self.count(start, end) / 360.0
+                return count_days(start, end) / 360.0
             case DayCounter.ACT365:
-                return self.count(start, end) / 365.0
+                return count_days(start, end) / 365.0
             case DayCounter.THIRTY360:
                 return _thirty_360(start, end)
             case DayCounter.THIRTYE360:
@@ -38,6 +34,11 @@ def dcf(self, start: date, end: date) -> float:
                 raise ValueError(f"Unknown day counter: {self}")
 
 
+def count_days(start: date, end: date) -> float:
+    """Count the number of days between 2 dates"""
+    return date_diff(end, start).total_seconds() / 86400
+
+
 def _thirty_e360(start: date, end: date) -> float:
     d1 = min(start.day, 30)
     d2 = min(end.day, 30)

ccy/tradingcentres/__init__.py

@@ -1,26 +1,47 @@
 from __future__ import annotations
 
-from dataclasses import dataclass, field
 from datetime import date, timedelta
+from typing_extensions import Annotated, Doc
+
 import holidays
 import holidays.countries
 import holidays.financial
+from pydantic import BaseModel, Field
 
 isoweekend = frozenset((6, 7))
 oneday = timedelta(days=1)
 
 trading_centres: dict[str, TradingCentre] = {}
 
 
-def prevbizday(dte: date, nd: int = 1, tcs: str | None = None) -> date:
+def prevbizday(
+    dte: Annotated[date, Doc("The reference date")],
+    nd: Annotated[int, Doc("Number of business days to move back")] = 1,
+    tcs: Annotated[str | None, Doc("Comma-separated trading centre codes")] = None,
+) -> date:
+    """Return the date nd business days before dte."""
     return centres(tcs).prevbizday(dte, nd)
 
 
-def nextbizday(dte: date, nd: int = 1, tcs: str | None = None) -> date:
+def nextbizday(
+    dte: Annotated[date, Doc("The reference date")],
+    nd: Annotated[
+        int,
+        Doc("Number of business days to move forward; 0 adjusts to next biz day"),
+    ] = 1,
+    tcs: Annotated[str | None, Doc("Comma-separated trading centre codes")] = None,
+) -> date:
+    """Return the date nd business days after dte."""
     return centres(tcs).nextbizday(dte, nd)
 
 
-def centres(codes: str | None = None) -> TradingCentres:
+def centres(
+    codes: Annotated[
+        str | None, Doc("Comma-separated trading centre codes, e.g. 'LON,NY'")
+    ] = None,
+) -> TradingCentres:
+    """Return a [TradingCentres][ccy.tradingcentres.TradingCentres] instance
+    for the given centre codes."""
     tcs = TradingCentres()
     if codes:
         lcs = codes.upper().replace(" ", "").split(",")
@@ -31,32 +52,44 @@ def centres(codes: str | None = None) -> TradingCentres:
     return tcs
 
 
-@dataclass
-class TradingCentre:
-    code: str
-    calendar: holidays.HolidayBase
+class TradingCentre(BaseModel, arbitrary_types_allowed=True):
+    code: str = Field(description="The code of the trading centre")
+    calendar: holidays.HolidayBase = Field(
+        exclude=True,
+        description="The holiday calendar of the trading centre",
+    )
 
-    def isholiday(self, dte: date) -> bool:
+    def isholiday(self, dte: Annotated[date, Doc("The date to check")]) -> bool:
+        """Return True if the date is a holiday."""
         return dte in self.calendar
 
 
-@dataclass
-class TradingCentres:
-    centres: dict[str, TradingCentre] = field(default_factory=dict)
+class TradingCentres(BaseModel):
+    centres: dict[str, TradingCentre] = Field(default_factory=dict)
 
     @property
     def code(self) -> str:
+        """Comma-separated sorted codes of the trading centres."""
         return ",".join(sorted(self.centres))
 
-    def isbizday(self, dte: date) -> bool:
+    def isbizday(self, dte: Annotated[date, Doc("The date to check")]) -> bool:
+        """Return True if the date is a business day across all centres."""
         if dte.isoweekday() in isoweekend:
             return False
         for c in self.centres.values():
             if c.isholiday(dte):
                 return False
         return True
 
-    def nextbizday(self, dte: date, nd: int = 1) -> date:
+    def nextbizday(
+        self,
+        dte: Annotated[date, Doc("The reference date")],
+        nd: Annotated[
+            int,
+            Doc("Number of business days to move forward; 0 adjusts to next biz day"),
+        ] = 1,
+    ) -> date:
+        """Return the date nd business days after dte."""
         n = 0
         while not self.isbizday(dte):
             dte += oneday
@@ -66,7 +99,12 @@ def nextbizday(self, dte: date, nd: int = 1) -> date:
                 n += 1
         return dte
 
-    def prevbizday(self, dte: date, nd: int = 1) -> date:
+    def prevbizday(
+        self,
+        dte: Annotated[date, Doc("The reference date")],
+        nd: Annotated[int, Doc("Number of business days to move back")] = 1,
+    ) -> date:
+        """Return the date nd business days before dte."""
         n = 0
         if nd < 0:
             return self.nextbizday(dte, -nd)

docs/trading-centres.md

@@ -0,0 +1,85 @@
+# Trading Centres
+
+Trading centres provide business day calendars for financial date calculations.
+A [TradingCentre][ccy.tradingcentres.TradingCentre] wraps a single holiday calendar.
+[TradingCentres][ccy.tradingcentres.TradingCentres] combines multiple centres for joint business day calculations.
+
+!!! note "Installation"
+    This feature requires the `holidays` extra:
+    ```bash
+    pip install ccy[holidays]
+    ```
+
+## Available centres
+
+| Code | Description |
+|------|-------------|
+| `TGT` | TARGET (European Central Bank) |
+| `LON` | London (United Kingdom) |
+| `NY` | New York (United States) |
+
+## Functions
+
+::: ccy.tradingcentres.centres
+
+::: ccy.tradingcentres.nextbizday
+
+::: ccy.tradingcentres.prevbizday
+
+## Classes
+
+::: ccy.tradingcentres.TradingCentre
+
+::: ccy.tradingcentres.TradingCentres
+
+## Usage
+
+### Business day checks
+
+```python
+from datetime import date
+from ccy.tradingcentres import centres
+
+tcs = centres("TGT")
+tcs.isbizday(date(2024, 12, 25))  # False — Christmas
+tcs.isbizday(date(2024, 12, 24))  # True
+```
+
+Combine multiple centres — a day is a business day only if it is in all of them:
+
+```python
+tcs = centres("LON,NY")
+tcs.code  # "LON,NY"
+tcs.isbizday(date(2024, 7, 4))  # False — US Independence Day
+```
+
+### Next and previous business day
+
+```python
+from ccy.tradingcentres import nextbizday, prevbizday
+from datetime import date
+
+friday = date(2024, 12, 20)
+
+nextbizday(friday)        # date(2024, 12, 23) — skips weekend
+nextbizday(friday, nd=2)  # date(2024, 12, 24)
+
+prevbizday(friday)        # date(2024, 12, 19)
+prevbizday(friday, nd=3)  # date(2024, 12, 17)
+```
+
+Pass a centre code to apply its holiday calendar:
+
+```python
+nextbizday(date(2024, 12, 24), tcs="TGT")  # date(2024, 12, 27) — skips Christmas
+```
+
+### `nd=0` — adjust to business day
+
+Passing `nd=0` to `nextbizday` adjusts the date forward to the next business day if it falls on a weekend or holiday, and leaves it unchanged otherwise:
+
+```python
+saturday = date(2024, 12, 21)
+nextbizday(saturday, nd=0)  # date(2024, 12, 23)
+nextbizday(friday, nd=0)    # date(2024, 12, 20) — already a business day
+```

mkdocs.yml

@@ -27,12 +27,39 @@ theme:
     - navigation.path
     - content.code.copy
 
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_root_heading: true
+            show_if_no_docstring: true
+            inherited_members: true
+            members_order: source
+            separate_signature: true
+            unwrap_annotated: true
+            filters:
+              - "!^_[a-zA-Z0-9_]*"
+              - "!^model_post_init$"
+            merge_init_into_class: true
+            docstring_section_style: spacy
+            signature_crossrefs: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            extensions:
+              - griffe_typingdoc
+              - griffe_pydantic:
+                  schema: false
+
 markdown_extensions:
+  - admonition
   - pymdownx.highlight:
       anchor_linenums: true
   - pymdownx.superfences
 
 nav:
   - Home: index.md
   - Day Counters: daycounters.md
+  - Trading Centres: trading-centres.md
   - Dates & Periods: dates.md

pyproject.toml

@@ -9,6 +9,7 @@ requires-python = ">=3.11"
 dependencies = [
     "python-dateutil>=2.9.0",
     "pycountry>=24.6.1",
+    "pydantic>=2.0",
     "typing-extensions>=4.12",
 ]
 
@@ -35,8 +36,11 @@ dev = [
     "types-python-dateutil>=2.9.0.20241003",
 ]
 book = [
+    "griffe-pydantic>=1.0",
+    "griffe-typingdoc>=0.2",
     "mkdocs>=1.6",
     "mkdocs-material>=9.0",
+    "mkdocstrings[python]>=0.25",
 ]
 
 [build-system]

tests/test_dc.py

@@ -10,13 +10,14 @@ def test_alldc():
     assert len(DayCounter) == 5
 
 
-def test_getdb():
+def test_dcf():
     for dc in DayCounter:
         assert dc.value == str(dc)
         start = date.today()
-        assert dc.count(start, start + timedelta(days=1)) == 1
         assert dc.dcf(start, start + timedelta(days=1)) > 0
 
+
+def test_invalid_dc():
     with pytest.raises(ValueError):
         DayCounter("kaputt")