*: rephrase strings

passbook/lib/templatetags/passbook_utils.py

@@ -5,7 +5,7 @@ from urllib.parse import urlencode
 from django import template
 from django.db.models import Model
 from django.template import Context
-from django.utils.html import escape
+from django.utils.html import escape, mark_safe
 from structlog import get_logger
 
 from passbook.lib.config import CONFIG
@@ -105,4 +105,4 @@ def debug(obj) -> str:
 @register.filter
 def doc(obj) -> str:
     """Return docstring of object"""
-    return obj.__doc__
+    return mark_safe(obj.__doc__.replace("\n", "<br>"))

passbook/policies/expression/models.py

@@ -8,7 +8,7 @@ from passbook.policies.types import PolicyRequest, PolicyResult
 
 
 class ExpressionPolicy(Policy):
-    """Implement custom logic using python."""
+    """Execute arbitrary Python code to implement custom checks and validation."""
 
     expression = models.TextField()
 

passbook/policies/hibp/models.py

@@ -13,7 +13,7 @@ LOGGER = get_logger()
 
 
 class HaveIBeenPwendPolicy(Policy):
-    """Check if password is on HaveIBeenPwned's list by upload the first
+    """Check if password is on HaveIBeenPwned's list by uploading the first
     5 characters of the SHA1 Hash."""
 
     allowed_count = models.IntegerField(default=0)

passbook/providers/oauth/models.py

@@ -12,8 +12,9 @@ from passbook.lib.utils.template import render_to_string
 
 
 class OAuth2Provider(Provider, AbstractApplication):
-    """Generic OAuth2 Provider for applications not using OpenID-Connect. This Provider
+    """Generic OAuth2 Provider for applications not using OpenID-Connect.
-    also supports the GitHub-pretend mode."""
+    This Provider also supports the GitHub-pretend mode for Applications that don't support
+    generic OAuth."""
 
     form = "passbook.providers.oauth.forms.OAuth2ProviderForm"
 

passbook/providers/saml/models.py

@@ -25,7 +25,7 @@ class SAMLBindings(models.TextChoices):
 
 
 class SAMLProvider(Provider):
-    """SAML 2.0-based authentication protocol."""
+    """SAML 2.0 Endpoint for applications which support SAML."""
 
     name = models.TextField()
     processor_path = models.CharField(max_length=255, choices=[])
@@ -157,7 +157,7 @@ class SAMLProvider(Provider):
 
 
 class SAMLPropertyMapping(PropertyMapping):
-    """SAML Property mapping, allowing Name/FriendlyName mapping to a list of strings"""
+    """Map User/Group attribute to SAML Attribute, which can be used by the Service Provider."""
 
     saml_name = models.TextField(verbose_name="SAML Name")
     friendly_name = models.TextField(default=None, blank=True, null=True)

passbook/sources/ldap/models.py

@@ -10,7 +10,7 @@ from passbook.core.models import Group, PropertyMapping, Source
 
 
 class LDAPSource(Source):
-    """LDAP Authentication source"""
+    """Federate LDAP Directory with passbook, or create new accounts in LDAP."""
 
     server_uri = models.TextField(
         validators=[URLValidator(schemes=["ldap", "ldaps"])],
@@ -81,7 +81,7 @@ class LDAPSource(Source):
 
 
 class LDAPPropertyMapping(PropertyMapping):
-    """Map LDAP Property to User or Group object"""
+    """Map LDAP Property to User or Group object attribute"""
 
     object_field = models.TextField()
 

passbook/sources/oauth/models.py

@@ -11,7 +11,7 @@ from passbook.sources.oauth.clients import get_client
 
 
 class OAuthSource(Source):
-    """Configuration for OAuth provider."""
+    """Login using a Generic OAuth provider."""
 
     provider_type = models.CharField(max_length=255)
     request_token_url = models.CharField(
@@ -78,7 +78,7 @@ class OAuthSource(Source):
 
 
 class GitHubOAuthSource(OAuthSource):
-    """Abstract subclass of OAuthSource to specify GitHub Form"""
+    """Social Login using GitHub.com or a GitHub-Enterprise Instance."""
 
     form = "passbook.sources.oauth.forms.GitHubOAuthSourceForm"
 
@@ -90,7 +90,7 @@ class GitHubOAuthSource(OAuthSource):
 
 
 class TwitterOAuthSource(OAuthSource):
-    """Abstract subclass of OAuthSource to specify Twitter Form"""
+    """Social Login using Twitter.com"""
 
     form = "passbook.sources.oauth.forms.TwitterOAuthSourceForm"
 
@@ -102,7 +102,7 @@ class TwitterOAuthSource(OAuthSource):
 
 
 class FacebookOAuthSource(OAuthSource):
-    """Abstract subclass of OAuthSource to specify Facebook Form"""
+    """Social Login using Facebook.com."""
 
     form = "passbook.sources.oauth.forms.FacebookOAuthSourceForm"
 
@@ -114,7 +114,7 @@ class FacebookOAuthSource(OAuthSource):
 
 
 class DiscordOAuthSource(OAuthSource):
-    """Abstract subclass of OAuthSource to specify Discord Form"""
+    """Social Login using Discord."""
 
     form = "passbook.sources.oauth.forms.DiscordOAuthSourceForm"
 
@@ -126,7 +126,7 @@ class DiscordOAuthSource(OAuthSource):
 
 
 class GoogleOAuthSource(OAuthSource):
-    """Abstract subclass of OAuthSource to specify Google Form"""
+    """Social Login using Google or Gsuite."""
 
     form = "passbook.sources.oauth.forms.GoogleOAuthSourceForm"
 
@@ -138,7 +138,7 @@ class GoogleOAuthSource(OAuthSource):
 
 
 class AzureADOAuthSource(OAuthSource):
-    """Abstract subclass of OAuthSource to specify AzureAD Form"""
+    """Social Login using Azure AD."""
 
     form = "passbook.sources.oauth.forms.AzureADOAuthSourceForm"
 
@@ -150,7 +150,7 @@ class AzureADOAuthSource(OAuthSource):
 
 
 class OpenIDOAuthSource(OAuthSource):
-    """Abstract subclass of OAuthSource to specify OpenID Form"""
+    """Login using a Generic OpenID-Connect compliant provider."""
 
     form = "passbook.sources.oauth.forms.OAuthSourceForm"
 

passbook/sources/saml/models.py

@@ -17,7 +17,7 @@ class SAMLBindingTypes(models.TextChoices):
 
 
 class SAMLSource(Source):
-    """SAML Source"""
+    """Authenticate using an external SAML Identity Provider."""
 
     issuer = models.TextField(
         blank=True,

passbook/stages/captcha/models.py

@@ -6,7 +6,7 @@ from passbook.flows.models import Stage
 
 
 class CaptchaStage(Stage):
-    """Captcha Stage instance"""
+    """Verify the user is human using Google's reCaptcha."""
 
     public_key = models.TextField(
         help_text=_(

passbook/stages/consent/models.py

@@ -5,7 +5,7 @@ from passbook.flows.models import Stage
 
 
 class ConsentStage(Stage):
-    """Consent Stage instance"""
+    """Prompt the user for confirmation."""
 
     type = "passbook.stages.consent.stage.ConsentStage"
     form = "passbook.stages.consent.forms.ConsentStageForm"

passbook/stages/dummy/models.py

@@ -5,7 +5,7 @@ from passbook.flows.models import Stage
 
 
 class DummyStage(Stage):
-    """Dummy stage, mostly used to debug"""
+    """Used for debugging."""
 
     type = "passbook.stages.dummy.stage.DummyStage"
     form = "passbook.stages.dummy.forms.DummyStageForm"

passbook/stages/email/models.py

@@ -21,7 +21,7 @@ class EmailTemplates(models.TextChoices):
 
 
 class EmailStage(Stage):
-    """Email-based verification."""
+    """Sends an Email to the user with a token to confirm their Email address."""
 
     host = models.TextField(default="localhost")
     port = models.IntegerField(default=25)

passbook/stages/identification/models.py

@@ -21,7 +21,7 @@ class Templates(models.TextChoices):
 
 
 class IdentificationStage(Stage):
-    """Identification stage, allows a user to identify themselves to authenticate."""
+    """Allows the user to identify themselves for authentication."""
 
     user_fields = ArrayField(
         models.CharField(max_length=100, choices=UserFields.choices),

passbook/stages/invitation/models.py

@@ -10,7 +10,8 @@ from passbook.flows.models import Stage
 
 
 class InvitationStage(Stage):
-    """Invitation stage, to enroll themselves with enforced parameters"""
+    """Simplify enrollment; allow users to use a single
+    link to create their user with pre-defined parameters."""
 
     continue_flow_without_invitation = models.BooleanField(
         default=False,

passbook/stages/otp_static/models.py

@@ -10,7 +10,7 @@ from passbook.flows.models import Stage
 
 
 class OTPStaticStage(Stage):
-    """Generate static tokens for the user as a backup"""
+    """Generate static tokens for the user as a backup."""
 
     token_count = models.IntegerField(default=6)
 

passbook/stages/otp_time/models.py

@@ -17,7 +17,7 @@ class TOTPDigits(models.IntegerChoices):
 
 
 class OTPTimeStage(Stage):
-    """Enroll a user's device into Time-based OTP"""
+    """Enroll a user's device into Time-based OTP."""
 
     digits = models.IntegerField(choices=TOTPDigits.choices)
 

passbook/stages/otp_validate/models.py

@@ -6,7 +6,7 @@ from passbook.flows.models import NotConfiguredAction, Stage
 
 
 class OTPValidateStage(Stage):
-    """Validate user's configured OTP Device"""
+    """Validate user's configured OTP Device."""
 
     not_configured_action = models.TextField(
         choices=NotConfiguredAction.choices, default=NotConfiguredAction.SKIP

passbook/stages/password/models.py

@@ -13,7 +13,7 @@ from passbook.flows.views import NEXT_ARG_NAME
 
 
 class PasswordStage(Stage):
-    """Password-based Django-backend Authentication Stage"""
+    """Prompts the user for their password, and validates it against the configured backends."""
 
     backends = ArrayField(
         models.TextField(),

passbook/stages/prompt/models.py

@@ -95,7 +95,7 @@ class Prompt(models.Model):
 
 
 class PromptStage(PolicyBindingModel, Stage):
-    """Prompt Stage, pointing to multiple prompts"""
+    """Define arbitrary prompts for the user."""
 
     fields = models.ManyToManyField(Prompt)
 

passbook/stages/user_delete/models.py

@@ -5,7 +5,8 @@ from passbook.flows.models import Stage
 
 
 class UserDeleteStage(Stage):
-    """Delete stage, delete a user from saved data."""
+    """Deletes the currently pending user without confirmation.
+    Use with caution."""
 
     type = "passbook.stages.user_delete.stage.UserDeleteStageView"
     form = "passbook.stages.user_delete.forms.UserDeleteStageForm"

passbook/stages/user_login/models.py

@@ -5,7 +5,7 @@ from passbook.flows.models import Stage
 
 
 class UserLoginStage(Stage):
-    """Login stage, allows a user to identify themselves to authenticate."""
+    """Attaches the currently pending user to the current session."""
 
     type = "passbook.stages.user_login.stage.UserLoginStageView"
     form = "passbook.stages.user_login.forms.UserLoginStageForm"

passbook/stages/user_logout/models.py

@@ -5,7 +5,7 @@ from passbook.flows.models import Stage
 
 
 class UserLogoutStage(Stage):
-    """Logout stage, allows a user to identify themselves to authenticate."""
+    """Resets the users current session."""
 
     type = "passbook.stages.user_logout.stage.UserLogoutStageView"
     form = "passbook.stages.user_logout.forms.UserLogoutStageForm"

passbook/stages/user_write/models.py

@@ -5,7 +5,8 @@ from passbook.flows.models import Stage
 
 
 class UserWriteStage(Stage):
-    """Write stage, write a user from saved data."""
+    """Writes currently pending data into the pending user, or if no user exists,
+    creates a new user with the data."""
 
     type = "passbook.stages.user_write.stage.UserWriteStageView"
     form = "passbook.stages.user_write.forms.UserWriteStageForm"