Merge pull request #15 from hapytex/feature/get-index

indexing and slicing

Author: KommuSoft

.github/workflows/build.yml

@@ -12,18 +12,12 @@ jobs:
       - uses: psf/black@stable
         with:
           options: "--check"
-       pylint unit_of_time
   test:
     name: run tests
-    runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version:
-          - '3.9'
-          - '3.10'
-          - '3.11'
-          - '3.12'
-          - '3.13'
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
+    runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python
@@ -32,20 +26,15 @@ jobs:
         python-version: ${{ matrix.python-version }}
     - name: Run test
       run: |
-        pip install pytest-cov
-        pytest --junitxml=pytest.xml --cov-fail-under=100 --cov-report=term-missing:skip-covered --cov=unit_of_time timetest.py
+        pip install pytest-cov pytest-random-order
+        pytest --random-order --junitxml=pytest.xml --cov-fail-under=100 --cov-report=term-missing:skip-covered --cov=unit_of_time timetest.py
     - name: Coveralls
       uses: coverallsapp/github-action@v2
   build:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version:
-          - '3.9'
-          - '3.10'
-          - '3.11'
-          - '3.12'
-          - '3.13'
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
     steps:
     - name: checkout code
       uses: actions/checkout@v4

README.md

@@ -105,6 +105,55 @@ for dt in Quarter(date(1958, 3, 25)):
 
 we can also convert such collection to a list.
 
+### Subscripting
+
+The `Day`, `Week`, `Month, etc. classes have `.get_index_for_date(…)` and `.get_date_from_index(…)` methods, which allow to determine how many days, weeks, months, quarters and years are between `date.min` and the date given, and convert this back to a date. For example:
+
+```python3
+Week.get_index_for_date(date(1958, 3, 25))  # 102123
+Week.get_date_from_index(102123)  # date(1958, 3, 24)
+```
+
+so 1958-03-25 is the 102'123 week since 0001-01-01, and that week starts the 24<sup>th</sup> of March, 1958.
+
+We can also use the index to get a `TimUnit` with:
+
+```python3
+Week[102123]  # Week(date(1958, 3, 24))
+```
+
+moreover a week itself can be subscripted, for example:
+
+```python3
+Week(date(1958, 3, 24))[2]  # date(1958, 3, 26)
+```
+
+one can also slice to created an object that is a sliced "view" that generates `Week`s or `date`s in the week respectively. This view can then be sliced or indexed further. For example:
+
+```python3
+Week[102123:105341:2]
+```
+
+is a collection of `Week` objects between `1958-03-24` and `2019-11-25` each time with one week in between.
+
+
+The `Week` class itself is also iterable, for example:
+
+```python3
+for week in Week:
+    print(week)
+```
+
+will start enumerating over all weeks since 0001-01-01.
+
+A time unit also has a length: the number of time units that can be represented, so:
+
+```python3
+len(Week)  # 521722
+```
+
+means the software can represent 521'722 weeks from 0001-01-01 to 9999-12-26.
+
 ### Shifting units of time
 
 The units of time can also be shifted, for example:
@@ -181,7 +230,7 @@ class Decade(TimeunitKind):
 
 this might be useful if the formatting is more advanced than what Python's date formatter can handle.
 
-Furthermore, one implements the `.truncate(..)` class method to convert a date to the start of the date range, and the `_next(..)` which returns the first date for the next decade.
+Furthermore, one implements the `.truncate(…)` class method to convert a date to the start of the date range, and the `_next(…)` which returns the first date for the next decade.
 
 With these functions, we have registered a new time unit.
 

timetest.py

@@ -2,6 +2,7 @@
 from datetime import date, datetime, time, timedelta
 
 from unit_of_time import Year, Quarter, Month, Week, Day, TimeunitKind, Timeunit
+from itertools import islice
 
 
 class Decade(TimeunitKind):
@@ -19,26 +20,52 @@ def truncate(cls, dt):
         Returns:
                 date: The first day (January 1) of the decade in which `dt` falls.
         """
-        return date(10 * (dt.year // 10), 1, 1)
+        return date(max(10 * (dt.year // 10), 1), 1, 1)
+
+    @classmethod
+    def get_index_for_date(cls, dt):
+        """
+        Return the zero-based decade index for the given date.
+
+        Parameters:
+            dt (date or datetime): The date for which to compute the decade index.
+
+        Returns:
+            int: The decade index equal to the calendar year divided by 10 using integer division (year // 10).
+        """
+        return dt.year // 10
+
+    @classmethod
+    def get_date_from_index(cls, idx):
+        """
+        Return the start date (January 1) of the decade represented by the given index.
+
+        Parameters:
+            idx (int): Decade index; the corresponding year is 10 * idx.
+
+        Returns:
+            datetime.date: January 1 of the year 10 * idx.
+        """
+        return date(max(10 * idx, 1), 1, 1)
 
     @classmethod
     def last_day(cls, dt):
         """
-        Return the last day of the decade containing the given date.
+        Return the last date of the decade that contains the given date.
 
         Parameters:
-                dt (date or datetime): The date for which to determine the last day of its decade.
+            dt (date | datetime): Date or datetime within the target decade.
 
         Returns:
-                date: The last day of the decade as a date object.
+            date: The last day of that decade.
         """
         dt = cls.truncate(dt)
         return date(dt.year + 10, 1, 1) - timedelta(days=1)
 
 
 TIME_UNITS = [Decade, Year, Quarter, Month, Week, Day]
-START_DATE = date(1302, 7, 11)
-END_DATE = date(2019, 11, 25)
+START_DATE = date(902, 7, 11)
+END_DATE = date(1019, 11, 25)
 
 
 class TimeUnitTest(unittest.TestCase):
@@ -99,6 +126,17 @@ def test_to_int(self):
                     self.assertLess(tu, tu.next)
                     self.assertLessEqual(tu.previous, tu)
                     self.assertLessEqual(tu, tu.next)
+                    idx = kind.get_index_for_date(tu.dt)
+                    self.assertEqual(
+                        idx,
+                        kind.get_index_for_date(tu.next.dt) - 1,
+                    )
+                    self.assertEqual(tu.dt, kind.get_date_from_index(idx))
+                    self.assertEqual(tu, kind[idx])
+                    if dt == tu.first_date:
+                        for idx2, dt2 in enumerate(tu):
+                            self.assertEqual(idx, kind.get_index_for_date(dt2))
+                            self.assertEqual(dt2, tu[idx2])
                     self.assertGreater(tu, tu.previous)
                     self.assertGreater(tu.next, tu)
                     self.assertGreaterEqual(tu, tu.previous)
@@ -109,6 +147,8 @@ def test_to_int(self):
                     self.assertEqual(TimeunitKind.from_int(int(tu)), tu)
                     self.assertIn(dt, tu)
                     self.assertIn((dt, dt), tu)
+                    with self.assertRaises(TypeError):
+                        (dt, None) in tu
                     self.assertIn((tu.first_date, tu.last_date), tu)
                     with self.assertRaises(TypeError):
                         self.assertIn(1425, tu)
@@ -151,8 +191,16 @@ def test_to_int(self):
                     self.assertEqual(tu.previous.previous.previous, 3 << tu)
                     self.assertLess(tu.last_date, tu.next.first_date)
                     self.assertLess(tu.previous.last_date, tu.first_date)
-                    self.assertEqual((tu.next.first_date - tu.last_date), timedelta(days=1))
-                    self.assertEqual((tu.first_date - tu.previous.last_date), timedelta(days=1))
+                    self.assertEqual(
+                        (tu.next.first_date - tu.last_date), timedelta(days=1)
+                    )
+                    self.assertEqual(
+                        (tu.first_date - tu.previous.last_date), timedelta(days=1)
+                    )
+
+    def test_repr(self):
+        self.assertEqual("Week", repr(Week))
+        self.assertEqual("Week[102123:105341:]", repr(Week[102123:105341:]))
 
     def test_hierarchy(self):
         """
@@ -166,6 +214,7 @@ def test_hierarchy(self):
         """
         for i, superkind in enumerate(TIME_UNITS, 1):
             for kind in TIME_UNITS[i:]:
+                self.assertLess(superkind, kind)
                 for dt in self.date_range_yield():
                     with self.subTest(superkind=superkind, kind=kind, dt=dt):
                         stu = superkind(dt)
@@ -193,7 +242,10 @@ def test_kinds(self):
             self.assertEqual(kind, kind.kind_int)
             self.assertEqual(kind.kind_int, kind)
             self.assertEqual(d[kind], kind in seen)
+            self.assertEqual(kind.get_index_for_date(date.min), 0)
             d[kind] = True
+            self.assertEqual(list(kind[10:110:10][5:9:2]), list(kind[60:100:20]))
+            self.assertEqual(list(islice(kind, 3)), list(kind[:3]))
             self.assertNotIn(kind, seen)
             seen.add(kind)
             for kind2 in TIME_UNITS[i:]: