From ba37d805a3c5c2f2e88fdbf6bf1971475a64494e Mon Sep 17 00:00:00 2001
From: "Mr. Python" <2789762371@qq.com>
Date: Mon, 7 Oct 2024 22:14:34 +0800
Subject: [PATCH] Format, write notes and add type hints for sequence.py

---
 .pylintrc          |  2 +-
 cyaron/sequence.py | 74 +++++++++++++++++++++++++++++++++++-----------
 2 files changed, 58 insertions(+), 18 deletions(-)

diff --git a/.pylintrc b/.pylintrc
index 71a41c0..de2c0b1 100644
--- a/.pylintrc
+++ b/.pylintrc
@@ -1,3 +1,3 @@
 [MASTER]
 py-version=3.5
-disable=R0902,R0913,R0917,R0912
\ No newline at end of file
+disable=R0902,R0903,R0913,R0917,R0912
\ No newline at end of file
diff --git a/cyaron/sequence.py b/cyaron/sequence.py
index 625456e..f1df388 100644
--- a/cyaron/sequence.py
+++ b/cyaron/sequence.py
@@ -1,33 +1,73 @@
-from .utils import *
+"""
+This module provides a `Sequence` class for generating sequences
+based on a given formula and initial values.
+
+Classes:
+    Sequence: A class for creating and managing sequences.
+"""
+
+from typing import Callable, Dict, List, Optional, Tuple, TypeVar, Union
+from typing import cast as typecast
+
+from .utils import list_like
+
+T = TypeVar('T')
+
 
 class Sequence:
-    """Class Sequence: the tool class for sequences.
-    """
+    """A class for creating and managing sequences."""
 
-    def __init__(self, formula, initial_values=()):
-        """__init__(self, formula, initial_values=() -> None
-            Create a sequence object.
-            int formula(int, function) -> the formula function ...
+    def __init__(self,
+                 formula: Callable[[int, Callable[[int], T]], T],
+                 initial_values: Optional[Union[List[T], Tuple[T, ...],
+                                                Dict[int, T]]] = ()):
+        """
+        Initialize a sequence object.
+        Parameters:
+            formula: A function that defines the formula for the sequence.
+            initial_values (optional): Initial values for the sequence. 
+                Can be a list, tuple, or dictionary. Defaults to an empty tuple.
         """
         if not callable(formula):
-            raise Exception("formula must be a function")
+            raise TypeError("formula must be a function")
         self.formula = formula
         if list_like(initial_values):
-            self.values = dict(enumerate(initial_values))
+            self.values = dict(
+                enumerate(
+                    typecast(Union[List[T], Tuple[T, ...]], initial_values)))
         elif isinstance(initial_values, dict):
             self.values = initial_values
         else:
-            raise Exception("Initial_values must be either a list/tuple or a dict.")
+            raise TypeError(
+                "Initial_values must be either a list/tuple or a dict.")
 
-    def __get_one(self, i):
+    def get_one(self, i: int):
+        """
+        Retrieve the value at the specified index, computing it if necessary.
+        Args:
+            i (int): The index of the value to retrieve.
+        Returns:
+            The value at the specified index.
+        If the value at the specified index is not already computed, it will be
+        calculated using the provided formula and stored for future access.
+        """
         if i in self.values:
             return self.values[i]
-
-        self.values[i] = self.formula(i, self.__get_one)
+        self.values[i] = self.formula(i, self.get_one)
         return self.values[i]
 
-    def get(self, left_range, right_range=None):
+    def get(self, left_range: int, right_range: Optional[int] = None):
+        """
+        Retrieve a sequence of elements within the specified range.
+        If only `left_range` is provided, a single element is retrieved.
+        If both `left_range` and `right_range` are provided, a list of elements
+        from `left_range` to `right_range` (inclusive) is retrieved.
+        Args:
+            left_range: The starting index or the single index to retrieve.
+            right_range (optional): The ending index for the range retrieval. Defaults to None.
+        Returns:
+            A single element if `right_range` is None, otherwise a list of elements.
+        """
         if right_range is None:
-            return self.__get_one(left_range)
-
-        return [self.__get_one(i) for i in range(left_range, right_range+1)]
+            return self.get_one(left_range)
+        return [self.get_one(i) for i in range(left_range, right_range + 1)]