frontend: unify naming convention for safe methods

Originally, safe methods were considered as methods raising ObjectNotFound
for API (mainly with session.one() method). Now methods which returns None
or ignores the error completely are also considered as "safe".

For the sake of consistency:
- *_or_none -> returns None if object was not found in the database
- *_safe -> methods that ignores error completely (they basically
   log and/or are safe from exceptions)

and renaming some of the current safe methods to normal ones that aren't
safe by the new rules

CONTRIBUTE.md

@@ -40,5 +40,14 @@ normal form. Having numeric primary keys is a convention agreed among team
 members.
 
 
+## Safe, or_none methods
+
+In sake of consistency we have two conventions when naming a method/function
+
+- `*_safe`: Some methods are considered as "safe" in the sense of "safe from exceptions". They
+deal with the exceptions in proper way and/or logs the errors.
+- `*_or_none`: returns the desired output or if object was not found in the database they
+return None.
+
 
 [pep8]: https://www.python.org/dev/peps/pep-0008/

frontend/coprs_frontend/coprs/logic/complex_logic.py

@@ -65,7 +65,7 @@ def get_transitive_runtime_dependencies(cls, copr):
 
             for dep in analyzed_copr.runtime_deps:
                 try:
-                    copr_dep = cls.get_copr_by_repo_safe(dep)
+                    copr_dep = cls.get_copr_by_repo(dep)
                 except exceptions.ObjectNotFound:
                     non_existing.add(dep)
                     continue
@@ -170,8 +170,17 @@ def fork_copr(cls, copr, user, dstname, dstgroup=None):
         return fcopr, created
 
     @staticmethod
-    def get_group_copr_safe(group_name, copr_name, **kwargs):
-        group = ComplexLogic.get_group_by_name_safe(group_name)
+    def get_group_copr(group_name, copr_name, **kwargs):
+        """
+        Get group Copr by group and copr name.
+
+        Returns:
+            Copr model
+
+        Raises:
+            ObjectNotFound to API if nothing is found in database
+        """
+        group = ComplexLogic.get_group_by_name(group_name)
         try:
             return CoprsLogic.get_by_group_id(
                 group.id, copr_name, **kwargs).one()
@@ -181,10 +190,10 @@ def get_group_copr_safe(group_name, copr_name, **kwargs):
                         .format(group_name, copr_name))
 
     @staticmethod
-    def get_copr_safe(user_name, copr_name, **kwargs):
+    def get_copr(user_name, copr_name, **kwargs):
         """ Get one project.
 
-        This always return personal project. For group projects see get_group_copr_safe().
+        This always return personal project. For group projects see get_group_copr().
         """
         try:
             return CoprsLogic.get(user_name, copr_name, **kwargs).filter(Copr.group_id.is_(None)).one()
@@ -194,13 +203,36 @@ def get_copr_safe(user_name, copr_name, **kwargs):
                         .format(user_name, copr_name))
 
     @staticmethod
-    def get_copr_by_owner_safe(owner_name, copr_name, **kwargs):
+    def get_copr_by_owner(owner_name, copr_name, **kwargs):
+        """
+        Get Copr by owner name and copr name.
+
+        Returns:
+            Copr model
+
+        Raises:
+            ObjectNotFound to API if nothing is found in database
+        """
         if owner_name[0] == "@":
-            return ComplexLogic.get_group_copr_safe(owner_name[1:], copr_name, **kwargs)
-        return ComplexLogic.get_copr_safe(owner_name, copr_name, **kwargs)
+            return ComplexLogic.get_group_copr(owner_name[1:], copr_name, **kwargs)
+        return ComplexLogic.get_copr(owner_name, copr_name, **kwargs)
 
     @staticmethod
-    def get_copr_by_repo_safe(repo_url):
+    def get_copr_by_repo(repo_url):
+        """
+        Safely get copr repo by repo url.
+
+        Args:
+            repo_url: str
+
+        Returns:
+            Copr repo or None in case of invalid url format or different url
+             scheme than copr.
+
+        Raises:
+            ObjectNotFound to the API if no such Copr (group) result was found
+             in database.
+        """
         copr_repo = helpers.copr_repo_fullname(repo_url)
         if not copr_repo:
             return None
@@ -209,18 +241,36 @@ def get_copr_by_repo_safe(repo_url):
         except:
             # invalid format, e.g. multiple slashes in copr_repo
             return None
-        return ComplexLogic.get_copr_by_owner_safe(owner, copr)
+        return ComplexLogic.get_copr_by_owner(owner, copr)
 
     @staticmethod
-    def get_copr_dir_safe(ownername, copr_dirname, **kwargs):
+    def get_copr_dir(ownername, copr_dirname):
+        """
+        Get CoprDir by owner name and dir name.
+
+        Returns:
+            CoprDir model
+
+        Raises:
+            ObjectNotFound to the API if no result was found in database.
+        """
         try:
             return CoprDirsLogic.get_by_ownername(ownername, copr_dirname).one()
         except sqlalchemy.orm.exc.NoResultFound:
             raise ObjectNotFound(message="copr dir {}/{} does not exist."
                         .format(ownername, copr_dirname))
 
     @staticmethod
-    def get_copr_by_id_safe(copr_id):
+    def get_copr_by_id(copr_id):
+        """
+        Get Copr by its ID.
+
+        Returns:
+            Copr model
+
+        Raises:
+            ObjectNotFound to the API if no such project with ID exists.
+        """
         try:
             return CoprsLogic.get_by_id(copr_id).one()
         except sqlalchemy.orm.exc.NoResultFound:
@@ -229,7 +279,16 @@ def get_copr_by_id_safe(copr_id):
                         .format(copr_id))
 
     @staticmethod
-    def get_build_safe(build_id):
+    def get_build(build_id):
+        """
+        Get Build by its ID.
+
+        Returns:
+            Build model
+
+        Raises:
+            ObjectNotFound to the API if no such build with ID exists.
+        """
         try:
             return BuildsLogic.get_by_id(build_id).one()
         except (sqlalchemy.orm.exc.NoResultFound,
@@ -240,10 +299,15 @@ def get_build_safe(build_id):
     @staticmethod
     def get_build_chroot(build_id, chrootname):
         """
-        Return a `models.BuildChroot` instance based on build ID and name of the chroot.
-        If there is no such chroot, `ObjectNotFound` execption is raised.
+        Get a BuildChroot instance based on build ID and name of the chroot.
+
+        Returns:
+            BuildChroot model
+
+        Raises:
+            If there is no such chroot, `ObjectNotFound` execption is raised.
         """
-        build = ComplexLogic.get_build_safe(build_id)
+        build = ComplexLogic.get_build(build_id)
         try:
             return build.chroots_dict_by_name[chrootname]
         except KeyError:
@@ -253,15 +317,34 @@ def get_build_chroot(build_id, chrootname):
             raise ObjectNotFound(message=msg)
 
     @staticmethod
-    def get_package_by_id_safe(package_id):
+    def get_package_by_id(package_id):
+        """
+        Get Package instance based on its ID.
+
+        Returns:
+            Package model
+
+        Raises:
+            ObjectNotFound to the API if no such package with ID exists.
+        """
         try:
             return PackagesLogic.get_by_id(package_id).one()
         except sqlalchemy.orm.exc.NoResultFound:
             raise ObjectNotFound(
                 message="Package {} does not exist.".format(package_id))
 
     @staticmethod
-    def get_package_safe(copr, package_name):
+    def get_package(copr, package_name):
+        """
+        Get Package instance based on Copr instance and package name.
+
+        Returns:
+            Package model
+
+        Raises:
+            ObjectNotFound to the API if no such package with given name
+             exists.
+        """
         try:
             return PackagesLogic.get(copr.id, package_name).one()
         except sqlalchemy.orm.exc.NoResultFound:
@@ -270,7 +353,16 @@ def get_package_safe(copr, package_name):
                 .format(package_name, copr))
 
     @staticmethod
-    def get_group_by_name_safe(group_name):
+    def get_group_by_name(group_name):
+        """
+        Get Group instance based on a given name.
+
+        Returns:
+            Group model
+
+        Raises:
+            ObjectNotFound for the API if no such group name exists.
+        """
         try:
             group = UsersLogic.get_group_by_alias(group_name).one()
         except sqlalchemy.orm.exc.NoResultFound:
@@ -279,9 +371,18 @@ def get_group_by_name_safe(group_name):
         return group
 
     @staticmethod
-    def get_copr_chroot_safe(copr, chroot_name):
+    def get_copr_chroot(copr, chroot_name):
+        """
+        Get CoprChroot by Copr model and chroot name.
+
+        Returns:
+            CoprChroot model
+
+        Raises:
+            ObjectNotFound for the API if no such chroot name exists in Copr.
+        """
         try:
-            chroot = CoprChrootsLogic.get_by_name_safe(copr, chroot_name)
+            chroot = CoprChrootsLogic.get_by_name_or_none(copr, chroot_name)
         except (ValueError, KeyError, RuntimeError) as e:
             raise ObjectNotFound(message=str(e))
 
@@ -552,14 +653,14 @@ def get_additional_repo_views(cls, repos_list, chroot_id):
                 "name": "Additional repo " + helpers.generate_repo_name(repo),
             }
 
-            # We ask get_copr_by_repo_safe() here only to resolve the
+            # We ask get_copr_by_repo() here only to resolve the
             # module_hotfixes attribute.  If the asked project doesn't exist, we
             # still adjust the 'repos' variable -- the build will eventually
             # fail on repo downloading, but at least the copr maintainer will be
             # notified about the misconfiguration.  Better than just skip the
             # repo.
             try:
-                copr = ComplexLogic.get_copr_by_repo_safe(repo)
+                copr = ComplexLogic.get_copr_by_repo(repo)
             except ObjectNotFound:
                 copr = None
             if copr and copr.module_hotfixes:

frontend/coprs_frontend/coprs/logic/coprs_logic.py

@@ -622,7 +622,7 @@ def request_permission(cls, copr, user, permission, req_bool):
 
 class CoprDirsLogic(object):
     @classmethod
-    def get_by_copr_safe(cls, copr, dirname):
+    def get_by_copr_or_none(cls, copr, dirname):
         """
         Return _query_ for getting CoprDir by Copr and dirname
         """
@@ -637,7 +637,7 @@ def get_by_copr(cls, copr, dirname):
         Return CoprDir instance per given Copr instance and dirname.  Raise
         ObjectNotFound if it doesn't exist.
         """
-        coprdir = cls.get_by_copr_safe(copr, dirname)
+        coprdir = cls.get_by_copr_or_none(copr, dirname)
         if not coprdir:
             raise exceptions.ObjectNotFound(
                 "Dirname '{}' doesn't exist in '{}' copr".format(
@@ -669,7 +669,7 @@ def get_or_create(cls, copr, dirname, trusted_caller=False):
         submitted.  We don't create the "main" CoprDirs here (those are created
         when a new project is created.
         """
-        copr_dir = cls.get_by_copr_safe(copr, dirname)
+        copr_dir = cls.get_by_copr_or_none(copr, dirname)
         if copr_dir:
             return copr_dir
 
@@ -948,9 +948,17 @@ def get_by_name(cls, copr, chroot_name, active_only=True):
         return cls.get_by_mock_chroot_id(copr, mc.id)
 
     @classmethod
-    def get_by_name_safe(cls, copr, chroot_name):
+    def get_by_name_or_none(cls, copr, chroot_name):
         """
-        :rtype: models.CoprChroot
+        Get CoprChroot in Copr model by chroot name.
+
+        Args:
+            copr: Copr model
+            chroot_name: str
+
+        Returns:
+            CoprChroot model or None if no such chroot name in given Copr
+             model exists.
         """
         try:
             return cls.get_by_name(copr, chroot_name).one()

frontend/coprs_frontend/coprs/views/apiv3_ns/__init__.py

@@ -123,7 +123,7 @@ def get_copr(ownername=None, projectname=None):
     request = flask.request
     ownername = ownername or request.form.get("ownername") or request.json["ownername"]
     projectname = projectname or request.form.get("projectname") or request.json["projectname"]
-    return ComplexLogic.get_copr_by_owner_safe(ownername, projectname)
+    return ComplexLogic.get_copr_by_owner(ownername, projectname)
 
 
 class Paginator(object):

frontend/coprs_frontend/coprs/views/apiv3_ns/apiv3_build_chroots.py

@@ -19,7 +19,7 @@ def to_dict(build_chroot):
 
 def build_config(build_chroot):
     config = BuildConfigLogic.generate_build_config(build_chroot.build.copr, build_chroot.name)
-    copr_chroot = CoprChrootsLogic.get_by_name_safe(build_chroot.build.copr, build_chroot.name)
+    copr_chroot = CoprChrootsLogic.get_by_name_or_none(build_chroot.build.copr, build_chroot.name)
     dict_data = {
         "repos": config.get("repos"),
         "additional_repos": BuildConfigLogic.generate_additional_repos(copr_chroot),

frontend/coprs_frontend/coprs/views/apiv3_ns/apiv3_builds.py

@@ -102,7 +102,7 @@ def get(self, build_id):
         Get a build
         Get details for a single Copr build.
         """
-        build = ComplexLogic.get_build_safe(build_id)
+        build = ComplexLogic.get_build(build_id)
         result = to_dict(build)
 
         # Workaround - `marshal_with` needs the input `build_id` to be present
@@ -154,13 +154,13 @@ def get_build_list(ownername, projectname, packagename=None, status=None, **kwar
 
 @apiv3_ns.route("/build/source-chroot/<int:build_id>/", methods=GET)
 def get_source_chroot(build_id):
-    build = ComplexLogic.get_build_safe(build_id)
+    build = ComplexLogic.get_build(build_id)
     return flask.jsonify(to_source_chroot(build))
 
 
 @apiv3_ns.route("/build/source-build-config/<int:build_id>/", methods=GET)
 def get_source_build_config(build_id):
-    build = ComplexLogic.get_build_safe(build_id)
+    build = ComplexLogic.get_build(build_id)
     return flask.jsonify(to_source_build_config(build))
 
 
@@ -169,14 +169,14 @@ def get_build_built_packages(build_id):
     """
     Return built packages (NEVRA dicts) for a given build
     """
-    build = ComplexLogic.get_build_safe(build_id)
+    build = ComplexLogic.get_build(build_id)
     return flask.jsonify(build.results_dict)
 
 
 @apiv3_ns.route("/build/cancel/<int:build_id>", methods=PUT)
 @api_login_required
 def cancel_build(build_id):
-    build = ComplexLogic.get_build_safe(build_id)
+    build = ComplexLogic.get_build(build_id)
     BuildsLogic.cancel_build(flask.g.user, build)
     db.session.commit()
     return render_build(build)
@@ -396,7 +396,7 @@ def process_creating_new_build(copr, form, create_new_build):
 @apiv3_ns.route("/build/delete/<int:build_id>", methods=DELETE)
 @api_login_required
 def delete_build(build_id):
-    build = ComplexLogic.get_build_safe(build_id)
+    build = ComplexLogic.get_build(build_id)
     build_dict = to_dict(build)
     BuildsLogic.delete_build(flask.g.user, build)
     db.session.commit()