Examples
========

Comprehensive examples demonstrating various use cases of the xfinance Python SDK.

Basic Compound Interest
-----------------------

.. code-block:: python

   from xfinance_sdk import XFinanceClient
   from xfinance_sdk.models.request import CompoundInterestRequest
   from decimal import Decimal

   client = XFinanceClient(api_key="your-api-key")

   # Calculate with different compounding frequencies
   frequencies = {
       "Annual": 1,
       "Semi-Annual": 2,
       "Quarterly": 4,
       "Monthly": 12,
       "Daily": 365
   }

   for name, freq in frequencies.items():
       request = CompoundInterestRequest(
           principal=Decimal("10000"),
           annual_rate=Decimal("0.05"),
           years=10,
           compounding_frequency=freq
       )
       response = client.calculate_compound_interest(request)
       print(f"{name}: ${response.final_amount:,.2f}")

Mortgage Calculator
-------------------

.. code-block:: python

   from xfinance_sdk.models.request import LoanCalculationRequest

   def calculate_mortgage(loan_amount, interest_rate, years):
       request = LoanCalculationRequest(
           loan_amount=Decimal(str(loan_amount)),
           annual_rate=Decimal(str(interest_rate)),
           term_years=years
       )
       return client.calculate_loan_payment(request)

   # 30-year fixed mortgage
   response = calculate_mortgage(300000, 0.04, 30)
   print(f"30-year ${300000:,.0f} at 4%: ${response.monthly_payment:,.2f}/month")

   # 15-year fixed mortgage
   response = calculate_mortgage(300000, 0.035, 15)
   print(f"15-year ${300000:,.0f} at 3.5%: ${response.monthly_payment:,.2f}/month")

Retirement Planning
-------------------

.. code-block:: python

   from xfinance_sdk.models.request import InvestmentReturnsRequest

   def retirement_projections(initial, monthly, rate, years):
       request = InvestmentReturnsRequest(
           initial_investment=Decimal(str(initial)),
           monthly_contribution=Decimal(str(monthly)),
           expected_annual_return=Decimal(str(rate)),
           years=years
       )
       return client.calculate_investment_returns(request)

   # Conservative retirement plan
   response = retirement_projections(50000, 1000, 0.06, 30)
   print(f"Retirement fund: ${response.final_value:,.2f}")

   # Aggressive retirement plan
   response = retirement_projections(50000, 2000, 0.08, 25)
   print(f"Retirement fund: ${response.final_value:,.2f}")

Error Handling Example
----------------------

.. code-block:: python

   from xfinance_sdk.exceptions import (
       BadRequestError, UnauthorizedError, ValidationError
   )

   try:
       # This will fail validation (negative principal)
       request = CompoundInterestRequest(
           principal=Decimal("-10000"),
           annual_rate=Decimal("0.05"),
           years=10,
           compounding_frequency=12
       )
       response = client.calculate_compound_interest(request)
   except ValidationError as e:
       print(f"Validation error: {e}")
   except UnauthorizedError as e:
       print(f"Authentication error: {e}")
   except BadRequestError as e:
       print(f"API error: {e}")
   except Exception as e:
       print(f"Unexpected error: {e}")

Batch Processing
----------------

.. code-block:: python

   import asyncio
   from xfinance_sdk import AsyncXFinanceClient

   async def process_multiple_requests(requests):
       client = AsyncXFinanceClient(api_key="your-api-key")
       try:
           results = []
           for request in requests:
               response = await client.calculate_compound_interest(request)
               results.append(response.final_amount)
           return results
       finally:
           await client.close()

   # Create multiple requests
   requests = [
       CompoundInterestRequest(
           principal=Decimal("10000"),
           annual_rate=Decimal("0.05 + i * 0.01"),
           years=10,
           compounding_frequency=12
       ) for i in range(5)
   ]

   results = asyncio.run(process_multiple_requests(requests))
   for i, result in enumerate(results):
       print(f"Scenario {i+1}: ${result:,.2f}")