WIP: ✨ Is23/po center preparation

[pcrespov]

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

[codecov]

Codecov Report

❌ Patch coverage is 70.74830% with 43 lines in your changes missing coverage. Please review.
✅ 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%)	⬆️	Carriedforward from 3700e93
unittests	85.76% <70.74%> (-0.15%)	⬇️

*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%)	⬇️
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%)	⬆️
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%)	⬇️
webclient	∅ <ø> (∅)
webserver	80.69% <53.84%> (-6.07%)	⬇️

---

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.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull Request Overview

This PR refactors user admin API query handling and adds robust ordering support for API list operations. The main changes include:

• Introduction of generic ordering infrastructure via OrderingQueryParams with support for comma-separated field ordering
• Enhanced user account listing with validated multi-field ordering capabilities
• Improved type annotations using annotated_types.doc() for clearer parameter documentation
• Email validation improvements in invitation models with lowercase normalization

Reviewed Changes

Copilot reviewed 19 out of 20 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
.github/instructions/python.instructions.md	Added guidelines for using annotated_types.doc() for parameter documentation
packages/models-library/src/models_library/list_operations.py	New module defining OrderDirection, OrderClause, and check_ordering_list for validated ordering operations
packages/models-library/src/models_library/rest_ordering.py	Refactored to add OrderingQueryParams with comma-separated string parsing support
packages/models-library/src/models_library/invitations.py	Updated to use Annotated types, enforce lowercase emails, and use datetime.now(tz=UTC)
packages/models-library/src/models_library/api_schemas_webserver/users.py	Added UserAccountOrderFields and integrated OrderingQueryParams into UsersAccountListQueryParams
services/web/server/src/simcore_service_webserver/users/_accounts_repository.py	Added OrderKeys, MergedUserData types, and ordering support in list_merged_pre_and_registered_users
services/web/server/src/simcore_service_webserver/users/_accounts_service.py	Updated documentation using annotated_types.doc() and added order_by parameter support
services/web/server/src/simcore_service_webserver/users/_controller/rest/accounts_rest.py	Added field mapping for ordering and integrated order_by into list endpoint
services/web/server/src/simcore_service_webserver/users/plugin.py	Renamed import from users_rest to profile_rest
api/specs/web-server/_users_admin.py	Updated to use separate query model and explicit order_by parameter
api/specs/web-server/_common.py	Improved assertion error message in as_query
Test files	Added comprehensive tests for ordering validation, invitation timestamps, and case-insensitive search

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[mergify]

🧪 CI Insights

Here's what we observed from your CI run for edc2260.

❌ Job Failures

Pipeline	Job	Health on master	Retries	🔍 CI Insights	📄 Logs
CI	unit-tests		0	View	View

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud