API Reference
============

This section provides detailed documentation for all public classes and functions in AWS SSO Manager.

AWSsso Class
-----------

The main class for managing AWS SSO credentials.

.. autoclass:: aws_sso.AWSsso
   :members:
   :undoc-members:
   :show-inheritance:
   :special-members: __init__, __enter__, __exit__

Key Methods
~~~~~~~~~~

- ``__init__(aws_exec_file_path, db_path, refresh_window_hours=6, max_retries=3, retry_delay=5)``: Initialize the AWS SSO manager
- ``ensure_valid_credentials()``: Check and refresh credentials if needed
- ``get_expiration_time()``: Get the expiration time of current credentials
- ``get_last_refresh_time()``: Get the timestamp of the last credential refresh
- ``refresh_credentials()``: Force a credential refresh
- ``should_refresh_credentials()``: Check if credentials need refreshing

Example Usage
~~~~~~~~~~~

.. code-block:: python

    from aws_sso import AWSsso
    from pathlib import Path

    # Initialize with custom settings
    sso = AWSsso(
        aws_exec_file_path='/usr/local/bin/aws',  # Adjust for your system
        db_path=Path('./credentials.db'),
        refresh_window_hours=12,
        max_retries=5,
        retry_delay=10
    )

    # Use as context manager
    with sso:
        sso.ensure_valid_credentials()
        if sso.should_refresh_credentials():
            sso.refresh_credentials()

Exceptions
---------

Custom exceptions for error handling.

AuthenticationError
~~~~~~~~~~~~~~~~

.. autoexception:: aws_sso.exceptions.AuthenticationError
   :members:
   :show-inheritance:

Raised when AWS SSO authentication fails. Common causes:
   - Invalid AWS SSO configuration
   - Network connectivity issues
   - Expired SSO session

Example handling:

.. code-block:: python

    try:
        sso.ensure_valid_credentials()
    except AuthenticationError as e:
        print(f"Authentication failed: {e}")
        # Handle authentication failure

CredentialError
~~~~~~~~~~~~~

.. autoexception:: aws_sso.exceptions.CredentialError
   :members:
   :show-inheritance:

Raised for credential-related issues. Common causes:
   - Database access errors
   - Invalid credential format
   - File permission issues

Example handling:

.. code-block:: python

    try:
        expiration = sso.get_expiration_time()
    except CredentialError as e:
        print(f"Credential error: {e}")
        # Handle credential error