[Docs] Add/update docstrings and license text in every file

calsocial/forms.py

@@ -1,3 +1,22 @@
+# Calendar.social
+# Copyright (C) 2018 Gergely Polonkai
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Forms for Calendar.social
+"""
+
 from flask_babelex import lazy_gettext as _
 from flask_wtf import FlaskForm
 import pytz
@@ -8,17 +27,32 @@ from wtforms.widgets import TextArea
 
 
 class RegistrationForm(FlaskForm):
+    """Registration form
+    """
+
     username = StringField(_('Username'), validators=[DataRequired()])
     email = StringField(_('Email address'), validators=[Email()])
     password = PasswordField(_('Password'), validators=[DataRequired()])
     password_retype = PasswordField(_('Password, once more'), validators=[DataRequired()])
 
     def validate_password_retype(self, field):
+        """Validate the ``password_retype`` field
+
+        Its value must match the ``password`` field’s.
+        """
+
         if field.data != self.password.data:
             raise ValidationError(_('The two passwords must match!'))
 
 
 class TimezoneField(SelectField):
+    """Field for selecting a time zone
+
+    Note: this field overrides whatever is passed to the ``choices`` parameter, and fills
+    ``choices`` with the common timezones of pytz.  In every other aspects, it behaves exactly
+    like `SelectField`.
+    """
+
     def __init__(self, *args, **kwargs):
         kwargs.update({
             'choices': [
@@ -44,6 +78,9 @@ class TimezoneField(SelectField):
 
     @staticmethod
     def is_pytz_instance(value):
+        """Check if ``value`` is a valid pytz time zone instance
+        """
+
         return value is pytz.UTC or isinstance(value, pytz.tzinfo.BaseTzInfo)
 
     def process_data(self, value):
@@ -68,6 +105,9 @@ class TimezoneField(SelectField):
 
 
 class EventForm(FlaskForm):
+    """Form for event creation/editing
+    """
+
     title = StringField(_('Title'), validators=[DataRequired()])
     time_zone = TimezoneField(_('Time zone'), validators=[DataRequired()])
     start_time = DateTimeField(_('Start time'), validators=[DataRequired()])
@@ -76,6 +116,9 @@ class EventForm(FlaskForm):
     description = StringField(_('Description'), widget=TextArea())
 
     def populate_obj(self, obj):
+        """Populate ``obj`` with event data
+        """
+
         FlaskForm.populate_obj(self, obj)
 
         timezone = self.time_zone.data
@@ -85,5 +128,10 @@ class EventForm(FlaskForm):
         obj.end_time = timezone.localize(self.end_time.data).astimezone(pytz.utc)
 
     def validate_end_time(self, field):
+        """Validate the ``end_time`` field
+
+        Its value must be later than the value of the ``start_time`` field.
+        """
+
         if field.data < self.start_time.data:
             raise ValidationError(_('End time must be later than start time!'))