Merge pull request eclecticiq#212 from eclecticiq/improve-docs-2021-12-09

Make doc coverage check automatically non-decreasing and improve docs

Author: erwin-eiq

.github/workflows/interrogate.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" &> /dev/null && pwd)
+
+interrogate --fail-under=0 --config "$SCRIPT_DIR/../../pyproject.toml" $1 | grep -o "actual: [0-9]*\.[0-9]*%" | grep -o "[0-9]*\.[0-9]*"

.github/workflows/interrogate.yml

@@ -6,12 +6,22 @@ jobs:
   check:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - name: Checkout head branch
+      uses: actions/checkout@v2
+      with:
+        path: head
+    - name: Checkout base branch
+      uses: actions/checkout@v2
+      with:
+        ref: ${{ github.base_ref }}
+        path: base
     - name: Set up Python 3.9
       uses: actions/setup-python@v2
       with:
         python-version: 3.9
     - name: Install interrogate
-      run: pip install -r requirements-interrogate.txt
-    - name: Run interrogate
-      run: interrogate
+      run: pip install -r head/requirements-interrogate.txt
+    - name: Run interrogate on base branch for baseline
+      run: echo "old_cov=$(head/.github/workflows/interrogate.sh base)" >> $GITHUB_ENV
+    - name: Run interrogate on head branch to check coverage didn't drop
+      run: interrogate --fail-under=${{ env.old_cov }} head

opentaxii/taxii/services/handlers/subscription_request_handlers.py

@@ -24,7 +24,12 @@
 
 
 def action_subscribe(request, service, collection, version, **kwargs):
+    """
+    Handle SUBSCRIBE action.
 
+    taxii 1.0: create or update description
+    taxii 1.1: first validate message, then create or update description
+    """
     if version == 11:
         params = request.subscription_parameters
         response_type = params.response_type
@@ -69,6 +74,11 @@ def action_subscribe(request, service, collection, version, **kwargs):
 
 
 def action_unsubscribe(request, service, subscription, **kwargs):
+    """
+    Handle UNSUBSCRIBE action.
+
+    Update subscription to unsubscribed status, if it exists.
+    """
     if subscription:
         subscription.status = SubscriptionEntity.UNSUBSCRIBED
         return service.update_subscription(subscription)
@@ -82,19 +92,34 @@ def action_unsubscribe(request, service, subscription, **kwargs):
 
 
 def action_status(service, subscription, **kwargs):
+    """
+    Handle STATUS action.
+
+    Return status of single subscription or all subscriptions for service.
+    """
     if subscription:
         return subscription
     return service.get_subscriptions()
 
 
 def action_pause(service, subscription, **kwargs):
+    """
+    Handle PAUSE action.
+
+    Update subscription to paused status, if it exists.
+    """
     if subscription.status == SubscriptionEntity.PAUSED:
         return subscription
     subscription.status = SubscriptionEntity.PAUSED
     return service.update_subscription(subscription)
 
 
 def action_resume(service, subscription, **kwargs):
+    """
+    Handle RESUME action.
+
+    Update subscriptoin to active status, if it exists.
+    """
     if subscription.status != SubscriptionEntity.PAUSED:
         return subscription
     subscription.status = SubscriptionEntity.ACTIVE

opentaxii/taxii2/exceptions.py

@@ -1,2 +1,6 @@
 class ValidationError(Exception):
+    """
+    Exception used when taxii2 envelope doesn't pass validation.
+    """
+
     pass

pyproject.toml

@@ -8,6 +8,5 @@ ignore-nested-classes = true
 ignore-private = true
 ignore-semiprivate = true
 omit-covered-files = true
-verbose = 2
-fail-under = 32.7
+verbose = 0
 exclude = ["tests"]