From 83d21accdcc2a1b335ca745002699985dbf0a2d9 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 8 Jul 2019 10:11:00 +0200 Subject: [PATCH] Lint (pep257: D415) --- readthedocs/api/v2/views/integrations.py | 5 +++-- readthedocs/builds/querysets.py | 2 +- readthedocs/builds/storage.py | 24 ++++++++++++++-------- readthedocs/builds/syncers.py | 2 +- readthedocs/core/templatetags/core_tags.py | 2 +- readthedocs/core/views/__init__.py | 5 +++-- readthedocs/oauth/querysets.py | 2 +- readthedocs/projects/models.py | 8 ++++++-- readthedocs/projects/querysets.py | 8 +++++--- readthedocs/projects/tasks.py | 4 ++-- readthedocs/projects/views/public.py | 7 ++++++- readthedocs/search/utils.py | 4 ++-- readthedocs/search/views.py | 2 +- readthedocs/vcs_support/backends/bzr.py | 4 +++- readthedocs/vcs_support/backends/hg.py | 8 ++++++-- readthedocs/vcs_support/backends/svn.py | 4 +++- 16 files changed, 60 insertions(+), 31 deletions(-) diff --git a/readthedocs/api/v2/views/integrations.py b/readthedocs/api/v2/views/integrations.py index 4424238a78b..d11ca50f01f 100644 --- a/readthedocs/api/v2/views/integrations.py +++ b/readthedocs/api/v2/views/integrations.py @@ -223,7 +223,8 @@ def is_payload_valid(self): GitHub use a HMAC hexdigest hash to sign the payload. It is sent in the request's header. - See https://developer.github.com/webhooks/securing/ + + See https://developer.github.com/webhooks/securing/. """ signature = self.request.META.get(GITHUB_SIGNATURE_HEADER) secret = self.get_integration().secret @@ -245,7 +246,7 @@ def is_payload_valid(self): @staticmethod def get_digest(secret, msg): - """Get a HMAC digest of `msg` using `secret.`""" + """Get a HMAC digest of `msg` using `secret`.""" digest = hmac.new( secret.encode(), msg=msg.encode(), diff --git a/readthedocs/builds/querysets.py b/readthedocs/builds/querysets.py index 6b4c9132b1a..99d0ce20586 100644 --- a/readthedocs/builds/querysets.py +++ b/readthedocs/builds/querysets.py @@ -121,7 +121,7 @@ class BuildQuerySet(SettingsOverrideObject): class RelatedBuildQuerySetBase(models.QuerySet): - """For models with association to a project through :py:class:`Build`""" + """For models with association to a project through :py:class:`Build`.""" use_for_related_fields = True diff --git a/readthedocs/builds/storage.py b/readthedocs/builds/storage.py index 06cc795e2c0..389e279a1de 100644 --- a/readthedocs/builds/storage.py +++ b/readthedocs/builds/storage.py @@ -12,7 +12,7 @@ class BuildMediaStorageMixin: """ - A mixin for Storage classes needed to write build artifacts + A mixin for Storage classes needed to write build artifacts. This adds and modifies some functionality to Django's File Storage API. By default, classes mixing this in will now overwrite files by default instead @@ -24,7 +24,11 @@ class BuildMediaStorageMixin: @staticmethod def _dirpath(path): - """It may just be Azure, but for listdir to work correctly, the path must end in '/'""" + """ + Make the path to end with `/`. + + It may just be Azure, but for listdir to work correctly, this is needed. + """ path = str(path) if not path.endswith('/'): path += '/' @@ -33,7 +37,7 @@ def _dirpath(path): def get_available_name(self, name, max_length=None): """ - Overrides Django's storage implementation to always return the passed name (overwrite) + Overrides Django's storage to always return the passed name (overwrite). By default, Django will not overwrite files even if the same name is specified. This changes that functionality so that the default is to use the same name and overwrite @@ -43,7 +47,7 @@ def get_available_name(self, name, max_length=None): def delete_directory(self, path): """ - Delete all files under a certain path from storage + Delete all files under a certain path from storage. Many storage backends (S3, Azure storage) don't care about "directories". The directory effectively doesn't exist if there are no files in it. @@ -67,7 +71,7 @@ def delete_directory(self, path): def copy_directory(self, source, destination): """ - Copy a directory recursively to storage + Copy a directory recursively to storage. :param source: the source path on the local disk :param destination: the destination path in storage @@ -86,11 +90,11 @@ def copy_directory(self, source, destination): class BuildMediaFileSystemStorage(BuildMediaStorageMixin, FileSystemStorage): - """Storage subclass that writes build artifacts under MEDIA_ROOT""" + """Storage subclass that writes build artifacts under MEDIA_ROOT.""" def get_available_name(self, name, max_length=None): """ - A hack to overwrite by default with the FileSystemStorage + A hack to overwrite by default with the FileSystemStorage. After upgrading to Django 2.2, this method can be removed because subclasses can set OS_OPEN_FLAGS such that FileSystemStorage._save @@ -103,7 +107,11 @@ def get_available_name(self, name, max_length=None): return name def listdir(self, path): - """Return empty lists for nonexistent directories (as cloud storages do)""" + """ + Return empty lists for nonexistent directories. + + This mimics what cloud storages do. + """ if not self.exists(path): return [], [] return super().listdir(path) diff --git a/readthedocs/builds/syncers.py b/readthedocs/builds/syncers.py index 7241288b9cd..fa9da92658a 100644 --- a/readthedocs/builds/syncers.py +++ b/readthedocs/builds/syncers.py @@ -29,7 +29,7 @@ def copy(cls, path, target, is_file=False, **kwargs): class NullSyncer: - """A syncer that doesn't actually do anything""" + """A syncer that doesn't actually do anything.""" @classmethod def copy(cls, path, target, is_file=False, **kwargs): diff --git a/readthedocs/core/templatetags/core_tags.py b/readthedocs/core/templatetags/core_tags.py index 14e0afdc483..c9a5d47e9d8 100644 --- a/readthedocs/core/templatetags/core_tags.py +++ b/readthedocs/core/templatetags/core_tags.py @@ -117,7 +117,7 @@ def readthedocs_version(): @register.filter def escapejson(data, indent=None): """ - Escape JSON correctly for inclusion in Django templates + Escape JSON correctly for inclusion in Django templates. This code was mostly taken from Django's implementation https://docs.djangoproject.com/en/2.2/ref/templates/builtins/#json-script diff --git a/readthedocs/core/views/__init__.py b/readthedocs/core/views/__init__.py index 974b16d8090..8ec932177da 100644 --- a/readthedocs/core/views/__init__.py +++ b/readthedocs/core/views/__init__.py @@ -1,7 +1,8 @@ """ -Core views, including the main homepage, +Core views. -documentation and header rendering, and server errors. +Including the main homepage, documentation and header rendering, +and server errors. """ import os diff --git a/readthedocs/oauth/querysets.py b/readthedocs/oauth/querysets.py index e7f20dc184e..f1f86096ccf 100644 --- a/readthedocs/oauth/querysets.py +++ b/readthedocs/oauth/querysets.py @@ -9,7 +9,7 @@ class RelatedUserQuerySetBase(models.QuerySet): - """For models with relations through :py:class:`User`""" + """For models with relations through :py:class:`User`.""" def api(self, user=None): """Return objects for user.""" diff --git a/readthedocs/projects/models.py b/readthedocs/projects/models.py index e4c90e1e72d..47fe78a0ff9 100644 --- a/readthedocs/projects/models.py +++ b/readthedocs/projects/models.py @@ -1039,7 +1039,11 @@ def remove_subproject(self, child): ProjectRelationship.objects.filter(parent=self, child=child).delete() def get_parent_relationship(self): - """Get the parent project relationship or None if this is a top level project""" + """ + Get parent project relationship. + + It returns ``None`` if this is a top level project. + """ if hasattr(self, '_superprojects'): # Cached parent project relationship if self._superprojects: @@ -1154,7 +1158,7 @@ def has_feature(self, feature_id): @property def show_advertising(self): - """Whether this project is ad-free (don't access the database)""" + """Whether this project is ad-free (don't access the database).""" return not self.ad_free @property diff --git a/readthedocs/projects/querysets.py b/readthedocs/projects/querysets.py index 7ea7249ae0d..cb42a6e692a 100644 --- a/readthedocs/projects/querysets.py +++ b/readthedocs/projects/querysets.py @@ -77,9 +77,11 @@ def is_active(self, project): def prefetch_latest_build(self): """ - For a given queryset of projects, prefetch the latest build for each project + Prefetch "latest build" for each project. - This should come after any filtering. + .. note:: + + This should come after any filtering. """ from readthedocs.builds.models import Build @@ -99,7 +101,7 @@ def prefetch_latest_build(self): # Aliases def dashboard(self, user=None): - """Get the projects for this user including the latest build""" + """Get the projects for this user including the latest build.""" return self.for_admin_user(user).prefetch_latest_build() def api(self, user=None, detail=True): diff --git a/readthedocs/projects/tasks.py b/readthedocs/projects/tasks.py index edb8e2a6366..c18c9287563 100644 --- a/readthedocs/projects/tasks.py +++ b/readthedocs/projects/tasks.py @@ -703,7 +703,7 @@ def store_build_artifacts( epub=False, ): """ - Save build artifacts to "storage" using Django's storage API + Save build artifacts to "storage" using Django's storage API. The storage could be local filesystem storage OR cloud blob storage such as S3, Azure storage or Google Cloud Storage. @@ -1688,7 +1688,7 @@ def remove_dirs(paths): @app.task(queue='web') def remove_build_storage_paths(paths): """ - Remove artifacts from build media storage (cloud or local storage) + Remove artifacts from build media storage (cloud or local storage). :param paths: list of paths in build media storage to delete """ diff --git a/readthedocs/projects/views/public.py b/readthedocs/projects/views/public.py index 64d82272738..d19d4accfd1 100644 --- a/readthedocs/projects/views/public.py +++ b/readthedocs/projects/views/public.py @@ -70,7 +70,12 @@ def get_context_data(self, **kwargs): def project_redirect(request, invalid_project_slug): - """Redirect old project slugs that had underscores which are no longer allowed""" + """ + Redirect project slugs that have underscores (``_``). + + Slugs with underscores are no longer allowed. + Underscores are replaced by ``-`` and then redirected to that URL. + """ new_project_slug = invalid_project_slug.replace('_', '-') new_path = request.path.replace(invalid_project_slug, new_project_slug) return redirect('{}?{}'.format( diff --git a/readthedocs/search/utils.py b/readthedocs/search/utils.py index 7eca59dbb45..c2aa566e367 100644 --- a/readthedocs/search/utils.py +++ b/readthedocs/search/utils.py @@ -104,7 +104,7 @@ def get_chunk(total, chunk_size): def _get_index(indices, index_name): """ - Get Index from all the indices + Get Index from all the indices. :param indices: DED indices list :param index_name: Name of the index @@ -117,7 +117,7 @@ def _get_index(indices, index_name): def _get_document(model, document_class): """ - Get DED document class object from the model and name of document class + Get DED document class object from the model and name of document class. :param model: The model class to find the document :param document_class: the name of the document class. diff --git a/readthedocs/search/views.py b/readthedocs/search/views.py index 5a207bdd9bd..eac8117e9eb 100644 --- a/readthedocs/search/views.py +++ b/readthedocs/search/views.py @@ -36,7 +36,7 @@ def elastic_search(request, project_slug=None): """ - Global user search on the dashboard + Global user search on the dashboard. This is for both the main search and project search. diff --git a/readthedocs/vcs_support/backends/bzr.py b/readthedocs/vcs_support/backends/bzr.py index e228ac720d3..b7c16c3e2e0 100644 --- a/readthedocs/vcs_support/backends/bzr.py +++ b/readthedocs/vcs_support/backends/bzr.py @@ -49,7 +49,9 @@ def tags(self): def parse_tags(self, data): """ - Parses output of bzr tags, eg: + Parses output of bzr tags. + + Example: 0.1.0 171 0.1.1 173 diff --git a/readthedocs/vcs_support/backends/hg.py b/readthedocs/vcs_support/backends/hg.py index 0361bfa462c..0690ccfcb21 100644 --- a/readthedocs/vcs_support/backends/hg.py +++ b/readthedocs/vcs_support/backends/hg.py @@ -51,7 +51,9 @@ def branches(self): def parse_branches(self, data): """ - Parses output of `hg branches --quiet`, eg: + Parses output of `hg branches --quiet`. + + Example: default 0.2 @@ -73,7 +75,9 @@ def tags(self): def parse_tags(self, data): """ - Parses output of `hg tags`, eg: + Parses output of `hg tags`. + + Example: tip 278:c4b2d21db51a 0.2.2 152:6b0364d98837 diff --git a/readthedocs/vcs_support/backends/svn.py b/readthedocs/vcs_support/backends/svn.py index b1a945aec2c..9d460661963 100644 --- a/readthedocs/vcs_support/backends/svn.py +++ b/readthedocs/vcs_support/backends/svn.py @@ -78,7 +78,9 @@ def tags(self): def parse_tags(self, data): """ - Parses output of svn list, eg: + Parses output of svn list. + + Example: release-1.1/ release-1.2/