From a141f35c2392fb1467170a6d2a4ff9045de19356 Mon Sep 17 00:00:00 2001
From: Phoenix Zerin <phx@phx.nz>
Date: Mon, 6 Feb 2023 18:12:44 +1300
Subject: [PATCH] =?UTF-8?q?Added=20documentation=20for=20`Choice.case=5Fse?=
 =?UTF-8?q?nsitive`=20=F0=9F=98=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/simple_filters.rst | 30 +++++++++++++++++++++++-------
 pyproject.toml          |  2 +-
 2 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/docs/simple_filters.rst b/docs/simple_filters.rst
index 84e108a..9032a7e 100644
--- a/docs/simple_filters.rst
+++ b/docs/simple_filters.rst
@@ -219,20 +219,36 @@ initialiser.
 
    import filters as f
 
-   filter_ = f.Choice(choices=('Moe', 'Larry', 'Curly'))
+   runner = f.FilterRunner(f.Choice(choices=('Moe', 'Larry', 'Curly')))
 
-   runner = f.FilterRunner(filter_, 'Curly')
+   runner.apply('Curly')
    assert runner.is_valid() is True
    assert runner.cleaned_data == 'Curly'
 
-   runner = f.FilterRunner(filter_, 'Shemp')
+   runner.apply('Shemp')
    assert runner.is_valid() is False
 
-.. note::
+The comparison is case-sensitive by default; you can override this by passing
+``case_sensitive=False`` to the filter initialiser.
+
+The ``choices`` passed to the filter initialiser are the 'canonical' ones; when
+a match is found, the filter will always return the matching choice, rather than
+the raw input.
+
+.. code-block:: python
+
+   import filters as f
 
-   The comparison is case-sensitive; chain this filter with :ref:`case-fold` for
-   case-insensitive comparison (but note that this will modify the resulting
-   value).
+   runner = f.FilterRunner(
+       f.Choice(
+           choices=['Weiße Taube', 'Wellensittich', 'Spatz'],
+           case_sensitive=False
+       )
+   )
+
+   runner.apply('weisse taube')
+   assert runner.is_valid() is True
+   assert runner.cleaned_data == 'Weiße Taube'
 
 .. _date:
 
diff --git a/pyproject.toml b/pyproject.toml
index f087451..0a0f8eb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -2,7 +2,7 @@
 
 [project]
 name = "phx-filters"
-version = "3.2.0"
+version = "3.2.1"
 description = "Validation and data pipelines made easy!"
 readme = "README.rst"
 requires-python = ">= 3.6"