Add param types and return to functions

embed_video/admin.py

@@ -24,6 +24,9 @@ class AdminVideoWidget(forms.TextInput):
                     u'<hr style="visibility: hidden; clear:both">'
 
     def __init__(self, attrs=None):
+        """
+        :type attrs: dict
+        """
         default_attrs = {'size': '40'}
 
         if attrs:
@@ -32,6 +35,10 @@ class AdminVideoWidget(forms.TextInput):
         super(AdminVideoWidget, self).__init__(default_attrs)
 
     def render(self, name, value='', attrs=None, size=(420, 315)):
+        """
+        :type name: str
+        :type attrs: dict
+        """
         output = super(AdminVideoWidget, self).render(name, value, attrs)
 
         if not value:
@@ -66,8 +73,11 @@ class AdminVideoMixin(object):
     """
 
     def formfield_for_dbfield(self, db_field, **kwargs):
+        """
+        :type db_field: str
+        """
         if isinstance(db_field, EmbedVideoField):
             return db_field.formfield(widget=AdminVideoWidget)
 
-        return super(AdminVideoMixin, self) \
+        return super(AdminVideoMixin, self)\
             .formfield_for_dbfield(db_field, **kwargs)

embed_video/backends.py

@@ -46,6 +46,12 @@ def detect_backend(url):
 
     Goes over backends in ``settings.EMBED_VIDEO_BACKENDS``,
     calls :py:func:`~VideoBackend.is_valid` and returns backend instance.
+
+    :param url: URL which is passed to `is_valid` methods of VideoBackends.
+    :type url: str
+
+    :return: Returns recognized VideoBackend
+    :rtype: VideoBackend
     """
 
     for backend_name in EMBED_VIDEO_BACKENDS:
@@ -102,6 +108,8 @@ class VideoBackend(object):
     Pattern in which the code is inserted.
 
     Example: ``http://myvideo.com?code=%s``
+
+    :type: str
     """
 
     pattern_thumbnail_url = None
@@ -109,11 +117,15 @@ class VideoBackend(object):
     Pattern in which the code is inserted to get thumbnail url.
 
     Example: ``http://static.myvideo.com/thumbs/%s``
+
+    :type: str
     """
 
     allow_https = True
     """
     Sets if HTTPS version allowed for specific backend.
+
+    :type: bool
     """
 
     template_name = 'embed_video/embed_code.html'
@@ -122,22 +134,30 @@ class VideoBackend(object):
 
     Passed template variables: ``{{ backend }}`` (instance of VideoBackend),
     ``{{ width }}``, ``{{ height }}``
+
+    :type: str
     """
 
     default_query = ''
     """
     Default query string or `QueryDict` appended to url
+
+    :type: str
     """
 
     is_secure = False
     """
     Decides if secured protocol (HTTPS) is used.
+
+    :type: bool
     """
 
     def __init__(self, url):
         """
         First it tries to load data from cache and if it don't succeed, run
         :py:meth:`init` and then save it to cache.
+
+        :type url: str
         """
         self.backend = self.__class__.__name__
         self._url = url
@@ -187,6 +207,9 @@ class VideoBackend(object):
 
     @query.setter
     def query(self, value):
+        """
+        :type value: QueryDict | str
+        """
         self._query = value \
             if isinstance(value, QueryDict) \
             else QueryDict(value, mutable=True)
@@ -196,12 +219,16 @@ class VideoBackend(object):
         """
         Class method to control if passed url is valid for current backend. By
         default it is done by :py:data:`re_detect` regex.
+
+        :type url: str
         """
         return True if cls.re_detect.match(url) else False
 
     def get_code(self):
         """
         Returns video code matched from given url by :py:data:`re_code`.
+
+        :rtype: str
         """
         match = self.re_code.search(self._url)
         if match:
@@ -219,6 +246,8 @@ class VideoBackend(object):
         """
         Returns thumbnail URL folded from :py:data:`pattern_thumbnail_url` and
         parsed code.
+
+        :rtype: str
         """
         return self.pattern_thumbnail_url.format(code=self.code,
                                                  protocol=self.protocol)
@@ -226,6 +255,10 @@ class VideoBackend(object):
     def get_embed_code(self, width, height):
         """
         Returns embed code rendered from template :py:data:`template_name`.
+
+        :type width: int | str
+        :type height: int | str
+        :rtype: str
         """
         return render_to_string(self.template_name, {
             'backend': self,
@@ -234,9 +267,15 @@ class VideoBackend(object):
         })
 
     def get_info(self):
+        """
+        :rtype: dict
+        """
         raise NotImplementedError
 
     def set_options(self, options):
+        """
+        :type options: dict
+        """
         for key in options:
             setattr(self, key, options[key])
 
@@ -321,10 +360,16 @@ class SoundCloudBackend(VideoBackend):
 
     @cached_property
     def width(self):
+        """
+        :rtype: str
+        """
         return self.info.get('width')
 
     @cached_property
     def height(self):
+        """
+        :rtype: str
+        """
         return self.info.get('height')
 
     def get_info(self):

embed_video/settings.py

@@ -6,8 +6,11 @@ EMBED_VIDEO_BACKENDS = getattr(settings, 'EMBED_VIDEO_BACKENDS', (
     'embed_video.backends.VimeoBackend',
     'embed_video.backends.SoundCloudBackend',
 ))
+""" :type: tuple[str] """
 
 EMBED_VIDEO_TIMEOUT = getattr(settings, 'EMBED_VIDEO_TIMEOUT', 10)
+""" :type: int """
 
 EMBED_VIDEO_YOUTUBE_DEFAULT_QUERY = \
     getattr(settings, 'EMBED_VIDEO_YOUTUBE_DEFAULT_QUERY', 'wmode=opaque')
+""" :type: django.db.models.QuerySet | str """

embed_video/templatetags/embed_video_tags.py

@@ -59,6 +59,12 @@ class VideoNode(Node):
     re_option = re.compile(r'^(?P<key>[\w]+)=(?P<value>.+)$')
 
     def __init__(self, parser, token):
+        """
+        :param parser: Django template parser
+        :type parser: django.template.base.Parser
+        :param token: Django template token
+        :type token: django.template.base.Token
+        """
         self.parser = parser
         self.bits = list(token.split_contents())
         self.tag_name = str(self.pop_bit())
@@ -88,6 +94,14 @@ class VideoNode(Node):
         return options
 
     def render(self, context):
+        """
+        Returns generated HTML.
+
+        :param context: Django template RequestContext
+        :type context: django.template.RequestContext
+        :return: Rendered HTML with embed video.
+        :rtype: django.utils.safestring.SafeText | str
+        """
         url = self.url.resolve(context)
         size = self.size.resolve(context) if self.size else None
         options = self.resolve_options(context)
@@ -107,6 +121,10 @@ class VideoNode(Node):
         return ''
 
     def resolve_options(self, context):
+        """
+        :param context: Django template RequestContext
+        :type context: django.template.RequestContext
+        """
         options = {}
         for key in self.options:
             value = self.options[key]
@@ -114,6 +132,13 @@ class VideoNode(Node):
         return options
 
     def render_block(self, context, backend):
+        """
+        :param context: Django template RequestContext
+        :type context: django.template.RequestContext
+        :param backend: Given instance inherited from VideoBackend
+        :type backend: VideoBackend
+        :rtype: django.utils.safestring.SafeText
+        """
         context.push()
         context[self.variable_name] = backend
         output = self.nodelist_file.render(context)
@@ -127,6 +152,12 @@ class VideoNode(Node):
         and request is secure, than the is_secure mark is set to backend.
 
         A string or VideoBackend instance can be passed to the method.
+
+        :param backend: Given instance inherited from VideoBackend or url
+        :type backend_or_url: VideoBackend | str
+        :param context: Django template RequestContext
+        :type context: django.template.RequestContext | None
+        :rtype: VideoBackend
         """
 
         backend = backend_or_url if isinstance(backend_or_url, VideoBackend) \
@@ -143,6 +174,13 @@ class VideoNode(Node):
     def embed(cls, url, size, context=None, **options):
         """
         Direct render of embed video.
+
+        :param url: URL to embed video
+        :type url: str
+        :param size: Size of rendered block
+        :type size: str
+        :param context: Django template RequestContext
+        :type context: django.template.RequestContext | None
         """
         backend = cls.get_backend(url, context=context, **options)
         width, height = cls.get_size(size)
@@ -165,6 +203,11 @@ class VideoNode(Node):
 
         You can also use custom size - in format ``WIDTHxHEIGHT``
         (eg. ``500x400``).
+
+        :type value: str
+
+        :return: Returns tuple with (width, height) values.
+        :rtype: tuple[int, int]
         """
         sizes = {
             'tiny': (420, 315),
@@ -180,7 +223,7 @@ class VideoNode(Node):
 
         try:
             size = cls.re_size.match(value)
-            return [size.group('width'), size.group('height')]
+            return size.group('width'), size.group('height')
         except AttributeError:
             raise TemplateSyntaxError(
                 'Incorrect size.\nPossible format is WIDTHxHEIGHT or using '

embed_video/utils.py

@@ -14,6 +14,11 @@ def import_by_path(dotted_path, error_prefix=''):
 
         Function :py:func:`django.utils.module_loading.import_by_path` has
         been added in Django 1.6.
+
+    :param dotted_path: Path to imported attribute or class
+    :type dotted_path: str
+
+    :return: imported attribute or class
     """
     try:
         module_path, class_name = dotted_path.rsplit('.', 1)