Release 20.6

NEWS.rst

@@ -1,6 +1,39 @@
 NEWS
 ====
 
+20.6.0 - 2020-06-07
+-------------------
+ * This is the last release of Klein expected to support Python 2.
+ * This is the last release of Klein expected to support Python 3.5.
+ * Python 3.4 is no longer supported by Klein. [`#284 <https://github.com/twisted/klein/pull/284>`_]
+ * Python 3.8 is now supported by Klein. [`#303 <https://github.com/twisted/klein/pull/303>`_]
+ * ``klein.app.subroute`` is now also available as ``klein.subroute``. [`#293 <https://github.com/twisted/klein/pull/293>`_]
+ * Support for forms and sessions. [`#276 <https://github.com/twisted/klein/pull/276>`_]
+ * The ``Klein`` class now supports deep copy by implementing ``__copy__``. [`#74 <https://github.com/twisted/klein/pull/74>`_]
+
+19.6.0 - 2019-06-07
+-------------------
+
+New "forms" and "sessions" subsystems provide official support for POST requests, including CSRF protection, form generation to include CSRF tokens, dependency injection to populate parameters from both the request and session, as well as lightweight JSON API support.
+
+17.10.0 - 2017-10-22
+--------------------
+
+17.2.0 - 2017-03-03
+-------------------
+
+16.12.0 - 2016-12-13
+--------------------
+
+15.3.1 - 2015-12-17
+-------------------
+
+15.2.0 - 2015-11-30
+-------------------
+
+15.1.0 - 2015-07-08
+-------------------
+
 15.0.0 - 2015-01-11
 -------------------
  * [BUG] Klein now includes its test package as part of the distribution. [`#65 <https://github.com/twisted/klein/pull/65>`_]

docs/release.rst

@@ -8,18 +8,15 @@ Each version is numbered with the major portion being the last two digits of the
 That is, the first release of 2016 would be 16.0, and the second would be 16.1.
 
 
-Doing a Release
+Releasing Klein
 ---------------
 
-#. Create a branch called "release-<version>"
-#. Run :code:`python incremental.update Klein --rc && python incremental.update Klein`
-#. Commit, and push the branch
-#. Open a PR from the branch (follow the usual process for merging a PR).
-#. Pull latest :code:`master`: :code:`git checkout master && git pull --rebase`
-#. Clear the directory of any other changes using ``git clean -f -x -d  .``
-#. Tag the release using ``git tag -s <release> -m "Tag <release> release"``
-#. Push up the tag using ``git push --tags``.
-#. Make a pull request for this changes.
-   Continue when it is merged.
-#. Generate the tarball and wheel using ``python setup.py sdist bdist_wheel``.
-#. Upload the tarball and wheel using ``twine upload dist/klein-*``.
+#. Start with a clean (no changes) source tree on the master branch.
+#. Create a new release candidate: :code:`tox -e release -- start`
+#. Commit and push the branch
+#. Open a PR from the branch (follow the usual process for opening a PR).
+#. As appropriate, pull the latest code from :code:`master`: :code:`git checkout master && git pull --rebase` (or use the GitHub UI)
+#. To publish a release candidate to PyPI: :code:`tox -e release -- publish`
+#. Obtain an approving review for the PR using the usual process.
+#. To publish a production release: :code:`tox -e release -- publish --final`
+#. Merge the PR to the master branch.

release.py

@@ -0,0 +1,317 @@
+# Copyright (c) Twisted Matrix Laboratories.
+# See LICENSE for details.
+
+from enum import Enum
+from os import chdir
+from pathlib import Path
+from shutil import rmtree
+from subprocess import CalledProcessError, run
+from sys import exit, stderr
+from tempfile import mkdtemp
+from typing import Any, Dict, NoReturn, Optional, Sequence
+
+from click import group as commandGroup, option as commandOption
+
+from git import Repo as Repository, TagReference
+from git.refs.head import Head
+
+from incremental import Version
+
+
+class PyPI(Enum):
+    Test = "testpypi"
+    Production = "pypi"
+
+
+def warning(message: str) -> None:
+    """
+    Print a warning.
+    """
+    print(f"WARNING: {message}", file=stderr)
+
+
+def error(message: str, exitStatus: int) -> NoReturn:
+    """
+    Print an error message and exit with the given status.
+    """
+    print(f"ERROR: {message}", file=stderr)
+    exit(exitStatus)
+
+
+def spawn(args: Sequence[str]) -> None:
+    """
+    Spawn a new process with the given arguments, raising L{SystemExit} with
+    captured output if the exit status is non-zero.
+    """
+    print("Executing command:", " ".join(repr(arg) for arg in args))
+    try:
+        run(args, input=b"", capture_output=True, check=True)
+    except CalledProcessError as e:
+        error(f"command {e.cmd} failed: {e.stderr}", 1)
+
+
+def currentVersion() -> Version:
+    """
+    Determine the current version.
+    """
+    # Incremental doesn't have an API to do this, so we are duplicating some
+    # code from its source tree. Boo.
+    versionInfo: Dict[str, Any] = {}
+    versonFile = Path(__file__).parent / "src" / "klein" / "_version.py"
+    exec (versonFile.read_text(), versionInfo)  # noqa: E211  # black py2.7
+    return versionInfo["__version__"]
+
+
+def fadeToBlack() -> None:
+    """
+    Run black to reformat the source code.
+    """
+    spawn(["tox", "-e", "black-reformat"])
+
+
+def incrementVersion(candidate: bool) -> None:
+    """
+    Increment the current release version.
+    If C{candidate} is C{True}, the new version will be a release candidate;
+    otherwise it will be a regular release.
+    """
+    # Incremental doesn't have an API to do this, so we have to run a
+    # subprocess. Boo.
+    args = ["python", "-m", "incremental.update", "klein"]
+    if candidate:
+        args.append("--rc")
+    spawn(args)
+
+    # Incremental generates code that black wants to reformat.
+    fadeToBlack()
+
+
+def releaseBranchName(version: Version) -> str:
+    """
+    Compute the name of the release branch for the given version.
+    """
+    return f"release-{version.major}.{version.minor}"
+
+
+def releaseBranch(repository: Repository, version: Version) -> Optional[Head]:
+    """
+    Return the release branch corresponding to the given version.
+    """
+    branchName = releaseBranchName(version)
+
+    if branchName in repository.heads:
+        return repository.heads[branchName]
+
+    return None
+
+
+def releaseTagName(version: Version) -> str:
+    """
+    Compute the name of the release tag for the given version.
+    """
+    return version.public()
+
+
+def createReleaseBranch(repository: Repository, version: Version) -> Head:
+    """
+    Create a new release branch.
+    """
+    branchName = releaseBranchName(version)
+
+    if branchName in repository.heads:
+        error(f'Release branch "{branchName}" already exists.', 1)
+
+    print(f'Creating release branch: "{branchName}"')
+    return repository.create_head(branchName)
+
+
+def clone(repository: Repository, tag: TagReference) -> Path:
+    """
+    Clone a tagged version from the given repository's origin.
+    Return the path to the new clone.
+    """
+    path = Path(mkdtemp())
+
+    print(f"Cloning repository with tag {tag} at {path}...")
+    Repository.clone_from(
+        url=next(repository.remotes.origin.urls),
+        to_path=str(path),
+        branch=tag.name,
+        multi_options=["--depth=1"],
+    )
+
+    return path
+
+
+def distribute(
+    repository: Repository, tag: TagReference, test: bool = False
+) -> None:
+    """
+    Build a distribution for the project at the given path and upload to PyPI.
+    """
+    src = clone(repository, tag)
+
+    if test:
+        pypi = PyPI.Test
+    else:
+        pypi = PyPI.Production
+
+    wd = Path.cwd()
+    try:
+        chdir(src)
+
+        print("Building distribution at:", src)
+        spawn(["python", "setup.py", "sdist", "bdist_wheel"])
+
+        print(f"Uploading distribution to {pypi.value}...")
+        twineCommand = ["twine", "upload"]
+        twineCommand.append(f"--repository={pypi.value}")
+        twineCommand += [str(p) for p in Path("dist").iterdir()]
+        spawn(twineCommand)
+
+    finally:
+        chdir(wd)
+
+    rmtree(str(src))
+
+
+def startRelease() -> None:
+    """
+    Start a new release:
+     * Increment the current version to a new release candidate version.
+     * Create a corresponding branch.
+     * Switch to the new branch.
+    """
+    repository = Repository()
+
+    if repository.head.ref != repository.heads.master:
+        error(
+            f"working copy is from non-master branch: {repository.head.ref}", 1
+        )
+
+    if repository.is_dirty():
+        warning("working copy is dirty")
+
+    version = currentVersion()
+
+    if version.release_candidate is not None:
+        error(f"current version is already a release candidate: {version}", 1)
+
+    incrementVersion(candidate=True)
+    version = currentVersion()
+
+    print(f"New release candidate version: {version.public()}")
+
+    branch = createReleaseBranch(repository, version)
+    branch.checkout()
+
+    print("Next steps (to be done manually):")
+    print(" • Commit version changes to the new release branch:", branch)
+    print(" • Push the release branch to GitHub")
+    print(" • Open a pull request on GitHub from the release branch")
+
+
+def bumpRelease() -> None:
+    """
+    Increment the release candidate version.
+    """
+    repository = Repository()
+
+    if repository.is_dirty():
+        warning("working copy is dirty")
+
+    version = currentVersion()
+
+    if version.release_candidate is None:
+        error(f"current version is not a release candidate: {version}", 1)
+
+    branch = releaseBranch(repository, version)
+
+    if repository.head.ref != branch:
+        error(
+            f'working copy is on branch "{repository.head.ref}", '
+            f'not release branch "{branch}"',
+            1,
+        )
+
+    incrementVersion(candidate=True)
+    version = currentVersion()
+
+    print("New release candidate version:", version.public())
+
+
+def publishRelease(final: bool, test: bool = False) -> None:
+    """
+    Publish the current version.
+    """
+    repository = Repository()
+
+    if repository.is_dirty():
+        error("working copy is dirty", 1)
+
+    version = currentVersion()
+
+    if version.release_candidate is None:
+        error(f"current version is not a release candidate: {version}", 1)
+
+    branch = releaseBranch(repository, version)
+
+    if repository.head.ref != branch:
+        error(
+            f'working copy is on branch "{repository.head.ref}", '
+            f'not release branch "{branch}"',
+            1,
+        )
+
+    incrementVersion(candidate=False)
+    version = currentVersion()
+
+    versonFile = Path(__file__).parent / "src" / "klein" / "_version.py"
+    repository.index.add(str(versonFile))
+    repository.index.commit(f"Update version to {version}")
+
+    tagName = releaseTagName(version)
+
+    if tagName in repository.tags:
+        tag = repository.tags[tagName]
+        message = f"Release tag already exists: {tagName}"
+        if tag.commit != repository.head.ref.commit:
+            error(message, 1)
+        else:
+            print(message)
+    else:
+        print("Creating release tag:", tagName)
+        tag = repository.create_tag(
+            tagName, ref=branch, message=f"Tag release {version.public()}"
+        )
+
+    print("Pushing tag to origin:", tag)
+    repository.remotes.origin.push(refspec=tag.path)
+
+    distribute(repository, tag, test=test)
+
+
+@commandGroup()
+def main() -> None:
+    pass
+
+
+@main.command()
+def start() -> None:
+    startRelease()
+
+
+@main.command()
+def bump() -> None:
+    bumpRelease()
+
+
+@main.command()
+@commandOption("--test/--production")
+@commandOption("--final/--candidate")
+def publish(final: bool, test: bool) -> None:
+    publishRelease(final=final, test=test)
+
+
+if __name__ == "__main__":
+    main()

setup.py

@@ -16,6 +16,7 @@
             'Programming Language :: Python :: 3.5',
             'Programming Language :: Python :: 3.6',
             'Programming Language :: Python :: 3.7',
+            'Programming Language :: Python :: 3.8',
             'Programming Language :: Python :: Implementation :: CPython',
             'Programming Language :: Python :: Implementation :: PyPy',
             'Topic :: Internet :: WWW/HTTP :: Dynamic Content',