Proper docstrings added

Author: monim67

bootstrap_datepicker_plus/__init__.py

@@ -1,5 +1,8 @@
+"""This module contains the widget classes."""
+
 from bootstrap_datepicker_plus._base import BasePickerInput
 
+
 __all__ = (
     'DatePickerInput',
     'TimePickerInput',
@@ -10,35 +13,81 @@
 
 
 class DatePickerInput(BasePickerInput):
+    """
+    Widget to display a Date-Picker Calendar on a DateField property.
+
+    Args:
+        - attrs (dict): HTML attributes of rendered HTML input
+        - format (string): Python DateTime format eg. "%Y-%m-%d"
+        - options (dict): Options to customize the widget, see README
+    """
+
     picker_type = 'DATE'
     format = '%m/%d/%Y'
     format_key = 'DATE_INPUT_FORMATS'
 
 
 class TimePickerInput(BasePickerInput):
+    """
+    Widget to display a Time-Picker Calendar on a TimeField property.
+
+    Args:
+        - attrs (dict): HTML attributes of rendered HTML input
+        - format (string): Python DateTime format eg. "%Y-%m-%d"
+        - options (dict): Options to customize the widget, see README
+    """
+
     picker_type = 'TIME'
     format = '%H:%M'
     format_key = 'TIME_INPUT_FORMATS'
     template_name = 'bootstrap_datepicker_plus/time-picker.html'
 
 
 class DateTimePickerInput(BasePickerInput):
+    """
+    Widget to display a DateTime-Picker Calendar on a DateTimeField property.
+
+    Args:
+        - attrs (dict): HTML attributes of rendered HTML input
+        - format (string): Python DateTime format eg. "%Y-%m-%d"
+        - options (dict): Options to customize the widget, see README
+    """
+
     picker_type = 'DATETIME'
     format = '%m/%d/%Y %H:%M'
     format_key = 'DATETIME_INPUT_FORMATS'
 
 
 class MonthPickerInput(BasePickerInput):
+    """
+    Widget to display a Month-Picker Calendar on a DateField property.
+
+    Args:
+        - attrs (dict): HTML attributes of rendered HTML input
+        - format (string): Python DateTime format eg. "%Y-%m-%d"
+        - options (dict): Options to customize the widget, see README
+    """
+
     picker_type = 'MONTH'
     format = '%Y-%m-01'
     format_key = 'DATE_INPUT_FORMATS'
 
 
 class YearPickerInput(BasePickerInput):
+    """
+    Widget to display a Year-Picker Calendar on a DateField property.
+
+    Args:
+        - attrs (dict): HTML attributes of rendered HTML input
+        - format (string): Python DateTime format eg. "%Y-%m-%d"
+        - options (dict): Options to customize the widget, see README
+    """
+
     picker_type = 'YEAR'
     format = '%Y-01-01'
     format_key = 'DATE_INPUT_FORMATS'
 
     def _link_to(self, linked_picker):
+        """Customize the options when linked with other date-time input"""
         yformat = self.config['options']['format'].replace('-01-01', '-12-31')
         self.config['options']['format'] = yformat

bootstrap_datepicker_plus/_base.py

@@ -1,4 +1,6 @@
 # -*- coding: utf-8 -*-
+"""Contains Base Date-Picker input class for widgets of this package."""
+
 from json import dumps as json_dumps
 from bootstrap_datepicker_plus._helpers import (
     get_base_input,
@@ -7,6 +9,8 @@
 
 
 class BasePickerInput(get_base_input()):
+    """Base Date-Picker input class for widgets of this package."""
+
     template_name = 'bootstrap_datepicker_plus/date-picker.html'
     picker_type = 'DATE'
     format = '%m/%d/%Y'
@@ -44,6 +48,8 @@ class BasePickerInput(get_base_input()):
     )
 
     class Media:
+        """JS/CSS resources needed to render the date-picker calendar."""
+
         js = (
             'https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.9.0/'
             'moment-with-locales.min.js',
@@ -59,19 +65,20 @@ class Media:
 
     @classmethod
     def format_py2js(cls, datetime_format):
-        ''' convert python datetime format to moment format '''
+        """Convert python datetime format to moment datetime format."""
         for js_format, py_format in cls.format_map:
             datetime_format = datetime_format.replace(py_format, js_format)
         return datetime_format
 
     @classmethod
     def format_js2py(cls, datetime_format):
-        ''' convert moment format to python datetime format '''
+        """Convert moment datetime format to python datetime format."""
         for js_format, py_format in cls.format_map:
             datetime_format = datetime_format.replace(js_format, py_format)
         return datetime_format
 
     def __init__(self, attrs=None, format=None, options=None):
+        """Initialize the Date-picker widget."""
         self.format_param = format
         self.options_param = options if options else {}
         self.config = self._default_config.copy()
@@ -84,13 +91,15 @@ def __init__(self, attrs=None, format=None, options=None):
         super().__init__(attrs, self._calculate_format())
 
     def _calculate_options(self):
+        """Calculate and Return the options."""
         _options = self._default_options.copy()
         _options.update(self.options)
         if self.options_param:
             _options.update(self.options_param)
         return _options
 
     def _calculate_format(self):
+        """Calculate and Return the datetime format."""
         _format = self.format_param if self.format_param else self.format
         if self.config['options'].get('format'):
             _format = self.format_js2py(self.config['options'].get('format'))
@@ -99,27 +108,31 @@ def _calculate_format(self):
         return _format
 
     def get_context(self, name, value, attrs):
+        """Return widget context dictionary."""
         context = super().get_context(
             name, value, attrs)
         context['widget']['attrs']['dp_config'] = json_dumps(self.config)
         return context
 
     def start_of(self, event_id):
-        '''
-        Set Datepicker as the start-date of a date-range
+        """
+        Set Date-Picker as the start-date of a date-range.
 
-        event_id => a user-defined unique string to identify the date-range
-        '''
+        Args:
+            - event_id (string): User-defined unique id for linking two fields
+        """
         DatePickerDictionary.items[str(event_id)] = self
         return self
 
     def end_of(self, event_id, import_options=True):
-        '''
-        Set Datepicker as the end-date of a date-range
+        """
+        Set Date-Picker as the end-date of a date-range.
 
-        event_id => a user-defined unique string to identify the date-range
-        import_options => import options from other input, default is TRUE
-        '''
+        Args:
+            - event_id (string): User-defined unique id for linking two fields
+            - import_options (bool): inherit options from start-date input,
+              default: TRUE
+        """
         event_id = str(event_id)
         if event_id in DatePickerDictionary.items:
             linked_picker = DatePickerDictionary.items[event_id]
@@ -142,4 +155,9 @@ def end_of(self, event_id, import_options=True):
         return self
 
     def _link_to(self, linked_picker):
+        """
+        Executed when two date-inputs are linked together.
+
+        This method for sub-classes to override to customize the linking.
+        """
         pass

bootstrap_datepicker_plus/_compatibility.py

@@ -1,4 +1,6 @@
 # -*- coding: utf-8 -*-
+"""Contains fallback/missing classes and methods for older django versions."""
+
 from functools import lru_cache
 from pathlib import Path
 
@@ -12,20 +14,28 @@
 
 
 class BaseRenderer:
+    """Missing class from django.forms.renderers module."""
+
     def get_template(self, template_name):
+        """Return template name."""
         raise NotImplementedError('subclasses must implement get_template()')
 
     def render(self, template_name, context, request=None):
+        """Render template from template_name."""
         template = self.get_template(template_name)
         return template.render(context, request=request).strip()
 
 
 class EngineMixin:
+    """Missing class from django.forms.renderers module."""
+
     def get_template(self, template_name):
+        """Return template name."""
         return self.engine.get_template(template_name)
 
     @cached_property
     def engine(self):
+        """Return Render Engine."""
         return self.backend({
             'APP_DIRS': True,
             'DIRS': [str(ROOT / self.backend.app_dirname)],
@@ -36,28 +46,40 @@ def engine(self):
 
 class DjangoTemplateRenderer(EngineMixin, BaseRenderer):
     """
+    Missing default template renderer from django.forms.renderers module.
+
     Load Django templates from the built-in widget templates in
     django/forms/templates and from apps' 'templates' directory.
     """
+
     backend = DjangoTemplates
 
 
 @lru_cache()
 def get_default_renderer():
+    """Missing method from django.forms.renderers module."""
     return DjangoTemplateRenderer()
 
 
 class CompatibleDateTimeBaseInput(DateTimeBaseInput):
+    """Fallback class containing methods missing in older django version."""
+
     format = '%m/%d/%Y'
     format_key = 'DATE_INPUT_FORMATS'
     template_name = 'bootstrap_datepicker_plus/date-picker.html'
 
     def format_value(self, value):
+        """
+        Return a value as it should appear when rendered in a template.
+
+        Missing method of django.forms.widgets.Widget class
+        """
         if value == '' or value is None:
             return None
         return formats.localize_input(value, self.format)
 
     def get_context(self, name, value, attrs):
+        """Missing method of django.forms.widgets.Widget class."""
         context = {}
         context['widget'] = {
             'name': name,
@@ -71,11 +93,16 @@ def get_context(self, name, value, attrs):
         return context
 
     def render(self, name, value, attrs=None, renderer=None):
-        """Render the widget as an HTML string."""
+        """
+        Render the widget as an HTML string.
+
+        Missing method of django.forms.widgets.Widget class
+        """
         context = self.get_context(name, value, attrs)
         return self._render(self.template_name, context, renderer)
 
     def _render(self, template_name, context, renderer=None):
+        """Missing method of django.forms.widgets.Widget class."""
         if renderer is None:
             renderer = get_default_renderer()
         return mark_safe(renderer.render(template_name, context))

bootstrap_datepicker_plus/_helpers.py

@@ -1,4 +1,12 @@
+"""Contains the helper classes and methods used throughout the project."""
+
+
 def get_base_input(test=False):
+    """
+    Return DateTimeBaseInput class from django.forms.widgets module
+
+    Return _compatibility.DateTimeBaseInput class for older django versions.
+    """
     from django.forms.widgets import DateTimeBaseInput
     if 'get_context' in dir(DateTimeBaseInput) and not test:
         # django version 1.11 and above
@@ -13,10 +21,13 @@ def get_base_input(test=False):
 
 
 class DatePickerDictionary:
+    """Keeps track of all date-picker input classes."""
+
     _i = 0
     items = dict()
 
     @classmethod
     def generate_id(cls):
+        """Return a unique ID for each date-picker input class."""
         cls._i += 1
         return 'dp_%s' % cls._i