Doc string update to be more consitent

Also fixed a bug `update_settings_from_fixture`.

README.md

@@ -36,8 +36,8 @@ For a complete installation guide please visit the installation documentation
     * `pip install -r requirements.txt`
 * Configuration (_adjust them accordingly to your needs_)
     * For development copy `flaskbb/configs/development.py.example` to `flaskbb/configs/development.py`
-* Database creation
-    * `python manage.py createall`
+* Create the database & populate it
+    * `python manage.py populate`
 * Run the development server
     * `python manage.py runserver`
 * Visit [localhost:8080](http://localhost:8080)

flaskbb/app.py

@@ -48,9 +48,8 @@ from flaskbb.utils.settings import flaskbb_config
 
 
 def create_app(config=None):
-    """
-    Creates the app.
-    """
+    """Creates the app."""
+
     # Initialize the app
     app = Flask("flaskbb")
 
@@ -108,9 +107,8 @@ def configure_api(app):
 
 
 def configure_extensions(app):
-    """
-    Configures the extensions
-    """
+    """Configures the extensions."""
+
     # Flask-Plugins
     plugin_manager.init_app(app)
 
@@ -150,9 +148,8 @@ def configure_extensions(app):
 
     @login_manager.user_loader
     def load_user(user_id):
-        """
-        Loads the user. Required by the `login` extension
-        """
+        """Loads the user. Required by the `login` extension."""
+
         unread_count = db.session.query(db.func.count(PrivateMessage.id)).\
             filter(PrivateMessage.unread,
                    PrivateMessage.user_id == user_id).subquery()
@@ -180,9 +177,8 @@ def configure_extensions(app):
 
 
 def configure_template_filters(app):
-    """
-    Configures the template filters
-    """
+    """Configures the template filters."""
+
     app.jinja_env.filters['markup'] = render_markup
     app.jinja_env.filters['format_date'] = format_date
     app.jinja_env.filters['time_since'] = time_since
@@ -207,27 +203,25 @@ def configure_template_filters(app):
 
 
 def configure_context_processors(app):
-    """
-    Configures the context processors
-    """
+    """Configures the context processors."""
+
     @app.context_processor
     def inject_flaskbb_config():
+        """Injects the ``flaskbb_config`` config variable into the
+        templates.
         """
-        Injects the ``flaskbb_config`` config variable into the templates.
-        """
+
         return dict(flaskbb_config=flaskbb_config)
 
 
 def configure_before_handlers(app):
-    """
-    Configures the before request handlers
-    """
+    """Configures the before request handlers."""
 
     @app.before_request
     def update_lastseen():
-        """
-        Updates `lastseen` before every reguest if the user is authenticated
-        """
+        """Updates `lastseen` before every reguest if the user is
+        authenticated."""
+
         if current_user.is_authenticated():
             current_user.lastseen = datetime.datetime.utcnow()
             db.session.add(current_user)
@@ -243,9 +237,7 @@ def configure_before_handlers(app):
 
 
 def configure_errorhandlers(app):
-    """
-    Configures the error handlers
-    """
+    """Configures the error handlers."""
 
     @app.errorhandler(403)
     def forbidden_page(error):
@@ -261,9 +253,7 @@ def configure_errorhandlers(app):
 
 
 def configure_logging(app):
-    """
-    Configures logging.
-    """
+    """Configures logging."""
 
     logs_folder = os.path.join(app.root_path, os.pardir, "logs")
     from logging.handlers import SMTPHandler

flaskbb/utils/helpers.py

@@ -72,7 +72,7 @@ def get_categories_and_forums(query_result, user):
            .....:     for forum, forumsread in forums:
            .....:         print "\t", forum, forumsread
 
-   This will print something this:
+   This will print something like this:
         <Category 1>
             <Forum 1> None
             <Forum 2> <flaskbb.forum.models.ForumsRead object at 0x38fdb50>
@@ -375,6 +375,7 @@ def format_quote(post):
     else:
         profile_url = url_for('user.profile', username=post.username,
                               _external=True)
+        # just ignore this long line :P
         quote = '[b][url={profile_url}]{post.username}[/url] wrote:[/b][quote]{post.content}[/quote]\n'.\
                 format(post=post, profile_url=profile_url)
 

flaskbb/utils/permissions.py

@@ -95,7 +95,7 @@ def can_moderate(user, forum=None, perm=None):
 
 
 def can_edit_post(user, post):
-    """Check if the post can be edited by the user"""
+    """Check if the post can be edited by the user."""
     topic = post.topic
 
     if can_moderate(user, topic.forum):
@@ -109,19 +109,19 @@ def can_edit_post(user, post):
 
 
 def can_delete_post(user, post):
-    """Check if the post can be deleted by the user"""
+    """Check if the post can be deleted by the user."""
     return check_perm(user=user, perm='deletepost', forum=post.topic.forum,
                       post_user_id=post.user_id)
 
 
 def can_delete_topic(user, topic):
-    """Check if the topic can be deleted by the user"""
+    """Check if the topic can be deleted by the user."""
     return check_perm(user=user, perm='deletetopic', forum=topic.forum,
                       post_user_id=topic.user_id)
 
 
 def can_post_reply(user, topic):
-    """Check if the user is allowed to post in the forum"""
+    """Check if the user is allowed to post in the forum."""
     if can_moderate(user, topic.forum):
         return True
 
@@ -132,7 +132,7 @@ def can_post_reply(user, topic):
 
 
 def can_post_topic(user, forum):
-    """Checks if the user is allowed to create a new topic in the forum"""
+    """Checks if the user is allowed to create a new topic in the forum."""
     return check_perm(user=user, perm='posttopic', forum=forum)
 
 

flaskbb/utils/populate.py

@@ -14,39 +14,41 @@ from flaskbb.forum.models import Post, Topic, Forum, Category
 
 
 def delete_settings_from_fixture(fixture):
-    """
-    Deletes the settings from a fixture from the database.
+    """Deletes the settings from a fixture from the database.
+
+    :param fixture: The fixture that should be deleted.
     """
     for settingsgroup in fixture:
         group = SettingsGroup.query.filter_by(key=settingsgroup[0]).first()
 
-        for settings in settingsgroup[1]['settings']:
+        for settings in settingsgroup[1]["settings"]:
             setting = Setting.query.filter_by(key=settings[0]).first()
             setting.delete()
         group.delete()
 
 
 def create_settings_from_fixture(fixture):
-    """
-    Inserts the settings from a fixture into the database.
+    """Inserts the settings from a fixture into the database.
+
+    :param fixture: The fixture which should inserted.
     """
     for settingsgroup in fixture:
         group = SettingsGroup(
             key=settingsgroup[0],
-            name=settingsgroup[1]['name'],
-            description=settingsgroup[1]['description']
+            name=settingsgroup[1]["name"],
+            description=settingsgroup[1]["description"]
         )
 
         group.save()
 
-        for settings in settingsgroup[1]['settings']:
+        for settings in settingsgroup[1]["settings"]:
             setting = Setting(
                 key=settings[0],
-                value=settings[1]['value'],
-                value_type=settings[1]['value_type'],
-                name=settings[1]['name'],
-                description=settings[1]['description'],
-                extra=settings[1].get('extra', ""),     # Optional field
+                value=settings[1]["value"],
+                value_type=settings[1]["value_type"],
+                name=settings[1]["name"],
+                description=settings[1]["description"],
+                extra=settings[1].get("extra", ""),     # Optional field
 
                 settingsgroup=group.key
             )
@@ -55,9 +57,18 @@ def create_settings_from_fixture(fixture):
 
 def update_settings_from_fixture(fixture, overwrite_group=False,
                                  overwrite_setting=False):
-    """
-    Updates the database settings from a fixture.
+    """Updates the database settings from a fixture.
     Returns the number of updated groups and settings.
+
+    :param fixture: The fixture which should be inserted/updated.
+
+    :param overwrite_group: Set this to ``True`` if you want to overwrite
+                            the group if it already exists.
+                            Defaults to ``False``.
+
+    :param overwrite_setting: Set this to ``True`` if you want to overwrite the
+                              setting if it already exists.
+                              Defaults to ``False``.
     """
     groups_count = 0
     settings_count = 0
@@ -65,47 +76,59 @@ def update_settings_from_fixture(fixture, overwrite_group=False,
 
         group = SettingsGroup.query.filter_by(key=settingsgroup[0]).first()
 
-        if group is not None and overwrite_group or group is None:
+        if (group is not None and overwrite_group) or group is None:
             groups_count += 1
-            group = SettingsGroup(
-                key=settingsgroup[0],
-                name=settingsgroup[1]['name'],
-                description=settingsgroup[1]['description']
-            )
+
+            if group is not None:
+                group.name = settingsgroup[1]["name"]
+                group.description = settingsgroup[1]["description"]
+            else:
+                group = SettingsGroup(
+                    key=settingsgroup[0],
+                    name=settingsgroup[1]["name"],
+                    description=settingsgroup[1]["description"]
+                )
 
             group.save()
 
-        for settings in settingsgroup[1]['settings']:
+        for settings in settingsgroup[1]["settings"]:
 
             setting = Setting.query.filter_by(key=settings[0]).first()
 
-            if setting is not None and overwrite_setting or setting is None:
+            if (setting is not None and overwrite_setting) or setting is None:
                 settings_count += 1
-                setting = Setting(
-                    key=settings[0],
-                    value=settings[1]['value'],
-                    value_type=settings[1]['value_type'],
-                    name=settings[1]['name'],
-                    description=settings[1]['description'],
-                    extra=settings[1].get('extra', ""),
-                    settingsgroup=group.key
-                )
+
+                if setting is not None:
+                    setting.value = settings[1]["value"]
+                    setting.value_type = settings[1]["value_type"]
+                    setting.name = settings[1]["name"]
+                    setting.description = settings[1]["description"]
+                    setting.extra = settings[1].get("extra", "")
+                    setting.settingsgroup = group.key
+                else:
+                    setting = Setting(
+                        key=settings[0],
+                        value=settings[1]["value"],
+                        value_type=settings[1]["value_type"],
+                        name=settings[1]["name"],
+                        description=settings[1]["description"],
+                        extra=settings[1].get("extra", ""),
+                        settingsgroup=group.key
+                    )
+
                 setting.save()
+
     return groups_count, settings_count
 
 
 def create_default_settings():
-    """
-    Creates the default settings
-    """
+    """Creates the default settings."""
     from flaskbb.fixtures.settings import fixture
     create_settings_from_fixture(fixture)
 
 
 def create_default_groups():
-    """
-    This will create the 5 default groups
-    """
+    """This will create the 5 default groups."""
     from flaskbb.fixtures.groups import fixture
     result = []
     for key, value in fixture.items():
@@ -120,9 +143,15 @@ def create_default_groups():
 
 
 def create_admin_user(username, password, email):
+    """Creates the administrator user.
+
+    :param username: The username of the user.
+
+    :param password: The password of the user.
+
+    :param email: The email address of the user.
     """
-    Creates the administrator user
-    """
+
     admin_group = Group.query.filter_by(admin=True).first()
     user = User()
 
@@ -135,10 +164,8 @@ def create_admin_user(username, password, email):
 
 
 def create_welcome_forum():
-    """
-    This will create the `welcome forum` that nearly every
-    forum software has after the installation process is finished
-    """
+    """This will create the `welcome forum` with a welcome topic."""
+
     if User.query.count() < 1:
         raise "You need to create the admin user first!"
 
@@ -158,9 +185,8 @@ def create_welcome_forum():
 
 
 def create_test_data():
-    """
-    Creates 5 users, 2 categories and 2 forums in each category. It also opens
-    a new topic topic in each forum with a post.
+    """Creates 5 users, 2 categories and 2 forums in each category.
+    It also creates a new topic topic in each forum with a post.
     """
     create_default_groups()
     create_default_settings()
@@ -208,8 +234,7 @@ def create_test_data():
 
 
 def insert_mass_data(topics=100, posts=100):
-    """
-    Creates 100 topics in the first forum and each topic has 100 posts.
+    """Creates 100 topics in the first forum and each topic has 100 posts.
     Returns ``True`` if the topics and posts were successfully created.
 
     :param topics: The amount of topics in the forum.

flaskbb/utils/widgets.py

@@ -13,8 +13,7 @@ from wtforms.widgets.core import Select, HTMLString, html_params
 
 
 class SelectDateWidget(object):
-    """
-    Renders a DateTime field with 3 selects.
+    """Renders a DateTime field with 3 selects.
     For more information see: http://stackoverflow.com/a/14664504
     """
     FORMAT_CHOICES = {

manage.py

@@ -69,43 +69,14 @@ def initdb():
 
 @manager.command
 def dropdb():
-    """Deletes the database"""
+    """Deletes the database."""
 
     db.drop_all()
 
 
-@manager.option('-s', '--settings', dest="settings")
-@manager.option('-f', '--force', dest="force")
-def update(settings=None, force=False):
-    """Updates the settings via a fixture. All fixtures have to be placed
-    in the `fixture`.
-    Usage: python manage.py update -s your_fixture
-    """
-    try:
-        fixture = import_string(
-            "flaskbb.fixtures.{}".format(settings)
-        )
-        fixture = fixture.fixture
-    except ImportError:
-        raise "{} fixture is not available".format(settings)
-
-    if force:
-        count = update_settings_from_fixture(fixture, overwrite_group=True,
-                                             overwrite_setting=True)
-        app.logger.info(
-            "{} groups and {} settings forcefully updated."
-            .format(count[0], count[1])
-        )
-    else:
-        count = update_settings_from_fixture(fixture)
-        app.logger.info(
-            "{} groups and {} settings updated.".format(count[0], count[1])
-        )
-
-
 @manager.command
-def createall(dropdb=False, createdb=False):
-    """Creates the database with some testing content.
+def populate(dropdb=False, createdb=False):
+    """Creates the database with some default data.
     If you do not want to drop or create the db add
     '-c' (to not create the db) and '-d' (to not drop the db)
     """
@@ -126,7 +97,7 @@ def createall(dropdb=False, createdb=False):
 @manager.option('-p', '--password', dest='password')
 @manager.option('-e', '--email', dest='email')
 def create_admin(username=None, password=None, email=None):
-    """Creates the admin user"""
+    """Creates the admin user."""
 
     if not (username and password and email):
         username = prompt("Username")
@@ -139,8 +110,8 @@ def create_admin(username=None, password=None, email=None):
 @manager.option('-u', '--username', dest='username')
 @manager.option('-p', '--password', dest='password')
 @manager.option('-e', '--email', dest='email')
-def initflaskbb(username=None, password=None, email=None):
-    """Initializes FlaskBB with all necessary data"""
+def init(username=None, password=None, email=None):
+    """Initializes FlaskBB with all necessary data."""
 
     app.logger.info("Creating default data...")
     try:
@@ -149,7 +120,8 @@ def initflaskbb(username=None, password=None, email=None):
     except IntegrityError:
         app.logger.error("Couldn't create the default data because it already "
                          "exist!")
-        if prompt_bool("Do you want to recreate the database? (y/n)"):
+        if prompt_bool("Found an existing database."
+                       "Do you want to recreate the database? (y/n)"):
             db.session.rollback()
             db.drop_all()
             upgrade()
@@ -187,11 +159,40 @@ def insertmassdata():
     insert_mass_data()
 
 
+@manager.option('-s', '--settings', dest="settings")
+@manager.option('-f', '--force', dest="force", default=False)
+def update(settings=None, force=False):
+    """Updates the settings via a fixture. All fixtures have to be placed
+    in the `fixture`.
+    Usage: python manage.py update -s your_fixture
+    """
+
+    try:
+        fixture = import_string(
+            "flaskbb.fixtures.{}".format(settings)
+        )
+        fixture = fixture.fixture
+    except ImportError:
+        raise "{} fixture is not available".format(settings)
+
+    if force:
+        count = update_settings_from_fixture(fixture, overwrite_group=True,
+                                             overwrite_setting=True)
+        app.logger.info(
+            "{} groups and {} settings forcefully updated."
+            .format(count[0], count[1])
+        )
+    else:
+        count = update_settings_from_fixture(fixture)
+        app.logger.info(
+            "{} groups and {} settings updated.".format(count[0], count[1])
+        )
+
+
 @manager.command
 def update_translations():
-    """
-    Updates the translations
-    """
+    """Updates the translations."""
+
     translations_folder = os.path.join(app.root_path, "translations")
     source_file = os.path.join(translations_folder, "messages.pot")
 
@@ -203,9 +204,8 @@ def update_translations():
 
 @manager.command
 def add_translations(translation):
-    """
-    Adds a new language to the translations
-    """
+    """Adds a new language to the translations."""
+
     translations_folder = os.path.join(app.root_path, "translations")
     source_file = os.path.join(translations_folder, "messages.pot")
 
@@ -217,9 +217,8 @@ def add_translations(translation):
 
 @manager.command
 def compile_translations():
-    """
-    Compiles the translations.
-    """
+    """Compiles the translations."""
+
     translations_folder = os.path.join(app.root_path, "translations")
 
     subprocess.call(["pybabel", "compile", "-d", translations_folder])
@@ -228,10 +227,10 @@ def compile_translations():
 # Plugin translation commands
 @manager.command
 def add_plugin_translations(plugin, translation):
+    """Adds a new language to the plugin translations. Expects the name
+    of the plugin and the translations name like "en".
     """
-    Adds a new language to the plugin translations
-    Expects the name of the plugin and the translations name like "en"
-    """
+
     plugin_folder = os.path.join(PLUGINS_FOLDER, plugin)
     translations_folder = os.path.join(plugin_folder, "translations")
 
@@ -245,10 +244,8 @@ def add_plugin_translations(plugin, translation):
 
 @manager.command
 def update_plugin_translations(plugin):
-    """
-    Updates the plugin translations
-    Expects the name of the plugin.
-    """
+    """Updates the plugin translations. Expects the name of the plugin."""
+
     plugin_folder = os.path.join(PLUGINS_FOLDER, plugin)
     translations_folder = os.path.join(plugin_folder, "translations")
 
@@ -262,10 +259,8 @@ def update_plugin_translations(plugin):
 
 @manager.command
 def compile_plugin_translations(plugin):
-    """
-    Compile the plugin translations.
-    Expects the name of the plugin.
-    """
+    """Compile the plugin translations. Expects the name of the plugin."""
+
     plugin_folder = os.path.join(PLUGINS_FOLDER, plugin)
     translations_folder = os.path.join(plugin_folder, "translations")