Merge pull request #34 from unt-libraries/modernize

Begin modernizing the pycallnumber package (v0.2.0). - Add Python 3.8, 3.9, 3.10, 3.11 support. - Drop Python 3.4 support. - Move to `pyproject.toml` + `setup.cfg` package configuration. - Use `setuptools_scm` for versioning. - Move to a `src` layout. - Improve tox configuration for CI/CD.
unt-libraries · Nov 18, 2022 · dfabc0b · dfabc0b
2 parents 03f8f6c + d6ce545
commit dfabc0b
Show file tree

Hide file tree

Showing 46 changed files with 492 additions and 269 deletions.
diff --git a/.github/workflows/do-checks-and-tests.yml b/.github/workflows/do-checks-and-tests.yml
@@ -0,0 +1,60 @@
+name: Run linters and tests
+on: [push, workflow_call, workflow_dispatch]
+jobs:
+
+  run-linters:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: Upgrade pip and install tox
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install tox
+      - name: Run linter
+        run: tox -e flake8
+
+  run-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - python: '2.7'
+            tox-env: '27'
+          - python: '3.5'
+            tox-env: '35'
+          - python: '3.6'
+            tox-env: '36'
+          - python: '3.7'
+            tox-env: '37'
+          - python: '3.8'
+            tox-env: '38'
+          - python: '3.9'
+            tox-env: '39'
+          - python: '3.10'
+            tox-env: '310'
+          - python: '3.11'
+            tox-env: '311'
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Upgrade pip and install tox
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install tox
+      - name: Run tests
+        run: tox -e "py${{ matrix.tox-env }}-{oldest,latest}"
+
+  trigger-publish:
+    if: ${{ github.ref_type == 'tag' && startsWith(github.ref_name, 'v') }}
+    needs: [run-linters, run-tests]
+    uses: ./.github/workflows/publish.yml
+    secrets:
+      TEST_PYPI_API_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
+      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -0,0 +1,126 @@
+name: Build and publish package
+on:
+  workflow_call:
+    inputs:
+      skipTestUpload:
+        description: 'Skip uploading the package to Test PyPI?'
+        required: false
+        default: false
+        type: boolean
+      skipLiveUpload:
+        description: 'Skip uploading the package to Live PyPI?'
+        required: false
+        default: false
+        type: boolean
+    secrets:
+      TEST_PYPI_API_TOKEN:
+        required: true
+      PYPI_API_TOKEN:
+        required: true
+  workflow_dispatch:
+    inputs:
+      skipTestUpload:
+        description: 'Skip uploading the package to Test PyPI?'
+        required: false
+        default: false
+        type: boolean
+      skipLiveUpload:
+        description: 'Skip uploading the package to Live PyPI?'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: Upgrade pip and install tox
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install tox
+      - name: Build the package
+        run: tox -e build_package
+      - name: Tar the dist directory
+        run: tar -cvf dist.tar dist
+      - name: Upload dist.tar
+        uses: actions/upload-artifact@v3
+        with:
+          name: pycallnumber-dist
+          path: dist.tar
+          retention-days: 1
+
+  test-built-package:
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - python: '2.7'
+            tox-env: '27'
+          - python: '3.5'
+            tox-env: '35'
+          - python: '3.6'
+            tox-env: '36'
+          - python: '3.7'
+            tox-env: '37'
+          - python: '3.8'
+            tox-env: '38'
+          - python: '3.9'
+            tox-env: '39'
+          - python: '3.10'
+            tox-env: '310'
+          - python: '3.11'
+            tox-env: '311'
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Upgrade pip and install tox
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install tox
+      - name: Download dist.tar
+        uses: actions/download-artifact@v3
+        with:
+          name: pycallnumber-dist
+      - name: Un-tar built package
+        run: |
+          tar -xvf dist.tar
+          ls -Rl
+      - name: Install built package and run tests
+        run: tox -e "py${{ matrix.tox-env }}-test_built_package"
+
+  publish:
+    needs: test-built-package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download built package
+        uses: actions/download-artifact@v3
+        with:
+          name: pycallnumber-dist
+      - name: Un-tar built package
+        run: |
+          tar -xvf dist.tar
+          ls -Rl
+      - name: Publish package to Test PyPI
+        if: ${{ !inputs.skipTestUpload }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          repository_url: https://test.pypi.org/legacy/
+      - name: Publish package to Live PyPI
+        if: ${{ !inputs.skipLiveUpload && github.ref_type == 'tag' && startsWith(github.ref_name, 'v') && !(contains(github.ref_name, 'dev') || contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc')) }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -1,10 +1,11 @@
 *.pyc
-/dist/
-/build/
-/*.egg-info
-/*.egg
+dist/
+dist.tar
+build/
+*.egg-info
+*.egg
 .cache/
 __pycache__/
 .python-version
-/.eggs/
-/.tox/
+.eggs/
+.tox/
diff --git a/.travis.yml b/.travis.yml
diff --git a/LICENSE.txt → LICENSE b/LICENSE.txt → LICENSE
diff --git a/MANIFEST.in b/MANIFEST.in
diff --git a/README.md b/README.md
@@ -1,4 +1,6 @@
-# pycallnumber [![Build Status](https://travis-ci.org/unt-libraries/pycallnumber.svg?branch=master)](https://travis-ci.org/unt-libraries/pycallnumber)
+# pycallnumber
+
+[![Build Status](https://github.com/unt-libraries/pycallnumber/actions/workflows/do-checks-and-tests.yml/badge.svg?branch=master)](https://github.com/unt-libraries/pycallnumber/actions)
 
 Use pycallnumber in your library's Python projects to parse, model, and manipulate any type of call number string. Support for Library of Congress, Dewey Decimal, SuDocs, and local call numbers is built in, and you can extend built-in classes to customize behavior or model other types of call numbers and formatted strings.
 
@@ -10,60 +12,68 @@ Use pycallnumber in your library's Python projects to parse, model, and manipula
 
 ### Requirements
 
-  * Python 2.7, 3.4, 3.5, 3.6, or 3.7
+Tests pass on Linux and MacOS Python 2.7, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10, and 3.11. Versions 3.4 and below may still work, but I'm unable to get these to compile any more so cannot test them.
+
+#### Warning: Outdated Python Versions
+
+***Warning*** — The next release, v1.0.0, will drop support for Python versions older than 3.7.
+
+### Dependencies
+
+If you're using Python >=3.8, there are no external dependencies beyond the standard library.
+
+For Python 2.7 to 3.7, the `importlib_metadata` backport is used for `importlib.metadata` functionality (first available in Python 3.8).
+
+For Python 2.7, the `future` module is used to replicate various Python 3 behaviors.
 
 ### Setup
 
-Installing to a [virtualenv](http://docs.python-guide.org/en/latest/dev/virtualenvs/) using pip is recommended.
+Installing to a [virtualenv](https://docs.python-guide.org/en/latest/dev/virtualenvs/) using pip is recommended.
 
 ```sh
-$ pip install -U pip        # Do this if the install fails at first
-$ pip install pycallnumber
+$ python -m pip install pycallnumber
 ```
 
 #### Development setup and testing
 
-If you want to contribute to pycallnumber, you'll want to fork the project and then download and install your fork from GitHub. E.g.:
+If you want to contribute to pycallnumber, you should fork the project and then download and install your fork from GitHub. E.g.:
 
 ```sh
-$ git clone https://github.com/[your-github-user]/pycallnumber.git pycallnumber
+git clone https://github.com/[your-github-user]/pycallnumber.git pycallnumber
 ```
 or (SSH)
 ```sh
-$ git clone git@github.com:[your-github-user]/pycallnumber.git pycallnumber
+git clone git@github.com:[your-github-user]/pycallnumber.git pycallnumber
 ```
 
-```sh
-$ pip install ./pycallnumber
-```
-or, if you're updating to a newer version,
-```sh
-$ pip install --upgrade ./pycallnumber
-```
+Then use pip to do an editable install of the package with the `dev` extras (which installs pytest).
 
-If not using pip, you can run the setuptools install command instead:
 ```sh
-$ cd pycallnumber
-$ python setup.py install
+cd pycallnumber
+python -m pip install -e .[dev]
 ```
 
 ##### Running tests
 
-(The below commands assume you've installed from GitHub and are in the repository root.)
+(The below commands assume you've installed from GitHub as described above and are in the repository root.)
 
-You can use [pytest](http://doc.pytest.org/) to run tests in your current Python environment.
+Invoke [pytest](http://doc.pytest.org/) to run tests in your current Python environment.
 ```sh
-$ pip install pytest
-$ py.test
+pytest
 ```
 
-Or you can use [tox](https://tox.readthedocs.io/) to run tests against multiple Python versions.
+##### Tox
+
+You can use [tox](https://tox.wiki/en/latest/) to run tests against multiple Python versions, provided you have them available on the `PATH`. An excellent tool for this is [pyenv](https://github.com/pyenv/pyenv) with [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv).
+
+The tox configuration is in `pyproject.toml` (see the `[tool.tox]` section), which defines several test environments. You can run them all at once or target specific environments.
+
 ```sh
-$ pip install tox
-$ tox               # run tests against all configured environments
-$ tox -e py27       # run tests just against python 2.7
-$ tox -e py34       # run tests just against python 3.4
-etc.
+tox                  # run tests against all configured environments
+tox -e py27-oldest   # run tests against python 2.7 with oldest deps
+tox -e py310-latest  # run tests against python 3.10 with latest deps
+tox -e flake8        # run flake8 linting
+# etc.
 ```
 
 [Top](#top)

diff --git a/pycallnumber/__init__.py b/pycallnumber/__init__.py