feat(fastapi): let FilterConfig control generated query parameter names

[ruicleite96]

Stacked on #784 — the first commit here is that fix, which this depends on to be demonstrable. Review #784 first; this diff is the second commit.

Problem

The query parameter names provide_filters generates are hardcoded. Eleven string literals:

ids  createdBefore  createdAfter  updatedBefore  updatedAfter
currentPage  pageSize  searchString  searchIgnoreCase  orderBy  sortOrder

plus camelize() applied to the model's own field names for the per-field filters (statusIn, isActive, expenseCategoryId, …).

There is no hook to change them. An application whose public API is snake_case cannot use the generator at all, and one using suffix conventions (issue_date__gte, parent_id__is_null) has no way to express them. The only escape is to hand-roll the parameter layer, which means reimplementing the inspect.Parameter assembly this module already does well.

Change

An optional alias_generator on FilterConfig, receiving each parameter's snake_case name and returning the query parameter to expose:

provide_filters({
    "search": "name",
    "pagination_type": "limit_offset",
    "alias_generator": lambda name: name,          # snake_case throughout
})

Every generated name now derives from a snake_case canonical form, and the default generator is camelize, which reproduces the existing names exactly:

canonical	camelize (default)
created_before	createdBefore
page_size	pageSize
search_ignore_case	searchIgnoreCase
sort_order	sortOrder

So output is byte-identical unless a generator is supplied. test_default_names_are_unchanged pins that.

The cache had to change with it

Putting a callable in the config exposed a real hazard. The key was hash((_CACHE_NAMESPACE, make_hashable(config))) — an int. Functions hash by identity, identity is the address, and reducing the key to an int drops the last reference to the function. CPython then reuses that address for the next generator, so two different generators produce the same key and DependencyCache returns the wrong providers.

This is not theoretical — I hit it while testing:

default  : ['createdBefore', ...]
snake    : ['created_before', ...]
upper    : ['created_before', ...]   # wrong: got snake's dependency

Two changes fix it:

• the cache key is the hashable tuple rather than hash() of it, so the tuple retains the callable;
• make_hashable keeps hashable callables as-is instead of str()-ing them into an address.

test_distinct_generators_get_distinct_dependencies covers it.

tests/unit/test_extensions/test_fastapi/test_providers.py::test_create_filter_dependencies_cache_miss asserted the key was hash(...); it now asserts the tuple. That is the one intentional test change.

Naming things opens the door to naming two things the same

A generator is free to be non-injective, and the result is silent. FastAPI binds the one query value
to both parameters, so a created_before/created_after pair collapsed onto a single name asks for
< x AND > x and matches nothing, while the schema shows one parameter where there should be two:

provide_filters({"created_at": True, "alias_generator": lambda n: n.split("_")[0]})
# openapi parameters: ['created']
# GET /x?created=2020-06-01  ->  BeforeAfter(before=2020-06-01, after=2020-06-01)

The default generator collides too, and always could — this part is a pre-existing bug rather than
something the generator introduces:

provide_filters({"boolean_fields": ["status_in"], "in_fields": ["status"]})
# both reach 'statusIn'; openapi parameters: ['statusIn']

Every generated parameter asks for its name exactly once, so a name asked for twice is always two
parameters colliding. Building the dependency now raises ImproperConfigurationError naming both
sides instead of producing a filter surface that quietly does not work.

Worth flagging for review: a config that hits the pre-existing statusIn case starts raising at
startup where it previously built. It was already broken — one of the two filters was unreachable —
but it is a behaviour change, so say the word if you would rather it warn than raise.

Tests

tests/unit/test_extensions/test_fastapi/test_provider_alias_generator.py:

• default names unchanged, asserted as a full ordered list;
• a generator renames every parameter, including the per-field ones;
• distinct generators get distinct dependencies, and the default config is unaffected;
• a colliding generator is rejected, and so is the status_in/status pair under the default.

Full tests/unit/test_extensions/ suite passes. ruff check, ruff format and mypy clean.

Scope

FastAPI only. The Litestar provider names its parameters the same way and could take the same hook — I left it out to keep this reviewable, and am happy to add it here or in a follow-up if you want parity.

I am also happy to change the generator's signature if you would prefer something richer than Callable[[str], str] — for example receiving (field, operator) separately, which is what fastapi-filters does. One string keeps the fixed parameters and the per-field ones under a single transform, which is why I started there.