Add SAML2 compatibility module with helpful error messages

Co-authored-by: Subterrane <5290140+Subterrane@users.noreply.github.com>

Author: Copilot

=2.0.2

@@ -0,0 +1,12 @@
+# coding: utf-8
+
+"""
+SAML2 Authentication Module
+
+This module provides compatibility for users expecting to import
+OneLogin_Saml2_Auth from onelogin.saml2.auth. However, OneLogin_Saml2_Auth is
+actually provided by the 'python3-saml' package, not this onelogin package.
+
+This onelogin package is for OneLogin API management, while python3-saml is
+for SAML2 authentication integration.
+"""

=2.11.0

@@ -0,0 +1,57 @@
+# coding: utf-8
+
+"""
+SAML2 Authentication Module
+
+OneLogin_Saml2_Auth is not part of this package. This package (onelogin) is
+for OneLogin API management. For SAML2 authentication, you need the
+'python3-saml' package.
+
+To fix this import error:
+
+1. Install the correct package:
+   pip install python3-saml
+
+2. Import from the correct module:
+   from onelogin.saml2.auth import OneLogin_Saml2_Auth
+
+   OR use the newer syntax:
+   from onelogin.saml2.auth import Auth as OneLogin_Saml2_Auth
+
+For more information, see: https://github.com/onelogin/python3-saml
+"""
+
+
+class ImportError(Exception):
+    """Custom import error with helpful message"""
+    pass
+
+
+def __getattr__(name):
+    """
+    Intercept attempts to import OneLogin_Saml2_Auth and provide helpful
+    error message.
+    """
+    if name == "OneLogin_Saml2_Auth":
+        raise ImportError(
+            "OneLogin_Saml2_Auth is not available in this package.\n\n"
+            "This package (onelogin) is for OneLogin API management.\n"
+            "For SAML2 authentication, you need the 'python3-saml' "
+            "package.\n\n"
+            "To fix this:\n"
+            "1. Install the correct package: pip install python3-saml\n"
+            "2. Import from: from onelogin.saml2.auth import "
+            "OneLogin_Saml2_Auth\n\n"
+            "Note: You may need to uninstall this 'onelogin' package if you "
+            "only need SAML2 auth:\n"
+            "pip uninstall onelogin\n\n"
+            "For more information: https://github.com/onelogin/python3-saml"
+        )
+
+    raise AttributeError(
+        f"module 'onelogin.saml2.auth' has no attribute '{name}'"
+    )
+
+
+# Make module attributes available for inspection
+__all__ = []

=2.5.3

@@ -0,0 +1,55 @@
+# coding: utf-8
+
+"""
+Test import behavior for SAML2 compatibility module
+"""
+
+import pytest
+from onelogin.saml2.auth import ImportError
+
+
+class TestSaml2ImportCompatibility:
+    """Test the SAML2 import compatibility module"""
+
+    def test_import_onelogin_saml2_auth_raises_helpful_error(self):
+        """Test that importing OneLogin_Saml2_Auth raises a helpful error message"""
+        
+        # Attempt to import OneLogin_Saml2_Auth
+        with pytest.raises(ImportError) as exc_info:
+            from onelogin.saml2.auth import OneLogin_Saml2_Auth
+        
+        # Verify the error message contains helpful guidance
+        error_message = str(exc_info.value)
+        assert "OneLogin_Saml2_Auth is not available in this package" in error_message
+        assert "python3-saml" in error_message
+        assert "pip install python3-saml" in error_message
+        assert "https://github.com/onelogin/python3-saml" in error_message
+
+    def test_getattr_for_nonexistent_attribute_raises_attribute_error(self):
+        """Test that accessing non-existent attributes raises AttributeError"""
+        
+        import onelogin.saml2.auth
+        with pytest.raises(AttributeError) as exc_info:
+            getattr(onelogin.saml2.auth, 'NonExistentClass')
+        
+        error_message = str(exc_info.value)
+        assert "module 'onelogin.saml2.auth' has no attribute 'NonExistentClass'" in error_message
+
+    def test_saml2_module_can_be_imported(self):
+        """Test that the saml2 module itself can be imported without error"""
+        
+        import onelogin.saml2
+        # Should not raise any errors
+        
+    def test_saml2_auth_module_can_be_imported(self):
+        """Test that the saml2.auth module itself can be imported without error"""
+        
+        import onelogin.saml2.auth
+        # Should not raise any errors
+
+    def test_saml2_auth_module_has_empty_all_list(self):
+        """Test that __all__ is defined and empty"""
+        
+        import onelogin.saml2.auth
+        assert hasattr(onelogin.saml2.auth, '__all__')
+        assert onelogin.saml2.auth.__all__ == []