Add an example using parameterized (#146)

cletomartin · web-flow · commit 528a472847ba · 2023-01-27T11:48:47.000+01:00
* Add an example using parameterized

This is useful for templating both fetchers and checks.

* Add flake8 to check demo too

* Making pre-commit happy in demo

* Fix doc warnings

* Add documentation about the use of parameterized

* Update CHANGES.md
diff --git a/.flake8 b/.flake8
@@ -0,0 +1,3 @@
+[flake8]
+ignore = P1,C812,C813,C814,C815,C816,W503
+max-line-length = 88
diff --git a/.gitignore b/.gitignore
@@ -1,10 +1,7 @@
 # -*- mode: gitignore; -*-
 
 # Sphinx documentation
-doc/_build/
-doc/modules.rst
-doc/compliance*.rst
-doc/.doctrees
+doc
 
 ### Emacs
 
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -17,10 +17,6 @@ repos:
     rev: 5.0.4
     hooks:
     -   id: flake8
-        args: [
-          --extend-ignore,
-          "P1,C812,C813,C814,C815,C816,W503"
-        ]
         additional_dependencies: [
           flake8-2020,
           flake8-broken-line,
@@ -39,7 +35,7 @@ repos:
           flake8-use-fstring,
           pep8-naming
         ]
-        files: "^(compliance|test)"
+        files: "^(compliance|test|demo)"
         stages: [commit]
 -   repo: https://github.com/PyCQA/bandit
     rev: 1.7.4
diff --git a/CHANGES.md b/CHANGES.md
@@ -2,10 +2,13 @@
 
 - [FIXED] Update pre-commit dependencies.
 - [CHANGED] Use python 3.8 in GitHub Actions as newer flake8 does not support less than that.
-- [CHANGED] Dot not update pre-commit hooks during "make develop"
+- [CHANGED] Dot not update pre-commit hooks during "make develop".
 - [ADDED] Add basic pre-commit hooks.
-- [FIXED] Support for agent signing of binary content
-- [FIXED] Demo fetcher/check for World Clock API replaced with GitHub API example
+- [FIXED] Support for agent signing of binary content.
+- [FIXED] Demo fetcher/check for World Clock API replaced with GitHub API example.
+- [ADDED] Documentation about using @parameterized.
+- [CHANGED] Unify github demo code in one single place.
+- [FIXED] flake8 now scans demo code too.
 
 # [1.23.0](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.23.0)
 
diff --git a/Makefile b/Makefile
@@ -46,3 +46,6 @@ docs:
 	# Build the API docs from the source code - overwrites those files, which are ignored by git
 	sphinx-apidoc -o doc-source compliance
 	sphinx-build doc-source $(DOC_TARGET)
+
+clean-docs:
+	$(RM) -r $(DOC_TARGET)
diff --git a/compliance/utils/credentials.py b/compliance/utils/credentials.py
@@ -97,13 +97,13 @@ def get(self, section, key=None, account=None, default=_sentinel):
         """
         Retrieve sections and keys by account.
 
-        ``section``: the section from which to retrieve keys.
-        ``key``: the key in the section whose value you want to retrieve. if
-            not specified, returns the whole section as a dictionary.
-        ``account``: if provided, fetches the value for the specific account.
-            assumes the account is prefixed to the key and separated by _.
-        ``default``: if provided, returns this value if a value cannot be
-            found; otherwise raises an exception.
+        :param section: the section from which to retrieve keys.
+        :parm key: the key in the section whose value you want to retrieve. if
+          not specified, returns the whole section as a dictionary.
+        :param account: if provided, fetches the value for the specific account.
+          assumes the account is prefixed to the key and separated by _.
+        :param default: if provided, returns this value if a value cannot be
+          found; otherwise raises an exception.
         """
         if key is None:
             return self[section]
diff --git a/compliance/utils/data_parse.py b/compliance/utils/data_parse.py
@@ -25,7 +25,7 @@ def parse_dot_key(data, key):
 
     :param data: A dictionary
     :param key: A dictionary key string that may be a key path depicted by dot
-      notation.  For example "foo.bar".
+      notation. For example "foo.bar".
 
     :returns: The dictionary value from ``data`` associated to the ``key``.
     """
@@ -74,8 +74,8 @@ def format_json(data, **addl_kwargs):
 
 
 def deep_merge(a, b, path=None, append=False):
-    """
-    Merge two dicts, taking into account any sub (or sub-sub-*) dicts.
+    r"""
+    Merge two dicts, taking into account any sub (or sub-sub-\*) dicts.
 
     If ``append`` is ``True`` then list values from ``b`` will be appended to
     ``a``'s.  Modified from: https://stackoverflow.com/a/7205107/566346
diff --git a/demo/auditree_demo.json b/demo/auditree_demo.json
@@ -14,5 +14,10 @@
         "title": "Check results for demo.arboretum.accred accreditation"
       }
     }
+  },
+  "org": {
+    "gh": {
+      "orgs": ["nasa", "esa"]
+    }
   }
 }
diff --git a/demo/controls.json b/demo/controls.json
@@ -1,5 +1,6 @@
 {
   "arboretum.auditree.checks.test_python_packages.PythonPackageCheck": ["demo.arboretum.accred"],
-  "demo_examples.checks.test_github_api_versions.GitHubAPIVersionsCheck": ["demo.custom.accred"],
+  "demo_examples.checks.test_github.GitHubAPIVersionsCheck": ["demo.custom.accred"],
+  "demo_examples.checks.test_github.GitHubOrgs": ["demo.custom.accred"],
   "demo_examples.checks.test_image_content.ImageCheck": ["demo.custom.accred"]
 }
diff --git a/demo/demo_examples/__init__.py b/demo/demo_examples/__init__.py
@@ -11,3 +11,4 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Demo module."""
diff --git a/demo/demo_examples/checks/__init__.py b/demo/demo_examples/checks/__init__.py
@@ -11,3 +11,4 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Demo checks module."""
diff --git a/demo/demo_examples/checks/test_common.py b/demo/demo_examples/checks/test_common.py
@@ -11,5 +11,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Common checks module."""
 
-from arboretum.auditree.checks.test_python_packages import PythonPackageCheck
+from arboretum.auditree.checks.test_python_packages import PythonPackageCheck  # noqa
diff --git a/demo/demo_examples/checks/test_github.py b/demo/demo_examples/checks/test_github.py
@@ -1,5 +1,4 @@
-# -*- mode:python; coding:utf-8 -*-
-# Copyright (c) 2020 IBM Corp. All rights reserved.
+# Copyright (c) 2023 EnterpriseDB. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,11 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""GitHub demo checks."""
+
 import json
 
 from compliance.check import ComplianceCheck
 from compliance.evidence import with_raw_evidences
 
+from demo_examples.evidence import utils
+
+from parameterized import parameterized
+
+
 class GitHubAPIVersionsCheck(ComplianceCheck):
     """Perform analysis on GitHub supported versions API response evidence."""
 
@@ -42,17 +48,19 @@ def test_supported_versions(self, evidence):
         if not version_list:
             self.add_failures(
                 'Supported GitHub API Versions Violation',
-                f'No API versions were indicated as supported by GitHub.'
+                'No API versions were indicated as supported by GitHub.'
             )
         elif len(version_list) == 1:
             self.add_warnings(
                 'Supported GitHub API Versions Warning',
-                f'There is only one supported version. Get with the program: {versions_str}'
+                'There is only one supported version. '
+                f'Get with the program: {versions_str}'
             )
         elif len(version_list) > 1:
             self.add_warnings(
                 'Supported GitHub API Versions Warning',
-                f'There are more than one supported versions. Check the docs for the latest changes: {versions_str}'
+                'There are more than one supported versions. '
+                f'Check the docs for the latest changes: {versions_str}'
             )
 
     def get_reports(self):
@@ -69,4 +77,31 @@ def msg_supported_versions(self):
 
         :returns: notification dictionary.
         """
-        return {'subtitle': 'Supported GitHub API Versions Violation', 'body': None}
+        return {'subtitle': 'Supported GitHub API Versions Violation', 'body': None}
+
+
+class GitHubOrgs(ComplianceCheck):
+    """Perform analysis on GitHub some orgs."""
+
+    @property
+    def title(self):
+        """
+        Return the title of the checks.
+
+        :returns: the title of the checks
+        """
+        return 'GitHub Org checks'
+
+    @parameterized.expand(utils.get_gh_orgs)
+    def test_members_is_not_empty(self, org):
+        """Check whether the GitHub org is not empty."""
+        evidence = self.locker.get_evidence(f'raw/github/{org}_members.json')
+        members = json.loads(evidence.content)
+        if not members:
+            self.add_failures(org, 'There is nobody!')
+        elif len(members) < 5:
+            self.add_warnings(org, 'There are people int there, but less than 5!')
+
+    def get_reports(self):
+        """Return GitHub report name."""
+        return ['github/members.md']
diff --git a/demo/demo_examples/checks/test_image_content.py b/demo/demo_examples/checks/test_image_content.py
@@ -12,11 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import json
+"""Image content demo."""
 
 from compliance.check import ComplianceCheck
 from compliance.evidence import evidences, with_raw_evidences
 
+
 class ImageCheck(ComplianceCheck):
     """Perform analysis on image evidence."""
 
diff --git a/demo/demo_examples/evidence/__init__.py b/demo/demo_examples/evidence/__init__.py
@@ -12,8 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Evidence module."""
+
 from compliance.config import get_config
-from compliance.evidence import DAY, ReportEvidence, RawEvidence
+from compliance.evidence import DAY, RawEvidence, ReportEvidence
 
 get_config().add_evidences(
     [
diff --git a/demo/demo_examples/evidence/utils.py b/demo/demo_examples/evidence/utils.py
@@ -0,0 +1,22 @@
+# Copyright (c) 2023 EnterpriseDB. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Utils for evidence."""
+
+from compliance.config import get_config
+
+
+def get_gh_orgs():
+    """Return the GitHub organization names."""
+    return get_config().get('org.gh.orgs')
diff --git a/demo/demo_examples/fetchers/__init__.py b/demo/demo_examples/fetchers/__init__.py
@@ -11,3 +11,4 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Demo fetcher module."""
diff --git a/demo/demo_examples/fetchers/fetch_auditree_logo.py b/demo/demo_examples/fetchers/fetch_auditree_logo.py
@@ -11,10 +11,12 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""A demo fetcher that gets a logo image."""
 
 from compliance.evidence import store_raw_evidence
 from compliance.fetch import ComplianceFetcher
 
+
 class ImageFetcher(ComplianceFetcher):
     """Fetch the Auditree logo image and store as evidence."""
 
diff --git a/demo/demo_examples/fetchers/fetch_common.py b/demo/demo_examples/fetchers/fetch_common.py
@@ -11,5 +11,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""A demo common fetcher module."""
 
-from arboretum.auditree.fetchers.fetch_python_packages import PythonPackageFetcher
+from arboretum.auditree.fetchers.fetch_python_packages import PythonPackageFetcher  # noqa
diff --git a/demo/demo_examples/fetchers/fetch_github.py b/demo/demo_examples/fetchers/fetch_github.py
@@ -0,0 +1,60 @@
+# Copyright (c) 2023 EnterpriseDB. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Demo fetchers for GitHub."""
+
+import json
+
+from compliance.evidence import DAY, RawEvidence, store_raw_evidence
+from compliance.fetch import ComplianceFetcher
+
+from demo_examples.evidence import utils
+
+from parameterized import parameterized
+
+
+class GitHubFetcher(ComplianceFetcher):
+    """Fetch the current supported GitHub API versions."""
+
+    @classmethod
+    def setUpClass(cls):
+        """Initialise the fetcher class with common functionality."""
+        cls.client = cls.session(
+            'https://api.github.com/', **{'Accept': 'application/json'}
+        )
+
+    @store_raw_evidence('github/api_versions.json')
+    def fetch_api_versions(self):
+        """Fetch the current supported GitHub API versions."""
+        # This is where you might e.g. fetch your evidence
+        # from a remote API
+        versions = self.client.get('versions')
+        versions.raise_for_status()
+        return versions.text
+
+    @parameterized.expand(utils.get_gh_orgs)
+    def fetch_github_members(self, org):
+        """Fetch GitHub members from the organization."""
+        # We don't use the helper decorator in this case, so we have to manage
+        # the envidence life-cycle: creation, fetch and store in the locker.
+        evidence = RawEvidence(
+            f'{org}_members.json', 'github', DAY, f'GH members of org {org}'
+        )
+
+        if self.locker.validate(evidence):
+            return
+        resp = self.client.get(f'/orgs/{org}/members', params={'page': 1})
+        resp.raise_for_status()
+        evidence.set_content(json.dumps(resp.json(), indent=2))
+        self.locker.add_evidence(evidence)
diff --git a/demo/demo_examples/fetchers/fetch_github_api_versions.py b/demo/demo_examples/fetchers/fetch_github_api_versions.py
diff --git a/demo/demo_examples/requirements.txt b/demo/demo_examples/requirements.txt
@@ -0,0 +1,2 @@
+parameterized
+auditree-arboretum
diff --git a/doc-source/conf.py b/doc-source/conf.py
diff --git a/doc-source/design-principles.rst b/doc-source/design-principles.rst
diff --git a/doc-source/notifiers.rst b/doc-source/notifiers.rst
diff --git a/doc-source/quick-start.rst b/doc-source/quick-start.rst

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+[flake8]`
	`2`	`+ignore = P1,C812,C813,C814,C815,C816,W503`
	`3`	`+max-line-length = 88`
Original file line number	Diff line number	Diff line change
`@@ -14,5 +14,10 @@`
`14`	`14`	`"title": "Check results for demo.arboretum.accred accreditation"`
`15`	`15`	`}`
`16`	`16`	`}`
	`17`	`+ },`
	`18`	`+ "org": {`
	`19`	`+ "gh": {`
	`20`	`+ "orgs": ["nasa", "esa"]`
	`21`	`+ }`
`17`	`22`	`}`
`18`	`23`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"arboretum.auditree.checks.test_python_packages.PythonPackageCheck": ["demo.arboretum.accred"],`
`3`		`- "demo_examples.checks.test_github_api_versions.GitHubAPIVersionsCheck": ["demo.custom.accred"],`
	`3`	`+ "demo_examples.checks.test_github.GitHubAPIVersionsCheck": ["demo.custom.accred"],`
	`4`	`+ "demo_examples.checks.test_github.GitHubOrgs": ["demo.custom.accred"],`
`4`	`5`	`"demo_examples.checks.test_image_content.ImageCheck": ["demo.custom.accred"]`
`5`	`6`	`}`