.. AWS SSO Manager documentation master file, created by
   sphinx-quickstart on Mon Jun 23 14:18:46 2025.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to AWS SSO Manager!
==========================

AWS SSO Manager is a Python package that simplifies AWS SSO (Single Sign-On) authentication and credential management. It's designed to make working with AWS SSO seamless by automating credential refresh, tracking validity, and providing a clean interface for AWS SSO operations.

Why AWS SSO Manager?
------------------

* **Automated Credential Management**: Never worry about expired credentials again
* **Simple Integration**: Easy to integrate with existing Python applications
* **Robust Error Handling**: Built-in retry mechanisms and clear error messages
* **Cross-Platform Support**: Works on Windows, macOS, and Linux
* **Production Ready**: Includes logging, monitoring, and best practices

Features
--------

* Automatic AWS SSO credential refresh
* Credential validity tracking and monitoring
* SQLite-based credential timestamp storage
* Configurable refresh windows and retry mechanisms
* Context manager support for automatic cleanup
* Comprehensive logging and error handling

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   installation
   usage
   api
   contributing

Quick Start
----------

Here's a complete example to get you started:

.. code-block:: python

   from aws_sso import AWSsso
   from pathlib import Path
   import logging

   # Enable logging (optional but recommended)
   logging.basicConfig(level=logging.INFO)

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

   try:
       # Use as a context manager for automatic cleanup
       with sso:
           # Ensure credentials are valid (will refresh if needed)
           sso.ensure_valid_credentials()

           # Get credential information
           expiration = sso.get_expiration_time()
           last_refresh = sso.get_last_refresh_time()

           print(f"Credentials will expire at: {expiration}")
           print(f"Last refresh time: {last_refresh}")

           # Your AWS operations here...

   except Exception as e:
       print(f"Error: {e}")

Getting Started
-------------

1. :doc:`installation` - Install and configure AWS SSO Manager
2. :doc:`usage` - Learn how to use AWS SSO Manager effectively
3. :doc:`api` - Detailed API reference
4. :doc:`contributing` - Contribute to AWS SSO Manager

Need Help?
---------

If you encounter any issues or have questions:

* Check the :doc:`usage` guide for common solutions
* Review the :doc:`api` documentation for detailed information
* File an issue on our GitHub repository

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`