data/config path entry_points with minimal examples

.github/workflows/test.yml

@@ -1,5 +1,8 @@
-# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+# This workflow will install Python dependencies, run tests and lint with a
+# variety of Python versions
+#
+# For more information see:
+# https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
 
 name: Python package
 
@@ -9,38 +12,142 @@ on:
   pull_request:
     branches: [ master ]
 
+env:
+  PIP_DISABLE_PIP_VERSION_CHECK: 1
+
+defaults:
+  run:
+    shell: bash -l {0}
+
 jobs:
   build:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
 
-    runs-on: ${{ matrix.os }}
+      - name: Upgrade packaging deps
+        run: |
+          set -eux
+          python -m pip install --upgrade --user pip wheel setuptools
+
+      - name: Build distributions
+        run: |
+          set -eux
+          python setup.py sdist bdist_wheel
+          cd dist
+          sha256sum * | tee SHA256SUMS
+
+      - name: publish dists
+        uses: actions/upload-artifact@v2
+        with:
+          name: jupyter_core dist ${{ github.run_number }}
+          path: ./dist
+
+  test:
+    needs: [build]
+    runs-on: ${{ matrix.os }}-latest
     strategy:
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        os: [ubuntu, macos, windows]
+        python-version: [3.6, 3.7, 3.8, 3.9, pypy3]
+        include:
+          - os: ubuntu
+            py-cmd: python
+          - os: macos
+            py-cmd: python3
+          - os: windows
+            py-cmd: python
+          # different dists
+          - python-version: 3.6
+            dist: jupyter_core*.tar.gz
+          - python-version: 3.7
+            dist: jupyter_core*.whl
+          - python-version: 3.8
+            dist: jupyter_core*.tar.gz
+          - python-version: 3.9
+            dist: jupyter_core*.whl
+          - python-version: pypy3
+            dist: jupyter_core*.tar.gz
+        exclude:
+          - os: windows
+            python-version: pypy3
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Get pip cache dir
-      id: pip-cache
-      run: |
-        echo "::set-output name=dir::$(pip cache dir)"
-    - name: pip cache
-      uses: actions/cache@v2
-      with:
-        path: ${{ steps.pip-cache.outputs.dir }}
-        key: ${{ runner.os }}-pip-${{ hashFiles('dev-requirements.txt', 'setup.cfg') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install --upgrade setuptools
-        pip install --upgrade nose
-        pip install -r dev-requirements.txt .
-    - name: Test with pytest
-      run: |
-        pytest jupyter_core
+      - uses: actions/checkout@v2
+
+      - uses: actions/download-artifact@v2
+        with:
+          name: jupyter_core dist ${{ github.run_number }}
+          path: ./dist
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Upgrade packaging deps
+        run: |
+          ${{ matrix.py-cmd }} -m pip install --upgrade pip wheel setuptools
+
+      - name: Install distribution and test dependencies
+        run: |
+          set -eux
+          cd dist
+          ls
+          ${{ matrix.py-cmd }} -m pip install -r ../dev-requirements.txt
+          ${{ matrix.py-cmd }} -m pip install --ignore-installed $(ls ${{ matrix.dist }})
+          ${{ matrix.py-cmd }} -m pip freeze
+          ${{ matrix.py-cmd }} -m pip check
+
+      - name: Test with pytest (entrypoints)
+        run: |
+          set -eux
+          cd dist
+          ${{ matrix.py-cmd }} -m pytest -vv --ff --pyargs jupyter_core \
+            --cov=jupyter_core \
+            --cov-report=term-missing:skip-covered \
+            --cov-report=html \
+            --no-cov-on-fail
+
+      - name: Test with pytest (importlib_metadata)
+        env:
+          JUPYTER_ENTRY_POINT_FINDER: importlib_metadata
+        run: |
+          set -eux
+          cd dist
+          ${{ matrix.py-cmd }} -m pytest -vv --ff --pyargs jupyter_core \
+            --cov=jupyter_core \
+            --cov-report=term-missing:skip-covered \
+            --cov-report=html \
+            --no-cov-on-fail
+
+      - name: Upload coverage
+        if: ${{ matrix.python-version != 'pypy3' }}
+        run: |
+          set -eux
+          cd dist
+          ${{ matrix.py-cmd }} -m pip install -vv codecov
+          ${{ matrix.py-cmd }} -m codecov
+
+      - name: Test setuptools example
+        run: |
+          set -eux
+          cd examples/jupyter_path_entrypoint_setuptools
+          ${{ matrix.py-cmd }} -m pip install -e .
+          ${{ matrix.py-cmd }} -m jupyter --paths | tee paths.txt
+          cat paths.txt | grep entry_point_example_setuptools.share.jupyter
+          cat paths.txt | grep entry_point_example_setuptools.etc.jupyter
+
+      - name: Test flit example
+        run: |
+          set -eux
+          ${{ matrix.py-cmd }} -m pip install flit
+          cd examples/jupyter_path_entrypoint_flit
+          ${{ matrix.py-cmd }} -m flit install --pth-file
+          ${{ matrix.py-cmd }} -m jupyter --paths | tee paths.txt
+          cat paths.txt | grep entry_point_example_flit.share.jupyter
+          cat paths.txt | grep entry_point_example_flit.etc.jupyter

MANIFEST.in

@@ -13,6 +13,7 @@ graft jupyter_core/tests/dotipython_empty
 
 # docs subdirs we want to skip
 prune docs/_build
+prune examples
 
 # Patterns to exclude from any directory
 global-exclude *~

dev-requirements.txt

@@ -1,2 +1,3 @@
-pytest
 ipykernel
+pytest
+pytest-cov

docs/changelog.rst

@@ -1,6 +1,19 @@
 Changes in jupyter-core
 =======================
 
+4.8
+---
+
+4.8.0
+~~~~~
+
+`on
+GitHub <https://github.com/jupyter/jupyter_core/releases/tag/4.8.0>`__
+
+- Add new ``jupyter_data_paths`` and ``jupyter_config_paths`` ``entry_points``
+  (:ghpull:`209`) to allow python packages to extend the data and config paths
+  in ``jupyter --paths``. These paths are considered immediately after those put
+  in-place with ``data_files``, but work with modern python packaging tools.
 
 4.7
 ---

examples/jupyter_path_entrypoint_flit/COPYING.md

@@ -0,0 +1,61 @@
+# The Jupyter licensing terms
+
+Jupyter is licensed under the terms of the Modified BSD License (also known as
+New or Revised or 3-Clause BSD), as follows:
+
+- Copyright (c) 2015-, Jupyter Development Team
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, this
+list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+Neither the name of the Jupyter Development Team nor the names of its
+contributors may be used to endorse or promote products derived from this
+software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+## About the Jupyter Development Team
+
+The Jupyter Development Team is the set of all contributors to the Jupyter
+project.  This includes all of the Jupyter subprojects. A full list with
+details is kept in the documentation directory, in the file
+`about/credits.txt`.
+
+The core team that coordinates development on GitHub can be found here:
+https://github.com/ipython/.
+
+## Our Copyright Policy
+
+Jupyter uses a shared copyright model. Each contributor maintains copyright
+over their contributions to Jupyter. It is important to note that these
+contributions are typically only changes to the repositories. Thus, the Jupyter
+source code in its entirety is not the copyright of any single person or
+institution.  Instead, it is the collective copyright of the entire Jupyter
+Development Team.  If individual contributors want to maintain a record of what
+changes/contributions they have specific copyright on, they should indicate
+their copyright in the commit message of the change, when they commit the
+change to one of the Jupyter repositories.
+
+With this in mind, the following banner should be used in any source code file
+to indicate the copyright and license terms:
+
+    # Copyright (c) Jupyter Development Team.
+    # Distributed under the terms of the Modified BSD License.

examples/jupyter_path_entrypoint_flit/README.md

@@ -0,0 +1,39 @@
+# entry_point_example_flit
+
+A minimal example of a package which provides additional `jupyter_*_path`s
+via `entry_points`, packaged with `flit`.
+
+## Developing
+
+### Setup
+
+- ensure `flit` is installed
+
+### Editable install
+
+On any platform, enable live development by putting a `.pth` file in `site-packages`:
+
+```bash
+flit install --pth-file
+```
+
+On UNIX, a symlink may be used instead:
+
+```bash
+flint install --symlink
+```
+
+### Building
+
+```bash
+flit build
+```
+
+Optionally, set the `SOURCE_DATE_EPOCH` environment variable to ensure a
+[reproducible](https://reproducible-builds.org) `.whl`.
+
+> For example, to use the last `git` commit:
+>
+> ```bash
+> SOURCE_DATE_EPOCH=$(git log -1 --format=%ct) flit build
+> ```

examples/jupyter_path_entrypoint_flit/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["flit_core >=2,<4"]
+build-backend = "flit_core.buildapi"
+
+[tool.flit.metadata]
+module = "entry_point_example_flit"
+author = "Sir Robin"
+author-email = "[email protected]"
+home-page = "https://github.com/sirrobin/foobar"
+
+[tool.flit.entrypoints.jupyter_config_paths]
+entry-point-example-flit = "entry_point_example_flit:JUPYTER_CONFIG_PATHS"
+
+[tool.flit.entrypoints.jupyter_data_paths]
+entry-point-example-flit = "entry_point_example_flit:JUPYTER_DATA_PATHS"
+
+[tool.flit.sdist]
+include = ["src/entry_point_example_flit/etc/", "src/entry_point_example_flit/share/"]
+exclude = ["src/entry_point_example_flit/share/*/example_excluded_file_flit.json"]

examples/jupyter_path_entrypoint_flit/src/entry_point_example_flit/__init__.py

@@ -0,0 +1,5 @@
+"""an example of using the jupyter_*_paths entry_points with flit"""
+__version__ = "0.1.0"
+
+JUPYTER_CONFIG_PATHS = ["etc/jupyter"]
+JUPYTER_DATA_PATHS = ["share/jupyter"]

examples/jupyter_path_entrypoint_flit/src/entry_point_example_flit/etc/jupyter/jupyter_config.d/entrypoint-example-flit.json

@@ -0,0 +1,5 @@
+{
+  "SingletonConfigurable": {
+    "log_level": "INFO"
+  }
+}

examples/jupyter_path_entrypoint_flit/src/entry_point_example_flit/share/jupyter/example_excluded_file_flit.json

@@ -0,0 +1 @@
+[]

examples/jupyter_path_entrypoint_flit/src/entry_point_example_flit/share/jupyter/example_file_flit.json

@@ -0,0 +1 @@
+{}