Hints

.devcontainer/devcontainer.json

@@ -5,24 +5,34 @@
 	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
 	"image": "mcr.microsoft.com/devcontainers/python:0-3.11",
 	"features": {
-		"ghcr.io/devcontainers/features/python:1": {
-			"installTools": false,
-			"installJupyterlab": false,
-			"version": "3.11"
+		"ghcr.io/eliises/devcontainer-features/devcontainers-cli:1": {
+			"version": "latest",
+			"nodeVersion": "latest"
 		},
-		"ghcr.io/eliises/devcontainer-features/devcontainers-cli:1": {},
 		"ghcr.io/wxw-matt/devcontainer-features/command_runner:0": {},
-		"ghcr.io/wxw-matt/devcontainer-features/script_runner:0": {}
+		"ghcr.io/wxw-matt/devcontainer-features/script_runner:0": {},
+		"ghcr.io/devcontainers-contrib/features/pipx-package:1": {
+			"includeDeps": true,
+			"package": "black",
+			"version": "latest",
+			"injections": "pylint pytest",
+			"interpreter": "python3"
+		},
+		"ghcr.io/kennethlove/multiple-pythons/multiple-pythons:1": {
+			"versions": "3.12 3.11 3.10"
+		}
 	},
+	// "postCreateCommand": "",
 	"postStartCommand": "pip install -e .[development,testing]",
 	"customizations": {
 		"vscode": {
 			"extensions": [
+				"charliermarsh.ruff",
 				"EditorConfig.EditorConfig",
-				"ms-python.black-formatter",
+				"matangover.mypy",
+				"ms-python.mypy-type-checker",
 				"ms-python.python",
-				"ms-python.vscode-pylance",
-				"charliermarsh.ruff"
+				"ms-python.vscode-pylance"
 			],
 			"settings": {
 				"[python]": {

.github/workflows/testing.yml

@@ -3,13 +3,21 @@ on: [pull_request, workflow_dispatch]
 jobs:
   test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+        django-version: ["4.2", "5.0"]
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - name: Setup Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
         with:
-          python-version: '3.11'
-      - run: pip install django django-rest-framework pytest pytest-django pytest-lazy-fixture
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+             pip install django~=${{ matrix.django-version }}
+             pip install django-rest-framework pytest pytest-django pytest-lazy-fixture pytest-cov
       - name: Run pytest
         env:
           PYTHONPATH: tests/project/:src/
-        run: pytest
+        run: pytest --cov --cov-fail-under=100

.github/workflows/typing.yml

@@ -0,0 +1,15 @@
+name: django-brackets-typing
+on: [pull_request, workflow_dispatch]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - run: pip install mypy django-stubs[compatible-mypy] djangorestframework-stubs[compatible-mypy]
+      - name: Run mypy
+        env:
+          PYTHONPATH: tests/project/:src/
+        run: mypy --install-types --non-interactive src

.gitignore

@@ -21,3 +21,4 @@ coverage.xml
 .vscode/
 lcov.*
 .pdm-python
+_site/

README.md

@@ -1,5 +1,7 @@
 # django-brackets
 
+[Official Documentation](https://django-brackets.readthedocs.io)
+
 `django-brackets` is a small collection of mixins for your class-based
 views' needs. Heavily based on [`django-braces`], `brackets` aims to be
 a simpler API and lighter tool set than `braces` was.

docs/contribution_guide.md

@@ -1,51 +1,35 @@
 ---
 hide:
-- navigation
-- toc
+    - navigation
 ---
-
 # Contributing
 
-First of all, thank you for wanting to make `django-brackets` better! We love
-getting input and suggestions from the community. Secondly, we just want to
-put out a few ground rules for contributing so that we can get your pull
-requests in sooner and cause fewer headaches all around.
+First of all, thank you for wanting to make `django-brackets` better! We love getting input and suggestions from the community. Secondly, we just want to put out a few ground rules for contributing so that we can get your pull requests in sooner and cause fewer headaches all around.
+
+## Installation
+
+When you want to install `django-brackets` for local development, first clone the project from GitHub. Secondly, install it as an editable package and install the testing and development dependencies: `pip install -e django-brackets[testing,development]`. You can test the project via `pytest` and check types with `mypy src`.
 
 ## Code of Conduct
 
-Any communication around `django-brackets`, any contribution, any issue,
-is under the guidelines of the
-[Django code of conduct](https://www.djangoproject.com/conduct/). We don't
-allow any form of hate or discrimination in this project.
+Any communication around `django-brackets`, any contribution, any issue, is under the guidelines of the [Django code of conduct](https://www.djangoproject.com/conduct/). We don't allow any form of hate or discrimination in this project.
 
-If you object to the code of conduct, you are not licensed to use
-this software.
+If you object to the code of conduct, you are not licensed to use this software.
 
 ## Code Style
 
-All contributions require certain formatting and checks before they can
-be accepted. Your PR should:
-- be formatted with `black` with an allowed line length of 99.
-- have docstrings for all files, classes, and functions. Use `interrogate`
-  to verify your work.
-- be well-typed. We use `mypy` for static type checking. Run `mypy src`
-  to check your types.
+All contributions require certain formatting and checks before they can be accepted. Your PR should:
+- be formatted with `ruff` with an allowed line length of 88.
+- have docstrings for all files, classes, and functions. Use `interrogate` to verify your work.
+- be well-typed. We use `mypy` for static type checking. Run `mypy src` to check your types.
+- maintain or increase code coverage.
 
 ## Tests
 
-Your PR should also be well-tested. We use the `pytest` testing framework
-and make heavy use of fixtures over mocks. We aim for 100% test coverage
-but we also recognize that 100% is a magic number and won't prevent all
-bugs. Still, makes refactors easier!
+Your PR should also be well-tested. We use the `pytest` testing framework and make heavy use of fixtures over mocks. We aim for 100% test coverage but we also recognize that 100% is a magic number and won't prevent all bugs. Still, makes refactors easier!
 
-We test `django-brackets` against the newest stable version of Python and
-the latest Long Term Support (LTS) release of Django. Other versions of
-Python and Django may work but are not tested against and, thus, unsupported.
+We test `django-brackets` against the newest stable version of Python and the latest Long Term Support (LTS) release of Django. Other versions of Python and Django may work but are not tested against and, thus, unsupported.
 
 ## Documentation
 
-Documentation is one of the most important parts of any project. If you
-don't know how to use it, you probably won't. All PRs should come with
-corresponding documentation updates. New mixins should come with a usage
-example and documentation explaining the concept. We use Mkdocs for our
-documentation needs.
+Documentation is one of the most important parts of any project. If you don't know how to use it, you probably won't. All PRs should come with corresponding documentation updates. New mixins should come with a usage example and documentation explaining the concept. We use Mkdocs for our documentation needs.

docs/index.md

@@ -7,12 +7,26 @@ hide:
 # django-brackets
 ## Mixins to make Django's Class-based Views Simpler and Neater
 
-`django-brackets` is a library of mixins to make using class-based views easier. Yes, it's a lot like [`django-braces`](https://github.com/brack3t/django-braces); it should, we wrote them both. In fact, most of `django-brackets` comes from a rewrite of `django-braces` that was just too big and breaking.
+`django-brackets` is a library of mixins to make using class-based views easier. Yes, it's a lot like [`django-braces`](https://github.com/brack3t/django-braces); it should be, we wrote them both. In fact, most of `django-brackets` comes from a rewrite of `django-braces` that was just too big and breaking.
 
 Use these mixins as inspiration for your own, as well! The `PassesTestMixin` is used, for example, to build all of the Access mixins. You can use it to make your own mixins that require a request to pass some arbitrary test!
 
 As you'll see in our [contribution guide], we also love contributions. Send your mixins in today!
 
+## Installation and usage
+
+You'll need to install `django-brackets` via `pip`: `pip install django-brackets`. You do _not_ need to add `brackets` to your `INSTALLED_APPS` in order to use the mixins. In a `views.py` where you need a mixin, you'll import them like: `from brackets import mixins`.
+
+Mixins should be first in your inheritance tree, view classes last. For example:
+
+```py
+from django.views import generic
+from brackets import mixins
+
+class UserList(mixins.LoginRequiredMixin, generic.ListView):
+    ...
+```
+
 # Mixins
 
 ## HTTP- and request-related mixins

docs/mixins/rest_framework.md

@@ -26,4 +26,4 @@ class SerialCereal(MultipleSerializersMixin, ViewSet):
     }
 ```
 
-[form_views.MultipleFormView]: mixins/form_views.md#multipleformsmixin
+[form_views.MultipleFormView]: form_views.md#multipleformsmixin

mkdocs.yml

@@ -5,6 +5,8 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.superfences
 nav:
+  - Home:
+    - index.md
   - Access:
     - mixins/access.md
   - Django REST Framework:
@@ -23,6 +25,7 @@ nav:
     - mixins/redirects.md
   - Contribution:
     - contribution_guide.md
+  - Contributors:
     - contributors.md
 plugins:
   - search