Change log#

To be included in the next release#

v11.1.3.dev34+g75196e333 /UNRELEASED DRAFT/#

(2025-12-08)

Bug fixes#

  • Fixed prompting for the encrypted private key password interactively, when the password in not set in the private_key_password attribute in the pyOpenSSL TLS adapter. Also improved the private key password to accept the Callable type.

    – by @jatalahd

    Related issues and pull requests on GitHub: #798.

  • The cheroot.ssl.builtin SSL adapter now responds with a 400 Bad Request error to plaintext HTTP requests on HTTPS ports by detecting them before the SSL handshake, matching the behavior of cheroot.ssl.pyopenssl. Previously, such requests would fail during the SSL handshake without sending an HTTP response.

    – by @julianz-

    Related issues and pull requests on GitHub: #800.

  • Plaintext HTTP error responses on HTTPS ports now reliably send complete messages to clients using sendall() instead of buffered writes that may not flush before the connection closes.

    – by @julianz-

    Related issues and pull requests on GitHub: #800.

Deprecations (removal in next major release)#

  • Deprecated bind() method from the Adapter interface and respective implementations. Previously bind() was doing nothing in the builtin TLS adapter but was being used in the pyOpenSSLAdapter to wrap the socket. Socket wrapping is now done exclusively in the wrap() method subclass implementations. A side-effect of this change is that the ssl_adapter argument of prepare_socket() is also deprecated.

    – by @julianz-

    Related issues and pull requests on GitHub: #801.

Contributor-facing changes#

Released versions#

v11.1.2#

(2025-11-07)

Bug fixes#

  • The “service unavailable” thread is now turn down properly when the server is shut down – by @itamarst.

    This fixes a regression in Cheroot originally introduced in v11.0.0 that would manifest itself under Python 3.12 and older. In certain conditions like under CherryPy, it would also lead to hangs on tear-down.

    Related issues and pull requests on GitHub: #769, #794.

v11.1.1#

(2025-11-03)

Packaging updates and notes for downstreams#

  • The packaging configuration has been fixed to ensure that only cheroot package will be installed into site-packages/ – by @webknjaz.

    This fixes a regression introduced in version 11.1.0.

    Related issues and pull requests on GitHub: #790.

    Related commits on GitHub: @d286d1a.

v11.1.0#

(2025-11-03)

Features#

  • Added optional private key password argument to SSL adapters to support password-protected private keys – by @jatalahd.

    Related issues and pull requests on GitHub: #752.

Contributor-facing changes#

  • Added missing __all__ and IS_WINDOWS definitions to .pyi stub files for mypy.

    – by @julianz-

    Related issues and pull requests on GitHub: #774.

  • Made test_http_over_https_error compatible with Solaris – by @mtelka.

    Related issues and pull requests on GitHub: #776.

  • Increased timeout values test_client.server_instance.timeout and http_request_timeout to make related tests more stable.

    Related issues and pull requests on GitHub: #777.

v11.0.0#

(2025-09-21)

Features#

  • When load is too high, Cheroot now responds with a 503 Service Unavailable HTTP error. Previously it silently closed the connection.

    – by @itamarst

    Related issues and pull requests on GitHub: #745.

Removals and backward incompatible breaking changes#

  • Cheroot dropped support for Python 3.6 and 3.7. It now requires Python 3.8 or later.

    – by @jaraco

    Related issues and pull requests on GitHub: #565, #633.

    Related commits on GitHub: @437863e.

Packaging updates and notes for downstreams#

  • Declared Python 3.12 and Python 3.13 as supported officially – by @webknjaz.

    Related issues and pull requests on GitHub: #696.

    Related commits on GitHub: @5db4f63.

  • The minimum version of the setuptools-scm build dependency has been set to 7. The Git archives are now produced by it natively, instead of relying on a third party plugin which is no longer being used.

    – by @serhii73

    Related issues and pull requests on GitHub: #628.

  • The packaging metadata has been migrated to the pyproject.toml-based PEP 621 declaration – by @jaraco and @webknjaz.

    As a part of this update, the minimum version of the setuptools build backend was bumped to 61.2. Moreover, any compatibility shims that existed in setup.cfg and setup.py have been removed for good.

    Related issues and pull requests on GitHub: #690.

Contributor-facing changes#

  • The test infrastructure has been updated to stop using the pytest-forked plugin – by @jaraco and @webknjaz.

    This plugin was causing problems with upgrading to modern versions of Pytest and it is not going to be fixed anytime soon.

    It was used in a test that interacts with the system resource limits under *NIX environments in hopes to isolate the side effects caused by the preparatory code.

    It is possible that this will have an effect on the test sessions and we may have to look for alternative solutions for test process isolation.

    Related issues and pull requests on GitHub: #502, #511, #680, #681, #703.

  • The test infrastructure has been updated to start using the upstream reusable workflow reusable-tox.yml from https://github.com/tox-dev/workflow – by @webknjaz.

    This chance allows us to de-duplicate the commonly used CI shape.

    Related issues and pull requests on GitHub: #743.

v10.0.1#

(2024-04-22)

Bug fixes#

  • Fixed a flaw where internally unhandled exceptions could crash the worker threads and eventually starve the server of its processing resources. It is no longer and issue and the unhandled errors are now logged and suppressed except for a few expected exceptions that are used for normal interruption requests.

    – by @cameronbrunner and @webknjaz

    Related issues and pull requests on GitHub: #310, #346, #354, #358, #365, #375, #599, #641, #649.

  • Fixed compatibility with Python 3.8 in the built-in TLS adapter that relies on ssl.

    Modern Python versions communicate specialized exceptions ssl.SSLEOFError and ssl.SSLZeroReturnError where the older versions errored out in a very generic way.

    – by @toppk and @webknjaz

    Related issues and pull requests on GitHub: #517, #518.

Packaging updates and notes for downstreams#

  • Started signing the package distribution artifacts in CI/CD with Sigstore and uploading them to GitHub Releases – by @webknjaz.

    Related commits on GitHub: @27a3c94, @c45f184.

  • The change log management is now implemented through the Towncrier tool – by @webknjaz.

    The contributors are now expected to include change log fragment files in their pull requests.

    These news snippets can link one or more issues or pull requests, and be of one or more of the following categories:

    • bugfix: A bug fix for something we deemed an improper undesired behavior that got corrected in the release to match pre-agreed expectations.

    • feature: A new behavior, public APIs. That sort of stuff.

    • deprecation: A declaration of future API removals and breaking changes in behavior.

    • breaking: When something public gets removed in a breaking way. Could be deprecated in an earlier release.

    • doc: Notable updates to the documentation structure or build process.

    • packaging: Notes for downstreams about unobvious side effects and tooling. Changes in the test invocation considerations and runtime assumptions.

    • contrib: Stuff that affects the contributor experience. e.g. Running tests, building the docs, setting up the development environment.

    • misc: Changes that are hard to assign to any of the above categories.

    Related issues and pull requests on GitHub: #654.

Contributor-facing changes#

  • Started type-checking the project with MyPy against a range of versions instead of just one — Python 3.8–3.12 – by @webknjaz.

    Related commits on GitHub: @4fa1e66, @676edc4, @be9dbc4.

  • The project how has a .git-blame-ignore-revs letting GitHub know which auto-formatting revisions to ignore. It is also possible to integrate it locally, if one wants to do so.

    – by @webknjaz

    Related commits on GitHub: @5980a3f, @f8a1cc4.

  • The project adopted the autopep8 tool to assist with automatic code formatting. It is chosen over black because it is less intrusive which is important to the maintainer as it promotes inclusivity. autopep8 is integrated into the pre-commit check runner and is configured to only correct PEP 8 violations, avoiding changes to compliant snippets.

    – by @webknjaz

    Related commits on GitHub: @65ba7e6.

  • The continuous integration and pull request merges have been set up to only merge pull requests through merge queues – by @webknjaz.

    Related commits on GitHub: @a7149e0.

  • Documented the upgraded release process – by @webknjaz.

    Related commits on GitHub: @df0d1a0.

  • The change log management is now implemented through the Towncrier tool – by @webknjaz.

    The contributors are now expected to include change log fragment files in their pull requests.

    These news snippets can link one or more issues or pull requests, and be of one or more of the following categories:

    • bugfix: A bug fix for something we deemed an improper undesired behavior that got corrected in the release to match pre-agreed expectations.

    • feature: A new behavior, public APIs. That sort of stuff.

    • deprecation: A declaration of future API removals and breaking changes in behavior.

    • breaking: When something public gets removed in a breaking way. Could be deprecated in an earlier release.

    • doc: Notable updates to the documentation structure or build process.

    • packaging: Notes for downstreams about unobvious side effects and tooling. Changes in the test invocation considerations and runtime assumptions.

    • contrib: Stuff that affects the contributor experience. e.g. Running tests, building the docs, setting up the development environment.

    • misc: Changes that are hard to assign to any of the above categories.

    Related issues and pull requests on GitHub: #654.

v10.0.0#

(2023-05-20)

  • #504 via #505: Cheroot now accepts a reuse_port parameter on the HTTPServer object. Subclasses overriding prepare_socket will no longer work and will need to adapt to the new interface.

v9.0.0#

(2022-11-19)

  • #252 via #339: Cheroot now requires Python 3.6 or later. Python 3.5 and Python 2.7 are still supported by the maint/8.x branch and stabilizing bugfixes will be accepted to that branch.

v8.6.0#

(2022-01-03)

Significant improvements:

  • #384 via #385, #406: Exposed type stubs with annotations for public API – by @kasium.

  • #401 (related to the #352 effort): Started reusing the the expriration_interval setting as timeout in the low-level select() invocation, effectively reducing the system load when idle, that is noticeable on low-end hardware systems. On Windows OS, due to different select() behavior, the effect is less significant and comes with a theoretically decreased performance on quickly repeating requests, which has however found to be not significant in real world scenarios. – by @MichaIng.

Internal changes:

  • Implemented a manual-trigger-based release workflow.

  • Integrated publishing GitHub Releases into the workflow.

  • Migrated the docs theme to Furo (created by @pradyunsg).

  • Attempted to improve the stability of testing.

  • Configured the CI to test the same distribution as will be shipped.

  • Improved the linting setup and contributor checklists.

  • Stopped running tests under Ubuntu 16.04.

  • Tweaked the distribution packages metadata to satisfy strict checks.

  • Implemented distribution build reproducibility using a pip constraints lock-file.

  • Added per-environment lock-files into the tox test environments.

v8.5.2#

(2021-01-18)

  • #358 via #359: Fixed a regression from #199 that made the worker threads exit on invalid connection attempts and could make the whole server unresponsive once there was no workers left. – by @cameronbrunner.

v8.5.1#

(2020-12-12)

v8.5.0#

(2020-12-05)

  • #305 via #311: In ConnectionManager, process connections as they become active rather than waiting for a tick event, addressing performance degradation introduced in v8.1.0 – by @liamstask.

  • #341 via #342: Suppress legitimate OS errors expected on shutdown – by @webknjaz.

v8.4.8#

(2020-11-24)

  • #317 via #337: Fixed a regression in 8.4.5 where the connections dictionary would change size during iteration, leading to a RuntimeError raised in the logs – by @liamstask.

v8.4.7#

(2020-11-15)

  • #334: Started filtering out TLS/SSL errors when the version requested by the client is unsupported – by @sanderjo and @Safihre.

v8.4.6#

(2020-11-15)

v8.4.5#

(2020-08-24)

  • #312 via #313: Fixed a regression introduced in the earlier refactoring in v8.4.4 via #309 that caused the connection manager to modify the selector map while looping over it – by @liamstask.

  • #312 via #316: Added a regression test for the error handling in get_conn() to ensure more stability – by @cyraxjoe.

v8.4.4#

(2020-08-12)

v8.4.3#

(2020-08-12)

  • #282: Fixed a race condition happening when an HTTP client attempts to reuse a persistent HTTP connection after it’s been discarded on the server in HTTPRequest but no TCP FIN packet has been received yet over the wire – by @meaksh.

    This change populates the Keep-Alive header exposing the timeout value for persistent HTTP/1.1 connections which helps mitigate such race conditions by letting the client know not to reuse the connection after that time interval.

v8.4.2#

(2020-07-28)

  • Fixed a significant performance regression introduced in v8.1.0 (#305 via #308) - by @mar10.

    The issue turned out to add 0.1s delay on new incoming connection processing. We’ve lowered that delay to mitigate the problem short-term, better fix is yet to come.

v8.4.1#

(2020-07-26)

v8.4.0#

(2020-07-23)

  • Converted management from low-level select() to high-level selectors (#249 via #301) - by @tommilligan.

    This change also introduces a conditional dependency on selectors2 as a fall-back for legacy Python interpreters.

v8.3.1#

(2020-07-13)

  • Fixed TLS socket related unclosed resource warnings (#291 and #298).

  • Made terminating keep-alive connections more graceful (#263 via #277).

v8.3.0#

(2020-02-09)

  • cherrypy/cherrypy#910 via #243: Provide TLS-related details via WSGI environment interface.

  • #248: Fix parsing of the --bind CLI option for abstract UNIX sockets.

v8.2.1#

(2019-10-17)

v8.2.0#

(2019-10-14)

  • Deprecated use of negative timeouts as alias for infinite timeouts in ThreadPool.stop.

  • cherrypy/cherrypy#1662 via #74: For OPTION requests, bypass URI as path if it does not appear absolute.

v8.1.0#

(2019-10-09)

  • Workers are now request-based, addressing the long-standing issue with keep-alive connections (#91 via #199).

v8.0.0#

(2019-10-09)

  • #231 via #232: Remove custom setup.cfg parser handling, allowing the project (including sdist) to build/run on setuptools 41.4. Now building cheroot requires setuptools 30.3 or later (for declarative config support) and preferably 34.4 or later (as indicated in pyproject.toml).

v7.0.0#

(2019-09-26)

  • #224: Refactored “open URL” behavior in webtest to rely on retry_call. Callers can no longer pass raise_subcls or ssl_context positionally, but must pass them as keyword arguments.

v6.6.0#

(2019-09-25)

  • Revisit #85 under #221. Now backports.functools_lru_cache is only required on Python 3.2 and earlier.

  • cherrypy/cherrypy#1206 via #204: Fix race condition in threadpool shrink code.

v6.5.8#

(2019-09-05)

  • #222 via @621f4ee: Fix socket.SO_PEERCRED constant fallback value under PowerPC.

v6.5.7#

(2019-09-03)

  • #198 via @9f7affe: Fix race condition when toggling stats counting in the middle of request processing.

  • Improve post Python 3.9 compatibility checks.

  • Fix support of abstract namespace sockets.

v6.5.6#

(2019-08-19)

  • #218 via #219: Fix HTTP parser to return 400 on invalid major-only HTTP version in Request-Line.

v6.5.5#

(2019-04-25)

  • #99 via #186: Sockets now collect statistics (bytes read and written) on Python 3 same as Python 2.

  • cherrypy/cherrypy#1618 via #180: Ignore OpenSSL’s 1.1+ Error 0 under any Python while wrapping a socket.

v6.5.4#

(2019-01-01)

v6.5.3#

(2018-12-20)

  • #149: Make SCRIPT_NAME optional per PEP 333.

v6.5.2#

(2018-09-03)

v6.5.1#

(2018-09-02)

v6.5.0#

(2018-08-29)

v6.4.0#

(2018-08-01)

v6.3.3#

(2018-07-10)

v6.3.2#

(2018-06-16)

  • #100 via #101: Respond with HTTP 400 to malicious Content-Length in request headers.

v6.3.1#

(2018-05-21)

v6.3.0#

(2018-05-17)

  • #87: Add cheroot command and runpy launcher to launch a WSGI app from the command-line.

v6.2.4#

(2018-04-19)

  • Fix missing resolve_peer_creds argument in cheroot.wsgi.Server being bypassed into cheroot.server.HTTPServer.

  • #85: Revert conditional dependencies. System packagers should honor the dependencies as declared by cheroot, which are defined intentionally.

v6.2.3#

(2018-04-14)

  • #85: Skip installing dependencies from backports namespace under Python 3.

v6.2.2#

(2018-04-14)

v6.2.1#

(2018-04-10)

  • #83: Fix regression, caused by inverted check for Windows OS.

  • Add more URLs to distribution metadata

v6.2.0#

(2018-04-10)

  • #37: Implement PEERCRED lookup over UNIX-socket HTTP connection.

    • Discover connected process’ PID/UID/GID

    • Respect server switches: peercreds_enabled and peercreds_resolve_enabled

    • get_peer_creds and resolve_peer_creds methods on connection

    • peer_pid, peer_uid, peer_gid, peer_user and peer_group properties on connection

    • X_REMOTE_PID, X_REMOTE_UID, X_REMOTE_GID, X_REMOTE_USER (REMOTE_USER) and X_REMOTE_GROUP WSGI environment variables when enabled and supported

    • Per-connection caching to reduce lookup cost

v6.1.2#

(2018-04-08)

v6.1.1#

(2018-04-07)

v6.1.0#

(2018-04-05)

  • #67: Refactor test suite to completely rely on pytest.

    • Integrate pytest-testmon and pytest-watch

    • Stabilize testing

  • cherrypy/cherrypy#1664 via #66: Implement input termination flag support as suggested by @mitsuhiko in his wsgi.input_terminated Proposal.

  • #73: Fix SSL error bypassing.

  • #77 via #78: Fix WSGI documentation example to support Python 3.

  • #76: Send correct conditional HTTP error in helper function.

  • cherrypy/cherrypy#1404 via #75: Fix headers being unsent before request closed. Now we double check that they’ve been sent.

  • Minor docs improvements.

  • Minor refactoring.

v6.0.0#

(2017-12-04)

  • Drop support for Python 2.6, 3.1, 3.2, and 3.3.

  • Also drop built-in SSL support for Python 2.7 earlier than 2.7.9.

v5.11.0#

(2017-12-04)

  • cherrypy/cherrypy#1621: To support webtest applications that feed absolute URIs to getPage() but expect the scheme/host/port to be ignored (as cheroot 5.8 and earlier did), provide a strip_netloc helper and recipe for calling it in a subclass.

v5.10.0#

(2017-11-23)

  • Minor refactorings of cheroot/server.py to reduce redundancy of behavior.

  • Delinting with fewer exceptions.

  • Restored license to BSD.

v5.9.2#

(2017-11-23)

  • #61: Re-release without spurious files in the distribution.

v5.9.1#

(2017-11-17)

  • #58: Reverted encoding behavior in wsgi module to correct regression in CherryPy tests.

v5.9.0#

(2017-11-16)

  • cherrypy/cherrypy#1088 and #53: Avoid using SO_REUSEADDR on Windows where it has different semantics.

  • cheroot.tests.webtest adopts the one method that was unique in CherryPy, now superseding the implementation there.

  • Substantial cleanup around compatibility functions (_compat module).

  • License unintentionally changed to MIT. BSD still declared and intended.

v5.8.3#

(2017-08-11)

  • Improve HTTP request line validation:

    • Improve HTTP version parsing

  • Fix HTTP CONNECT method processing:

    • Respond with 405 Method Not Allowed if proxy_mode is False

    • Validate that request-target is in authority-form

  • Improve tests in test.test_core

  • #44: Fix EPROTOTYPE @ Mac OS

v5.8.2#

(2017-08-07)

  • Fix #39 regression. Add HTTP request line check: absolute URI path must start with a forward slash (“/”).

v5.8.1#

(2017-08-05)

v5.8.0#

(2017-08-01)

  • CI improvements:

    • Switch to native PyPy support in Travis CI

    • Take into account PEP 257 compliant modules

    • Build wheel in AppVeyor and store it as an artifact

  • Improve urllib support in cheroot._compat

  • #38 via #39: Improve URI parsing:

    • Make it compliant with RFC 7230, RFC 7231 and RFC 2616

    • Fix setting of environ['QUERY_STRING'] in WSGI

    • Introduce proxy_mode and strict_mode argument in server.HTTPRequest

    • Fix decoding of Unicode URIs in WSGI 1.0 gateway

v5.7.0#

(2017-06-24)

  • CI improvements:

    • Don’t run tests during deploy stage

    • Use VM based build job environments only for pyenv environments

    • Opt-in for beta trusty image @ Travis CI

    • Be verbose when running tests (show test names)

    • Show xfail/skip details during test run

  • #34: Fix _handle_no_ssl error handler calls

  • #21: Fix test_conn tests:

    • Improve setup_server def in HTTP connection tests

    • Fix HTTP streaming tests

    • Fix HTTP/1.1 pipelining test under Python 3

    • Fix test_readall_or_close test

    • Fix test_No_Message_Body

    • Clarify test_598 fail reason

  • #36: Add GitHub templates for PR, issue && contributing

  • #27: Default HTTP Server header to Cheroot version str

  • Cleanup _compat functions from server module

v5.6.0#

(2017-06-20)

v5.5.2#

(2017-06-18)

v5.5.1#

(2017-06-18)

v5.5.0#

(2017-05-02)

  • #17 via #25: Instead of a read_headers function, cheroot now supplies a HeaderReader class to perform the same function.

    Any HTTPRequest object may override the header_reader attribute to customize the handling of incoming headers.

    The server module also presents a provisional implementation of a DropUnderscoreHeaderReader that will exclude any headers containing an underscore. It remains an exercise for the implementer to demonstrate how this functionality might be employed in a server such as CherryPy.

  • #26: Configured TravisCI to run tests under OS X.

v5.4.0#

(2017-03-19)

  • #22: Add “ciphers” parameter to SSLAdapter.

v5.3.0#

(2017-03-12)

v5.2.0#

(2017-03-02)

  • #5: Set Server.version to Cheroot version instead of CherryPy version.

  • #4: Prevent tracebacks and drop bad HTTPS connections in the BuiltinSSLAdapter, similar to pyOpenSSLAdapter.

  • #3: Test suite now runs and many tests pass. Some are still failing.

v5.1.0#

(2017-01-22)

v5.0.1#

(2017-01-14)

  • Fix error in parse_request_uri created in @68a5769.

v5.0.0#

(2017-01-14)