From 1ae140c11e7be9750e40394f49a27afdefb4e4b0 Mon Sep 17 00:00:00 2001 From: Oskar Hahn Date: Sat, 26 Jan 2013 12:28:51 +0100 Subject: [PATCH] Add docstrings to the motion class --- openslides/motion/models.py | 105 +++++++++++++++++++++++++++++------- openslides/motion/urls.py | 2 +- openslides/motion/views.py | 17 +++++- 3 files changed, 104 insertions(+), 20 deletions(-) diff --git a/openslides/motion/models.py b/openslides/motion/models.py index 780e848bc..6b68bda19 100644 --- a/openslides/motion/models.py +++ b/openslides/motion/models.py @@ -37,6 +37,12 @@ RELATION = ( class RelatedPersonsManager(models.Manager): + """ + Manager for MotionRelatedPersons. + + Returns a custom manager with gives a specific queryset for one type of + persons. + """ def __init__(self, relation, *args, **kwargs): super(RelatedPersonsManager, self).__init__(*args, **kwargs) for key, value in RELATION: @@ -52,6 +58,15 @@ class RelatedPersonsManager(models.Manager): class MotionRelatedPersons(models.Model): + """ + Saves the all persons related to a motion. + + relation = 1: submitter + relation = 2: supporter + + The custom manager submitter and supporter return a queryset with the + specific persons. + """ submitter = RelatedPersonsManager(relation=1) supporter = RelatedPersonsManager(relation=2) objects = models.Manager() @@ -62,6 +77,9 @@ class MotionRelatedPersons(models.Model): class Motion(SlideMixin, models.Model): + """ + The Motion-Model. + """ prefix = "motion" # Rename this in the slide-system # TODO: Use this attribute for the default_version, if the permission system @@ -93,13 +111,16 @@ class Motion(SlideMixin, models.Model): # TODO: Use transaction def save(self, *args, **kwargs): + """ + Saves the motion. Create or update a motion_version object + """ super(Motion, self).save(*args, **kwargs) new_data = False for attr in ['_title', '_text', '_reason']: if hasattr(self, attr): new_data = True break - need_new_version = True # TODO: Do we need a new version (look in config) + need_new_version = True # TODO: Do we need a new version (look in config) if hasattr(self, '_version') or (new_data and need_new_version): version = self.new_version del self._new_version @@ -127,70 +148,114 @@ class Motion(SlideMixin, models.Model): return reverse('motion_delete', args=[str(self.id)]) def get_title(self): + """ + Get the title of the motion. The titel is taken from motion.version + """ try: return self._title except AttributeError: - return self.default_version.title + return self.version.title def set_title(self, title): + """ + Set the titel of the motion. The titel will me saved in motion.save() + """ self._title = title title = property(get_title, set_title) def get_text(self): + """ + Get the text of the motion. Simular to get_title() + """ try: return self._text except AttributeError: - return self.default_version.text + return self.version.text def set_text(self, text): + """ + Set the text of the motion. Simular to set_title() + """ self._text = text text = property(get_text, set_text) def get_reason(self): + """ + Get the reason of the motion. Simular to get_title() + """ try: return self._reason except AttributeError: - return self.default_version.reason + return self.version.reason def set_reason(self, reason): + """ + Set the reason of the motion. Simular to set_title() + """ self._reason = reason reason = property(get_reason, set_reason) + @property + def submitter(self): + """ + Return a queryset with all submitter of this motion. + """ + return MotionRelatedPersons.submitter.filter(motion=self) + + @property + def supporter(self): + """ + Returns a queryset with all supporter of this motion. + """ + return MotionRelatedPersons.supporter.filter(motion=self) + @property def new_version(self): + """ + On the first call, it creates a new version. On any later call, it + use the existing new version. + + The new_version object will be deleted when it is saved into the db + """ try: return self._new_version except AttributeError: self._new_version = MotionVersion(motion=self) return self._new_version - @property - def submitter(self): - return MotionRelatedPersons.submitter.filter(motion=self) - - @property - def supporter(self): - return MotionRelatedPersons.supporter.filter(motion=self) - def get_version(self, version_id): + """ + Return a specific version from version_id + """ # TODO: Check case, if version_id is not one of this motion return self.versions.get(pk=version_id) - def get_default_version(self): + def get_version(self): + """ + Get the "active" version object. This version will be used to get the + data for this motion. + """ try: - return self._default_version + return self._version except AttributeError: # TODO: choose right version via config return self.last_version - def set_default_version(self, version): + def set_version(self, version): + """ + Set the "active" version object. + + If version is None, the last_version will be used. + If version is a version object, this object will be used. + If version is Int, the N version of this motion will be used. + """ if version is None: try: - del self._default_version + del self._version except AttributeError: pass else: @@ -199,12 +264,16 @@ class Motion(SlideMixin, models.Model): elif type(version) is not MotionVersion: raise ValueError('The argument \'version\' has to be int or ' 'MotionVersion, not %s' % type(version)) - self._default_version = version + # TODO: Test, that the version is one of this motion + self._version = version - default_version = property(get_default_version, set_default_version) + version = property(get_version, set_version) @property def last_version(self): + """ + Get the newest version of the motion + """ # TODO: Fix the case, that the motion has no Version try: return self.versions.order_by('id').reverse()[0] diff --git a/openslides/motion/urls.py b/openslides/motion/urls.py index 3020f074e..59b9b7b2d 100644 --- a/openslides/motion/urls.py +++ b/openslides/motion/urls.py @@ -33,7 +33,7 @@ urlpatterns = patterns('openslides.motion.views', name='motion_edit', ), - url(r'^(?P\d+)/version/(?P\d+)/$', + url(r'^(?P\d+)/version/(?P[1-9]\d*)/$', 'motion_detail', name='motion_version_detail', ), diff --git a/openslides/motion/views.py b/openslides/motion/views.py index 49f4a7ffc..3121c3efd 100644 --- a/openslides/motion/views.py +++ b/openslides/motion/views.py @@ -34,6 +34,9 @@ from django.views.generic.edit import ModelFormMixin class MotionListView(ListView): + """ + List all motion. + """ permission_required = 'motion.can_see_motion' model = Motion @@ -41,6 +44,9 @@ motion_list = MotionListView.as_view() class MotionDetailView(DetailView): + """ + Show the details of one motion. + """ permission_required = 'motion.can_see_motion' model = Motion template_name = 'motion/motion_detail.html' @@ -49,19 +55,25 @@ class MotionDetailView(DetailView): object = super(MotionDetailView, self).get_object() version_id = self.kwargs.get('version_id', None) if version_id is not None: - object.default_version = int(version_id) -1 + object.version = int(version_id) -1 return object motion_detail = MotionDetailView.as_view() class MotionMixin(object): + """ + Mixin to add save the version-data to the motion-object + """ def manipulate_object(self, form): for attr in ['title', 'text', 'reason']: setattr(self.object, attr, form.cleaned_data[attr]) class MotionCreateView(MotionMixin, CreateView): + """ + Create a motion. + """ permission_required = 'motion.can_create_motion' model = Motion form_class = MotionCreateForm @@ -70,6 +82,9 @@ motion_create = MotionCreateView.as_view() class MotionUpdateView(MotionMixin, UpdateView): + """ + Update a motion. + """ model = Motion form_class = MotionUpdateForm