feat: Exception Filters (@Catch, @UseFilters, use_global_filters) — closes #112

[ItayTheDar]

Summary

Implements Issue #112 — NestJS-compatible Exception Filters as a first-class PyNest primitive.

• @Catch(*exc_types) — binds a filter class to one or more exception types; @Catch() catches everything
• @UseFilters(*filters) — applies filters at route-method or controller-class scope
• app.use_global_filters(*filters) — registers filters that apply to every route in the app
• ExceptionFilter ABC — subclass and implement async catch(exception, host)
• ArgumentsHost / HttpArgumentsHost — context object giving access to the Starlette Request inside a filter
• Built-in HTTP exceptions — NotFoundException, BadRequestException, ForbiddenException, UnauthorizedException, ConflictException, UnprocessableEntityException, MethodNotAllowedException, InternalServerErrorException (all subclass HttpException)

Filter resolution order (route → controller → global → framework default) is enforced and covered by integration tests.

Changes

File	Change
nest/common/exceptions.py	HttpException hierarchy, ExceptionFilter ABC, ArgumentsHost, HttpArgumentsHost
nest/core/decorators/filters.py	New — @Catch and @UseFilters
nest/core/decorators/class_based_view.py	Post-CBV route wrapping with filter dispatch
nest/core/pynest_application.py	use_global_filters() + _register_global_handler()
nest/common/__init__.py	Exports all new exception/filter symbols
nest/core/decorators/__init__.py	Exports Catch, UseFilters
nest/core/__init__.py	Exports Catch, UseFilters
pyproject.toml	Adds httpx to test dependency group
docs/exception_filters.md	New documentation page
mkdocs.yml	Adds Exception Filters to nav

Test plan

• uv run --group test pytest tests/ -v → 59 passed, 0 failures
• 17 unit tests: exception hierarchy, ArgumentsHost, ExceptionFilter ABC
• 9 unit tests: @Catch / @UseFilters decorator behaviour
• 11 integration tests via TestClient covering: global filter, controller-level filter, route-level priority, catch-all, type mismatch (no match), ArgumentsHost request access, async filter
• All 22 pre-existing tests continue to pass

🤖 Generated with Claude Code