test

app/models/gamestate.py

@@ -1,12 +1,21 @@
+"""Database models for persisted puzzle save points."""
+
 from .. import db
 
 
 class GameState(db.Model):
+    """Persist one saved puzzle session for a specific user."""
+
     __tablename__ = "game_state"
 
+    # These identifiers connect a save point to one concrete database row and
+    # to the user who owns it, which is necessary so save points stay private.
     id = db.Column(db.Integer, primary_key=True)
     user_id = db.Column(db.Integer, nullable=False)
 
+    # The remaining fields describe the board snapshot and the surrounding
+    # progress information, because a meaningful restore needs more than just
+    # piece coordinates.
     board = db.Column(db.Text, nullable=False)
     mode = db.Column(db.String(10), nullable=False)
     board_size = db.Column(db.Integer, nullable=False, default=8)
@@ -16,6 +25,9 @@ class GameState(db.Model):
     step_count = db.Column(db.Integer, nullable=False, default=0, server_default=db.text("0"))
     elapsed_seconds = db.Column(db.Integer, nullable=False, default=0, server_default=db.text("0"))
     is_solved = db.Column(db.Boolean, nullable=False, default=False, server_default=db.text("0"))
+
+    # Timestamps make it possible to sort, filter, and explain save points in
+    # the UI without asking the user to remember when each run was created.
     created_at = db.Column(db.DateTime, nullable=False, server_default=db.func.now())
     updated_at = db.Column(
         db.DateTime,

app/models/login_attempt.py

@@ -1,14 +1,26 @@
+"""Database model for temporary login-throttling information."""
+
 from .. import db
 
 
 class LoginAttempt(db.Model):
+    """Track failed login attempts per IP address."""
+
     __tablename__ = "login_attempts"
 
+    # The unique IP address is the central lookup key because the lockout
+    # policy is applied to the origin of failed requests, not to one account.
     id = db.Column(db.Integer, primary_key=True)
     ip_address = db.Column(db.String(45), unique=True, nullable=False)
+
+    # These values explain how far an address is into the lock flow and when
+    # the application may safely allow another login attempt.
     failed_attempts = db.Column(db.Integer, nullable=False, default=0, server_default=db.text("0"))
     locked_until = db.Column(db.DateTime)
     last_failed_at = db.Column(db.DateTime)
 
     def __repr__(self):
+        """Return a compact identifier for debugging and logging.
+        """
+
         return f"<LoginAttempt {self.ip_address}>"

app/models/user.py

@@ -1,17 +1,29 @@
+"""Database model for application user accounts."""
+
 from .. import db
 from flask_login import UserMixin
 
 
 class User(UserMixin, db.Model):
+    """Represent one authenticated account in the application."""
+
     __tablename__ = "users"
 
+    # These core identity fields are the minimum needed to create and safely
+    # authenticate an account.
     id = db.Column(db.Integer, primary_key=True)
     username = db.Column(db.String(20), unique=True, nullable=False)
     password = db.Column(db.String(255), nullable=False)
+
+    # The metadata and 2FA fields support account history and stronger account
+    # protection without changing the basic login flow.
     created_at = db.Column(db.DateTime, server_default=db.func.now())
     last_login = db.Column(db.DateTime)
     two_factor_enabled = db.Column(db.Boolean, nullable=False, default=False, server_default=db.text("0"))
     two_factor_secret = db.Column(db.String(64))
 
     def __repr__(self):
+        """Return a readable representation for debugging output.
+        """
+
         return f"<User {self.username}>"