chore(deps): bump actions/download-artifact from 8.0.1 to 8.0.2

.github/workflows/publish.yml

@@ -125,7 +125,7 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
         with:
           name: verified-pypi-package
           path: ${{ runner.temp }}/release-artifact
@@ -168,7 +168,7 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
         with:
           name: verified-pypi-package
           path: ${{ runner.temp }}/release-artifact
@@ -227,7 +227,7 @@ jobs:
       contents: write
 
     steps:
-      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
         with:
           name: verified-pypi-package
           path: ${{ runner.temp }}/release-artifact

examples/visualization_demo.py

@@ -13,6 +13,7 @@
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
 from oilpriceapi import OilPriceAPI
+from oilpriceapi.visualization import HAS_MATPLOTLIB
 
 # Configuration
 API_KEY = os.getenv("OILPRICEAPI_KEY")
@@ -30,8 +31,8 @@ def demo_price_series():
 
     client = OilPriceAPI(api_key=API_KEY, base_url=BASE_URL)
 
-    if not client.viz:
-        print("⚠️  Matplotlib not installed. Install with: pip install matplotlib")
+    if not HAS_MATPLOTLIB:
+        print("⚠️  Matplotlib not installed. Install with: pip install 'oilpriceapi[viz]'")
         return
 
     # Create visualization
@@ -76,7 +77,7 @@ def demo_spread_analysis():
 
     client = OilPriceAPI(api_key=API_KEY, base_url=BASE_URL)
 
-    if not client.viz:
+    if not HAS_MATPLOTLIB:
         print("⚠️  Visualization not available")
         return
 
@@ -112,7 +113,7 @@ def demo_sparklines():
 
     client = OilPriceAPI(api_key=API_KEY, base_url=BASE_URL)
 
-    if not client.viz:
+    if not HAS_MATPLOTLIB:
         print("⚠️  Visualization not available")
         return
 
@@ -146,7 +147,7 @@ def demo_small_multiples():
 
     client = OilPriceAPI(api_key=API_KEY, base_url=BASE_URL)
 
-    if not client.viz:
+    if not HAS_MATPLOTLIB:
         print("⚠️  Visualization not available")
         return
 
@@ -191,7 +192,7 @@ def main():
         print(f"\n✅ Matplotlib version: {matplotlib.__version__}")
     except ImportError:
         print("\n⚠️  Matplotlib not installed!")
-        print("   Install with: pip install matplotlib")
+        print("   Install with: pip install 'oilpriceapi[viz]'")
         return
 
     # Run demos

oilpriceapi/client.py

@@ -221,20 +221,29 @@ def __init__(
         # LTL + parcel carrier fuel surcharges (#101).
         self.fuel_surcharge = FuelSurchargeResource(self)
 
-        # Initialize visualization (optional)
-        self.viz: Optional["PriceVisualizer"]
-        try:
-            from .visualization import PriceVisualizer
-
-            self.viz = PriceVisualizer(self)
-        except ImportError:
-            self.viz = None
+        # Visualization is optional and built on first use of ``viz`` (#151):
+        # constructing a client must not import matplotlib or warn about it.
+        self._viz: Optional["PriceVisualizer"] = None
 
         # Initialize telemetry (opt-in, disabled by default)
         from .telemetry import Telemetry
 
         self._telemetry = Telemetry(enabled=enable_telemetry)
 
+    @property
+    def viz(self) -> "PriceVisualizer":
+        """Tufte-style charts, built on first access.
+
+        Building the visualizer imports nothing optional and never warns. If
+        matplotlib is missing, each plotting method raises ``ImportError``
+        naming the extra: ``pip install 'oilpriceapi[viz]'``.
+        """
+        if self._viz is None:
+            from .visualization import PriceVisualizer
+
+            self._viz = PriceVisualizer(self)
+        return self._viz
+
     def request(
         self,
         method: str,