UtilMeta Python Meta-Framework

UtilMeta determines the request path for an API function based on the following priority:

1. Template String: The path provided in the @api decorator (e.g., @api.get('article/{id}')).
2. Function Name: If no path is provided in the decorator, the function name is used as the path.
3. HTTP Method Name: If a function name is a valid HTTP method (e.g., get, post, put), its path is automatically set to '/' and cannot be overridden.

Path Match Priority: When defining multiple routes, place fixed paths (e.g., /article/feed) above variable path parameters (e.g., /article/{slug}) in your class definition. This ensures UtilMeta matches the specific route before falling back to the variable one.

from utilmeta.core import api

@api.route('/article')
class ArticleAPI(api.API):
    @api.get
    def feed(self): pass
    # GET /article/feed
    
    @api.get('{slug}')
    def get_article(self, slug: str): pass
    # GET /article/{slug}
    
    def get(self, id: int): pass
    # GET /article?id=<ID>

UtilMeta's declarative ORM allows you to define the expected structure of query results using a Schema class. By inheriting from orm.Schema[<ModelClass>], you map your database models to a structured schema that controls how data is serialized for clients.

Key behaviors:

• Field Mapping: If a field name in the Schema matches a field in the model, it is serialized to the declared type.
• Relationship Serialization: For foreign keys or relationships, you can specify another Schema class to serialize the entire related object instead of just the ID. This is useful for reducing API calls (e.g., returning an author object within an article response).
• Expression Fields: You can define fields that represent database expressions (like counts) using model-level functions.

from utilmeta.core import orm
from .models import User, Article
from django.db import models

# Define a schema for the User model
class UserSchema(orm.Schema[User]):
    username: str
    # An expression field querying the count of related 'articles'
    articles_num: int = models.Count('articles')

# Define a schema for the Article model with nested serialization
class ArticleSchema(orm.Schema[Article]):
    id: int
    # Serializes the entire related User object using UserSchema
    author: UserSchema
    content: str

When a schema needs a field that depends on the context of the current request (e.g., a following boolean that changes based on whether the requesting user follows the target user), use a get_runtime class method.

This method should return a new subclass of the original schema that overrides the field with a dynamic query expression (using orm.Field and expressions).

class ProfileSchema(UserBase):
    following: bool = False

    @classmethod
    def get_runtime(cls, user):
        if not user:
            return cls

        class ProfileRuntimeSchema(cls):
            following: bool = orm.Field(
                exp.Exists(
                    Follow.objects.filter(
                        following=exp.OuterRef('pk'), 
                        follower=user
                    )
                )
            )

        return ProfileRuntimeSchema

# Usage in API:
# await ProfileSchema.get_runtime(current_user).ainit(target_instance)

Hooks allow you to intercept and modify requests, responses, or errors.

Generic Hooks

Override these methods in your Client class for global processing:

• process_request(self, request: Request) -> Request: Modify the request. Returning a Response instance skips the network call and returns that response directly.
• process_response(self, response: Response) -> Response: Modify the response. Returning a Request instance triggers a retry/redirect.
• handle_error(self, error: Error): Handle errors. Returning a Response allows you to return a custom response instead of throwing.

Decorator Hooks

Use these for fine-grained control over specific functions:

• @api.before(func): Pre-processes the request before it is called. The first argument must be the request.Request object.
• @api.after(func): Processes the response after the call.
• @api.handle(func): Handles errors thrown during the call chain.

Execution Order for Default Functions:

1. @api.before $\rightarrow$ 2. process_request $\rightarrow$ 3. Network Request $\rightarrow$ 4. process_response $\rightarrow$ 5. @api.after.

class GithubClient(cli.Client):
    @api.get('https://api.github.com/user')
    async def get_user(self) -> response.Response: pass
    
    @api.before(get_user)
    def add_authorization(self, req: request.Request):
        req.headers['Authorization'] = f'token {self.token}'

Use response templates to parse API responses automatically. Declare the template as the return type hint of your request function. The template must inherit from response.Response or be a Union of multiple response classes.

Key properties for response templates:

• status: The expected HTTP status code. The client only parses the response into this template if the status matches.
• result: The type hint for the parsed result data.
• headers: The type hint for response headers (using a Schema).
• result_key: The key in the JSON response containing the actual data (e.g., if your API returns {"data": {...}}, set result_key = 'data').
• message_key: The key for error messages.
• state_key: The key for business/status codes.
• count_key: The key for pagination totals.

Access the unparsed raw response body via response.data.

from utilmeta.core import cli, api, request, response
import utype

class UserSchema(utype.Schema):
    id: int
    username: str

class UserResponse(response.Response):
    status = 200
    result: UserSchema

class UserClient(cli.Client):
    @api.post
    def login(
        self, 
        username: str = request.BodyParam,
        password: str = request.BodyParam,
    ) -> UserResponse: pass

If multiple endpoints within an api.API class require the same parameter (such as a path parameter defined in the class route), you can declare it as a class property. This makes the parameter available to all methods in the class without repeating the declaration in every function signature.

To define a general parameter, assign a value from utilmeta.core.request to a class property. Common request parameter types include:

• request.PathParam: For path parameters.
• request.QueryParam: For query string parameters.
• request.HeaderParam: For request header parameters.
• request.CookieParam: For cookie parameters.

Example: Using @api.route to define a path template and capturing a slug for all methods in the class.

from utilmeta.core import api, request

@api.route('{slug}/comments')
class CommentAPI(api.API):
    slug: str = request.PathParam

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # self.slug is now available for use in __init__ and all methods
        self.article = Article.objects.filter(slug=self.slug).first()

    def get(self):
        return CommentSchema.serialize(Comment.objects.filter(article=self.article))