Squashed 'utils_v2/' content from commit 76554fba

git-subtree-dir: utils_v2
git-subtree-split: 76554fbaab5e1629c9d1918d8dcf3187d3dd4866

nse/models/ipo.py

@@ -0,0 +1,208 @@
+"""
+
+    AUTHOR:
+
+        Khushal P Soonderji
+
+    DATE:
+
+        Thursday, 9th Jan., 2025.
+
+    OBJECTIVE:
+
+        To provide data models for NSE's calendar events.
+
+    REFERENCES:
+
+        N/A
+
+    DOWNLOADS:
+
+        N/A
+
+"""
+
+
+#   *****************************************************************************************************************
+#  *****                                                                                                          ****
+# ***                                                   IMPORT                                                      ***
+#  *****                                                                                                          ****
+#   *****************************************************************************************************************
+
+
+# To make sibling directories accessible for imports:
+import sys
+sys.path.append(".")
+sys.path.append("..")
+
+# For making data behaviour_models:
+from pydantic import BaseModel, Field, field_validator, AwareDatetime, computed_field
+from typing import Optional, Literal, List
+
+# My utils:
+from utils_v2.string import regex
+from utils_v2.date_time import date_time
+
+# To work with date and time:
+import datetime
+
+
+#   *****************************************************************************************************************
+#  *****                                                                                                          ****
+# ***                                           MACROS / ONE-TIME INIT                                              ***
+#  *****                                                                                                          ****
+#   *****************************************************************************************************************
+
+
+# --- Nothing Yet
+
+
+#   *****************************************************************************************************************
+#  *****                                                                                                          ****
+# ***                                                VARIABLES                                                      ***
+#  *****                                                                                                          ****
+#   *****************************************************************************************************************
+
+
+# --- Nothing Yet
+
+
+#   *****************************************************************************************************************
+#  *****                                                                                                          ****
+# ***                                                  FUNCTIONS                                                    ***
+#  *****                                                                                                          ****
+#   *****************************************************************************************************************
+
+
+class NSEIPO(BaseModel):
+
+    scrapeTs: AwareDatetime = Field(
+        description = "The time (UTC) at which this this data was scraped.",
+        frozen = True,
+        default_factory = lambda: date_time.get_current_utc_date_time(as_string = False)
+    )
+
+    issueStartTs: AwareDatetime = Field(
+        description = "The start date (UTC) of the issue.",
+        frozen = True
+    )
+
+    issueEndTs: AwareDatetime = Field(
+        description = "The end date (UTC) of the issue.",
+        frozen = True
+    )
+
+    listingTs: AwareDatetime | None = Field(
+        description = "The date when the company was listed on the exchange.",
+        frozen = True,
+        default = None
+    )
+
+    tz: str = Field(
+        description = "The timezone in which the dates have to be interpreted.",
+        frozen = True,
+        default = "Asia/Kolkata"
+    )
+
+    symbol: str = Field(
+        description = "The trading symbol of this listing.",
+        frozen = True
+    )
+
+    name: str = Field(
+        description = "The name of the parent company of this listing.",
+        frozen = True
+    )
+
+    status: Literal["Past", "Active", "Forthcoming"] | str = Field(
+        description = "Whether this IPO is active or has closed.",
+        frozen = True,
+        default = "Past"
+    )
+
+    kind: str | None = Field(
+        description = "The category under which this IPO falls.",
+        frozen = True,
+        default = None,
+        examples = ["SME", "EQ", "DEBT"]
+    )
+
+    upperBand: float | None = Field(
+        description = "The upper price of the price band.",
+        frozen = True,
+        default = None
+    )
+
+    lowerBand: float | None = Field(
+        description = "The lower price of the price band.",
+        frozen = True,
+        default = None
+    )
+
+    issuePrice: float | None = Field(
+        description = "The final price at which the shares were sold.",
+        frozen = True,
+        default = None
+    )
+
+    offerQty: int | None = Field(
+        description = "How many shares are being offered for sale by the parent.",
+        frozen = True,
+        default = None
+    )
+
+    bidQty: int | None = Field(
+        description = "How many shares investors are willing to buy.",
+        frozen = True,
+        default = None
+    )
+
+    bidFactor: float | None = Field(
+        description = "How many times over has the IPO been subscribed.",
+        frozen = True,
+        default = None
+    )
+
+    # ┏┓    ┏•
+    # ┃ ┏┓┏┓╋┓┏┓
+    # ┗┛┗┛┛┗┛┗┗┫
+    #          ┛
+
+    class Config:
+        extra = "ignore"
+
+    # ┏┓       ┏┓             ┓  ┏┓•  ┓ ┓
+    # ┣┫┓┏╋┏┓━━┃ ┏┓┏┳┓┏┓┓┏╋┏┓┏┫  ┣ ┓┏┓┃┏┫┏
+    # ┛┗┗┻┗┗┛  ┗┛┗┛┛┗┗┣┛┗┻┗┗ ┗┻  ┻ ┗┗ ┗┗┻┛
+    #                 ┛
+
+    pass
+
+    # ┓┏  ┓• ┓   •
+    # ┃┃┏┓┃┓┏┫┏┓╋┓┏┓┏┓┏
+    # ┗┛┗┻┗┗┗┻┗┻┗┗┗┛┛┗┛
+
+    @field_validator("scrapeTs", "issueStartTs", "issueEndTs", mode = "before")
+    def parse_date_time(cls, value):
+        if isinstance(value, datetime.datetime):
+            value = date_time.to_timezone(value, date_time.TIMEZONE_UTC)
+        return value
+
+    # ┏┓           ┏┓
+    # ┃ ┓┏┏╋┏┓┏┳┓  ┣ ┓┏┏┓┏┏
+    # ┗┛┗┻┛┗┗┛┛┗┗  ┻ ┗┻┛┗┗┛
+
+    def to_json(self) -> dict:
+        return self.model_dump()
+
+
+#   *****************************************************************************************************************
+#  *****                                                                                                          ****
+# ***                                               MAIN PROGRAM                                                    ***
+#  *****                                                                                                          ****
+#   *****************************************************************************************************************
+
+
+if __name__ == "__main__":
+
+    pass