Merge branch 'master' into default_prefixes

Author: nicholascar

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,61 @@
+<!--
+Thank you for your contribution to this project. This project has no formal
+funding or full-time maintainers and relies entirely on independent
+contributors to keep it alive and relevant.
+
+This pull request template includes some guidelines intended to help
+contributors, not to deter contributions. While we prefer that PRs follow our
+guidelines, we will not reject PRs solely on the basis that they do not, though
+we may take longer to process them as in most cases the remaining work will
+have to be done by someone else.
+
+If you have any questions regarding our guidelines, submit the PR as is
+and ask.
+
+More detailed guidelines for pull requests are provided in our [developers
+guide](https://github.com/RDFLib/rdflib/blob/master/docs/developers.rst).
+
+As a reminder, PRs that are smaller in size and scope will be reviewed and
+merged quicker, so please consider if your PR could be split up into more than
+one independent part before submitting it, no PR is too small. The maintainers
+of this project may also split up larger PRs into smaller more manageable PRs
+if they deem it necessary.
+
+PRs should be reviewed and approved by at least two people other than the
+author using GitHub's review system before being merged. Reviews are open to
+anyone, so please consider reviewing other open pull requests as this will also
+free up the capacity required for your PR to be reviewed.
+-->
+
+# Summary of changes
+
+<!--
+Briefly explain what changes the pull request is making and why. Ideally this
+should cover all changes in the pull request as the changes will be reviewed
+against this summary to ensure that the PR does not include unintended changes.
+
+Please also explicitly state if the PR makes any changes that are not backwards
+compatible.
+-->
+
+# Checklist
+
+<!--
+If an item on this list doesn't apply to your pull request, just remove it.
+
+If, for some reason, you can't check some items on the checklist, or you are
+unsure about them, submit your PR as is and ask for help.
+-->
+
+- [ ] Checked that there aren't other open pull requests for
+  the same change.
+- [ ] Added tests for any changes that have a runtime impact.
+- [ ] Checked that all tests and type checking passes.
+- For changes that have a potential impact on users of this project:
+  - [ ] Updated relevant documentation to avoid inaccuracies.
+  - [ ] Considered adding additional documentation.
+  - [ ] Considered adding an example in `./examples` for new features.
+  - [ ] Considered updating our changelog (`CHANGELOG.md`).
+- [ ] Considered granting [push permissions to the PR branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork),
+  so maintainers can fix minor issues and keep your PR up to date.
+

.github/workflows/validate.yaml

@@ -20,29 +20,39 @@ jobs:
         python-version: ["3.7", "3.8", "3.9", "3.10"]
         os: [ubuntu-latest, macos-latest, windows-latest]
         include:
-          - {
-              python-version: "3.7",
-              os: ubuntu-latest,
-              extensive-tests: true,
-            }
+          - python-version: "3.7"
+            os: ubuntu-latest
+            extensive-tests: true
+          - python-version: "3.8"
+            os: ubuntu-latest
+            TOX_EXTRA_COMMAND: "- isort --check-only --diff ."
+          - python-version: "3.9"
+            os: ubuntu-latest
+            TOX_EXTRA_COMMAND: "- black --check --diff ./rdflib"
+          - python-version: "3.10"
+            os: ubuntu-latest
+            TOX_EXTRA_COMMAND: "flake8 --exit-zero rdflib"
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
-
       - uses: actions/setup-java@v2
         if: ${{ matrix.extensive-tests }}
         with:
           distribution: "temurin"
           java-version: "17"
-
+      - name: Setup env
+        shell: bash
+        run: |
+          MATRIX_PYTHON_VERSION=${{ matrix.python-version }}
+          echo "TOX_PYENV=py${MATRIX_PYTHON_VERSION//./}" >> ${GITHUB_ENV}
       - name: Get pip cache dir
         id: pip-cache
         shell: bash
         run: |
-          python -m ensurepip --upgrade
+          python -m ensurepip
           echo "::set-output name=dir::$(pip cache dir)"
       - name: Cache pip
         uses: actions/cache@v2
@@ -59,13 +69,15 @@ jobs:
           key: ${{ matrix.os }}-xdg-v1-${{ hashFiles('**/with-fuseki.sh') }}
           restore-keys: |
             ${{ matrix.os }}-xdg-v1-
-      - name: Install dependencies
+      - name: Install python dependencies
         shell: bash
+        # Installing tox-gh-actions to get some enhancement to output rendering
+        # in github actions. Eventually we can maybe collapse the tox-envs job
+        # into this one but there are some limitations of tox-gh-actions which
+        # preclude doing that at the moment.
         run: |
-          pip install --default-timeout 60 -r requirements.txt
-          pip install --default-timeout 60 -r requirements.dev.txt
-          python setup.py install
-      - name: Install extra dev dependencies
+          python -m pip install tox tox-gh-actions
+      - name: Install system depdendencies for extensive tests
         if: ${{ matrix.extensive-tests }}
         shell: bash
         run: |
@@ -77,7 +89,6 @@ jobs:
               brew install berkeley-db@4
               export BERKELEYDB_DIR=$(brew --prefix berkeley-db@4)
           fi
-          pip install --default-timeout 60 -r requirements.dev-extra.txt
       - name: Validate
         shell: bash
         run: |
@@ -86,14 +97,19 @@ jobs:
           then
             1>&2 echo "Running with fuseki"
             test_harness+="./with-fuseki.sh"
+            TOX_PYENV_SUFFIX=-extensive
           fi
-          black --config pyproject.toml --check --diff ./rdflib || true
-          isort --check-only --diff . || true
-          flake8 --exit-zero rdflib
-          mypy --show-error-context --show-error-codes
-          "${test_harness[@]}" pytest -ra --cov
+          TOXENV="${{ matrix.TOXENV }}"
+          TOXENV="${TOX_PYENV}${TOX_PYENV_SUFFIX}${TOXENV:+,${TOXENV}}"
+          export TOXENV
+          export TOX_EXTRA_COMMAND="${{ matrix.TOX_EXTRA_COMMAND }}"
+          "${test_harness[@]}" python -m tox
   docs:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        tox-env: ["docs"]
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python ${{env.DEFAULT_PYTHON}}
@@ -110,15 +126,15 @@ jobs:
         uses: actions/cache@v2
         with:
           path: ${{ steps.pip-cache.outputs.dir }}
-          key: docs-pip-v1-${{
+          key: tox-${{ matrix.tox-env }}-pip-v1-${{
             hashFiles('**/setup.py', '**/requirements*.txt') }}
           restore-keys: |
-            docs-pip-v1-
+            tox-${{ matrix.tox-env }}-pip-v1-
       - name: Install dependencies
         shell: bash
         run: |
-          python -m pip install tox
-      - name: Build docs
+          python -m pip install tox tox-gh-actions
+      - name: Run ${{ matrix.tox-env }}
         shell: bash
         run: |
-          python -m tox -e docs
+          python -m tox -e ${{ matrix.tox-env }}

.pre-commit-config.yaml

@@ -25,8 +25,8 @@ repos:
       description: "Black: The uncompromising Python code formatter"
       entry: black
       language: python
-      # WARNING: version should be the same as in `pyproject.toml`.
-      additional_dependencies: [black==21.9b0]
+      # WARNING: version should be the same as in `pyproject.toml` and `requirements.dev.txt`.
+      additional_dependencies: ["black>=22.0,<23"]
       # This is here to defer file selection to black which will do it based on
       # black config.
       pass_filenames: false

.readthedocs.yaml

@@ -0,0 +1,16 @@
+---
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+formats: all
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.7"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

docs/conf.py

@@ -43,6 +43,7 @@
 apidoc_module_dir = "../rdflib"
 apidoc_output_dir = "apidocs"
 autodoc_default_options = {"special-members": True}
+autodoc_typehints = "both"
 
 autosummary_generate = True
 

docs/developers.rst

@@ -10,14 +10,63 @@ This document describes the process and conventions to follow when
 developing RDFLib code.
 
 * Please be as Pythonic as possible (:pep:`8`).
-* Code should be formatted using `black <https://github.com/psf/black>`_
-  and we use Black v21.9b0, with the black.toml config file provided.
+* Code should be formatted using `black <https://github.com/psf/black>`_  and we use Black v22.1.0, with the black config in ``pyproject.toml``.
 * Code should also pass `flake8 <https://github.com/psf/black>`_ linting
   and `mypy <http://mypy-lang.org/>`_ type checking.
-* You must supply tests for new code
+* You must supply tests for new code.
 
 If you add a new cool feature, consider also adding an example in ``./examples``
 
+Pull Requests Guidelines
+------------------------
+
+Contributions to RDFLib are made through pull requests (PRs).
+
+In general, maintainers will only merge PRs if the following conditions are
+met:
+
+* The PR has been sufficiently reviewed.
+
+  Each PR should be reviewed and approved by at least two people other than the
+  author of the PR before it is merged and PRs will be processed faster if
+  they are easier to review and approve of.
+
+  Reviews are open to everyone, but the weight assigned to any particular
+  review is at the discretion of maintainers.
+
+* Changes that have a runtime impact are covered by unit tests.
+
+  There should either be existing tests that cover the changed code and
+  behaviour, or the PR should include tests. For more information about what is
+  considered adequate testing see the :ref:`Tests section <Tests>`.
+
+* Documentation that covers something that changed has been updated.
+
+* Type checks and unit tests that are part of our continuous integration
+  workflow pass.
+
+In addition to these conditions, PRs that are easier to review and approve will
+be processed quicker. The primary factors that determine this is the scope and
+size of a PR. If there are few changes and the scope is limited then there is
+less that a reviewer has to understand and less that they can disagree with. It
+is thus important to try and split up your changes into multiple independent
+PRs if possible. No PR is too small.
+
+For PRs that introduce breaking changes, it is even more critical that they are
+limited in size and scope, as they will likely have to be kept up to date with
+the master branch of this project for some time before they are merged.
+
+It is also critical that your PR is understandable both in what it does and why
+it does it, and how the change will impact the users of this project, for this
+reason it is essential that your PR's description explains the nature of the
+PR, what the PR intends to do, why this is desirable, and how this will affect
+the users of this project.
+
+Please note that while we would like all PRs to follow the guidelines given
+here, we will not reject a PR just because it does not.
+
+.. Tests:
+
 Tests
 -----
 Any new functionality being added to RDFLib _must_ have unit tests and
@@ -156,21 +205,26 @@ makes it easier to run validation on all supported python versions.
 
 .. code-block:: bash
 
-    # install tox
+    # Install tox.
     pip install tox
 
-    # list tox environments that run by default
+    # List the tox environments that run by default.
     tox -e
 
-    # list all tox environments
-    tox -a
-
-    # run default environment for all python versions
+    # Run the default environments.
     tox
 
-    # run a specific environment
+    # List all tox environments, including ones that don't run by default.
+    tox -a
+
+    # Run a specific environment.
     tox -e py37 # default environment with py37
-    tox -e py39-mypy # mypy environment with py39
+    tox -e py39-extra # extra tests with py39
+
+    # Override the test command.
+    # the below command will run `pytest test/test_translate_algebra.py`
+    # instead of the default pytest command.
+    tox -e py37,py39 -- pytest test/test_translate_algebra.py
 
 Writing documentation
 ---------------------

docs/index.rst

@@ -87,6 +87,7 @@ For developers
    CODE_OF_CONDUCT
    docs
    persisting_n3_terms
+   type_hints
 
 Source Code
 -----------

docs/sphinx-requirements.txt

@@ -1,5 +1,5 @@
-sphinx==4.4.0
-sphinxcontrib-apidoc
 git+https://github.com/gniezen/n3pygments.git
 myst-parser
+sphinx<5
+sphinxcontrib-apidoc
 sphinxcontrib-kroki