What do these changes do?

This pull request refactors user admin API query handling, and adds robust ordering support for API list operations. The main changes include enhanced ordering query parameter models, updates to user account filtering and ordering and a new convention for documenting type annotations. Additionally, invitation models now enforce lowercase emails and use more precise type annotations.

API List Operations and Ordering Support:

Introduced OrderDirection, OrderClause, and check_ordering_list in the new list_operations.py module, providing a generic and validated way to handle multi-field ordering for API queries.
Refactored rest_ordering.py to support generic ordering via OrderingQueryParams, parsing comma-separated strings into validated order clauses and handling duplicates/conflicts robustly. [1] [2]

User Admin API Query Refactoring:

Updated user admin API endpoint to use a new query parameter model (_Q) that combines filtering and pagination, and added support for an order_by parameter for flexible sorting. [1] [2]
Refactored UsersAccountListQueryParams to inherit from OrderingQueryParams and define valid ordering fields, improving API consistency and validation. [1] [2]

User Account Search Query Enhancements:

Modified glob string constraints and field descriptions to clarify that searches are case-insensitive, improving usability and documentation. [1] [2] [3]

Invitation Model Improvements:

Updated invitation models to use Annotated for all fields, enforce lowercase emails via AfterValidator, and clarify docstrings. Also switched to using datetime.now(tz=UTC) for timestamps. [1] [2] [3] [4]

Python Coding Instructions and Documentation:

Added a new section to .github/instructions/python.instructions.md describing how to use annotated_types.doc() for parameter and return type documentation, replacing traditional docstring Args/Returns sections. This encourages concise, type-driven documentation and provides usage examples.
Updated coding guidelines to clarify when to document parameters and how to use docstrings, and reorganized sections for clarity. [1] [2] [3]

Related issue/s

Implementing follow up on ITISFoundation/private-issues#23

How to test

Dev-ops

Oct 21 '25 17:10 pcrespov

Codecov Report

:x: Patch coverage is 70.74830% with 43 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 87.27%. Comparing base (3700e93) to head (edc2260).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #8545      +/-   ##
==========================================
+ Coverage   87.23%   87.27%   +0.03%     
==========================================
  Files        1935     1587     -348     
  Lines       76564    66229   -10335     
  Branches     1403      541     -862     
==========================================
- Hits        66793    57801    -8992     
+ Misses       9364     8292    -1072     
+ Partials      407      136     -271

Flag	Coverage Δ		*Carryforward flag
integrationtests	`64.03% <ø> (+0.02%)`	:arrow_up:	Carriedforward from 3700e93
unittests	`85.76% <70.74%> (-0.15%)`	:arrow_down:

*This pull request uses carry forward flags. Click here to find out more.

Components	Coverage Δ
pkg_aws_library	`∅ <ø> (∅)`
pkg_celery_library	`∅ <ø> (∅)`
pkg_dask_task_models_library	`∅ <ø> (∅)`
pkg_models_library	`92.83% <89.85%> (-0.07%)`	:arrow_down:
pkg_notifications_library	`∅ <ø> (∅)`
pkg_postgres_database	`∅ <ø> (∅)`
pkg_service_integration	`72.76% <ø> (ø)`
pkg_service_library	`∅ <ø> (∅)`
pkg_settings_library	`∅ <ø> (∅)`
pkg_simcore_sdk	`84.89% <ø> (ø)`
agent	`93.44% <ø> (ø)`
api_server	`91.37% <ø> (ø)`
autoscaling	`95.83% <ø> (ø)`
catalog	`92.06% <ø> (ø)`
clusters_keeper	`99.14% <ø> (ø)`
dask_sidecar	`91.72% <ø> (ø)`
datcore_adapter	`97.95% <ø> (ø)`
director	`75.81% <ø> (ø)`
director_v2	`91.08% <ø> (+0.01%)`	:arrow_up:
dynamic_scheduler	`96.66% <ø> (∅)`
dynamic_sidecar	`90.83% <ø> (ø)`
efs_guardian	`89.83% <ø> (ø)`
invitations	`90.90% <ø> (ø)`
payments	`92.70% <ø> (ø)`
resource_usage_tracker	`92.00% <ø> (ø)`
storage	`86.34% <ø> (-0.37%)`	:arrow_down:
webclient	`∅ <ø> (∅)`
webserver	`80.69% <53.84%> (-6.07%)`	:arrow_down:

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 3700e93...edc2260. Read the comment docs.

:rocket: New features to boost your workflow: