CHANGES.txt

Unreleased
----------

Feature
~~~~~~~

- Rename "master" git branch to "main"

- Add support for Python 3.12.

- Add Request.remote_host, exposing REMOTE_HOST environment variable.

- Added ``webob.acceptparse.Accept.parse_offer`` to codify what types of offers
  are compatible with ``webob.acceptparse.Accept.acceptable_offers``. This API
  also normalizes the offer with lowercased type/subtype and parameter names.
  See https://github.com/Pylons/webob/pull/376 and
  https://github.com/Pylons/webob/pull/379

- Consolidation of ``Accept`` header handling into a single class.
  See backward incompatibilities below for more information.
  See https://github.com/Pylons/webob/pull/460

- ``webob.acceptparse.Accept``, methods ``best_match``, ``quality``, and
  ``__contains__`` are undeprecated and their logic is made consistent with
  ``acceptable_offers``. See backward incompatibilities below.
  See https://github.com/Pylons/webob/pull/460

- Consolidation of ``AcceptCharset`` header handling into a single class.
  See backward incompatibilities below for more information.
  See https://github.com/Pylons/webob/pull/461

- ``webob.acceptparse.AcceptCharset``, methods ``best_match``, ``quality``, and
  ``__contains__`` are undeprecated and their logic is made consistent with
  ``acceptable_offers``. See backward incompatibilities below.
  See https://github.com/Pylons/webob/pull/461

- Consolidation of ``AcceptEncoding`` header handling into a single class.
  See backward incompatibilities below for more information.
  See https://github.com/Pylons/webob/pull/462

- ``webob.acceptparse.AcceptEncoding``, methods ``best_match``, ``quality``,
  and ``__contains__`` are undeprecated and their logic is made consistent with
  ``acceptable_offers``. See backward incompatibilities below.
  See https://github.com/Pylons/webob/pull/462

- Consolidation of ``AcceptLanguage`` header handling into a single class.
  See backward incompatibilities below for more information.
  See https://github.com/Pylons/webob/pull/463

- ``webob.acceptparse.AcceptLanguage.__contains__`` is undeprecated and its
  logic is made consistent with the ``basic_filtering`` algorithm.
  See backward incompatibilities below.
  See https://github.com/Pylons/webob/pull/463

Compatibility
~~~~~~~~~~~~~


Backwards Incompatibilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Drop support for Python 2.7, 3.4, 3.5, 3.6, and 3.7.

- Remove ``AcceptValidHeader``, ``AcceptNoHeader`` and ``AcceptInvalidHeader``.
  These classes are consolidated into ``Accept`` with a ``header_state``
  attribute for users that need to know the exact state of the header.
  See https://github.com/Pylons/webob/pull/460

- Remove previously-deprecated ``webob.acceptparse.MIMEAccept``.
  See https://github.com/Pylons/webob/pull/460

- Remove previously-deprecated ``webob.acceptparse.Accept.__iter__``.
  See https://github.com/Pylons/webob/pull/460

- ``webob.acceptparse.Accept`` methods, ``best_match``, ``quality``, and
  ``__contains__`` are now thin wrappers around ``acceptable_offers`` which
  modifies their behavior slightly:

  - Offers containing wildcards are no longer allowed.
  - A tuple can no longer be an offer containing server-side quality values.
  - An offer will only match a wildcard clause in the header, such as ``*/*``
    or ``text/*`` if it does not match something more specific.

  See https://github.com/Pylons/webob/pull/460

- Remove ``AcceptCharsetValidHeader``, ``AcceptCharsetNoHeader`` and
  ``AcceptCharsetInvalidHeader``. These classes are consolidated into
  ``AcceptCharset`` with a ``header_state`` attribute for users that need
  to know the state of the header.
  See https://github.com/Pylons/webob/pull/461

- Remove previously-deprecated ``webob.acceptparse.AcceptCharset.__iter__``.
  See https://github.com/Pylons/webob/pull/461

- ``webob.acceptparse.AcceptCharset`` methods, ``best_match``, ``quality``, and
  ``__contains__`` are now thin wrappers around ``acceptable_offers`` which
  modifies their behavior slightly:

  - A tuple can no longer be an offer containing server-side quality values.
  - An offer will only match a ``*`` clause in a header if it does not match
    any other clauses.

  See https://github.com/Pylons/webob/pull/461

- Remove ``AcceptEncodingValidHeader``, ``AcceptEncodingNoHeader`` and
  ``AcceptEncodingInvalidHeader``. These classes are consolidated into
  ``AcceptEncoding`` with a ``header_state`` attribute for users that need
  to know the state of the header.
  See https://github.com/Pylons/webob/pull/462

- Remove previously-deprecated ``webob.acceptparse.AcceptEncoding.__iter__``.
  See https://github.com/Pylons/webob/pull/462

- ``webob.acceptparse.AcceptEncoding`` methods, ``best_match``, ``quality``,
  and ``__contains__`` are now thin wrappers around ``acceptable_offers`` which
  modifies their behavior slightly:

  - A tuple can no longer be an offer containing server-side quality values.
  - An offer will only match a ``*`` clause in a header if it does not match
    any other clauses.
  - The ``identity`` offer was not properly considered a match unless the
    header explicitly it excluded via ``*;q=0`` or ``identity;q=0``.

  See https://github.com/Pylons/webob/pull/462

- Remove ``AcceptLanguageValidHeader``, ``AcceptLanguageNoHeader`` and
  ``AcceptLanguageInvalidHeader``. These classes are consolidated into
  ``AcceptLanguage`` with a ``header_state`` attribute for users that need
  to know the state of the header.
  See https://github.com/Pylons/webob/pull/463

- Remove previously-deprecated ``webob.acceptparse.AcceptLanguage`` methods
  ``__iter__``, ``best_match`` and ``quality``. Look at using
  ``basic_filtering`` and ``lookup`` methods instead that implement
  RFC-compliant algorithms for language negotiation.
  See https://github.com/Pylons/webob/pull/463

- ``webob.acceptparse.AcceptLanguage.basic_filtering`` now considers supplied
  language tags to all match with quality 1.0 if the header itself is missing
  or invalid.
  See https://github.com/Pylons/webob/pull/463

- ``webob.acceptparse.AcceptEncoding.__contains__`` method is now a thin
  wrapper around ``basic_filtering`` which modifies their behavior slightly:

  - A tuple can no longer be an offer containing server-side quality values.
  - An offer will only match a ``*`` clause in a header if it does not match
    any other clauses.
  - The ``identity`` offer was not properly considered a match unless the
    header explicitly it excluded via ``*;q=0`` or ``identity;q=0``.

  See https://github.com/Pylons/webob/pull/463

Experimental Features
~~~~~~~~~~~~~~~~~~~~~

- The SameSite value now includes a new option named "None", this is a new
  change that was introduced in
  https://tools.ietf.org/html/draft-west-cookie-incrementalism-00

  Please be aware that older clients are incompatible with this change:
  https://www.chromium.org/updates/same-site/incompatible-clients, WebOb does
  not enable SameSite on cookies by default, so there is no backwards
  incompatible change here.

  See https://github.com/Pylons/webob/issues/406

- Validation of SameSite values can be disabled by toggling a module flag. This
  is in anticipation of future changes in evolving cookie standards.
  The discussion in https://github.com/Pylons/webob/pull/407 (which initially
  expanded the allowed options) notes the sudden change to browser cookie
  implementation details may happen again.

  In May 2019, Google announced a new model for privacy controls in their
  browsers, which affected the list of valid options for the SameSite attribute
  of cookies. In late 2019, the company began to roll out these changes to their
  browsers to force developer adoption of the new specification.
  See https://www.chromium.org/updates/same-site and
  https://blog.chromium.org/2019/10/developers-get-ready-for-new.html for more
  details on this change.

  See https://github.com/Pylons/webob/pull/409


Bugfix
~~~~~~

- Response.content_type now accepts unicode strings on Python 2 and encodes
  them to latin-1. See https://github.com/Pylons/webob/pull/389 and
  https://github.com/Pylons/webob/issues/388

- Accept header classes now support a .copy() function that may be used to
  create a copy. This allows ``create_accept_header`` and other like functions
  to accept an pre-existing Accept header. See
  https://github.com/Pylons/webob/pull/386 and
  https://github.com/Pylons/webob/issues/385

- SameSite may now be passed as str or bytes to `Response.set_cookie` and
  `cookies.make_cookie`. This was an oversight as all other arguments would be
  correctly coerced before being serialized. See
  https://github.com/Pylons/webob/issues/361 and
  https://github.com/Pylons/webob/pull/362

- acceptparse.MIMEAccept which is deprecated in WebOb 1.8.0 made a backwards
  incompatible change that led to it raising on an invalid Accept header. This
  behaviour has now been reversed, as well as some other fixes to allow
  MIMEAccept to behave more like the old version. See
  https://github.com/Pylons/webob/pull/356

- ``acceptparse.AcceptValidHeader``, ``acceptparse.AcceptInvalidHeader``, and
  ``acceptparse.AcceptNoHeader`` will now always ignore offers that do not
  match the required media type grammar when calling ``.acceptable_offers()``.
  Previous versions raised a ``ValueError`` for invalid offers in
  ``AcceptValidHeader`` and returned them as acceptable in the others.
  See https://github.com/Pylons/webob/pull/372

- ``Response.body_file.write`` and ``Response.write`` now returns the written
  length. See https://github.com/Pylons/webob/pull/422

Warnings
~~~~~~~~

- Some backslashes introduced with the new accept handling code were causing
  DeprecationWarnings upon compiling the source to pyc files, all of the
  backslashes have been reigned in as appropriate, and users should no longer
  see DeprecationWarnings for invalid escape sequence. See
  https://github.com/Pylons/webob/issues/384