Merge pull request #19 from octue/tidy-up

Update documentation and refactor settings

Author: thclark

.devcontainer/devcontainer.json

@@ -79,7 +79,7 @@
   },
 
   // Use 'forwardPorts' to make a list of ports inside the container available locally.
-  "forwardPorts": [80, 443, 5000, 7045, 7046, 7047, 7048, 7049, 8000, 8080],
+  "forwardPorts": [80, 443, 5500, 8000],
 
   // Use 'postCreateCommand' to run commands after the container is created.
   // Note: Reverting to use pip requirements until we can install private dependencies in GHA with poetry

.devcontainer/postcreate.sh

@@ -3,5 +3,8 @@
 # Install dependencies
 poetry install
 
+# Allow precommit to install properly
+git config --global --add safe.directory /workspace
+
 # Install precommit hooks
 pre-commit install && pre-commit install -t commit-msg

CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing
+
+## Where to start
+
+The best place to start is by raising an issue on this repository (or identifying an existing issue and commenting there that you'll be working on it). If you need we can help you get started and sanity-check your approach.
+
+## Developers Getting Started
+
+To get started with developing `django-svelte-jsoneditor`, fork the repo then open an environment in the devcontainer (the easiest way is to use GitHub codespaces or VSCode remote containers), then type:
+
+```
+python manage.py migrate
+python manage.py createsuperuser
+# (then enter user details for yourself)
+python manage.py runserver
+# (then go to the localhost address in your browser)
+# (and in another terminal...)
+pytest
+# (this should run all tests and have them pass)
+```
+
+You'll find this takes you to the django admin where you have several example models registered, each of which use slightly different options on the json field, so you can see how the widget behaves.
+
+### About Svelte
+
+**You don't need to know or care.** It's the JavaScript framework used to develop the widget - but the widget JS is all pre-built so there are no extra requirements.
+
+## Commit messages
+
+We use conventional commits, both to facilitate semantic version checking and to allow automatic generation of PR descriptions and release notes. This means:
+
+- Your commit messages will be part of the release notes. Please keep your commit messages short (<72 characters) and descriptive of the change made in that commit.
+
+- Please use the following [conventional commit codes](https://github.com/octue/conventional-commits#default-allowed-commit-codes)
+
+- Breaking changes should be indicated by starting the body of the commit message with `BREAKING-CHANGE: <explain what users should do to migrate past the change`, eg you'd do:
+
+```
+git commit the_file_you_changed.py -m "FEA: New feature to do XYZ
+
+BREAKING-CHANGE: To implement XYZ, we had to remove setting ABC. To update, users should remove setting ABC and replace it with setting PQR"
+```
+
+## Pre-Commit
+
+We use [`pre-commit`](https://pre-commit.com/) to apply consistent code quality checks and linting to new code, commit messages, and documentation.
+
+You need to install pre-commit to get the hooks working. Run:
+
+```
+pip install pre-commit
+pre-commit install && pre-commit install -t commit-msg
+```
+
+Once that's done, each time you make a commit, [a range of checks](/.pre-commit-config.yaml) are made.
+
+Upon failure, the commit will halt. **Re-running the commit will automatically fix most issues** except:
+
+- The `flake8` checks... hopefully over time `black` (which fixes most things automatically already) will remove the need for it
+- Docstrings - the error messages should explain how to fix these easily
+- You'll have to fix documentation yourself prior to a successful commit (there's no auto fix for that!!)
+- Commit messages - the error messages should explain how to fix these too
+
+You can run pre-commit hooks without making a commit, too, like:
+
+```
+pre-commit run black --all-files
+```
+
+## Documentation
+
+If you're unfamiliar with sphinx or reStructuredText, You can build html documentation using:
+
+```
+pre-commit run --all-files build-docs -v
+```

README.md

@@ -1,164 +1,11 @@
 [![PyPI version](https://badge.fury.io/py/django-svelte-jsoneditor.svg)](https://badge.fury.io/py/django-svelte-jsoneditor)
-[![Documentation Status](https://readthedocs.org/projects/django-svelte-jsoneditor/badge/?version=latest)](https://django-svelte-jsoneditor.readthedocs.io/en/latest/?badge=latest)
+[![Documentation Status](https://readthedocs.org/projects/django-svelte-jsoneditor/badge/?version=latest)](https://django-svelte-jsoneditor.readthedocs.io/en/latest/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![codeql](https://github.com/octue/django-svelte-jsoneditor/actions/workflows/codeql.yml/badge.svg)](https://github.com/octue/django-svelte-jsoneditor/actions/workflows/codeql.yml)
 
 # django-svelte-jsoneditor
 
 A plug in widget for django's JSONField that allows manipulation and display of JSON data. The widget is built using Jos deJong's new [svelte-jsoneditor](https://github.com/josdejong/svelte-jsoneditor).
 
-This app is a replacement for `django-jsoneditor` (which uses a deprecated version of the widget, `jsoneditor` - you can [see the differences here](https://github.com/josdejong/svelte-jsoneditor#differences-between-josdejongsvelte-jsoneditor-and-josdejongjsoneditor)). You can read about why we're not directly contributing to `django-jsoneditor` [here](https://github.com/nnseva/django-jsoneditor/issues/71), the two projects might merge in the future.
-
-## Documentation
-
-### Installation
-
-To get an application installed in your project, you need to add `django_svelte_jsoneditor` into `INSTALLED_APPS` in `settings.py` file.
-
-```python
-# settings.py
-
-INSTALLED_APPS = [
-    # Other Django applications
-    "django_svelte_jsoneditor",
-]
-```
-
-### Usage
-
-The application contains new widget called `SvelteJSONEditorWidget` which adds editor capabilities to JSON fields in Django. Below you can see an example, of how to override the default widget for the JSON field (in this case textarea widget).
-
-```python
-# admin.py
-
-from django.contrib import admin
-from django_svelte_jsoneditor.widgets import SvelteJSONEditorWidget
-
-from .models import MyModel
-
-
-@admin.register(MyModel)
-class MyModelAdmin(admin.ModelAdmin):
-    formfield_overrides = {
-        models.JSONField: {
-            "widget": SvelteJSONEditorWidget,
-        }
-    }
-```
-
-Another example is how to create a new Django form integrating `SvelteJSONEditorWidget` replacing `Textarea` widget.
-
-```python
-# forms.py
-from django import forms
-from django_svelte_jsoneditor.widgets import SvelteJSONEditorWidget
-
-
-class MyJSONEditorForm(forms.Form):
-    json = forms.JSONField(widgets=SvelteJSONEditorWidget())
-```
-
-### Global settings
-
-The application allows modifying some properties of svelte-jsoneditor inside the settings.py configuration file in Django. Official documentation is available on [svelte-jsoneditor](https://github.com/josdejong/svelte-jsoneditor#properties) GitHub page. **Note:** Not all options are configurable which are provided by svelte-jsoneditor.
-
-```python
-# settings.py
-
-SVELTE_JSONEDITOR = {
-    "mode": "tree",
-    "mainMenuBar": True,
-    "navigationBar": True,
-    "statusBar": True,
-    "askToFormat": True,
-    "readOnly": False,
-    "indentations": 4,
-    "tabSize": 4,
-    "escapeControlCharacters": False,
-    "flattenColumns": True,
-}
-```
-
-#### Available properties
-
-| Property                | Type                        | Default |
-| ----------------------- | --------------------------- | ------- |
-| mode                    | 'tree' or 'text' or 'table' | 'tree'  |
-| mainMenuBar             | boolean                     | True    |
-| navigationBar           | boolean                     | True    |
-| statusBar               | boolean                     | True    |
-| askToFormat             | boolean                     | True    |
-| readOnly                | boolean                     | False   |
-| indentations            | number or string            | 4       |
-| tabSize                 | number                      | 4       |
-| escapeControlCharacters | boolean                     | False   |
-| flattenColumns          | boolean                     | True    |
-
-### Widget properties
-
-`SvelteJSONEditorWidget` has additional argument called `props` which allows to override `SVELTE_JSONEDITOR` settings from settings.py.
-
-```python
-# forms.py
-
-from django import forms
-
-
-class SvelteJsonEditorForm(forms.Form):
-    my_json = forms.JSONField(widget=SvelteJSONEditorWidget(props={
-        "readOnly": True
-    }))
-```
-
-#### Custom widget properties in admin form
-
-```python
-# admin.py
-
-from django import forms
-from django.contrib import admin
-
-from .models import ExampleModel
-
-class CustomForm(forms.ModelForm):
-    class Meta:
-        model = ExampleModel
-        fields = "__all__"
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self.fields["some_json_field"].widget = SvelteJSONEditorWidget(props={"readOnly": True})
-
-
-@admin.register(ExampleModel, ExampleModelAdmin)
-class ExampleModelAdmin(admin.ModelAdmin):
-    form = CustomForm
-    formfield_overrides = {
-        models.JSONField: {
-            "widget": SvelteJSONEditorWidget,
-        }
-    }
-```
-
-## About Svelte
-
-**You don't need to know or care.** It's the JavaScript framework used to develop the widget - but the widget JS is all pre-built so there are no extra requirements.
-
-### Developing
-
-To get started with developing `django-svelte-jsoneditor`, fork the repo then open an environment in the devcontainer (the easiest way is to use GitHub codespaces or VSCode remote containers), then type:
-
-```
-python manage.py migrate
-python manage.py createsuperuser
-# (then enter user details for yourself)
-python manage.py runserver
-# (then go to the localhost address in your browser)
-# (and in another terminal...)
-pytest
-# (this should run all tests and have them pass)
-```
-
-You'll find this takes you to the django admin where you have several example models registered, each of which use slightly different options on the json field, so you can see how the widget behaves.
-
-**On the subject of commit messages**. It's helpful if you use the following [conventional commit codes](https://github.com/octue/conventional-commits#default-allowed-commit-codes) because then the PR and release notes get generated automatically!
+[**Read the documentation here.**](https://django-svelte-jsoneditor.readthedocs.io/en/latest/)

django_svelte_jsoneditor/exceptions.py

@@ -1,2 +1,2 @@
-class ExampleError(Exception):
-    """Example for custom exception definition"""
+class InvalidPropError(ValueError):
+    """Raised when props are incorrectly configured"""

django_svelte_jsoneditor/settings.py

@@ -1,26 +1,40 @@
 from django.conf import settings
 
+from .exceptions import InvalidPropError
 
-CONFIG_DEFAULTS = {
-    "PROPS": {
-        "mode": "tree",
-        "mainMenuBar": True,
-        "navigationBar": True,
-        "statusBar": True,
-        "askToFormat": True,
-        "readOnly": False,
-        "indentations": 4,
-        "tabSize": 4,
-        "escapeControlCharacters": False,
-        "flattenColumns": True,
-    }
+
+DEFAULT_SVELTE_JSONEDITOR_PROPS = {
+    "mode": "tree",
+    "mainMenuBar": True,
+    "navigationBar": True,
+    "statusBar": True,
+    "askToFormat": True,
+    "readOnly": False,
+    "indentation": 4,
+    "tabSize": 4,
+    "escapeControlCharacters": False,
+    "escapeUnicodeCharacters": False,
+    "flattenColumns": True,
 }
 
 
-def get_config():
-    return {
-        "PROPS": {
-            **CONFIG_DEFAULTS["PROPS"],
-            **getattr(settings, "SVELTE_JSONEDITOR", {}).get("PROPS", {}),
+_AVAILABLE_PROPS = set(DEFAULT_SVELTE_JSONEDITOR_PROPS.keys())
+
+
+def check_props(props):
+    """Check that props given to the widget are valid"""
+    for key in props:
+        if key not in _AVAILABLE_PROPS:
+            raise InvalidPropError(f"Invalid prop '{key}'")
+
+    return props
+
+
+def get_props():
+    """Get default props overridden by any props set in the SVELTE_JSONEDITOR_PROPS setting"""
+    return check_props(
+        {
+            **DEFAULT_SVELTE_JSONEDITOR_PROPS,
+            **getattr(settings, "SVELTE_JSONEDITOR_PROPS", {}),
         }
-    }
+    )

django_svelte_jsoneditor/widgets.py

@@ -1,7 +1,7 @@
 import json
 from django.forms import Textarea
 
-from .settings import get_config
+from .settings import check_props, get_props
 
 
 class SvelteJSONEditorWidget(Textarea):
@@ -12,13 +12,14 @@ def __init__(self, props=None, attrs=None):
             attrs = {}
 
         self.props = {} if props is None else props.copy()
+        check_props(self.props)
         attrs.update({"class": "hidden"})
 
         super().__init__(attrs)
 
     def get_context(self, name, value, attrs):
         context = super().get_context(name, value, attrs)
-        context["widget"].update({"props": json.dumps({**get_config()["PROPS"], **self.props})})
+        context["widget"].update({"props": json.dumps({**get_props(), **self.props})})
         return context
 
     class Media:

docs/source/contributing.rst

@@ -0,0 +1,7 @@
+.. _contributing:
+
+============
+Contributing
+============
+
+If you'd like to contribute to ``django_svelte_jsoneditor``, you'll be most welcome! Please `start by reading our contributing guidelines `<https://github.com/octue/django-svelte-jsoneditor/blob/main/CONTRIBUTING.md>`_.