vnai 2.0.3__py3-none-any.whl → 2.0.4__py3-none-any.whl

vnai/scope/promo.py

@@ -1,3 +1,7 @@
+"""
+Promo module for vnai: fetches and presents promotional content periodically or on demand,
+using logging instead of printing to avoid polluting stdout for AI tools.
+"""
 import logging
 import requests
 from datetime import datetime
@@ -6,18 +10,29 @@ import threading
 import time
 import urllib.parse
 
+# Module-level logger setup
 logger = logging.getLogger(__name__)
 if not logger.hasHandlers():
+    # Add a simple stream handler that only outputs the message text
     handler = logging.StreamHandler()
     handler.setFormatter(logging.Formatter('%(message)s'))
     logger.addHandler(handler)
     logger.setLevel(logging.INFO)
 
 class ContentManager:
+    """
+    Singleton manager to fetch remote or fallback promotional content and
+    present it in different environments (Jupyter, terminal, other).
+
+    Displays content automatically at randomized intervals via a background thread.
+    """
     _instance = None
     _lock = threading.Lock()
 
     def __new__(cls):
+        """
+        Ensure only one instance of ContentManager is created (thread-safe).
+        """
         with cls._lock:
             if cls._instance is None:
                 cls._instance = super(ContentManager, cls).__new__(cls)
@@ -25,27 +40,36 @@ class ContentManager:
             return cls._instance
 
     def _initialize(self):
+        """
+        Internal initializer: sets up display timing, URLs, and starts the periodic display thread.
+        """
+        # Timestamp of last content display (epoch seconds)
         self.last_display = 0
+        # Minimum interval between displays (24 hours)
         self.display_interval = 24 * 3600
 
-        self.content_base_url = (
-            "https://vnstock-beam.hf.space/content-delivery"
-        )
-        self.target_url = (
-            "https://vnstocks.com/lp-khoa-hoc-python-chung-khoan"
-        )
+        # Base endpoints for fetching remote content and linking
+        self.content_base_url = "https://vnstock-beam.hf.space/content-delivery"
+        self.target_url = "https://vnstocks.com/lp-khoa-hoc-python-chung-khoan"
         self.image_url = (
             "https://vnstocks.com/img/trang-chu-vnstock-python-api-phan-tich-giao-dich-chung-khoan.jpg"
         )
 
+        # Launch the background thread to periodically present content
         self._start_periodic_display()
 
     def _start_periodic_display(self):
+        """
+        Launch a daemon thread that sleeps a random duration between 2–6 hours,
+        then checks if the display interval has elapsed and calls present_content.
+        """
         def periodic_display():
             while True:
+                # Randomize sleep to avoid synchronized requests across instances
                 sleep_time = random.randint(2 * 3600, 6 * 3600)
                 time.sleep(sleep_time)
 
+                # Present content if enough time has passed since last_display
                 current_time = time.time()
                 if current_time - self.last_display >= self.display_interval:
                     self.present_content(context="periodic")
@@ -53,66 +77,87 @@ class ContentManager:
         thread = threading.Thread(target=periodic_display, daemon=True)
         thread.start()
 
-    def fetch_remote_content(self, context="init", html=True):
+    def fetch_remote_content(self, context: str = "init", html: bool = True) -> str:
+        """
+        Fetch promotional content from remote service with context and format flag.
+
+        Args:
+            context: usage context (e.g., "init", "periodic", "loop").
+            html: if True, request HTML; otherwise plain text.
+
+        Returns:
+            The content string on HTTP 200, or None on failure.
+        """
         try:
+            # Build query params and URL
             params = {"context": context, "html": "true" if html else "false"}
             url = f"{self.content_base_url}?{urllib.parse.urlencode(params)}"
 
             response = requests.get(url, timeout=3)
             if response.status_code == 200:
                 return response.text
+            # Log non-200 responses at debug level
             logger.debug(f"Non-200 response fetching content: {response.status_code}")
             return None
         except Exception as e:
+            # Log exceptions without interrupting user code
             logger.debug(f"Failed to fetch remote content: {e}")
             return None
 
-    def present_content(self, environment=None, context="init"):
+    def present_content(self, environment: str = None, context: str = "init") -> None:
+        """
+        Present content according to the detected environment:
+        - In Jupyter: use display(HTML or Markdown).
+        - In terminal or other: log via logger.info().
+
+        Args:
+            environment: override detected environment ("jupyter", "terminal", else).
+            context: same context flag passed to fetch_remote_content and fallback logic.
+        """
+        # Update last display timestamp
         self.last_display = time.time()
 
+        # Auto-detect environment if not provided
         if environment is None:
             try:
                 from vnai.scope.profile import inspector
-
-                environment = (
-                    inspector.examine().get("environment", "unknown")
-                )
+                environment = inspector.examine().get("environment", "unknown")
             except Exception:
                 environment = "unknown"
 
-        if environment == "jupyter":
-            remote_content = self.fetch_remote_content(
-                context=context, html=True
-            )
-        else:
-            remote_content = self.fetch_remote_content(
-                context=context, html=False
-            )
-
-        fallback_content = self._generate_fallback_content(context)
+        # Retrieve remote or HTML/text content based on environment
+        remote_content = self.fetch_remote_content(
+            context=context, html=(environment == "jupyter")
+        )
+        # Generate fallback messages if remote fetch fails
+        fallback = self._generate_fallback_content(context)
 
         if environment == "jupyter":
+            # Rich display in Jupyter notebooks
             try:
                 from IPython.display import display, HTML, Markdown
 
                 if remote_content:
                     display(HTML(remote_content))
                 else:
+                    # Try Markdown, fallback to HTML
                     try:
-                        display(Markdown(fallback_content["markdown"]))
+                        display(Markdown(fallback["markdown"]))
                     except Exception:
-                        display(HTML(fallback_content["html"]))
+                        display(HTML(fallback["html"]))
             except Exception as e:
                 logger.debug(f"Jupyter display failed: {e}")
 
         elif environment == "terminal":
+            # Log terminal-friendly or raw content via logger
             if remote_content:
                 logger.info(remote_content)
             else:
-                logger.info(fallback_content["terminal"])
+                logger.info(fallback["terminal"])
 
         else:
-            logger.info(fallback_content["simple"])
+            # Generic simple message for other environments
+            logger.info(fallback["simple"])
 
     def _generate_fallback_content(self, context):
         fallback = {"html": "", "markdown": "", "terminal": "", "simple": ""}
@@ -211,8 +256,15 @@ Khám phá các tính năng mới nhất và tham gia cộng đồng để nhậ
             )
         return fallback
 
-# Singleton instance
+# Singleton instance for module-level use
 manager = ContentManager()
 
-def present(context="init"):  # module-level shortcut
+
+def present(context: str = "init") -> None:
+    """
+    Shortcut to ContentManager.present_content for external callers.
+
+    Args:
+        context: propagate context string to ContentManager.
+    """
     return manager.present_content(context=context)

vnai/scope/state.py

@@ -1,7 +1,5 @@
-##
-
-##
-
+# vnai/scope/state.py
+# System state tracking
 
 import time
 import threading
@@ -11,7 +9,7 @@ from datetime import datetime
 from pathlib import Path
 
 class Tracker:
-    #--
+    """Tracks system state and performance metrics"""
     
     _instance = None
     _lock = threading.Lock()
@@ -24,7 +22,7 @@ class Tracker:
             return cls._instance
     
     def _initialize(self):
-        #--
+        """Initialize tracker"""
         self.metrics = {
             "startup_time": datetime.now().isoformat(),
             "function_calls": 0,
@@ -41,8 +39,7 @@ class Tracker:
         
         self.privacy_level = "standard"
         
-        ##
-
+        # Setup data directory
         self.home_dir = Path.home()
         self.project_dir = self.home_dir / ".vnstock"
         self.project_dir.mkdir(exist_ok=True)
@@ -51,31 +48,26 @@ class Tracker:
         self.metrics_path = self.data_dir / "usage_metrics.json"
         self.privacy_config_path = self.project_dir / 'config' / "privacy.json"
         
-        ##
-
+        # Create config directory if it doesn't exist
         os.makedirs(os.path.dirname(self.privacy_config_path), exist_ok=True)
         
-        ##
-
+        # Load existing metrics
         self._load_metrics()
         
-        ##
-
+        # Load privacy settings
         self._load_privacy_settings()
         
-        ##
-
+        # Start background metrics collector
         self._start_background_collector()
     
     def _load_metrics(self):
-        #--
+        """Load metrics from file"""
         if self.metrics_path.exists():
             try:
                 with open(self.metrics_path, 'r') as f:
                     stored_metrics = json.load(f)
                     
-                ##
-
+                # Update metrics with stored values
                 for key, value in stored_metrics.items():
                     if key in self.metrics:
                         self.metrics[key] = value
@@ -83,7 +75,7 @@ class Tracker:
                 pass
     
     def _save_metrics(self):
-        #--
+        """Save metrics to file"""
         try:
             with open(self.metrics_path, 'w') as f:
                 json.dump(self.metrics, f)
@@ -91,7 +83,7 @@ class Tracker:
             pass
     
     def _load_privacy_settings(self):
-        #--
+        """Load privacy settings"""
         if self.privacy_config_path.exists():
             try:
                 with open(self.privacy_config_path, 'r') as f:
@@ -101,7 +93,7 @@ class Tracker:
                 pass
     
     def setup_privacy(self, level=None):
-        #--
+        """Configure privacy level for data collection"""
         privacy_levels = {
             "minimal": "Essential system data only",
             "standard": "Performance metrics and errors",
@@ -109,107 +101,90 @@ class Tracker:
         }
         
         if level is None:
-            ##
-
+            # Default level
             level = "standard"
         
         if level not in privacy_levels:
             raise ValueError(f"Invalid privacy level: {level}. Choose from {', '.join(privacy_levels.keys())}")
         
-        ##
-
+        # Store preference
         self.privacy_level = level
         
-        ##
-
+        # Store in configuration file
         with open(self.privacy_config_path, "w") as f:
             json.dump({"level": level}, f)
         
         return level
     
     def get_privacy_level(self):
-        #--
+        """Get current privacy level"""
         return self.privacy_level
     
     def _start_background_collector(self):
-        #--
+        """Start background metrics collection"""
         def collect_metrics():
             while True:
                 try:
                     import psutil
                     
-                    ##
-
+                    # Update peak memory
                     current_process = psutil.Process()
                     memory_info = current_process.memory_info()
-                    memory_usage = memory_info.rss / (1024 * 1024)  ##
-
+                    memory_usage = memory_info.rss / (1024 * 1024)  # MB
                     
                     if memory_usage > self.performance_metrics["peak_memory"]:
                         self.performance_metrics["peak_memory"] = memory_usage
                         
-                    ##
-
+                    # Save metrics periodically
                     self._save_metrics()
                     
                 except:
                     pass
                     
-                time.sleep(300)  ##
-
+                time.sleep(300)  # Run every 5 minutes
         
-        ##
-
+        # Start thread
         thread = threading.Thread(target=collect_metrics, daemon=True)
         thread.start()
     
     def record(self, event_type, data=None):
-        #--
-        ##
-
+        """Record an event"""
+        # Check privacy level
         if self.privacy_level == "minimal" and event_type != "errors":
-            ##
-
+            # In minimal mode, only track errors
             return True
             
-        ##
-
+        # Update counts
         if event_type in self.metrics:
             self.metrics[event_type] += 1
         else:
             self.metrics[event_type] = 1
             
-        ##
-
+        # Special handling for errors
         if event_type == "errors":
             self.performance_metrics["last_error_time"] = datetime.now().isoformat()
             
-        ##
-
+        # Special handling for function calls with timing data
         if event_type == "function_calls" and data and "execution_time" in data:
-            ##
-
+            # Keep up to 100 latest execution times
             self.performance_metrics["execution_times"].append(data["execution_time"])
             if len(self.performance_metrics["execution_times"]) > 100:
                 self.performance_metrics["execution_times"] = self.performance_metrics["execution_times"][-100:]
                 
-        ##
-
+        # Save if metrics change significantly
         if self.metrics["function_calls"] % 100 == 0 or event_type == "errors":
             self._save_metrics()
             
         return True
     
     def get_metrics(self):
-        #--
-        ##
-
+        """Get current metrics"""
+        # Calculate derived metrics
         avg_execution_time = 0
         if self.performance_metrics["execution_times"]:
             avg_execution_time = sum(self.performance_metrics["execution_times"]) / len(self.performance_metrics["execution_times"])
             
-        ##
-
+        # Add derived metrics to output
         output = self.metrics.copy()
         output.update({
             "avg_execution_time": avg_execution_time,
@@ -221,7 +196,7 @@ class Tracker:
         return output
     
     def reset(self):
-        #--
+        """Reset metrics"""
         self.metrics = {
             "startup_time": datetime.now().isoformat(),
             "function_calls": 0,
@@ -239,11 +214,10 @@ class Tracker:
         self._save_metrics()
         return True
 
-##
-
+# Create singleton instance
 tracker = Tracker()
 
 
 def record(event_type, data=None):
-    #--
+    """Record an event"""
     return tracker.record(event_type, data)

{vnai-2.0.3.dist-info → vnai-2.0.4.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: vnai
-Version: 2.0.3
+Version: 2.0.4
 Summary: System optimization and resource management toolkit
-Home-page: https://github.com/yourusername/vnai
-Author: Your Name
-Author-email: your.email@example.com
+Home-page: https://github.com/vnstock-hq/initialization/new/main
+Author: Vnstock HQ
+Author-email: support@vnstocks.com
 License: MIT
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
@@ -17,7 +17,6 @@ Requires-Dist: requests>=2.25.0
 Requires-Dist: psutil>=5.8.0
 Provides-Extra: dev
 Requires-Dist: pytest>=6.0.0; extra == "dev"
-Requires-Dist: black>=21.5b2; extra == "dev"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

vnai-2.0.4.dist-info/RECORD

@@ -0,0 +1,16 @@
+vnai/__init__.py,sha256=ClnS_1T23BjbzejrIW4KTsAVBhXuq9bjDUcRP5AIcPo,9082
+vnai/beam/__init__.py,sha256=xKb_iu9aAPXCulI7dENrvqVIhelSD1mIqKE9Go3GAHw,200
+vnai/beam/metrics.py,sha256=xVmVw93yhKeWzRZJurmrD9mWur16HyLJl_p1XqMwW_w,7187
+vnai/beam/pulse.py,sha256=jp1YwjLaMhne2nYhM5PofveDsdrSp2YtewQ2jjE78Is,3470
+vnai/beam/quota.py,sha256=yP5_Z62QJwOoCEgqqWuNkzm1Dar70UiJsu6W27LNqiw,21218
+vnai/flow/__init__.py,sha256=K3OeabzAWGrdPgTAOlDqrJh2y9aQW2pgLZg8tblN3ho,147
+vnai/flow/queue.py,sha256=b9YKUbiXDZRC3fVgEnA77EO0EMXAi8eCoBkHnAUI5Sc,4162
+vnai/flow/relay.py,sha256=RtIPRZ3BlQd-XgTbisJg0iC1HqikAjHGyyo8aTj_fUw,15766
+vnai/scope/__init__.py,sha256=overJZ_UiEfBRNcSieE1GPU_9X3oS4C5l6JeBaFFVxk,267
+vnai/scope/profile.py,sha256=6LL7Djke9F1HVA9eEExud2jZ5yGUfy9_NYt68nIj2-8,30737
+vnai/scope/promo.py,sha256=N4aWZdh92rVNovjCwuUjv-QdhoRwloPAn4Hydx4IcRs,12515
+vnai/scope/state.py,sha256=LlcZNKBy2mcAnD765BO2Tlv3Zzbak2TOEz4RUPMCFZ8,7490
+vnai-2.0.4.dist-info/METADATA,sha256=rgGwwXBeevv4rjzJ-hLADRkGnPcuTaC3rMnSgd_WMRw,988
+vnai-2.0.4.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
+vnai-2.0.4.dist-info/top_level.txt,sha256=4zI0qZHePCwvgSqXl4420sBcd0VzZn4MEcRsAIFae3k,5
+vnai-2.0.4.dist-info/RECORD,,

vnai-2.0.3.dist-info/RECORD

@@ -1,16 +0,0 @@
-vnai/__init__.py,sha256=SF3HcEadrvSmtotBCy8a6637UwTFiSAaAN0Azi0X4qg,7219
-vnai/beam/__init__.py,sha256=h19ZEQFnWTvqed0mpTcuQf-sT9XifWhfVbaobTEs91Q,131
-vnai/beam/metrics.py,sha256=lNYEeav5kMm8SGnlsxwz6aD3fRzOytopHhUPkUx9Avs,5950
-vnai/beam/pulse.py,sha256=-rN4tbcgNKmA74P2ThVkQqxabG0-UlhfRbFCyYPvKFw,2920
-vnai/beam/quota.py,sha256=DRlqZpztppdFDJymuJS6VCKLHZrkI_PX8cUtStHDSFM,16934
-vnai/flow/__init__.py,sha256=VW6R7c30M4q8PhOUqXyHwWlmk1BwPrYvcxtLFI0fWJo,91
-vnai/flow/queue.py,sha256=0R6LjF6PSUz37JV2SnsOQMBHps3bG5c0BGfEOUIPhcA,3650
-vnai/flow/relay.py,sha256=wIRojuZKQ5Jk1N-p2PkA9fkx-F7kwgVu0JIc0Iya5aw,13783
-vnai/scope/__init__.py,sha256=yB0qWMlKd2ix5tFlBcRPX6SYR1O8Di0mwgQC15u8l2o,207
-vnai/scope/profile.py,sha256=tIy39_FpcNKZCg3Dy5mgy0jdLQCH2FK2nfvUlTM72wM,26781
-vnai/scope/promo.py,sha256=NlKcyadl6BlOr2TMlKkdri4dkm8xIoI_3Z05ErcVnGo,9930
-vnai/scope/state.py,sha256=XUhuXNx1W6pce5vRY3IkSrR__MGetRo8lQt1bQIAOLM,6550
-vnai-2.0.3.dist-info/METADATA,sha256=IlnWkYA8m9Rxjyfu7JCgpwJw0C7ldherJqhQnAdRrug,1017
-vnai-2.0.3.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
-vnai-2.0.3.dist-info/top_level.txt,sha256=4zI0qZHePCwvgSqXl4420sBcd0VzZn4MEcRsAIFae3k,5
-vnai-2.0.3.dist-info/RECORD,,