Initial commit

.dockerignore

@@ -0,0 +1,7 @@
+.git
+.github
+.mypy_cache
+.pytest_cache
+.venv
+__pycache__
+*.egg-info

.github/CONTRIBUTING.md

@@ -0,0 +1,168 @@
+# Contributing
+
+Thanks for considering contributing! Please read this document to learn the various ways you can contribute to this project and how to go about doing it.
+
+## Bug reports and feature requests
+
+### Did you find a bug?
+
+First, do [a quick search](https://github.com/allenai/python-package-template/issues) to see whether your issue has already been reported.
+If your issue has already been reported, please comment on the existing issue.
+
+Otherwise, open [a new GitHub issue](https://github.com/allenai/python-package-template/issues).  Be sure to include a clear title
+and description.  The description should include as much relevant information as possible.  The description should
+explain how to reproduce the erroneous behavior as well as the behavior you expect to see.  Ideally you would include a
+code sample or an executable test case demonstrating the expected behavior.
+
+### Do you have a suggestion for an enhancement or new feature?
+
+We use GitHub issues to track feature requests. Before you create a feature request:
+
+* Make sure you have a clear idea of the enhancement you would like. If you have a vague idea, consider discussing
+it first on a GitHub issue.
+* Check the documentation to make sure your feature does not already exist.
+* Do [a quick search](https://github.com/allenai/python-package-template/issues) to see whether your feature has already been suggested.
+
+When creating your request, please:
+
+* Provide a clear title and description.
+* Explain why the enhancement would be useful. It may be helpful to highlight the feature in other libraries.
+* Include code examples to demonstrate how the enhancement would be used.
+
+## Making a pull request
+
+When you're ready to contribute code to address an open issue, please follow these guidelines to help us be able to review your pull request (PR) quickly.
+
+1. **Initial setup** (only do this once)
+
+    <details><summary>Expand details 👇</summary><br/>
+
+    If you haven't already done so, please [fork](https://help.github.com/en/enterprise/2.13/user/articles/fork-a-repo) this repository on GitHub.
+
+    Then clone your fork locally with
+
+        git clone https://github.com/USERNAME/python-package-template.git
+
+    or 
+
+        git clone git@github.com:USERNAME/python-package-template.git
+
+    At this point the local clone of your fork only knows that it came from *your* repo, github.com/USERNAME/python-package-template.git, but doesn't know anything the *main* repo, [https://github.com/allenai/python-package-template.git](https://github.com/allenai/python-package-template). You can see this by running
+
+        git remote -v
+
+    which will output something like this:
+
+        origin https://github.com/USERNAME/python-package-template.git (fetch)
+        origin https://github.com/USERNAME/python-package-template.git (push)
+
+    This means that your local clone can only track changes from your fork, but not from the main repo, and so you won't be able to keep your fork up-to-date with the main repo over time. Therefore you'll need to add another "remote" to your clone that points to [https://github.com/allenai/python-package-template.git](https://github.com/allenai/python-package-template). To do this, run the following:
+
+        git remote add upstream https://github.com/allenai/python-package-template.git
+
+    Now if you do `git remote -v` again, you'll see
+
+        origin https://github.com/USERNAME/python-package-template.git (fetch)
+        origin https://github.com/USERNAME/python-package-template.git (push)
+        upstream https://github.com/allenai/python-package-template.git (fetch)
+        upstream https://github.com/allenai/python-package-template.git (push)
+
+    Finally, you'll need to create a Python 3 virtual environment suitable for working on this project. There a number of tools out there that making working with virtual environments easier.
+    The most direct way is with the [`venv` module](https://docs.python.org/3.7/library/venv.html) in the standard library, but if you're new to Python or you don't already have a recent Python 3 version installed on your machine,
+    we recommend [Miniconda](https://docs.conda.io/en/latest/miniconda.html).
+
+    On Mac, for example, you can install Miniconda with [Homebrew](https://brew.sh/):
+
+        brew install miniconda
+
+    Then you can create and activate a new Python environment by running:
+
+        conda create -n my-package python=3.9
+        conda activate my-package
+
+    Once your virtual environment is activated, you can install your local clone in "editable mode" with
+
+        pip install -U pip setuptools wheel
+        pip install -e .[dev]
+
+    The "editable mode" comes from the `-e` argument to `pip`, and essential just creates a symbolic link from the site-packages directory of your virtual environment to the source code in your local clone. That way any changes you make will be immediately reflected in your virtual environment.
+
+    </details>
+
+2. **Ensure your fork is up-to-date**
+
+    <details><summary>Expand details 👇</summary><br/>
+
+    Once you've added an "upstream" remote pointing to [https://github.com/allenai/python-package-temlate.git](https://github.com/allenai/python-package-template), keeping your fork up-to-date is easy:
+
+        git checkout main  # if not already on main
+        git pull --rebase upstream main
+        git push
+
+    </details>
+
+3. **Create a new branch to work on your fix or enhancement**
+
+    <details><summary>Expand details 👇</summary><br/>
+
+    Committing directly to the main branch of your fork is not recommended. It will be easier to keep your fork clean if you work on a separate branch for each contribution you intend to make.
+
+    You can create a new branch with
+
+        # replace BRANCH with whatever name you want to give it
+        git checkout -b BRANCH
+        git push -u origin BRANCH
+
+    </details>
+
+4. **Test your changes**
+
+    <details><summary>Expand details 👇</summary><br/>
+
+    Our continuous integration (CI) testing runs [a number of checks](https://github.com/allenai/python-package-template/actions) for each pull request on [GitHub Actions](https://github.com/features/actions). You can run most of these tests locally, which is something you should do *before* opening a PR to help speed up the review process and make it easier for us.
+
+    First, you should run [`isort`](https://github.com/PyCQA/isort) and [`black`](https://github.com/psf/black) to make sure you code is formatted consistently.
+    Many IDEs support code formatters as plugins, so you may be able to setup isort and black to run automatically everytime you save.
+    For example, [`black.vim`](https://github.com/psf/black/tree/master/plugin) will give you this functionality in Vim. But both `isort` and `black` are also easy to run directly from the command line.
+    Just run this from the root of your clone:
+
+        isort .
+        black .
+
+    Our CI also uses [`ruff`](https://github.com/astral-sh/ruff) to lint the code base and [`mypy`](http://mypy-lang.org/) for type-checking. You should run both of these next with
+
+        ruff check .
+
+    and
+
+        mypy .
+
+    We also strive to maintain high test coverage, so most contributions should include additions to [the unit tests](https://github.com/allenai/python-package-template/tree/main/tests). These tests are run with [`pytest`](https://docs.pytest.org/en/latest/), which you can use to locally run any test modules that you've added or changed.
+
+    For example, if you've fixed a bug in `my_package/a/b.py`, you can run the tests specific to that module with
+
+        pytest -v tests/a/b_test.py
+
+    If your contribution involves additions to any public part of the API, we require that you write docstrings
+    for each function, method, class, or module that you add.
+    See the [Writing docstrings](#writing-docstrings) section below for details on the syntax.
+    You should test to make sure the API documentation can build without errors by running
+
+        make docs
+
+    If the build fails, it's most likely due to small formatting issues. If the error message isn't clear, feel free to comment on this in your pull request.
+
+    And finally, please update the [CHANGELOG](https://github.com/allenai/python-package-template/blob/main/CHANGELOG.md) with notes on your contribution in the "Unreleased" section at the top.
+
+    After all of the above checks have passed, you can now open [a new GitHub pull request](https://github.com/allenai/python-package-template/pulls).
+    Make sure you have a clear description of the problem and the solution, and include a link to relevant issues.
+
+    We look forward to reviewing your PR!
+
+    </details>
+
+### Writing docstrings
+
+We use [Sphinx](https://www.sphinx-doc.org/en/master/index.html) to build our API docs, which automatically parses all docstrings
+of public classes and methods using the [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) extension.
+Please refer to autoc's documentation to learn about the docstring syntax.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,46 @@
+name: 🐛 Bug Report
+description: Create a report to help us reproduce and fix the bug
+labels: 'bug'
+
+body:
+- type: markdown
+  attributes:
+    value: >
+      #### Before submitting a bug, please make sure the issue hasn't been already addressed by searching through [the existing and past issues](https://github.com/allenai/python-package-template/issues?q=is%3Aissue+sort%3Acreated-desc+).
+- type: textarea
+  attributes:
+    label: 🐛 Describe the bug
+    description: |
+      Please provide a clear and concise description of what the bug is.
+
+      If relevant, add a minimal example so that we can reproduce the error by running the code. It is very important for the snippet to be as succinct (minimal) as possible, so please take time to trim down any irrelevant code to help us debug efficiently. We are going to copy-paste your code and we expect to get the same result as you did: avoid any external data, and include the relevant imports, etc. For example:
+
+      ```python
+      # All necessary imports at the beginning
+      import my_package
+
+      # A succinct reproducing example trimmed down to the essential parts:
+      assert False is True, "Oh no!"
+      ```
+
+      If the code is too long (hopefully, it isn't), feel free to put it in a public gist and link it in the issue: https://gist.github.com.
+
+      Please also paste or describe the results you observe instead of the expected results. If you observe an error, please paste the error message including the **full** traceback of the exception. It may be relevant to wrap error messages in ```` ```triple quotes blocks``` ````.
+    placeholder: |
+      A clear and concise description of what the bug is.
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: Versions
+    description: |
+      Please run the following and paste the output below.
+      ```sh
+      python --version && pip freeze
+      ```
+  validations:
+    required: true
+- type: markdown
+  attributes:
+    value: >
+      Thanks for contributing 🎉!

.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,21 @@
+name: 📚 Documentation
+description: Report an issue related to https://my-package.readthedocs.io/latest
+labels: 'documentation'
+
+body:
+- type: textarea
+  attributes:
+    label: 📚 The doc issue
+    description: >
+      A clear and concise description of what content in https://my-package.readthedocs.io/latest is an issue.
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: Suggest a potential alternative/fix
+    description: >
+      Tell us how we could improve the documentation in this regard.
+- type: markdown
+  attributes:
+    value: >
+      Thanks for contributing 🎉!

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,26 @@
+name: 🚀 Feature request
+description: Submit a proposal/request for a new feature
+labels: 'feature request'
+
+body:
+- type: textarea
+  attributes:
+    label: 🚀 The feature, motivation and pitch
+    description: >
+      A clear and concise description of the feature proposal. Please outline the motivation for the proposal. Is your feature request related to a specific problem? e.g., *"I'm working on X and would like Y to be possible"*. If this is related to another GitHub issue, please link here too.
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: Alternatives
+    description: >
+      A description of any alternative solutions or features you've considered, if any.
+- type: textarea
+  attributes:
+    label: Additional context
+    description: >
+      Add any other context or screenshots about the feature request.
+- type: markdown
+  attributes:
+    value: >
+      Thanks for contributing 🎉!

.github/actions/setup-venv/action.yml

@@ -0,0 +1,56 @@
+name: Python virtualenv
+description: Set up a Python virtual environment with caching
+inputs:
+  python-version:
+    description: The Python version to use
+    required: true
+  cache-prefix:
+    description: Update this to invalidate the cache
+    required: true
+    default: v0
+runs:
+  using: composite
+  steps:
+    - name: Setup Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - shell: bash
+      run: |
+        # Install prerequisites.
+        pip install --upgrade pip setuptools wheel virtualenv
+
+    - shell: bash
+      run: |
+        # Get the exact Python version to use in the cache key.
+        echo "PYTHON_VERSION=$(python --version)" >> $GITHUB_ENV
+
+    - uses: actions/cache@v2
+      id: virtualenv-cache
+      with:
+        path: .venv
+        key: ${{ inputs.cache-prefix }}-${{ runner.os }}-${{ env.PYTHON_VERSION }}-${{ hashFiles('pyproject.toml') }}
+
+    - if: steps.virtualenv-cache.outputs.cache-hit != 'true'
+      shell: bash
+      run: |
+        # Set up virtual environment without cache hit.
+        test -d .venv || virtualenv -p $(which python) --copies --reset-app-data .venv
+        . .venv/bin/activate
+        pip install -e .[dev]
+
+    - if: steps.virtualenv-cache.outputs.cache-hit == 'true'
+      shell: bash
+      run: |
+        # Set up virtual environment from cache hit.
+        . .venv/bin/activate
+        pip install --no-deps -e .[dev]
+
+    - shell: bash
+      run: |
+        # Show environment info.
+        . .venv/bin/activate
+        echo "✓ Installed $(python --version) virtual environment to $(which python)"
+        echo "Packages:"
+        pip freeze

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+- package-ecosystem: "pip"
+  directory: "/"
+  schedule:
+    interval: "daily"
+  open-pull-requests-limit: 10
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "daily"

.github/pull_request_template.md

@@ -0,0 +1,18 @@
+<!-- To ensure we can review your pull request promptly please complete this template entirely. -->
+
+<!-- Please reference the issue number here. You can replace "Fixes" with "Closes" if it makes more sense. -->
+Fixes #
+
+Changes proposed in this pull request:
+<!-- Please list all changes/additions here. -->
+-
+
+## Before submitting
+
+<!-- Please complete this checklist BEFORE submitting your PR to speed along the review process. -->
+- [ ] I've read and followed all steps in the [Making a pull request](https://github.com/allenai/python-package-template/blob/main/.github/CONTRIBUTING.md#making-a-pull-request)
+    section of the `CONTRIBUTING` docs.
+- [ ] I've updated or added any relevant docstrings following the syntax described in the
+    [Writing docstrings](https://github.com/allenai/python-package-template/blob/main/.github/CONTRIBUTING.md#writing-docstrings) section of the `CONTRIBUTING` docs.
+- [ ] If this PR fixes a bug, I've added a test that will fail without my fix.
+- [ ] If this PR adds a new feature, I've added tests that sufficiently cover my new functionality.

.github/workflows/main.yml

@@ -0,0 +1,149 @@
+name: Main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+    tags:
+      - "v*.*.*"
+
+env:
+  # Change this to invalidate existing cache.
+  CACHE_PREFIX: v0
+  PYTHONPATH: ./
+
+jobs:
+  checks:
+    name: Python ${{ matrix.python }} - ${{ matrix.task.name }}
+    runs-on: [ubuntu-latest]
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.8", "3.10"]
+        task:
+          - name: Test
+            run: |
+              pytest -v --color=yes tests/
+
+        include:
+          - python: "3.10"
+            task:
+              name: Lint
+              run: ruff check .
+
+          - python: "3.10"
+            task:
+              name: Type check
+              run: mypy .
+
+          - python: "3.10"
+            task:
+              name: Build
+              run: |
+                python -m build
+
+          - python: "3.10"
+            task:
+              name: Style
+              run: |
+                isort --check .
+                black --check .
+
+          - python: "3.10"
+            task:
+              name: Docs
+              run: cd docs && make html
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Python environment
+        uses: ./.github/actions/setup-venv
+        with:
+          python-version: ${{ matrix.python }}
+          cache-prefix: ${{ env.CACHE_PREFIX }}
+
+      - name: Restore mypy cache
+        if: matrix.task.name == 'Type check'
+        uses: actions/cache@v3
+        with:
+          path: .mypy_cache
+          key: mypy-${{ env.CACHE_PREFIX }}-${{ runner.os }}-${{ matrix.python }}-${{ hashFiles('*requirements.txt') }}-${{ github.ref }}-${{ github.sha }}
+          restore-keys: |
+            mypy-${{ env.CACHE_PREFIX }}-${{ runner.os }}-${{ matrix.python }}-${{ hashFiles('*requirements.txt') }}-${{ github.ref }}
+            mypy-${{ env.CACHE_PREFIX }}-${{ runner.os }}-${{ matrix.python }}-${{ hashFiles('*requirements.txt') }}
+
+      - name: ${{ matrix.task.name }}
+        run: |
+          . .venv/bin/activate
+          ${{ matrix.task.run }}
+
+      - name: Upload package distribution files
+        if: matrix.task.name == 'Build'
+        uses: actions/upload-artifact@v3
+        with:
+          name: package
+          path: dist
+
+      - name: Clean up
+        if: always()
+        run: |
+          . .venv/bin/activate
+          pip uninstall -y my-package
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: [checks]
+    if: startsWith(github.ref, 'refs/tags/')
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install requirements
+        run: |
+          pip install --upgrade pip setuptools wheel build
+          pip install -e .[dev]
+
+      - name: Prepare environment
+        run: |
+          echo "RELEASE_VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_ENV
+          echo "TAG=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
+
+      - name: Download package distribution files
+        uses: actions/download-artifact@v3
+        with:
+          name: package
+          path: dist
+
+      - name: Generate release notes
+        run: |
+          python scripts/release_notes.py > ${{ github.workspace }}-RELEASE_NOTES.md
+
+      - name: Publish package to PyPI
+        run: |
+          twine upload -u '${{ secrets.PYPI_USERNAME }}' -p '${{ secrets.PYPI_PASSWORD }}' dist/*
+
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          body_path: ${{ github.workspace }}-RELEASE_NOTES.md
+          prerelease: ${{ contains(env.TAG, 'rc') }}
+          files: |
+            dist/*

.github/workflows/pr_checks.yml

@@ -0,0 +1,29 @@
+name: PR Checks
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'my_package/**'
+
+jobs:
+  changelog:
+    name: CHANGELOG
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+
+    - name: Check that CHANGELOG has been updated
+      run: |
+        # If this step fails, this means you haven't updated the CHANGELOG.md
+        # file with notes on your contribution.
+        git diff --name-only $(git merge-base origin/main HEAD) | grep '^CHANGELOG.md$' && echo "Thanks for helping keep our CHANGELOG up-to-date!"

.github/workflows/setup.yml

@@ -0,0 +1,53 @@
+name: Setup
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  test_personalize:
+    name: Personalize
+    runs-on: [ubuntu-latest]
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.8"
+          cache: "pip"
+          cache-dependency-path: "setup-requirements.txt"
+
+      - name: Install prerequisites
+        run: |
+          pip install -r setup-requirements.txt
+
+      - name: Run personalize script
+        run: |
+          python scripts/personalize.py --github-org epwalsh --github-repo new-repo --package-name new-package --yes
+
+      - name: Verify changes
+        shell: bash
+        run: |
+          set -eo pipefail
+          # Check that 'new-package' replaced 'my-package' in some files.
+          grep -q 'new-package' pyproject.toml .github/workflows/main.yml .github/CONTRIBUTING.md
+          # Check that the new repo URL replaced the old one in some files.
+          grep -q 'https://github.com/epwalsh/new-repo' pyproject.toml .github/CONTRIBUTING.md
+          # Double check that there are no lingering mentions of old names.
+          for pattern in 'my[-_]package' 'https://github.com/allenai/python-package-template'; do
+            if find . -type f -not -path './.git/*' | xargs grep "$pattern"; then
+              echo "Found ${pattern} where it shouldn't be!"
+              exit 1
+            fi
+          done
+          echo "All good!"

.gitignore

@@ -0,0 +1,51 @@
+# build artifacts
+
+.eggs/
+.mypy_cache
+*.egg-info/
+build/
+dist/
+pip-wheel-metadata/
+
+
+# dev tools
+
+.envrc
+.python-version
+.idea
+.venv/
+.vscode/
+/*.iml
+pyrightconfig.json
+
+
+# jupyter notebooks
+
+.ipynb_checkpoints
+
+
+# miscellaneous
+
+.cache/
+doc/_build/
+*.swp
+.DS_Store
+
+
+# python
+
+*.pyc
+*.pyo
+__pycache__
+
+
+# testing and continuous integration
+
+.coverage
+.pytest_cache/
+.benchmarks
+
+# documentation build artifacts
+
+docs/build
+site/

.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+sphinx:
+  configuration: docs/source/conf.py
+  fail_on_warning: true
+
+python:
+  version: "3.8"
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev
+

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

Makefile

@@ -0,0 +1,17 @@
+.PHONY : docs
+docs :
+	rm -rf docs/build/
+	sphinx-autobuild -b html --watch my_package/ docs/source/ docs/build/
+
+.PHONY : run-checks
+run-checks :
+	isort --check .
+	black --check .
+	ruff check .
+	mypy .
+	CUDA_VISIBLE_DEVICES='' pytest -v --color=yes --doctest-modules tests/ my_package/
+
+.PHONY : build
+build :
+	rm -rf *.egg-info/
+	python -m build

README.md

@@ -0,0 +1,112 @@
+# python-package-template
+
+This is a template repository for Python package projects.
+
+## In this README :point_down:
+
+- [Features](#features)
+- [Usage](#usage)
+  - [Initial setup](#initial-setup)
+  - [Creating releases](#creating-releases)
+- [Projects using this template](#projects-using-this-template)
+- [FAQ](#faq)
+- [Contributing](#contributing)
+
+## Features
+
+This template repository comes with all of the boilerplate needed for:
+
+⚙️ Robust (and free) CI with [GitHub Actions](https://github.com/features/actions):
+  - Unit tests ran with [PyTest](https://docs.pytest.org) against multiple Python versions and operating systems.
+  - Type checking with [mypy](https://github.com/python/mypy).
+  - Linting with [ruff](https://astral.sh/ruff).
+  - Formatting with [isort](https://pycqa.github.io/isort/) and [black](https://black.readthedocs.io/en/stable/).
+
+🤖 [Dependabot](https://github.blog/2020-06-01-keep-all-your-packages-up-to-date-with-dependabot/) configuration to keep your dependencies up-to-date.
+
+📄 Great looking API documentation built using [Sphinx](https://www.sphinx-doc.org/en/master/) (run `make docs` to preview).
+
+🚀 Automatic GitHub and PyPI releases. Just follow the steps in [`RELEASE_PROCESS.md`](./RELEASE_PROCESS.md) to trigger a new release.
+
+## Usage
+
+### Initial setup
+
+1. [Create a new repository](https://github.com/allenai/python-package-template/generate) from this template with the desired name of your project.
+
+    *Your project name (i.e. the name of the repository) and the name of the corresponding Python package don't necessarily need to match, but you might want to check on [PyPI](https://pypi.org/) first to see if the package name you want is already taken.*
+
+2. Create a Python 3.8 or newer virtual environment.
+
+    *If you're not sure how to create a suitable Python environment, the easiest way is using [Miniconda](https://docs.conda.io/en/latest/miniconda.html). On a Mac, for example, you can install Miniconda using [Homebrew](https://brew.sh/):*
+
+    ```
+    brew install miniconda
+    ```
+
+    *Then you can create and activate a new Python environment by running:*
+
+    ```
+    conda create -n my-package python=3.9
+    conda activate my-package
+    ```
+
+3. Now that you have a suitable Python environment, you're ready to personalize this repository. Just run:
+
+    ```
+    pip install -r setup-requirements.txt
+    python scripts/personalize.py
+    ```
+
+    And then follow the prompts.
+
+    :pencil: *NOTE: This script will overwrite the README in your repository.*
+
+4. Commit and push your changes, then make sure all GitHub Actions jobs pass.
+
+5. (Optional) If you plan on publishing your package to PyPI, add repository secrets for `PYPI_USERNAME` and `PYPI_PASSWORD`. To add these, go to "Settings" > "Secrets" > "Actions", and then click "New repository secret".
+
+    *If you don't have PyPI account yet, you can [create one for free](https://pypi.org/account/register/).*
+
+6. (Optional) If you want to deploy your API docs to [readthedocs.org](https://readthedocs.org), go to the [readthedocs dashboard](https://readthedocs.org/dashboard/import/?) and import your new project.
+
+    Then click on the "Admin" button, navigate to "Automation Rules" in the sidebar, click "Add Rule", and then enter the following fields:
+
+    - **Description:** Publish new versions from tags
+    - **Match:** Custom Match
+    - **Custom match:** v[vV]
+    - **Version:** Tag
+    - **Action:** Activate version
+
+    Then hit "Save".
+
+    *After your first release, the docs will automatically be published to [your-project-name.readthedocs.io](https://your-project-name.readthedocs.io/).*
+
+### Creating releases
+
+Creating new GitHub and PyPI releases is easy. The GitHub Actions workflow that comes with this repository will handle all of that for you.
+All you need to do is follow the instructions in [RELEASE_PROCESS.md](./RELEASE_PROCESS.md).
+
+## Projects using this template
+
+Here is an incomplete list of some projects that started off with this template:
+
+- [ai2-tango](https://github.com/allenai/tango)
+- [cached-path](https://github.com/allenai/cached_path)
+- [beaker-py](https://github.com/allenai/beaker-py)
+- [gantry](https://github.com/allenai/beaker-gantry)
+- [ip-bot](https://github.com/abe-101/ip-bot)
+- [atty](https://github.com/mstuttgart/atty)
+
+☝️ *Want your work featured here? Just open a pull request that adds the link.*
+
+## FAQ
+
+#### Should I use this template even if I don't want to publish my package?
+
+Absolutely! If you don't want to publish your package, just delete the `docs/` directory and the `release` job in [`.github/workflows/main.yml`](https://github.com/allenai/python-package-template/blob/main/.github/workflows/main.yml).
+
+## Contributing
+
+If you find a bug :bug:, please open a [bug report](https://github.com/allenai/python-package-template/issues/new?assignees=&labels=bug&template=bug_report.md&title=).
+If you have an idea for an improvement or new feature :rocket:, please open a [feature request](https://github.com/allenai/python-package-template/issues/new?assignees=&labels=Feature+request&template=feature_request.md&title=).

RELEASE_PROCESS.md

@@ -0,0 +1,24 @@
+# GitHub Release Process
+
+## Steps
+
+1. Update the version in `my_package/version.py`.
+
+3. Run the release script:
+
+    ```bash
+    ./scripts/release.sh
+    ```
+
+    This will commit the changes to the CHANGELOG and `version.py` files and then create a new tag in git
+    which will trigger a workflow on GitHub Actions that handles the rest.
+
+## Fixing a failed release
+
+If for some reason the GitHub Actions release workflow failed with an error that needs to be fixed, you'll have to delete both the tag and corresponding release from GitHub. After you've pushed a fix, delete the tag from your local clone with
+
+```bash
+git tag -l | xargs git tag -d && git fetch -t
+```
+
+Then repeat the steps above.

docs/.gitignore

@@ -0,0 +1 @@
+build

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -W
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/CHANGELOG.md

@@ -0,0 +1 @@
+../../CHANGELOG.md

docs/source/CONTRIBUTING.md

@@ -0,0 +1 @@
+../../.github/CONTRIBUTING.md

docs/source/conf.py

@@ -0,0 +1,121 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import logging
+import os
+import sys
+from datetime import datetime
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+
+sys.path.insert(0, os.path.abspath("../../"))
+
+from my_package import VERSION, VERSION_SHORT  # noqa: E402
+
+# -- Project information -----------------------------------------------------
+
+project = "my-package"
+copyright = f"{datetime.today().year}, Allen Institute for Artificial Intelligence"
+author = "Allen Institute for Artificial Intelligence"
+version = VERSION_SHORT
+release = VERSION
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "myst_parser",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.doctest",
+    "sphinx_copybutton",
+    "sphinx_autodoc_typehints",
+]
+
+# Tell myst-parser to assign header anchors for h1-h3.
+myst_heading_anchors = 3
+
+suppress_warnings = ["myst.header"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build"]
+
+source_suffix = [".rst", ".md"]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    # Uncomment these if you use them in your codebase:
+    #  "torch": ("https://pytorch.org/docs/stable", None),
+    #  "datasets": ("https://huggingface.co/docs/datasets/master/en", None),
+    #  "transformers": ("https://huggingface.co/docs/transformers/master/en", None),
+}
+
+# By default, sort documented members by type within classes and modules.
+autodoc_member_order = "groupwise"
+
+# Include default values when documenting parameter types.
+typehints_defaults = "comma"
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+
+html_title = f"my-package v{VERSION}"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+html_css_files = ["css/custom.css"]
+
+html_favicon = "_static/favicon.ico"
+
+html_theme_options = {
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/allenai/python-package-template",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,  # noqa: E501
+            "class": "",
+        },
+    ],
+}
+
+# -- Hack to get rid of stupid warnings from sphinx_autodoc_typehints --------
+
+
+class ShutupSphinxAutodocTypehintsFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        if "Cannot resolve forward reference" in record.msg:
+            return False
+        return True
+
+
+logging.getLogger("sphinx.sphinx_autodoc_typehints").addFilter(ShutupSphinxAutodocTypehintsFilter())

docs/source/index.md

@@ -0,0 +1,27 @@
+# **my-package**
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Getting started
+
+installation
+overview
+```
+
+```{toctree}
+:hidden:
+:caption: Development
+
+CHANGELOG
+CONTRIBUTING
+License <https://raw.githubusercontent.com/allenai/python-package-template/main/LICENSE>
+GitHub Repository <https://github.com/allenai/python-package-template>
+```
+
+## Indices and tables
+
+```{eval-rst}
+* :ref:`genindex`
+* :ref:`modindex`
+```

docs/source/installation.md

@@ -0,0 +1,27 @@
+Installation
+============
+
+**my-package** supports Python >= 3.8.
+
+## Installing with `pip`
+
+**my-package** is available [on PyPI](https://pypi.org/project/my-package/). Just run
+
+```bash
+pip install my-package
+```
+
+## Installing from source
+
+To install **my-package** from source, first clone [the repository](https://github.com/allenai/python-package-template):
+
+```bash
+git clone https://github.com/allenai/python-package-template.git
+cd python-package-template
+```
+
+Then run
+
+```bash
+pip install -e .
+```

docs/source/overview.md

@@ -0,0 +1,3 @@
+Overview
+========
+

my_package/__init__.py

@@ -0,0 +1 @@
+from .version import VERSION, VERSION_SHORT

my_package/version.py

@@ -0,0 +1,11 @@
+_MAJOR = "0"
+_MINOR = "1"
+# On main and in a nightly release the patch should be one ahead of the last
+# released build.
+_PATCH = "0"
+# This is mainly for nightly builds which have the suffix ".dev$DATE". See
+# https://semver.org/#is-v123-a-semantic-version for the semantics.
+_SUFFIX = ""
+
+VERSION_SHORT = "{0}.{1}".format(_MAJOR, _MINOR)
+VERSION = "{0}.{1}.{2}{3}".format(_MAJOR, _MINOR, _PATCH, _SUFFIX)

pyproject.toml

@@ -0,0 +1,120 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# See https://setuptools.pypa.io/en/latest/userguide/quickstart.html for more project configuration options.
+name = "my-package"
+dynamic = ["version"]
+readme = "README.md"
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+authors = [
+    {name = "Allen Institute for Artificial Intelligence", email = "contact@allenai.org"}
+]
+requires-python = ">=3.8"
+dependencies = [
+  # Add your own dependencies here
+]
+license = {file = "LICENSE"}
+
+[project.urls]
+Homepage = "https://github.com/allenai/python-package-template"
+Repository = "https://github.com/allenai/python-package-template"
+Changelog = "https://github.com/allenai/python-package-template/blob/main/CHANGELOG.md"
+# Documentation = "https://my-package.readthedocs.io/"
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "mypy>=1.0,<1.5",
+    "black>=23.0,<24.0",
+    "isort>=5.12,<5.13",
+    "pytest",
+    "pytest-sphinx",
+    "pytest-cov",
+    "twine>=1.11.0",
+    "build",
+    "setuptools",
+    "wheel",
+    "Sphinx>=4.3.0,<7.1.0",
+    "furo==2023.7.26",
+    "myst-parser>=1.0,<2.1",
+    "sphinx-copybutton==0.5.2",
+    "sphinx-autobuild==2021.3.14",
+    "sphinx-autodoc-typehints==1.23.3",
+    "packaging"
+]
+
+[tool.setuptools.packages.find]
+exclude = [
+    "*.tests",
+    "*.tests.*",
+    "tests.*",
+    "tests",
+    "docs*",
+    "scripts*"
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+my_package = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = {attr = "my_package.version.VERSION"}
+
+[tool.black]
+line-length = 100
+include = '\.pyi?$'
+exclude = '''
+(
+      __pycache__
+    | \.git
+    | \.mypy_cache
+    | \.pytest_cache
+    | \.vscode
+    | \.venv
+    | \bdist\b
+    | \bdoc\b
+)
+'''
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+
+# You can override these pyright settings by adding a personal pyrightconfig.json file.
+[tool.pyright]
+reportPrivateImportUsage = false
+
+[tool.ruff]
+line-length = 115
+target-version = "py39"
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[tool.mypy]
+ignore_missing_imports = true
+no_site_packages = true
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+strict_optional = false
+
+[tool.pytest.ini_options]
+testpaths = "tests/"
+python_classes = [
+  "Test*",
+  "*Test"
+]
+log_format = "%(asctime)s - %(levelname)s - %(name)s - %(message)s"
+log_level = "DEBUG"

scripts/personalize.py

@@ -0,0 +1,179 @@
+"""
+Run this script once after first creating your project from this template repo to personalize
+it for own project.
+
+This script is interactive and will prompt you for various inputs.
+"""
+
+import sys
+from pathlib import Path
+from typing import Generator, List, Tuple
+
+import click
+from click_help_colors import HelpColorsCommand
+from rich import print
+from rich.markdown import Markdown
+from rich.prompt import Confirm
+from rich.syntax import Syntax
+from rich.traceback import install
+
+install(show_locals=True, suppress=[click])
+
+REPO_BASE = (Path(__file__).parent / "..").resolve()
+
+FILES_TO_REMOVE = {
+    REPO_BASE / ".github" / "workflows" / "setup.yml",
+    REPO_BASE / "setup-requirements.txt",
+    REPO_BASE / "scripts" / "personalize.py",
+}
+
+PATHS_TO_IGNORE = {
+    REPO_BASE / "README.md",
+    REPO_BASE / ".git",
+    REPO_BASE / "docs" / "source" / "_static" / "favicon.ico",
+}
+
+GITIGNORE_LIST = [
+    line.strip()
+    for line in (REPO_BASE / ".gitignore").open(encoding="utf-8").readlines()
+    if line.strip() and not line.startswith("#")
+]
+
+REPO_NAME_TO_REPLACE = "python-package-template"
+BASE_URL_TO_REPLACE = "https://github.com/allenai/python-package-template"
+
+
+@click.command(
+    cls=HelpColorsCommand,
+    help_options_color="green",
+    help_headers_color="yellow",
+    context_settings={"max_content_width": 115},
+)
+@click.option(
+    "--github-org",
+    prompt="GitHub organization or user (e.g. 'allenai')",
+    help="The name of your GitHub organization or user.",
+)
+@click.option(
+    "--github-repo",
+    prompt="GitHub repository (e.g. 'python-package-template')",
+    help="The name of your GitHub repository.",
+)
+@click.option(
+    "--package-name",
+    prompt="Python package name (e.g. 'my-package')",
+    help="The name of your Python package.",
+)
+@click.option(
+    "-y",
+    "--yes",
+    is_flag=True,
+    help="Run the script without prompting for a confirmation.",
+    default=False,
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    hidden=True,
+    default=False,
+)
+def main(
+    github_org: str, github_repo: str, package_name: str, yes: bool = False, dry_run: bool = False
+):
+    repo_url = f"https://github.com/{github_org}/{github_repo}"
+    package_actual_name = package_name.replace("_", "-")
+    package_dir_name = package_name.replace("-", "_")
+
+    # Confirm before continuing.
+    print(f"Repository URL set to: [link={repo_url}]{repo_url}[/]")
+    print(f"Package name set to: [cyan]{package_actual_name}[/]")
+    if not yes:
+        yes = Confirm.ask("Is this correct?")
+    if not yes:
+        raise click.ClickException("Aborted, please run script again")
+
+    # Personalize files.
+    replacements = [
+        (BASE_URL_TO_REPLACE, repo_url),
+        (REPO_NAME_TO_REPLACE, github_repo),
+        ("my-package", package_actual_name),
+        ("my_package", package_dir_name),
+    ]
+    if dry_run:
+        for old, new in replacements:
+            print(f"Replacing '{old}' with '{new}'")
+    for path in iterfiles(REPO_BASE):
+        if path.resolve() not in FILES_TO_REMOVE:
+            personalize_file(path, dry_run, replacements)
+
+    # Rename 'my_package' directory to `package_dir_name`.
+    if not dry_run:
+        (REPO_BASE / "my_package").replace(REPO_BASE / package_dir_name)
+    else:
+        print(f"Renaming 'my_package' directory to '{package_dir_name}'")
+
+    # Start with a fresh README.
+    readme_contents = f"""# {package_actual_name}\n"""
+    if not dry_run:
+        with open(REPO_BASE / "README.md", mode="w+t", encoding="utf-8") as readme_file:
+            readme_file.write(readme_contents)
+    else:
+        print("Replacing README.md contents with:\n", Markdown(readme_contents))
+
+    install_example = Syntax("pip install -e '.[dev]'", "bash")
+    print(
+        "[green]\N{check mark} Success![/] You can now install your package locally in development mode with:\n",
+        install_example,
+    )
+
+    # Lastly, remove that we don't need.
+    for path in FILES_TO_REMOVE:
+        assert path.is_file(), path
+        if not dry_run:
+            if path.name == "personalize.py" and sys.platform.startswith("win"):
+                # We can't unlink/remove an open file on Windows.
+                print("You can remove the 'scripts/personalize.py' file now")
+            else:
+                path.unlink()
+
+
+def iterfiles(dir: Path) -> Generator[Path, None, None]:
+    assert dir.is_dir()
+    for path in dir.iterdir():
+        if path in PATHS_TO_IGNORE:
+            continue
+
+        is_ignored_file = False
+        for gitignore_entry in GITIGNORE_LIST:
+            if path.relative_to(REPO_BASE).match(gitignore_entry):
+                is_ignored_file = True
+                break
+        if is_ignored_file:
+            continue
+
+        if path.is_dir():
+            yield from iterfiles(path)
+        else:
+            yield path
+
+
+def personalize_file(path: Path, dry_run: bool, replacements: List[Tuple[str, str]]):
+    with path.open(mode="r+t", encoding="utf-8") as file:
+        filedata = file.read()
+
+    should_update: bool = False
+    for old, new in replacements:
+        if filedata.count(old):
+            should_update = True
+            filedata = filedata.replace(old, new)
+
+    if should_update:
+        if not dry_run:
+            with path.open(mode="w+t", encoding="utf-8") as file:
+                file.write(filedata)
+        else:
+            print(f"Updating {path}")
+
+
+if __name__ == "__main__":
+    main()

scripts/prepare_changelog.py

@@ -0,0 +1,39 @@
+from datetime import datetime
+from pathlib import Path
+
+from my_package.version import VERSION
+
+
+def main():
+    changelog = Path("CHANGELOG.md")
+
+    with changelog.open() as f:
+        lines = f.readlines()
+
+    insert_index: int = -1
+    for i in range(len(lines)):
+        line = lines[i]
+        if line.startswith("## Unreleased"):
+            insert_index = i + 1
+        elif line.startswith(f"## [v{VERSION}]"):
+            print("CHANGELOG already up-to-date")
+            return
+        elif line.startswith("## [v"):
+            break
+
+    if insert_index < 0:
+        raise RuntimeError("Couldn't find 'Unreleased' section")
+
+    lines.insert(insert_index, "\n")
+    lines.insert(
+        insert_index + 1,
+        f"## [v{VERSION}](https://github.com/allenai/python-package-template/releases/tag/v{VERSION}) - "
+        f"{datetime.now().strftime('%Y-%m-%d')}\n",
+    )
+
+    with changelog.open("w") as f:
+        f.writelines(lines)
+
+
+if __name__ == "__main__":
+    main()

scripts/release.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+set -e
+
+TAG=$(python -c 'from my_package.version import VERSION; print("v" + VERSION)')
+
+read -p "Creating new release for $TAG. Do you want to continue? [Y/n] " prompt
+
+if [[ $prompt == "y" || $prompt == "Y" || $prompt == "yes" || $prompt == "Yes" ]]; then
+    python scripts/prepare_changelog.py
+    git add -A
+    git commit -m "Bump version to $TAG for release" || true && git push
+    echo "Creating new git tag $TAG"
+    git tag "$TAG" -m "$TAG"
+    git push --tags
+else
+    echo "Cancelled"
+    exit 1
+fi

scripts/release_notes.py

@@ -0,0 +1,81 @@
+# encoding: utf-8
+
+"""
+Prepares markdown release notes for GitHub releases.
+"""
+
+import os
+from typing import List, Optional
+
+import packaging.version
+
+TAG = os.environ["TAG"]
+
+ADDED_HEADER = "### Added 🎉"
+CHANGED_HEADER = "### Changed ⚠️"
+FIXED_HEADER = "### Fixed ✅"
+REMOVED_HEADER = "### Removed 👋"
+
+
+def get_change_log_notes() -> str:
+    in_current_section = False
+    current_section_notes: List[str] = []
+    with open("CHANGELOG.md") as changelog:
+        for line in changelog:
+            if line.startswith("## "):
+                if line.startswith("## Unreleased"):
+                    continue
+                if line.startswith(f"## [{TAG}]"):
+                    in_current_section = True
+                    continue
+                break
+            if in_current_section:
+                if line.startswith("### Added"):
+                    line = ADDED_HEADER + "\n"
+                elif line.startswith("### Changed"):
+                    line = CHANGED_HEADER + "\n"
+                elif line.startswith("### Fixed"):
+                    line = FIXED_HEADER + "\n"
+                elif line.startswith("### Removed"):
+                    line = REMOVED_HEADER + "\n"
+                current_section_notes.append(line)
+    assert current_section_notes
+    return "## What's new\n\n" + "".join(current_section_notes).strip() + "\n"
+
+
+def get_commit_history() -> str:
+    new_version = packaging.version.parse(TAG)
+
+    # Pull all tags.
+    os.popen("git fetch --tags")
+
+    # Get all tags sorted by version, latest first.
+    all_tags = os.popen("git tag -l --sort=-version:refname 'v*'").read().split("\n")
+
+    # Out of `all_tags`, find the latest previous version so that we can collect all
+    # commits between that version and the new version we're about to publish.
+    # Note that we ignore pre-releases unless the new version is also a pre-release.
+    last_tag: Optional[str] = None
+    for tag in all_tags:
+        if not tag.strip():  # could be blank line
+            continue
+        version = packaging.version.parse(tag)
+        if new_version.pre is None and version.pre is not None:
+            continue
+        if version < new_version:
+            last_tag = tag
+            break
+    if last_tag is not None:
+        commits = os.popen(f"git log {last_tag}..{TAG} --oneline --first-parent").read()
+    else:
+        commits = os.popen("git log --oneline --first-parent").read()
+    return "## Commits\n\n" + commits
+
+
+def main():
+    print(get_change_log_notes())
+    print(get_commit_history())
+
+
+if __name__ == "__main__":
+    main()

setup-requirements.txt

@@ -0,0 +1,3 @@
+click>=7.0,<9.0
+click-help-colors>=0.9.1,<0.10
+rich>=11.0,<14.0

tests/hello_test.py

@@ -0,0 +1,2 @@
+def test_hello():
+    print("Hello, World!")