Request routing¶

pacifico.request(...) is a dispatcher. Understanding its precedence prevents a request assembled for one data model from silently reaching another.

Dispatch order¶

app is non-empty?
├── yes → hosted application
└── no
    └── any report selector is non-empty?
        ├── yes → report
        └── no  → value (or value metadata)

The report selectors are:

document, item, chapter, section, subsection, paragraph

Routing examples¶

Arguments	Route	Reason
ticker="CHILE"	Value	No application or report selector
no selectors	Value metadata	Empty value selection and empty author trigger metadata
ticker="metadata"	Value metadata	Explicit value metadata marker
item="97004000-5"	Report	item is a report selector
document="metadata"	Report metadata	Report route plus metadata marker
app="<APP>", ticker="CHILE"	Application	app wins; ticker is forwarded as an app argument
app="<APP>", item="<ITEM>"	Application	app wins over report selectors

Valid report construction¶

Dispatch and validation are separate. chapter, section, subsection, or paragraph alone is enough to choose the report route, but the report builder requires at least document or item. Such a call therefore fails after routing.

Use:

pacifico.request(
    "token.key",
    document="<DOCUMENT>",
    chapter="<CHAPTER>",
)

not:

pacifico.request(
    "token.key",
    chapter="<CHAPTER>",
)

Extra keyword behavior¶

The public function accepts **kwargs, but only the application route consumes them:

# Forwarded to the hosted application
pacifico.request(
    "token.key",
    app="<APPLICATION_NAME>",
    customArgument="<VALUE>",
)

# Accepted by Python but silently ignored by the value route
pacifico.request(
    "token.key",
    ticker="CHILE",
    customArgument="<VALUE>",
)

This also makes typographical errors dangerous. For example, dataType="Price" is ignored; fieldType="Price" is required. Validate wrapper inputs and reject unknown keys before calling the client.

Build requests defensively¶

When arguments come from a form or configuration file:

REPORT_KEYS = {
    "document",
    "item",
    "chapter",
    "section",
    "subsection",
    "paragraph",
}


def validate_route(arguments):
    if arguments.get("app"):
        return "application"

    report_route = any(arguments.get(key, "") != "" for key in REPORT_KEYS)
    if report_route:
        if not (arguments.get("document") or arguments.get("item")):
            raise ValueError("A report needs document or item.")
        return "report"

    return "value"

Consider separate application-level functions such as get_values, get_reports, and run_application even though they all delegate to pacifico.request. Separate interfaces make invalid cross-route combinations harder to create.

Shared parameters are route-sensitive¶

dateStart, dateEnd, fixing, fieldType, versionType, author, version, and quality are modeled directly for value and report requests. On an application route, non-default values are forwarded as application arguments and interpreted only by that application's contract.

help has meaning only for applications. On value and report routes it does not change behavior.