Package architecture

The package provides a narrow public façade over request modeling, transport, asynchronous delivery, response conversion, and optional output.

Public surface

src/pacifico/__init__.py re-exports:

from pacifico.core.main.pacifico import request
from pacifico.util.Enumerations import Country, VersionType, Quality, Fixing

Applications should depend on those exports. The lower-level classes are tightly coupled to the server contract and shared private code.

Source layout

src/
├── pacifico/
│   ├── __init__.py
│   ├── core/
│   │   ├── main/pacifico.py
│   │   └── Service/
│   │       ├── Field/
│   │       └── ServiceRequest/
│   └── util/
│       ├── Arguments.py
│       ├── Downloader.py
│       ├── Enumerations.py
│       ├── Format.py
│       └── Output.py
└── pacifico_devel/
    └── shared private package/submodule
Component Responsibility
core/main/pacifico.py Public dispatcher and end-to-end workflows
ServiceRequestDataPointValue Build value request models
ServiceRequestDataPointReport Build report request models
ServiceRequestApplication Build app/help requests and prepare file inputs
FieldTicker / FieldReport Instrument and report selectors
FieldTimeInterval Validate dates and serialize fixing/range
FieldVersion / FieldQuality / FieldDataType Shared filters
Service Serialize and POST with x-api-key
Arguments Token loading and legacy CLI parsing
Downloader Poll temporary result URL
Format JSON, dictionary, and DataFrame conversion
Output Optional .csv/.txt writing

Call flow

pacifico.request(...)
        │
        ├── app set ───────────────→ ServiceRequestApplication
        ├── report selector set ───→ ServiceRequestDataPointReport
        └── otherwise ─────────────→ ServiceRequestDataPointValue
                                          │
                                  tokenReader + getResponse
                                          │
                                   POST API request
                                          │
                                    poll result URL
                                          │
                                  jsonToFormat(response)
                                          │
                                    optional writeFile
                                          │
                                        return

Request construction

Field classes validate Python types and serialize empty/default attributes away. The value builder creates:

  • one FieldTicker per ticker (or one broader selector field);
  • one FieldTimeInterval;
  • one FieldDataType;
  • one FieldVersion;
  • one FieldQuality.

The report builder replaces ticker fields with one FieldReport containing document hierarchy and an empty typed variant.

The outer data-point request serializes field objects into nested JSON strings expected by the companion API. This wire representation is an internal coupling; consumers should not construct it directly.

Route-specific normalization

The public façade performs several conversions before transport:

  • a value-route country string becomes Country;
  • fieldType becomes an internal field enum;
  • unspecified version type is resolved from whether version is empty;
  • default application arguments are removed;
  • application file arguments can be uploaded after a help lookup.

Other validation occurs inside field property setters. This is why an invalid enum or date usually fails before network access.

Transport

Service.getResponse:

  1. checks that the token is a string;
  2. calls the service object's getJson();
  3. posts that body to the configured HTTPS endpoint;
  4. sends the token in x-api-key;
  5. returns the response text as the result URL.

The endpoint, header name, and delivery protocol are implemented constants rather than public configuration options in this package version.

Response conversion

Format.jsonToFormat selects:

  • pass-through JSON;
  • json.loads for dictionary mode;
  • heuristic DataFrame conversion.

DataFrame route detection looks for "field" to identify values and "variant" or an application report marker to identify reports. Conversion flattens nested shared dimensions into rows. Parsing failures are commonly converted into synthetic error rows.

This heuristic design makes raw JSON the compatibility boundary for new or custom application responses.

Shared private submodule

The repository includes src/pacifico_devel as a Git submodule. The client uses shared message, enumeration, formatting, file-upload, and browser utilities from it. A source checkout without the initialized submodule can import the root package incompletely or fail during response/application handling.

Keep the submodule revision and client code synchronized. Do not replace it with an arbitrary latest commit during a reproducible build.

Import-time behavior

Importing pacifico imports the request module, which:

  • checks for requests and attempts a pip installation if it cannot be imported;
  • binds default request dates to the import date;
  • imports formatting code and shared dependencies;
  • can print a Selenium import warning when optional browser tooling is unavailable.

Production images should install all declared dependencies during the build stage rather than relying on runtime installation.

Compatibility boundaries

Changes in these areas require coordinated client/server validation:

  • serialized field names and enum numeric values;
  • dispatch precedence;
  • metadata trigger strings;
  • canonical and large-report response schemas;
  • typed report variant labels;
  • asynchronous result markers;
  • application help/file conventions;
  • DataFrame column names and order.

See Development and builds for a change checklist.