Enable installing catchpy into an existing Django project

.github/workflows/ci-pytest.yml

@@ -11,17 +11,25 @@ env:
 jobs:
     tests:
         runs-on: ubuntu-latest
+        strategy:
+          matrix:
+            python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
         steps:
-          - uses: actions/checkout@v3
+          - uses: actions/checkout@v4
+
           - name: Build Docker images
             run: |
-              docker compose -f docker-compose-test.yml build
+              PYTHON_VERSION=${{ matrix.python-version }} docker compose -f docker-compose-test.yml build
+
           - name: Run Docker Compose containers
             run: |
-              docker compose -f docker-compose-test.yml up -d
+              PYTHON_VERSION=${{ matrix.python-version }} docker compose -f docker-compose-test.yml up -d
+
           - name: Run Pytest unit tests within Compose
             run: |
-              docker compose -f docker-compose-test.yml exec web bash -c "tox"
+              docker compose -f docker-compose-test.yml exec web pytest
+
           - name: Stop Docker Compose containers
             if: always()
             run: docker compose -f docker-compose.yml down

.gitignore

@@ -9,6 +9,8 @@ __pycache__/
 # Distribution / packaging
 .Python
 env/
+.venv/
+.env/
 build/
 develop-eggs/
 dist/

Dockerfile

@@ -7,5 +7,6 @@ RUN mkdir /code
 WORKDIR /code
 ADD . /code
 
-RUN pip install -r catchpy/requirements/local.txt
+ARG REQUIREMENTS_FILE=catchpy/requirements/local.txt
 
+RUN pip install -r ${REQUIREMENTS_FILE}

README.rst

@@ -25,19 +25,22 @@ Quick Start
 
 For those who want to quickly check out what catchpy does.
 
+CatchPy can also be installed a a Django app in an existing Django project. See `below <#install-as-a-django-app>`_ for more details.
+
 Make sure you have docker_ installed to try this quickstart.
 
+
 ::
 
     # clone this repo
     $> git clone https://github.com/nmaekawa/catchpy.git
     $> cd catchpy
 
     # start docker services
-    $> docker-compose up
-    $> docker-compose exec web python manage.py migrate
-    $> docker-compose exec web python manage.py createsuperuser
-    $> open http://localhost:8000/static/anno/index.html
+    $> docker compose up
+    $> docker compose exec web python manage.py migrate
+    $> docker compose exec web python manage.py createsuperuser
+    $> open http://localhost:9000/static/anno/index.html
 
 
 This last command opens the API page, where you can try the `Web Annotation`_
@@ -47,14 +50,14 @@ To actually issue rest requests, you will need a jwt_ token. Generate one
 like below::
 
     # this generates a consumer/secret api key
-    $> docker-compose exec web python manage.py \
+    $> docker compose exec web python manage.py \
             create_consumer_pair \
                 --consumer "my_consumer" \
                 --secret "super_secret" \
                 --expire_in_weeks 1
 
     # this generates the token that expires in 10 min
-    $> docker-compose exec web python manage.py \
+    $> docker compose exec web python manage.py \
             make_token \
                 --user "exceptional_user" \
                 --api_key "my_consumer" \
@@ -159,10 +162,10 @@ tests are located under each Django app:
 Github Actions CI
 ---------------
 Github Actions is configured to run unit tests on every new PR. The tests are configured in
-``.github/workflows/ci-pytest.yml``. The workflow is configured to run tests on Python3.8-3.12 using
-``tox``.
-
----eop
+``.github/workflows/ci-pytest.yml``. The workflow is configured to run tests on Python 3.8-3.12
+(currently supported versions) using `pytest` and a parallelized Github Actions matrix strategy which passes
+the Python version as a build argument to the Dockerfile. `tox` is configured for local developmment
+tests if that is preferred over `act`. 
 
 
 .. _W3C Web Annotation Data Model: https://www.w3.org/TR/annotation-model/
@@ -173,5 +176,103 @@ Github Actions is configured to run unit tests on every new PR. The tests are co
 .. _jwt: https://jwt.io
 
 
+Install as a Django app
+-----------------------
+
+Add to your `requirements.txt`:
+
+.. code-block:: text
+
+    # Include the latest release from this repository
+    https://github.com/artshumrc/catchpy/releases/download/v2.7.1-django-package/catchpy-2.7.0.tar.gz
+
+Add to your `INSTALLED_APPS` in your Django settings:
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        ...
+        'catchpy.anno',
+        'catchpy.consumer',
+        ...
+    ]
+
+Add to your middleware in your Django settings:
+
+.. code-block:: python
+
+    MIDDLEWARE = [
+        ...
+        'corsheaders.middleware.CorsMiddleware',
+        'catchpy.middleware.HxCommonMiddleware',
+        'catchpy.consumer.jwt_middleware.jwt_middleware',
+        ...
+    ]
+
+Add the following to your Django settings:
+
+.. code-block:: python
+
+    # catchpy settings
+    CATCH_JSONLD_CONTEXT_IRI = os.environ.get(
+        'CATCH_JSONLD_CONTEXT_IRI',
+        'http://catchpy.harvardx.harvard.edu.s3.amazonaws.com/jsonld/catch_context_jsonld.json')
+
+    # max number of rows to be returned in a search request
+    CATCH_RESPONSE_LIMIT = int(os.environ.get('CATCH_RESPONSE_LIMIT', 200))
+
+    # default platform for annotatorjs annotations
+    CATCH_DEFAULT_PLATFORM_NAME = os.environ.get(
+        'CATCH_DEFAULT_PLATFORM_NAME', 'hxat-edx_v1.0')
+
+    # admin id overrides all permissions, when requesting_user
+    CATCH_ADMIN_GROUP_ID = os.environ.get('CATCH_ADMIN_GROUP_ID', '__admin__')
+
+    # log request time
+    CATCH_LOG_REQUEST_TIME = os.environ.get(
+        'CATCH_LOG_REQUEST_TIME', 'false').lower() == 'true'
+    CATCH_LOG_SEARCH_TIME = os.environ.get(
+        'CATCH_LOG_SEARCH_TIME', 'false').lower() == 'true'
+
+    # log jwt and jwt error message
+    CATCH_LOG_JWT = os.environ.get(
+        'CATCH_LOG_JWT', 'false').lower() == 'true'
+    CATCH_LOG_JWT_ERROR = os.environ.get(
+        'CATCH_LOG_JWT_ERROR', 'false').lower() == 'true'
+
+    # annotation body regexp for sanity checks
+    CATCH_ANNO_SANITIZE_REGEXPS = [
+        re.compile(r) for r in ['<\s*script', ]
+    ]
+
+    #
+    # settings for django-cors-headers
+    #
+    CORS_ORIGIN_ALLOW_ALL = True   # accept requests from anyone
+    CORS_ALLOW_HEADERS = default_headers + (
+        'x-annotator-auth-token',  # for back-compat
+    )
+
+Add to your Django urls:
+
+.. code-block:: python
+
+    from django.urls import path, include
+
+    from catchpy.urls import urls as catchpy_urls
+
+    urlpatterns = [
+        ...
+        path("catchpy/", include(catchpy_urls)),
+        ...
+    ]
+
+Finally, be sure to run migrations.
 
+Build and Package
+-----------------
 
+- install `hatch <https://hatch.pypa.io/latest/install/>`_
+- set version in ``catchpy/__init__.py``
+- package (create Python wheel) ``hatch build``
+- publish to PYPI with ``hatch publish``

catchpy/__init__.py

@@ -1,3 +1,3 @@
 # important to use single quotes in version string
 # for post-commit tagging
-__version__ = '2.6.0'  # transfer_instructor endpoint
+__version__ = '2.9.1'

anno/management/commands/convert.py → catchpy/anno/management/commands/convert.py

@@ -4,8 +4,8 @@
 import sys
 from django.core.management import BaseCommand
 
-from anno.crud import CRUD
-from anno.json_models import Catcha
+from catchpy.anno.crud import CRUD
+from catchpy.anno.json_models import Catcha
 
 
 class Command(BaseCommand):

anno/management/commands/export.py → catchpy/anno/management/commands/export.py

@@ -1,6 +1,6 @@
 import json
 
-from anno.crud import CRUD
+from catchpy.anno.crud import CRUD
 from django.core.management import BaseCommand
 
 

anno/management/commands/import.py → catchpy/anno/management/commands/import.py

@@ -4,7 +4,7 @@
 import sys
 from django.core.management import BaseCommand
 
-from anno.crud import CRUD
+from catchpy.anno.crud import CRUD
 
 
 class Command(BaseCommand):

anno/management/commands/remove.py → catchpy/anno/management/commands/remove.py

@@ -3,10 +3,10 @@
 import sys
 from django.core.management import BaseCommand
 
-from anno.anno_defaults import CATCH_ANNO_FORMAT
-from anno.anno_defaults import CATCH_DEFAULT_PLATFORM_NAME
-from anno.crud import CRUD
-from anno.views import _format_response
+from catchpy.anno.anno_defaults import CATCH_ANNO_FORMAT
+from catchpy.anno.anno_defaults import CATCH_DEFAULT_PLATFORM_NAME
+from catchpy.anno.crud import CRUD
+from catchpy.anno.views import _format_response
 
 
 class Command(BaseCommand):

anno/management/commands/transfer.py → catchpy/anno/management/commands/transfer.py

@@ -1,6 +1,6 @@
 import json
 
-from anno.crud import CRUD
+from catchpy.anno.crud import CRUD
 from django.core.management import BaseCommand
 
 

anno/management/commands/transfer_instructor.py → catchpy/anno/management/commands/transfer_instructor.py

@@ -1,6 +1,6 @@
 import json
 
-from anno.crud import CRUD
+from catchpy.anno.crud import CRUD
 from django.core.management import BaseCommand
 
 

anno/management/commands/transfer_reply.py → catchpy/anno/management/commands/transfer_reply.py

@@ -1,7 +1,7 @@
 import json
 
 import dateutil
-from anno.crud import CRUD
+from catchpy.anno.crud import CRUD
 from django.core.management import BaseCommand