Development and builds

Clone the complete source

The shared private package is a Git submodule:

git clone --recurse-submodules <REPOSITORY_URL>
cd pacifico-client

For an existing clone:

git submodule update --init --recursive

Use credential helpers or SSH configuration approved by the organization. Never embed access tokens in remote or submodule URLs.

Create an environment

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

An editable installation uses the package under src/pacifico while resolving its declared dependencies.

Packaging metadata

File Role
setup.cfg Package name, version, description, classifiers, dependency list, src discovery
pyproject.toml PEP 517 build backend and build-system requirements
README.md PyPI long description
LICENSE Proprietary license terms
src/pacifico_devel Pinned shared-code submodule

The current package metadata identifies version 0.0.9.42 and Python >=3.6.

Build distributions

python -m pip install build twine
python -m build
python -m twine check dist/*

The build produces a source distribution and wheel under dist/. Inspect both before an authorized publication:

  • package version and metadata;
  • included pacifico and required shared modules;
  • absence of token files, notebooks, local data, caches, and unrelated utilities;
  • clean install in a fresh environment;
  • representative value/report conversion.

Publication credentials and package-index actions are release-manager responsibilities.

Build the documentation

The site uses only MkDocs' built-in themes and Python-Markdown extensions configured in mkdocs.yml:

python -m pip install mkdocs
mkdocs serve

For CI or a local strict build without writing a site/ directory into the repository:

mkdocs build --strict --site-dir /tmp/pacifico-client-docs

strict: true is also set in the project configuration, so missing navigation pages and warnings fail the build.

Change checklist

When modifying pacifico.request or a field model:

  1. update the signature reference and route-specific guide;
  2. preserve timeFrecuency unless introducing a versioned migration;
  3. validate value, report, metadata, and application dispatch;
  4. verify single and list tickers;
  5. test date validation, single-date, latest, and multi-day normalization;
  6. verify all three output formats;
  7. verify both canonical and large report schemas;
  8. test synthetic error-row detection;
  9. confirm built-in file extensions and overwrite behavior;
  10. coordinate serialized changes with the API repository;
  11. build the documentation with strict mode;
  12. scan source, history, wheels, and sdists for secrets.

Contract smoke tests

Tests that use the live API require an approved token and should be opt-in. Keep default automated checks deterministic and credential-free:

  • import the public root exports;
  • inspect pacifico.request signature;
  • construct/serialize field models with placeholder values;
  • convert fixture JSON into each format;
  • assert exact DataFrame columns;
  • simulate processing, completion, timeout, and malformed payloads;
  • assert token-path behavior using temporary placeholder files;
  • assert application help/file logic with mocked network and upload calls.

Never record a real token, presigned URL, licensed response, or confidential application input in a fixture.

Version and release discipline

Before changing the version in setup.cfg:

  1. finalize client/server compatibility;
  2. update user-facing docs for behavior changes;
  3. pin and review the shared submodule commit;
  4. run the test and build checks;
  5. inspect distribution contents;
  6. install the wheel in a clean environment;
  7. obtain release approval.

The build-system dependency list and runtime dependency list overlap. Dependency changes should be intentional in both places and tested under the supported Python matrix.

Documentation style

  • Prefer executable Python examples with token.key or environment variables.
  • Use placeholders for application names and private identifiers.
  • State whether behavior is client validation, server normalization, or entitlement-dependent.
  • Document exact public spellings and enum requirements.
  • Keep internal implementation notes on architecture/reference pages, not in the first-run path.
  • Link within docs/ or to stable repository URLs so strict builds remain portable.