Publish an official package to PyPI (#40)

* Add mypy for checking types
* Add flake8 and fix issues
* Add interrogate and fix docstrings and type annotations
* Add coveralls
* Add complete test, lint, build and deploy pipeline to publish packages to PyPI
* Add mypy stubs

Author: mostafa

.flake8

@@ -0,0 +1,12 @@
+[flake8]
+    max-line-length = 100
+    per-file-ignores =
+        django_saml2_auth/tests/test_saml.py: E501, F821
+    exclude =
+        django_saml2_auth.egg-info,
+        dist,
+        build,
+        env,
+        venv,
+        .env,
+        .venv,

.github/workflows/deploy.yml

@@ -0,0 +1,58 @@
+name: deploy
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    name: Test and build django-saml2-auth
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        versions:
+          - { "djangoVersion": "2.2.27", "pythonVersion": "3.7" }
+          - { "djangoVersion": "2.2.27", "pythonVersion": "3.8" }
+          - { "djangoVersion": "2.2.27", "pythonVersion": "3.9" }
+          - { "djangoVersion": "2.2.27", "pythonVersion": "3.10" }
+          - { "djangoVersion": "3.2.12", "pythonVersion": "3.7" }
+          - { "djangoVersion": "3.2.12", "pythonVersion": "3.8" }
+          - { "djangoVersion": "3.2.12", "pythonVersion": "3.9" }
+          - { "djangoVersion": "3.2.12", "pythonVersion": "3.10" }
+          - { "djangoVersion": "4.0.3", "pythonVersion": "3.8" }
+          - { "djangoVersion": "4.0.3", "pythonVersion": "3.9" }
+          - { "djangoVersion": "4.0.3", "pythonVersion": "3.10" }
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+      - name: Set up Python 🐍
+        uses: actions/setup-python@v3
+        with:
+          python-version: ${{ matrix.versions.pythonVersion }}
+      - name: Install xmlsec1 📦
+        run: sudo apt-get install xmlsec1
+      - name: Install dependencies 📦
+        run: python -m pip install -r requirements_test.txt && python -m pip install -e .
+      - name: Install Django ${{ matrix.versions.djangoVersion }} 📦
+        run: python -m pip install Django==${{ matrix.versions.djangoVersion }}
+      - name: Check types and syntax 🦆
+        run: |
+          mypy .
+          flake8 .
+          interrogate --quiet --fail-under=95 .
+      - name: Test Django ${{ matrix.versions.djangoVersion }} with coverage 🧪
+        run: coverage run --source=django_saml2_auth -m pytest .
+      - name: Submit coverage report to Coveralls 📈
+        if: ${{ success() }}
+        run: coveralls
+        env:
+          COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
+      - name: Install build dependencies 📦
+        run: python -m pip install build --user
+      - name: Build a binary wheel and a source tarball 🏗️
+        run: python -m build --sdist --wheel .
+      - name: Publish package to PyPI 🎉
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip_existing: true

.github/workflows/test.yml

@@ -0,0 +1,3 @@
+"""
+django-saml2-auth is a Django app that provides a SAML2 authentication backend.
+"""

django_saml2_auth/__init__.py

@@ -29,3 +29,6 @@
 NO_JWT_PRIVATE_KEY = 1126
 NO_JWT_PUBLIC_KEY = 1127
 INVALID_JWT_ALGORITHM = 1128
+NO_USER_ID = 1129
+INVALID_TOKEN = 1130
+INVALID_NEXT_URL = 1131

django_saml2_auth/errors.py

@@ -1,9 +1,21 @@
 """Custom exception class for handling extra arguments."""
 
 
+from typing import Any, Dict, Optional
+
+
 class SAMLAuthError(Exception):
-    extra = None
+    """Custom exception class for handling extra arguments."""
+
+    extra: Optional[Dict[str, Any]] = None
+
+    def __init__(self, msg: str, extra: Optional[Dict[str, Any]] = None):
+        """Initialize exception class.
 
-    def __init__(self, msg, extra=None):
+        Args:
+            msg (str): Exception message.
+            extra (Optional[Dict[str, Any]], optional): Extra arguments.
+                Defaults to None.
+        """
         self.message = msg
         self.extra = extra

django_saml2_auth/exceptions.py

@@ -3,11 +3,22 @@
 
 from typing import Any, Callable, Dict, Mapping, Optional, Union
 
-from dictor import dictor
+from dictor import dictor  # type: ignore
 from django.conf import settings
 from django.http import HttpRequest, HttpResponse, HttpResponseRedirect
 from django.urls import NoReverseMatch
-from django_saml2_auth.errors import *
+from django_saml2_auth.errors import (ERROR_CREATING_SAML_CONFIG_OR_CLIENT,
+                                      INVALID_METADATA_URL,
+                                      NO_ISSUER_IN_SAML_RESPONSE,
+                                      NO_METADATA_URL_ASSOCIATED,
+                                      NO_METADATA_URL_OR_FILE,
+                                      NO_NAME_ID_IN_SAML_RESPONSE,
+                                      NO_SAML_CLIENT,
+                                      NO_SAML_RESPONSE_FROM_CLIENT,
+                                      NO_SAML_RESPONSE_FROM_IDP,
+                                      NO_TOKEN_SPECIFIED,
+                                      NO_USER_IDENTITY_IN_SAML_RESPONSE,
+                                      NO_USERNAME_OR_EMAIL_SPECIFIED)
 from django_saml2_auth.exceptions import SAMLAuthError
 from django_saml2_auth.utils import get_reverse, run_hook
 from saml2 import BINDING_HTTP_POST, BINDING_HTTP_REDIRECT, entity
@@ -67,7 +78,7 @@ def validate_metadata_url(url: str) -> bool:
         http_client = HTTPBase()
         metadata = MetaDataExtern(None, url=url, http=http_client)
         metadata.load()
-    except:
+    except Exception:
         return False
 
     return True
@@ -94,7 +105,7 @@ def get_metadata(user_id: Optional[str] = None) -> Mapping[str, Any]:
     saml2_auth_settings = settings.SAML2_AUTH
     get_metadata_trigger = dictor(saml2_auth_settings, "TRIGGER.GET_METADATA_AUTO_CONF_URLS")
     if get_metadata_trigger:
-        metadata_urls = run_hook(get_metadata_trigger, user_id)
+        metadata_urls = run_hook(get_metadata_trigger, user_id)  # type: ignore
         if metadata_urls:
             # Filter invalid metadata URLs
             filtered_metadata_urls = list(
@@ -127,21 +138,25 @@ def get_metadata(user_id: Optional[str] = None) -> Mapping[str, Any]:
 
 def get_saml_client(domain: str,
                     acs: Callable[..., HttpResponse],
-                    user_id: str = None) -> Optional[Saml2Client]:
+                    user_id: Optional[str] = None) -> Optional[Saml2Client]:
     """Create a new Saml2Config object with the given config and return an initialized Saml2Client
     using the config object. The settings are read from django settings key: SAML2_AUTH.
 
     Args:
         domain (str): Domain name to get SAML config for
         acs (Callable[..., HttpResponse]): The acs endpoint
+        user_id (str, optional): If passed, it will be further processed by the
+            GET_METADATA_AUTO_CONF_URLS trigger, which will return the metadata URL corresponding
+            to the given user identifier, either email or username. Defaults to None.
 
     Raises:
         SAMLAuthError: Re-raise any exception raised by Saml2Config or Saml2Client
 
     Returns:
         Optional[Saml2Client]: A Saml2Client or None
     """
-    acs_url = domain + get_reverse([acs, "acs", "django_saml2_auth:acs"])
+    # get_reverse raises an exception if the view is not found, so we can safely ignore type errors
+    acs_url = domain + get_reverse([acs, "acs", "django_saml2_auth:acs"])  # type: ignore
     metadata = get_metadata(user_id)
     if (("local" in metadata and not metadata["local"]) or
             ("remote" in metadata and not metadata["remote"])):
@@ -154,7 +169,7 @@ def get_saml_client(domain: str,
 
     saml2_auth_settings = settings.SAML2_AUTH
 
-    saml_settings = {
+    saml_settings: Dict[str, Any] = {
         "metadata": metadata,
         "allow_unknown_attributes": True,
         "debug": saml2_auth_settings.get("DEBUG", False),
@@ -208,7 +223,8 @@ def get_saml_client(domain: str,
 
 def decode_saml_response(
         request: HttpRequest,
-        acs: Callable[..., HttpResponse]) -> Union[HttpResponseRedirect, Optional[AuthnResponse]]:
+        acs: Callable[..., HttpResponse]) -> Union[
+            HttpResponseRedirect, Optional[AuthnResponse], None]:
     """Given a request, the authentication response inside the SAML response body is parsed,
     decoded and returned. If there are any issues parsing the request, the identity or the issuer,
     an exception is raised.
@@ -225,8 +241,8 @@ def decode_saml_response(
         SAMLAuthError: No user identity in SAML response.
 
     Returns:
-        Union[HttpResponseRedirect, Optional[AuthnResponse]]: Returns an AuthnResponse object for
-        extracting user identity from.
+        Union[HttpResponseRedirect, Optional[AuthnResponse], None]: Returns an AuthnResponse
+            object for extracting user identity from.
     """
     saml_client = get_saml_client(get_assertion_url(request), acs)
     if not saml_client:
@@ -313,8 +329,8 @@ def extract_user_identity(user_identity: Dict[str, Any]) -> Dict[str, Optional[A
     user["first_name"] = dictor(user_identity, f"{firstname_field}/0", pathsep="/")
     user["last_name"] = dictor(user_identity, f"{lastname_field}/0", pathsep="/")
 
-    TOKEN_REQUIRED = dictor(saml2_auth_settings, "TOKEN_REQUIRED", default=True)
-    if TOKEN_REQUIRED:
+    token_required = dictor(saml2_auth_settings, "TOKEN_REQUIRED", default=True)
+    if token_required:
         token_field = dictor(saml2_auth_settings, "ATTRIBUTES_MAP.token", default="token")
         user["token"] = dictor(user_identity, f"{token_field}.0")
 
@@ -334,7 +350,7 @@ def extract_user_identity(user_identity: Dict[str, Any]) -> Dict[str, Optional[A
             "status_code": 422
         })
 
-    if TOKEN_REQUIRED and not user.get("token"):
+    if token_required and not user.get("token"):
         raise SAMLAuthError("No token specified.", extra={
             "exc_type": ValueError,
             "error_code": NO_TOKEN_SPECIFIED,

django_saml2_auth/saml.py

@@ -0,0 +1,3 @@
+"""
+Tests for django_saml2_auth.
+"""

django_saml2_auth/tests/__init__.py

@@ -1,9 +1,14 @@
+"""
+Django settings for tests.
+"""
+
 import os
+from typing import List
 
 BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 SECRET_KEY = "SECRET"
 DEBUG = True
-ALLOWED_HOSTS = []
+ALLOWED_HOSTS: List[str] = []
 INSTALLED_APPS = [
     "django.contrib.admin",
     "django.contrib.auth",
@@ -84,7 +89,8 @@
     },
     "TRIGGER": {
         "BEFORE_LOGIN": "django_saml2_auth.tests.test_user.saml_user_setup",
-        "GET_METADATA_AUTO_CONF_URLS": "django_saml2_auth.tests.test_saml.get_metadata_auto_conf_urls"
+        "GET_METADATA_AUTO_CONF_URLS":
+        "django_saml2_auth.tests.test_saml.get_metadata_auto_conf_urls"
     },
     "ASSERTION_URL": "https://api.example.com",
     "ENTITY_ID": "https://api.example.com/sso/acs/",

django_saml2_auth/tests/settings.py

@@ -1,3 +1,7 @@
+"""
+Tests for saml.py
+"""
+
 from typing import Optional, List, Mapping
 
 import pytest
@@ -109,21 +113,25 @@ def get_user_identity() -> Mapping[str, List[str]]:
 
 
 def mock_parse_authn_request_response(
-        self: Saml2Client, response: AuthnResponse, binding: str) -> "MockAuthnResponse":
+        self: Saml2Client, response: AuthnResponse, binding: str
+) -> "MockAuthnResponse":  # type: ignore
     """Mock function to return an mocked instance of AuthnResponse.
 
     Returns:
         MockAuthnResponse: A mocked instance of AuthnResponse
     """
     class MockAuthnRequest:
+        """Mock class for AuthnRequest."""
         name_id = "Username"
 
         @staticmethod
         def issuer():
+            """Mock function for AuthnRequest.issuer()."""
             return METADATA_URL1
 
         @staticmethod
         def get_identity():
+            """Mock function for AuthnRequest.get_identity()."""
             return get_user_identity()
 
     return MockAuthnRequest()
@@ -168,6 +176,7 @@ def test_get_default_next_url_no_default_next_url(settings: SettingsWrapper):
 
     # This doesn't happen on a real instance, unless you don't have "admin:index" route
     assert str(exc_info.value) == "We got a URL reverse issue: ['admin:index']"
+    assert exc_info.value.extra is not None
     assert issubclass(exc_info.value.extra["exc_type"], NoReverseMatch)
 
 
@@ -332,11 +341,13 @@ def test_get_saml_client_failure_with_invalid_file(settings: SettingsWrapper):
         get_saml_client("example.com", acs)
 
     assert str(exc_info.value) == "[Errno 2] No such file or directory: '/invalid/metadata.xml'"
+    assert exc_info.value.extra is not None
     assert isinstance(exc_info.value.extra["exc"], FileNotFoundError)
 
 
 @responses.activate
-def test_decode_saml_response_success(settings: SettingsWrapper, monkeypatch: "MonkeyPatch"):
+def test_decode_saml_response_success(
+        settings: SettingsWrapper, monkeypatch: "MonkeyPatch"):  # type: ignore
     """Test decode_saml_response function to verify if it correctly decodes the SAML response.
 
     Args:
@@ -352,13 +363,13 @@ def test_decode_saml_response_success(settings: SettingsWrapper, monkeypatch: "M
                         "parse_authn_request_response",
                         mock_parse_authn_request_response)
     result = decode_saml_response(post_request, acs)
-    assert len(result.get_identity()) > 0
+    assert len(result.get_identity()) > 0  # type: ignore
 
 
 def test_extract_user_identity_success():
     """Test extract_user_identity function to verify if it correctly extracts user identity
     information from a (pysaml2) parsed SAML response."""
-    result = extract_user_identity(get_user_identity())
+    result = extract_user_identity(get_user_identity())  # type: ignore
     assert len(result) == 6
     assert result["username"] == result["email"] == "[email protected]"
     assert result["first_name"] == "John"
@@ -372,6 +383,6 @@ def test_extract_user_identity_token_not_required(settings: SettingsWrapper):
     information from a (pysaml2) parsed SAML response when token is not required."""
     settings.SAML2_AUTH["TOKEN_REQUIRED"] = False
 
-    result = extract_user_identity(get_user_identity())
+    result = extract_user_identity(get_user_identity())  # type: ignore
     assert len(result) == 5
     assert "token" not in result