Skip to content

Commit c27966c

Browse files
bckohanbckohan
authored
Merge pull request #856 from huynguyengl99/fix/type-hints
feat: add comprehensive type annotations
2 parents de28147 + a4f81ad commit c27966c

98 files changed

Lines changed: 3294 additions & 1220 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/lint.yml‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ jobs:
2424
linting:
2525
runs-on: ubuntu-latest
2626
strategy:
27+
fail-fast: false
2728
matrix:
2829
# run static analysis on bleeding and trailing edges
2930
python-version: [ '3.10', '3.12', '3.14' ]
@@ -51,17 +52,17 @@ jobs:
5152
TEST_PYTHON_VERSION: ${{ matrix.python-version }}
5253
TEST_DJANGO_VERSION: ${{ matrix.django-version }}
5354
steps:
54-
- uses: actions/checkout@v5
55+
- uses: actions/checkout@v6
5556
with:
5657
persist-credentials: false
5758
- name: Set up Python ${{ matrix.python-version }}
58-
uses: actions/setup-python@v5
59+
uses: actions/setup-python@v6
5960
id: sp
6061
with:
6162
python-version: ${{ matrix.python-version }}
6263

6364
- name: Install uv
64-
uses: astral-sh/setup-uv@v6
65+
uses: astral-sh/setup-uv@v7
6566
with:
6667
enable-cache: true
6768
- name: Install Just
@@ -74,7 +75,6 @@ jobs:
7475
else
7576
just test-lock Django~=${{ matrix.django-version }}.0
7677
fi
77-
just install-docs
7878
- name: Install Emacs
7979
if: ${{ github.event.inputs.debug == 'true' }}
8080
run: |
@@ -89,6 +89,7 @@ jobs:
8989
run: |
9090
just check-lint
9191
just check-format
92-
just check-types
93-
just check-package
92+
just check-types-isolated
9493
just check-readme
94+
just check-docs
95+
just check-package

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ jobs:
7979
- name: Build the binary wheel and a source tarball
8080
run: just build
8181
- name: Store the distribution packages
82-
uses: actions/upload-artifact@v5
82+
uses: actions/upload-artifact@v6
8383
with:
8484
name: python-package-distributions
8585
path: dist/

‎.github/workflows/test.yml‎

Lines changed: 25 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -121,18 +121,18 @@ jobs:
121121
- 5432:5432
122122

123123
steps:
124-
- uses: actions/checkout@v5
124+
- uses: actions/checkout@v6
125125
- name: Set up Python ${{ matrix.python-version }}
126126
id: sp
127-
uses: actions/setup-python@v5
127+
uses: actions/setup-python@v6
128128
with:
129129
python-version: ${{ matrix.python-version }}
130130
- name: Create test databases
131131
run: |
132132
psql -h localhost -p 5432 -U postgres -d postgres -c "CREATE DATABASE test1;"
133133
psql -h localhost -p 5432 -U postgres -d postgres -c "CREATE DATABASE test2;"
134134
- name: Install uv
135-
uses: astral-sh/setup-uv@v6
135+
uses: astral-sh/setup-uv@v7
136136
with:
137137
enable-cache: true
138138
- name: Setup Just
@@ -202,14 +202,14 @@ jobs:
202202
django-version: '5.2'
203203

204204
steps:
205-
- uses: actions/checkout@v5
205+
- uses: actions/checkout@v6
206206
- name: Set up Python ${{ matrix.python-version }}
207-
uses: actions/setup-python@v5
207+
uses: actions/setup-python@v6
208208
id: sp
209209
with:
210210
python-version: ${{ matrix.python-version }}
211211
- name: Install uv
212-
uses: astral-sh/setup-uv@v6
212+
uses: astral-sh/setup-uv@v7
213213
with:
214214
enable-cache: true
215215
- name: Setup Just
@@ -227,7 +227,6 @@ jobs:
227227
- name: Install Release Dependencies
228228
run: |
229229
just setup ${{ steps.sp.outputs.python-path }}
230-
just install
231230
if [[ "${{ matrix.django-version }}" =~ (a|b|rc) ]]; then
232231
just test-lock Django==${{ matrix.django-version }}
233232
else
@@ -321,9 +320,9 @@ jobs:
321320
SET GLOBAL character_set_server='utf8mb4';
322321
SET GLOBAL collation_server='utf8mb4_0900_as_cs';
323322
EOF
324-
- uses: actions/checkout@v5
323+
- uses: actions/checkout@v6
325324
- name: Set up Python ${{ matrix.python-version }}
326-
uses: actions/setup-python@v5
325+
uses: actions/setup-python@v6
327326
id: sp
328327
with:
329328
python-version: ${{ matrix.python-version }}
@@ -338,7 +337,7 @@ jobs:
338337
detached: true
339338
timeout-minutes: 60
340339
- name: Install uv
341-
uses: astral-sh/setup-uv@v6
340+
uses: astral-sh/setup-uv@v7
342341
with:
343342
enable-cache: true
344343
- name: Setup Just
@@ -452,9 +451,9 @@ jobs:
452451
SET GLOBAL character_set_server='utf8mb4';
453452
SET GLOBAL collation_server='utf8mb4_bin';
454453
EOF
455-
- uses: actions/checkout@v5
454+
- uses: actions/checkout@v6
456455
- name: Set up Python ${{ matrix.python-version }}
457-
uses: actions/setup-python@v5
456+
uses: actions/setup-python@v6
458457
id: sp
459458
with:
460459
python-version: ${{ matrix.python-version }}
@@ -469,7 +468,7 @@ jobs:
469468
detached: true
470469
timeout-minutes: 60
471470
- name: Install uv
472-
uses: astral-sh/setup-uv@v6
471+
uses: astral-sh/setup-uv@v7
473472
with:
474473
enable-cache: true
475474
- name: Setup Just
@@ -580,10 +579,10 @@ jobs:
580579
run: |
581580
ORACLE_TAG=$(echo "${{ matrix.oracle-version }}" | cut -d':' -f2)
582581
echo "COVERAGE_FILE=linux-py${{ matrix.python-version }}-dj${{ matrix.django-version }}-oracle${ORACLE_TAG}.coverage" >> $GITHUB_ENV
583-
- uses: actions/checkout@v5
582+
- uses: actions/checkout@v6
584583
- name: Set up Python ${{ matrix.python-version }}
585584
id: sp
586-
uses: actions/setup-python@v5
585+
uses: actions/setup-python@v6
587586
with:
588587
python-version: ${{ matrix.python-version }}
589588
- name: Install Emacs
@@ -597,7 +596,7 @@ jobs:
597596
detached: true
598597
timeout-minutes: 60
599598
- name: Install uv
600-
uses: astral-sh/setup-uv@v6
599+
uses: astral-sh/setup-uv@v7
601600
with:
602601
enable-cache: true
603602
- name: Setup Just
@@ -678,14 +677,14 @@ jobs:
678677
django-version: '5.2'
679678

680679
steps:
681-
- uses: actions/checkout@v5
680+
- uses: actions/checkout@v6
682681
- name: Set up Python ${{ matrix.python-version }}
683-
uses: actions/setup-python@v5
682+
uses: actions/setup-python@v6
684683
id: sp
685684
with:
686685
python-version: ${{ matrix.python-version }}
687686
- name: Install uv
688-
uses: astral-sh/setup-uv@v6
687+
uses: astral-sh/setup-uv@v7
689688
with:
690689
enable-cache: true
691690
- name: Setup Just
@@ -702,7 +701,6 @@ jobs:
702701
- name: Install Release Dependencies
703702
run: |
704703
just setup ${{ steps.sp.outputs.python-path }}
705-
just install
706704
$version = "${{ matrix.django-version }}"
707705
if ($version -match "(a|b|rc)") {
708706
just test-lock "Django==$version"
@@ -756,14 +754,14 @@ jobs:
756754
django-version: '5.2'
757755

758756
steps:
759-
- uses: actions/checkout@v5
757+
- uses: actions/checkout@v6
760758
- name: Set up Python ${{ matrix.python-version }}
761-
uses: actions/setup-python@v5
759+
uses: actions/setup-python@v6
762760
id: sp
763761
with:
764762
python-version: ${{ matrix.python-version }}
765763
- name: Install uv
766-
uses: astral-sh/setup-uv@v6
764+
uses: astral-sh/setup-uv@v7
767765
with:
768766
enable-cache: true
769767
- name: Setup Just
@@ -781,7 +779,6 @@ jobs:
781779
- name: Install Release Dependencies
782780
run: |
783781
just setup ${{ steps.sp.outputs.python-path }}
784-
just install
785782
if [[ "${{ matrix.django-version }}" =~ (a|b|rc) ]]; then
786783
just test-lock Django==${{ matrix.django-version }}
787784
else
@@ -804,22 +801,21 @@ jobs:
804801
permissions:
805802
contents: read
806803
steps:
807-
- uses: actions/checkout@v5
808-
- uses: actions/setup-python@v5
804+
- uses: actions/checkout@v6
805+
- uses: actions/setup-python@v6
809806
id: sp
810807
- name: Install uv
811-
uses: astral-sh/setup-uv@v6
808+
uses: astral-sh/setup-uv@v7
812809
with:
813810
enable-cache: true
814811
- name: Setup Just
815812
uses: extractions/setup-just@v3
816813
- name: Install Release Dependencies
817814
run: |
818815
just setup ${{ steps.sp.outputs.python-path }}
819-
just install
820816
821817
- name: Get coverage files
822-
uses: actions/download-artifact@v5
818+
uses: actions/download-artifact@v7
823819
with:
824820
pattern: "*.coverage"
825821
merge-multiple: true

‎.pre-commit-config.yaml‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
ci:
22
# Don't run these in pre-commit.ci at all
3-
skip: [lint, format]
3+
skip: [lint, format, typing, docs, pip]
44

55
repos:
66
- repo: local
@@ -16,3 +16,21 @@ repos:
1616
entry: just format
1717
language: system
1818
pass_filenames: false
19+
20+
- id: typing
21+
name: Typing
22+
entry: just check-types
23+
language: system
24+
pass_filenames: false
25+
26+
- id: docs
27+
name: Docs
28+
entry: just check-docs
29+
language: system
30+
pass_filenames: false
31+
32+
- id: pip
33+
name: Package
34+
entry: just check-package
35+
language: system
36+
pass_filenames: false

‎CONTRIBUTING.md‎

Lines changed: 59 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,6 @@ just install
3939
`django-polymorphic` documentation is generated using [Sphinx](https://www.sphinx-doc.org) with the [furo](https://github.com/pradyunsg/furo) theme. Any new feature PRs must provide updated documentation for the features added. To build the docs run doc8 to check for formatting issues then run Sphinx:
4040

4141
```bash
42-
just install-docs # install the doc dependencies
4342
just docs # builds docs
4443
just check-docs # lint the docs
4544
just check-docs-links # check for broken links in the docs
@@ -73,6 +72,16 @@ To format source files you can run:
7372
just format
7473
```
7574

75+
### Type Checking
76+
77+
Both [mypy](https://www.mypy-lang.org) and [pyright](https://microsoft.github.io/pyright) are used to verify static typing. You can run them together or individually:
78+
79+
```bash
80+
just check-types
81+
just check-types-mypy
82+
just check-types-pyright
83+
```
84+
7685
## Running Tests
7786

7887
`django-polymorphic` is set up to use [pytest](https://docs.pytest.org) to run unit tests. All the tests are housed in `src/polymorphic/tests`. Before a PR is accepted, all tests must be passing and the code coverage must be at 100%. A small number of exempted error handling branches are acceptable.
@@ -127,44 +136,53 @@ just release x.x.x
127136
## Just Recipes
128137

129138
```bash
130-
build # build docs and package
131-
build-docs # build the docs
132-
build-docs-html # build html documentation
133-
build-docs-pdf # build pdf documentation
134-
check # run all static checks
135-
check-docs # lint the documentation
136-
check-docs-links # check the documentation links for broken links
137-
check-format # check if the code needs formatting
138-
check-lint # lint the code
139-
check-package # run package checks
140-
check-readme # check that the readme renders
141-
check-types # run static type checking
142-
clean # remove all non repository artifacts
143-
clean-docs # remove doc build artifacts-
144-
clean-env # remove the virtual environment
145-
clean-git-ignored # remove all git ignored files
146-
coverage # generate the test coverage report
147-
debug-test *TESTS # debug a test - (break at test start/run in headed mode)
148-
docs # build and open the documentation
149-
docs-live # serve the documentation, with auto-reload
150-
fetch-refs LIB
151-
fix # fix formatting, linting issues and import sorting
152-
format # format the code and sort imports
153-
install *OPTS # update and install development dependencies
154-
install-docs # install documentation dependencies
155-
install-precommit # install git pre-commit hooks
156-
install_uv # install the uv package manager
157-
lint # sort the imports and fix linting issues
158-
make-test-migrations # regenerate test migrations using the lowest version of Django
159-
manage *COMMAND # run the django admin
160-
open-docs # open the html documentation
161-
precommit # run the pre-commit checks
162-
release VERSION # issue a release for the given semver string (e.g. 2.1.0)
163-
run +ARGS # run the command in the virtual environment
164-
setup python="python" # setup the venv, pre-commit hooks and playwright dependencies
165-
sort-imports # sort the python imports
166-
test *TESTS # run tests
167-
test-db DB_CLIENT="dev" *TESTS
168-
test-lock +PACKAGES # lock to specific python and versions of given dependencies
169-
validate_version VERSION # validate the given version string against the lib version
139+
build # build docs and package
140+
build-docs # build the docs
141+
build-docs-html # build html documentation
142+
build-docs-pdf # build pdf documentation
143+
check # run all static checks
144+
check-all # run all checks including doc link staleness (slow)
145+
check-docs # lint the documentation
146+
check-docs-links # check the documentation links for broken links
147+
check-format # check if the code needs formatting
148+
check-lint # lint the code
149+
check-package # run package checks
150+
check-readme # check that the readme renders
151+
check-types # run all static type checking
152+
check-types-isolated # run all static type checking in an isolated environment
153+
check-types-mypy *RUN_ARGS # run static type checking with mypy
154+
check-types-pyright *RUN_ARGS # run static type checking with pyright
155+
clean # remove all non repository artifacts
156+
clean-docs # remove doc build artifacts-
157+
clean-env # remove the virtual environment
158+
clean-git-ignored # remove all git ignored files
159+
coverage # generate the test coverage report
160+
debug-test *TESTS # debug an test
161+
docs # build and open the documentation
162+
docs-live # serve the documentation, with auto-reload
163+
fetch-refs LIB # get the intersphinx references for the given library
164+
fix # fix formatting, linting issues and import sorting
165+
format # format the code and sort imports
166+
install *OPTS # update and install development dependencies
167+
install-playwright # install playwright dependencies
168+
install-precommit # install git pre-commit hooks
169+
install_uv # install the uv package manager
170+
lint # sort the imports and fix linting issues
171+
manage *COMMAND # run the django admin
172+
open-docs # open the html documentation
173+
precommit # run the pre-commit checks
174+
release VERSION # issue a release for the given semver string (e.g. 2.1.0)
175+
remake-test-migrations # regenerate test migrations using the lowest version of Django
176+
run +ARGS # run the command in the virtual environment
177+
setup python="python" # setup the venv, pre-commit hooks and playwright dependencies
178+
sort-imports # sort the python imports
179+
test *TESTS # run tests
180+
test-db DB_CLIENT="dev" *TESTS # test against the specified database backend
181+
test-drf *TESTS # test django rest framework integration
182+
test-extra-views *TESTS # test django extra views integration
183+
test-guardian *TESTS # test guardian integration
184+
test-integrations DB_CLIENT="dev" # run all third party integration tests
185+
test-lock +PACKAGES # lock to specific python and versions of given dependencies
186+
test-reversion *TESTS # test django-revision integration
187+
validate_version VERSION # validate the given version string against the lib version
170188
```

0 commit comments

Comments
 (0)