From 93b02fa62bd280b01e43c351285435475a26cf50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Norman=20J=C3=A4ckel?= Date: Sun, 2 Jun 2013 22:23:58 +0200 Subject: [PATCH] Update docstrings, small enhancements to Oskar's motion rework. --- openslides/motion/models.py | 71 ++++++++++++++++++------------------- openslides/motion/views.py | 26 ++++++++------ 2 files changed, 49 insertions(+), 48 deletions(-) diff --git a/openslides/motion/models.py b/openslides/motion/models.py index fcd9c9548..0fdeee171 100644 --- a/openslides/motion/models.py +++ b/openslides/motion/models.py @@ -109,49 +109,44 @@ class Motion(SlideMixin, models.Model): 1. Set the state of a new motion to the default state. 2. Ensure that the identifier is not an empty string. 3. Save the motion object. - 4. Save the version data - 5. Set the active version for the motion, if a new version object was saved. + 4. Save the version data. + 5. Set the active version for the motion if a new version object was saved. The version data is *not* saved, if - 1. The django-feature 'update_fields' is used or - 2. The argument use_version is False (differ to None). + 1. the django-feature 'update_fields' is used or + 2. the argument use_version is False (differ to None). - The version object into which the data is saved is picked in this order: - 1. The argument use_version. - 2. The attribute use_version. As default, use_version is the - active_version. If the active_version is not set, it is the - last_version. If the last_version is not set, it is a - new_version. See use_version property. + The argument use_version is choose the version object into which the + version data is saved. + * If use_version is False, no version data is saved. + * If use_version is None, the last version is used. + * Else the given version is used. - use_version is the version object, in which the version data is saved. - * If use_version is False, no version data ist saved. - * If use_version is None, the last version is used. - - To use a new version object, you have to set it via use_version. You have - to set the title, text and reason into this version object. motion.title - etc will be ignored. + To create and use a new version object, you have to set it via the + use_version argument. You have to set the title, text and reason into + this version object before giving it to this save method. The properties + motion.title, motion.text and motion.reason will be ignored. """ if not self.state: self.reset_state() # Solves the problem, that there can only be one motion with an empty - # string as identifier + # string as identifier. if self.identifier is '': self.identifier = None super(Motion, self).save(*args, **kwargs) if 'update_fields' in kwargs: - # Do not save the version-data, if only some motion fields are updated + # Do not save the version data if only some motion fields are updated. return if use_version is False: - # We do not need to save the version + # We do not need to save the version. return elif use_version is None: use_version = self.get_last_version() - - # Save title, text and reason in the version object. + # Save title, text and reason into the version object. for attr in ['title', 'text', 'reason']: _attr = '_%s' % attr data = getattr(self, _attr, None) @@ -160,22 +155,24 @@ class Motion(SlideMixin, models.Model): delattr(self, _attr) # If version is not in the database, test if it has new data and set - # the version_number + # the version_number. if use_version.id is None: if not self.version_data_changed(use_version): - # We do not need to save the version + # We do not need to save the version. return version_number = self.versions.aggregate(Max('version_number'))['version_number__max'] or 0 use_version.version_number = version_number + 1 - # Necessary line, if the version was set before the motion had an id. - # propably a django bug. + # Necessary line if the version was set before the motion got an id. + # This is probably a Django bug. use_version.motion = use_version.motion use_version.save() # Set the active version of this motion. This has to be done after the - # version is saved to the database + # version is saved in the database. + # TODO: Move parts of these last lines of code outside the save method + # when other versions than the last ones should be edited later on. if self.active_version is None or not self.state.leave_old_version_active: self.active_version = use_version self.save(update_fields=['active_version']) @@ -198,11 +195,11 @@ class Motion(SlideMixin, models.Model): """ Compare the version with the last version of the motion. - Returns True if the version data (title, text, reason) is different. - Else, returns False. + Returns True if the version data (title, text, reason) is different, + else returns False. """ if not self.versions.exists(): - # if there is no version in the database, the data has always changed + # If there is no version in the database, the data has always changed. return True last_version = self.get_last_version() @@ -214,7 +211,7 @@ class Motion(SlideMixin, models.Model): def set_identifier(self): """ Sets the motion identifier automaticly according to the config - value, if it is not set yet. + value if it is not set yet. """ if config['motion_identifier'] == 'manually' or self.identifier: # Do not set an identifier. @@ -254,7 +251,7 @@ class Motion(SlideMixin, models.Model): """ Set the titel of the motion. - The title will be saved into the version object, wenn motion.save() is + The title will be saved in the version object, when motion.save() is called. """ self._title = title @@ -324,7 +321,7 @@ class Motion(SlideMixin, models.Model): The version data of the new version object is populated with the data set via motion.title, motion.text, motion.reason. If the data is not set, - it is population with the data from the last version object. + it is populated with the data from the last version object. """ new_version = MotionVersion(motion=self) if self.versions.exists(): @@ -334,7 +331,7 @@ class Motion(SlideMixin, models.Model): for attr in ['title', 'text', 'reason']: _attr = '_%s' % attr data = getattr(self, _attr, None) - if data is None and not last_version is None: + if data is None and last_version is not None: data = getattr(last_version, attr) if data is not None: setattr(new_version, attr, data) @@ -344,7 +341,7 @@ class Motion(SlideMixin, models.Model): """ Returns the active version of the motion. - If no active version is set by now, the last_version is used + If no active version is set by now, the last_version is used. """ if self.active_version: return self.active_version @@ -796,7 +793,7 @@ class State(models.Model): return self.name def save(self, **kwargs): - """Saves a state to the database. + """Saves a state in the database. Used to check the integrity before saving. """ @@ -831,7 +828,7 @@ class Workflow(models.Model): return self.name def save(self, **kwargs): - """Saves a workflow to the database. + """Saves a workflow in the database. Used to check the integrity before saving. """ diff --git a/openslides/motion/views.py b/openslides/motion/views.py index c93c8128a..4097304be 100644 --- a/openslides/motion/views.py +++ b/openslides/motion/views.py @@ -8,7 +8,7 @@ The views are automaticly imported from openslides.motion.urls. - :copyright: (c) 2011-2013 by the OpenSlides team, see AUTHORS. + :copyright: (c) 2011–2013 by the OpenSlides team, see AUTHORS. :license: GNU GPL, see LICENSE for more details. """ @@ -64,7 +64,8 @@ class MotionDetailView(DetailView): """ Return the template context. - Append the allowed actions for the motion to the context. + Append the allowed actions for the motion, the shown version and its + data to the context. """ version_number = self.kwargs.get('version_number', None) if version_number is not None: @@ -88,12 +89,12 @@ motion_detail = MotionDetailView.as_view() class MotionEditMixin(object): """ - Mixin for MotionViewsClasses to save the version data. + Mixin for motion views classes to save the version data. """ def form_valid(self, form): """ - Saves the Create or UpdateForm into a motion object. + Saves the CreateForm or UpdateForm into a motion object. """ self.object = form.save(commit=False) @@ -127,7 +128,7 @@ class MotionEditMixin(object): self.object.save(use_version=version) # Save the submitter an the supporter so the motion. - # TODO: only delete and save neccessary submitters and supporter + # TODO: Only delete and save neccessary submitters and supporters if 'submitter' in form.cleaned_data: self.object.submitter.all().delete() MotionSubmitter.objects.bulk_create( @@ -142,7 +143,7 @@ class MotionEditMixin(object): def get_form_class(self): """ - Return the FormClass to Create or Update the Motion. + Return the FormClass to create or update the motion. forms.BaseMotionForm is the base for the Class, and some FormMixins will be mixed in dependence of some config values. See motion.forms @@ -189,7 +190,7 @@ class MotionCreateView(MotionEditMixin, CreateView): def form_valid(self, form): """ - Write a log message, if the form is valid. + Write a log message if the form is valid. """ response = super(MotionCreateView, self).form_valid(form) self.object.write_log([ugettext_noop('Motion created')], self.request.user) @@ -207,17 +208,21 @@ class MotionUpdateView(MotionEditMixin, UpdateView): model = Motion def has_permission(self, request, *args, **kwargs): - """Check, if the request.user has the permission to edit the motion.""" + """ + Check if the request.user has the permission to edit the motion. + """ return self.get_object().get_allowed_actions(request.user)['update'] def form_valid(self, form): - """Write a log message, if the form is valid.""" + """ + Write a log message if the form is valid. + """ response = super(MotionUpdateView, self).form_valid(form) + self.object.write_log([ugettext_noop('Motion updated')], self.request.user) if (config['motion_remove_supporters'] and self.object.state.allow_support and not self.request.user.has_perm('motion.can_manage_motion')): self.object.clear_supporters() self.object.write_log([ugettext_noop('All supporters removed')], self.request.user) - self.object.write_log([ugettext_noop('Motion updated')], self.request.user) return response motion_edit = MotionUpdateView.as_view() @@ -246,7 +251,6 @@ class VersionPermitView(SingleObjectMixin, QuestionMixin, RedirectView): """ View to permit a version of a motion. """ - model = Motion question_url_name = 'motion_version_detail' success_url_name = 'motion_version_detail'