Usage Guide
===========

Basic Usage
----------

The AWS SSO Manager provides a simple interface for managing AWS SSO credentials. Here's how to use it:

1. Import the package:

   .. code-block:: python

      from aws_sso import AWSsso
      from pathlib import Path

2. Create an instance:

   .. code-block:: python

      sso = AWSsso(
          aws_exec_file_path=r'C:\Program Files\Amazon\AWSCLIV2\aws.exe',  # Adjust path for your system
          db_path=Path('./data/credentials.db'),
          refresh_window_hours=6
      )

3. Use the manager:

   .. code-block:: python

      # Ensure credentials are valid
      sso.ensure_valid_credentials()

      # Get expiration time
      expiration = sso.get_expiration_time()
      print(f"Credentials will expire at: {expiration}")

Advanced Usage
-------------

Custom Configuration
~~~~~~~~~~~~~~~~~~

You can customize the behavior with additional parameters:

.. code-block:: python

   sso = AWSsso(
       aws_exec_file_path=r'C:\Program Files\Amazon\AWSCLIV2\aws.exe',
       db_path=Path('./data/custom_credentials.db'),
       refresh_window_hours=12,  # Longer refresh window
       max_retries=5,           # More retries
       retry_delay=10           # Longer delay between retries
   )

Error Handling
~~~~~~~~~~~~~

Handle potential errors during authentication:

.. code-block:: python

   from aws_sso import AWSsso, AuthenticationError, CredentialError

   try:
       sso = AWSsso()
       sso.ensure_valid_credentials()
   except AuthenticationError as e:
       print(f"Authentication failed: {e}")
   except CredentialError as e:
       print(f"Credential error: {e}")

Context Manager
~~~~~~~~~~~~~

Use the context manager interface for automatic cleanup:

.. code-block:: python

   with AWSsso() as sso:
       sso.ensure_valid_credentials()
       # Work with AWS services...

Monitoring Credentials
~~~~~~~~~~~~~~~~~~~

Track credential status:

.. code-block:: python

   # Get last refresh time
   last_refresh = sso.get_last_refresh_time()
   if last_refresh:
       print(f"Last credential refresh: {last_refresh}")

   # Check if credentials need refresh
   if sso.should_refresh_credentials:
       print("Credentials need to be refreshed")
       sso.refresh_credentials()

Best Practices
-------------

1. **Path Management**: Use `Path` objects for file paths to ensure cross-platform compatibility
2. **Error Handling**: Always wrap credential operations in try-except blocks
3. **Logging**: Enable logging to track credential management:

   .. code-block:: python

      import logging
      logging.basicConfig(level=logging.INFO)

4. **Database Location**: Store the credentials database in a secure location
5. **Regular Checks**: Periodically check credential status in long-running applications

Common Issues
------------

AWS CLI Not Found
~~~~~~~~~~~~~~~

If you get a `FileNotFoundError`, ensure:
- AWS CLI is installed
- Correct path is provided to `aws_exec_file_path`
- AWS CLI is accessible from your environment

Authentication Failures
~~~~~~~~~~~~~~~~~~~~

If authentication fails:
- Check your AWS SSO configuration
- Verify your internet connection
- Ensure your AWS SSO session is active
- Check the AWS CLI configuration

Database Errors
~~~~~~~~~~~~~

If you encounter database errors:
- Ensure the database directory exists
- Check write permissions
- Verify the database path is valid