diff --git a/.basedpyright/baseline.json b/.basedpyright/baseline.json index ebffbbc51..1cb3893e4 100644 --- a/.basedpyright/baseline.json +++ b/.basedpyright/baseline.json @@ -1,111 +1,5 @@ { "files": { - "./bench/bench_file_hasher_cache.py": [ - { - "code": "reportUnusedCallResult", - "range": { - "startColumn": 12, - "endColumn": 26, - "lineCount": 1 - } - }, - { - "code": "reportUnknownParameterType", - "range": { - "startColumn": 14, - "endColumn": 16, - "lineCount": 1 - } - }, - { - "code": "reportMissingParameterType", - "range": { - "startColumn": 14, - "endColumn": 16, - "lineCount": 1 - } - }, - { - "code": "reportUnknownParameterType", - "range": { - "startColumn": 19, - "endColumn": 23, - "lineCount": 1 - } - }, - { - "code": "reportMissingParameterType", - "range": { - "startColumn": 19, - "endColumn": 23, - "lineCount": 1 - } - }, - { - "code": "reportUnknownVariableType", - "range": { - "startColumn": 4, - "endColumn": 10, - "lineCount": 1 - } - }, - { - "code": "reportUnknownVariableType", - "range": { - "startColumn": 11, - "endColumn": 26, - "lineCount": 1 - } - }, - { - "code": "reportUnknownMemberType", - "range": { - "startColumn": 37, - "endColumn": 58, - "lineCount": 1 - } - }, - { - "code": "reportUnknownMemberType", - "range": { - "startColumn": 33, - "endColumn": 56, - "lineCount": 1 - } - }, - { - "code": "reportUnknownMemberType", - "range": { - "startColumn": 29, - "endColumn": 52, - "lineCount": 1 - } - }, - { - "code": "reportUnknownMemberType", - "range": { - "startColumn": 12, - "endColumn": 28, - "lineCount": 1 - } - }, - { - "code": "reportUnknownArgumentType", - "range": { - "startColumn": 22, - "endColumn": 31, - "lineCount": 1 - } - }, - { - "code": "reportUnknownArgumentType", - "range": { - "startColumn": 39, - "endColumn": 48, - "lineCount": 1 - } - } - ], "./examples/async_vs_sync_pipeline.py": [ { "code": "reportUnusedCallResult", diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile deleted file mode 100644 index 33e1e11d6..000000000 --- a/.devcontainer/Dockerfile +++ /dev/null @@ -1,40 +0,0 @@ -# DevContainer image -FROM debian:bookworm-slim -RUN \ - adduser --system --disabled-password --shell /bin/bash --home /home/vscode vscode && \ - # docker setup - apt-get update && \ - apt-get install ca-certificates curl gnupg lsb-release -y && \ - mkdir -m 0755 -p /etc/apt/keyrings && \ - curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \ - echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null && \ - apt-get update && \ - apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y && \ - usermod -aG docker vscode && \ - apt-get clean -RUN \ - # common dev setup - apt update && \ - apt-get install sudo curl jq git bash-completion -y && \ - usermod -aG sudo vscode && \ - echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers && \ - echo '. /etc/bash_completion' >> /home/vscode/.bashrc && \ - echo 'export PS1="\[\e[32;1m\]\u\[\e[m\]@\[\e[34;1m\]\H\[\e[m\]:\[\e[33;1m\]\w\[\e[m\]$ "' >> /home/vscode/.bashrc && \ - chown vscode:nogroup /home/vscode/.bashrc && \ - apt-get clean - -USER vscode -ENV PATH=/home/vscode/.local/bin:$PATH -WORKDIR /home/vscode -COPY --chown=vscode:nogroup src/orcapod/requirements.txt /tmp/requirements.txt -RUN \ - # python setup - curl -LsSf https://astral.sh/uv/install.sh | sh && \ - uv venv -p 3.9 ~/.local/share/base && \ - uv pip install --no-cache-dir --upgrade pip flake8 black faker ipykernel -p ~/.local/share/base && \ - uv pip install --no-cache-dir -r /tmp/requirements.txt -p ~/.local/share/base && \ - rm /tmp/requirements.txt && \ - echo '. ~/.local/share/base/bin/activate' >> ~/.bashrc -ENV VIRTUAL_ENV=/home/vscode/.local/share/base - -CMD ["bash", "-c", "sudo rm /var/run/docker.pid; sudo dockerd"] \ No newline at end of file diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json deleted file mode 100644 index abe701282..000000000 --- a/.devcontainer/devcontainer.json +++ /dev/null @@ -1,39 +0,0 @@ -{ - "name": "Development", - "build": { - "dockerfile": "Dockerfile", - "context": ".." - }, - "overrideCommand": false, - "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}", - "mounts": [ - "source=${localWorkspaceFolderBasename}_devcontainer_docker_data,target=/var/lib/docker,type=volume" - ], - "remoteEnv": { - "LOCAL_WORKSPACE_FOLDER": "${localWorkspaceFolder}" - }, - "postStartCommand": "docker system prune -fa && docker volume prune -f && uv pip install -e .", - "hostRequirements": { - "cpus": 2, - "memory": "8gb", - "storage": "32gb" - }, - "runArgs": [ - "--name=${localWorkspaceFolderBasename}_devcontainer", - "--privileged", - "--cgroupns=host" - ], - "customizations": { - "vscode": { - "extensions": [ - "tamasfe.even-better-toml", // *.toml language support - "ms-python.black-formatter", // Black formatting on save - "ms-toolsai.jupyter", // Jupyter IDE - "eamodio.gitlens", // Git explorer in VSCode - "streetsidesoftware.code-spell-checker", // Catch spelling errors in docs - "GitHub.copilot-chat", // GitHub Copilot AI assistant - "ms-python.python" // Python IDE - ] - } - } -} \ No newline at end of file diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml index 379ef7e3e..745133b7b 100644 --- a/.github/workflows/run-tests.yml +++ b/.github/workflows/run-tests.yml @@ -51,8 +51,8 @@ jobs: runs-on: ubuntu-latest # Only run on push/manual trigger — not on PRs — to avoid consuming SpiralDB # resources on every review cycle. - # Requires SPIRAL_WORKLOAD_ID secret; fails loudly if absent so missing - # credentials don't silently drop coverage. Runs only on the development repository: + # Requires the SPIRAL_WORKLOAD_ID secret and the SPIRAL_PROJECT_ID repository variable; + # fails loudly if either is absent so missing settings don't silently drop coverage. Runs only on the development repository: # the public repository has no SpiralDB credentials, so the job is skipped there (ITL-1007). if: >- github.repository == 'metamorphic-labs/orcapod-python' @@ -64,7 +64,7 @@ jobs: env: SPIRAL_WORKLOAD_ID: ${{ secrets.SPIRAL_WORKLOAD_ID }} SPIRAL_INTEGRATION_TESTS: "1" - SPIRAL_PROJECT_ID: ${{ vars.SPIRAL_PROJECT_ID || 'test-orcapod-362211' }} + SPIRAL_PROJECT_ID: ${{ vars.SPIRAL_PROJECT_ID }} SPIRAL_SERVER_URL: https://api.spiraldb.dev # plain http no longer answers (ITL-1008); the repository variable of this name is not read steps: @@ -74,6 +74,12 @@ jobs: echo "::error::SPIRAL_WORKLOAD_ID secret is not set. SpiralDB integration tests cannot run. Configure the secret or investigate why it is missing." exit 1 + - name: Check for SPIRAL_PROJECT_ID + if: env.SPIRAL_PROJECT_ID == '' + run: | + echo "::error::SPIRAL_PROJECT_ID repository variable is not set. SpiralDB integration tests cannot run. Configure the variable or investigate why it is missing." + exit 1 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: fetch-depth: 0 # required: hatch-vcs needs full tag history diff --git a/.gitignore b/.gitignore index 831c746a4..b7f6a7977 100644 --- a/.gitignore +++ b/.gitignore @@ -1,11 +1,5 @@ # NFS cache files .nfs* -# Ignore data files in notebooks folder -notebooks/**/*.json -notebooks/**/*.yaml -notebooks/**/*.parquet -notebooks/**/*.pkl -notebooks/**/*.db # Ignore npy and npz data files by default *.np[yz] @@ -25,10 +19,6 @@ notebooks/**/*.db # Ignore profiler output *.prof -# Ignore any notebook that starts with an underscore or test -notebooks/**/_*.ipynb -notebooks/**/test*.ipynb - # Ignore vscode settings .vscode/ diff --git a/.zed/rules b/.zed/rules index 3f2be1038..6ab793c7c 100644 --- a/.zed/rules +++ b/.zed/rules @@ -15,31 +15,32 @@ When adding or changing any instruction, update BOTH: ## Design issues log -design_issues/ at the project root is the canonical log of known design problems, bugs, and -code quality issues: one file per entry (developer, November 11, 2026; ITL-968). There is no -DESIGN_ISSUES.md; never bring it back, and never put two entries in one file. +docs/dev/design_issues/ is the canonical log of known design problems, bugs, and code +quality issues: one file per entry (developer, November 11, 2026; ITL-968). There is no +DESIGN_ISSUES.md and no top-level design_issues/ (moved in ITL-1169; --check refuses both); +never bring either back, and never put two entries in one file. -- An entry is the file design_issues/-.md (e.g. - design_issues/ITL-955-GB1.md). Its first line is the "## " it belongs +- An entry is the file docs/dev/design_issues/-.md (e.g. + docs/dev/design_issues/ITL-955-GB1.md). Its first line is the "## " it belongs under, then a blank line, "### — ", the **Status:** ("open", "in progress" or "resolved"), **Severity:** and **Issue:** lines, a blank line and the body. - Read the log with `uv run python scripts/design_issues.py` (index by area; --status open - filters; --full prints every entry). Find one entry by id: ls design_issues/*-GB1.md. + filters; --full prints every entry). Find one entry by id: ls docs/dev/design_issues/*-GB1.md. - Check the files with `uv run python scripts/design_issues.py --check` (tests/test_design_issues.py runs it in CI). -- design_issues/README.md is the full statement of the convention, with the severity +- docs/dev/design_issues/README.md is the full statement of the convention, with the severity guide. When fixing a bug or addressing a design problem: -1. Check design_issues/ first — if a matching entry exists, edit its file: update its +1. Check docs/dev/design_issues/ first — if a matching entry exists, edit its file: update its status to "in progress" while working and "resolved" once done, adding a brief Fix: note. 2. If no matching entry exists, ask the user whether it should be added before proceeding. If yes, add it as a new file (status "open" or "in progress" as appropriate). When discovering a new issue that won't be fixed immediately, ask the user whether it should be -logged in design_issues/ before adding it. +logged in docs/dev/design_issues/ before adding it. ## Superpowers artifacts @@ -80,6 +81,9 @@ other ReST cross-reference roles. Use plain ``backtick`` notation to refer to na ## Documentation samples +docs/dev/ (the design issues log and the design specification) is developer material, kept +out of the published site (exclude_docs in mkdocs.yml) and out of the sample test. + Every fenced python block in README.md, docs/index.md, docs/getting-started.md, docs/troubleshooting.md, docs/concepts/, docs/reference/ and docs/tutorial/ is executed by tests/test_docs/test_doc_samples.py, and tests/test_docs/test_mkdocs_build.py runs @@ -562,7 +566,7 @@ tests/ ## Architecture overview -See orcapod-design.md at the project root for the full design specification. +See docs/dev/orcapod-design.md for the full design specification. ### Core data flow diff --git a/AGENT_COORDINATION.md b/AGENT_COORDINATION.md index adac28dfa..22a3bbe82 100644 --- a/AGENT_COORDINATION.md +++ b/AGENT_COORDINATION.md @@ -49,7 +49,7 @@ recorded. decisions the developer has already made. An issue that needs a design decision is not ready to dispatch until the decision is made, or the spec says to stop and ask. 5. **Check for overlap.** Two workers must not edit the same file region. Where overlap is - unavoidable (`CLAUDE.md`, a shared operator base class, one `design_issues/` entry), + unavoidable (`CLAUDE.md`, a shared operator base class, one `docs/dev/design_issues/` entry), name the overlap in both specs and say who owns the shared part. Sequence the issues instead if the overlap is substantial. 6. **Move the issues to In Progress** in Linear once the developer approves the wave. @@ -104,7 +104,7 @@ developer. - **Decision routing.** Send every design or scope question to the coordinator with the orchestration `ask` command and wait. Never open a local question prompt. Wherever - `CLAUDE.md` says "ask the user" or "wait for user approval" (adding a `design_issues/` + `CLAUDE.md` says "ask the user" or "wait for user approval" (adding a `docs/dev/design_issues/` entry, creating a Linear issue, approving a PR-review revision plan), that means `ask`. If the developer types into the worker's terminal directly, that instruction wins; tell the coordinator with an escalation. diff --git a/CLAUDE.md b/CLAUDE.md index f5adb0c8b..119b5ffbb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,31 +19,32 @@ When adding or changing any instruction, update BOTH: ## Design issues log -`design_issues/` at the project root is the canonical log of known design problems, bugs, and -code quality issues: one file per entry (developer, November 11, 2026; ITL-968). There is no -`DESIGN_ISSUES.md`; never bring it back, and never put two entries in one file. +`docs/dev/design_issues/` is the canonical log of known design problems, bugs, and code +quality issues: one file per entry (developer, November 11, 2026; ITL-968). There is no +`DESIGN_ISSUES.md` and no top-level `design_issues/` (moved in ITL-1169; `--check` refuses both); +never bring either back, and never put two entries in one file. -- An entry is the file `design_issues/<LINEAR-ISSUE-ID>-<ENTRY-ID>.md` (e.g. - `design_issues/ITL-955-GB1.md`). Its first line is the `## <area heading>` it belongs +- An entry is the file `docs/dev/design_issues/<LINEAR-ISSUE-ID>-<ENTRY-ID>.md` (e.g. + `docs/dev/design_issues/ITL-955-GB1.md`). Its first line is the `## <area heading>` it belongs under, then a blank line, `### <ENTRY-ID> — <title>`, the `**Status:**` (`open`, `in progress` or `resolved`), `**Severity:**` and `**Issue:**` lines, a blank line and the body. - Read the log with `uv run python scripts/design_issues.py` (index by area; `--status open` - filters; `--full` prints every entry). Find one entry by id: `ls design_issues/*-GB1.md`. + filters; `--full` prints every entry). Find one entry by id: `ls docs/dev/design_issues/*-GB1.md`. - Check the files with `uv run python scripts/design_issues.py --check` (`tests/test_design_issues.py` runs it in CI). -- `design_issues/README.md` is the full statement of the convention, with the severity +- `docs/dev/design_issues/README.md` is the full statement of the convention, with the severity guide. When fixing a bug or addressing a design problem: -1. Check `design_issues/` first — if a matching entry exists, edit its file: update its +1. Check `docs/dev/design_issues/` first — if a matching entry exists, edit its file: update its status to `in progress` while working and `resolved` once done, adding a brief **Fix:** note. 2. If no matching entry exists, ask the user whether it should be added before proceeding. If yes, add it as a new file (status `open` or `in progress` as appropriate). When discovering a new issue that won't be fixed immediately, ask the user whether it should be -logged in `design_issues/` before adding it. +logged in `docs/dev/design_issues/` before adding it. ## Superpowers artifacts @@ -84,6 +85,9 @@ to refer to names (e.g. ``PollingSource``, ``iter_data``, ``CursorInvalidatedErr ## Documentation samples +`docs/dev/` (the design issues log and the design specification) is developer material, kept +out of the published site (`exclude_docs` in `mkdocs.yml`) and out of the sample test. + Every fenced `python` block in `README.md`, `docs/index.md`, `docs/getting-started.md`, `docs/troubleshooting.md`, `docs/concepts/`, `docs/reference/` and `docs/tutorial/` is executed by `tests/test_docs/test_doc_samples.py`, and `tests/test_docs/test_mkdocs_build.py` runs @@ -575,7 +579,7 @@ tests/ ## Architecture overview -See `orcapod-design.md` at the project root for the full design specification. +See `docs/dev/orcapod-design.md` for the full design specification. ### Core data flow diff --git a/RELEASING.md b/RELEASING.md index f3e5c72a0..b8b1af4be 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -275,5 +275,5 @@ does not block or fail the release (no publish job depends on them). They call Because the Release workflow runs on `nauticalab`, these jobs do not run for a release at all today; completing the Linear release is a manual step until the developer decides otherwise (the issue ITL-1007 notes this "needs more thought"). Setup on `metamorphic-labs`: the -`LINEAR_ACCESS_KEY` repo secret (the key `metamorphic-brain/axon` uses) and a Linear release +`LINEAR_ACCESS_KEY` repo secret (the organisation's Linear access key) and a Linear release configured in the workspace. diff --git a/TESTING_PLAN.md b/TESTING_PLAN.md deleted file mode 100644 index 675f1b88e..000000000 --- a/TESTING_PLAN.md +++ /dev/null @@ -1,678 +0,0 @@ -# Comprehensive Specification-Derived Testing Plan - -## Context - -The orcapod-python codebase has grown complex with many interdependent components. Existing tests were often written by the same agent that implemented the code, risking "self-affirmation" — tests that validate what was built rather than what was specified. This plan creates an independent test suite derived purely from **design documents, protocol definitions, and interface contracts**, organized in a new `test-objective/` root folder. - -## Approach: Specification-First Testing - -Tests are derived from these specification sources (NOT from reading implementation code): -1. `orcapod-design.md` — the canonical design specification -2. Protocol definitions in `src/orcapod/protocols/` — interface contracts -3. Type annotations and docstrings — method signatures and documented behavior -4. `CLAUDE.md` architecture overview — documented invariants and constraints -5. `design_issues/` — known bugs that tests should catch - -## Deliverables - -### 1. `TESTING_PLAN.md` — comprehensive test case catalog at project root -### 2. `test-objective/` — concrete test implementations at project root - ---- - -## File Structure - -``` -test-objective/ -├── conftest.py # Shared fixtures (sources, streams, functions) -├── unit/ -│ ├── __init__.py -│ ├── test_types.py # Schema, ColumnConfig, ContentHash -│ ├── test_datagram.py # Datagram core behavior -│ ├── test_tag.py # Tag (system tags, ColumnConfig filtering) -│ ├── test_data.py # Data (source info, provenance) -│ ├── test_stream.py # ArrowTableStream construction & iteration -│ ├── test_sources.py # All source types + error conditions -│ ├── test_source_registry.py # SourceRegistry CRUD + edge cases -│ ├── test_data_function.py # PythonDataFunction + CachedDataFunction -│ ├── test_function_pod.py # FunctionPod, FunctionPodStream -│ ├── test_operators.py # All operators (Join, MergeJoin, SemiJoin, etc.) -│ ├── test_nodes.py # FunctionNode, OperatorNode, Persistent variants -│ ├── test_hashing.py # SemanticHasher, TypeHandlerRegistry, handlers -│ ├── test_databases.py # InMemory, DeltaLake, NoOp databases -│ ├── test_schema_utils.py # Schema extraction, union, intersection -│ ├── test_arrow_utils.py # Arrow table/schema utilities -│ ├── test_arrow_data_utils.py # System tags, source info, column helpers -│ ├── test_semantic_types.py # UniversalTypeConverter, SemanticTypeRegistry -│ ├── test_contexts.py # DataContext resolution, validation -│ ├── test_tracker.py # BasicTrackerManager, GraphTracker -│ └── test_lazy_module.py # LazyModule deferred import behavior -├── integration/ -│ ├── __init__.py -│ ├── test_pipeline_flows.py # End-to-end pipeline scenarios -│ ├── test_caching_flows.py # DB-backed caching (FunctionNode, OperatorNode) -│ ├── test_hash_invariants.py # Hash stability & Merkle chain properties -│ ├── test_provenance.py # System tag lineage through pipelines -│ └── test_column_config_filtering.py # ColumnConfig behavior across all components -└── property/ - ├── __init__.py - ├── test_schema_properties.py # Hypothesis-based schema algebra - ├── test_hash_properties.py # Hash determinism, collision resistance - └── test_operator_algebra.py # Commutativity, associativity, idempotency -``` - ---- - -## Unit Test Cases by Module - -### 1. `test_types.py` — Schema, ColumnConfig, ContentHash - -**Schema:** -- `test_schema_construction_from_dict` — Schema({"a": int, "b": str}) stores correct fields -- `test_schema_construction_with_kwargs` — Schema(fields, x=int) merges kwargs with precedence -- `test_schema_optional_fields` — optional_fields stored as frozenset, not in required_fields -- `test_schema_required_fields` — required_fields = all fields minus optional_fields -- `test_schema_immutability` — Schema is an immutable Mapping (no __setitem__) -- `test_schema_merge_compatible` — Schema.merge() combines non-conflicting schemas -- `test_schema_merge_type_conflict_raises` — Schema.merge() raises ValueError on type conflicts -- `test_schema_with_values_overrides_silently` — with_values() overrides without errors -- `test_schema_select_existing_fields` — select() returns subset -- `test_schema_select_missing_field_raises` — select() raises KeyError on missing field -- `test_schema_drop_existing_fields` — drop() removes fields -- `test_schema_drop_missing_field_silent` — drop() silently ignores missing fields -- `test_schema_is_compatible_with_superset` — returns True when other is superset -- `test_schema_is_not_compatible_with_subset` — returns False when other is subset -- `test_schema_empty` — Schema.empty() returns zero-field schema -- `test_schema_mapping_interface` — __getitem__, __contains__, __iter__, __len__ work correctly - -**ContentHash:** -- `test_content_hash_immutability` — frozen dataclass, cannot reassign method/digest -- `test_content_hash_to_hex` — to_hex(8) returns 8-char hex string -- `test_content_hash_to_int` — to_int() returns consistent integer -- `test_content_hash_to_uuid` — to_uuid() returns deterministic UUID -- `test_content_hash_to_base64` — to_base64() returns valid base64 -- `test_content_hash_to_string_and_from_string_roundtrip` — from_string(to_string()) == original -- `test_content_hash_display_name` — display_name() returns "method:short_hex" format -- `test_content_hash_equality` — same method+digest are equal -- `test_content_hash_inequality` — different digests are not equal - -**ColumnConfig:** -- `test_column_config_defaults` — all fields False by default -- `test_column_config_all` — ColumnConfig.all() sets everything True -- `test_column_config_data_only` — ColumnConfig.data_only() sets everything False -- `test_column_config_handle_config_dict` — handle_config(dict) normalizes to ColumnConfig -- `test_column_config_handle_config_all_info_override` — all_info=True overrides individual fields -- `test_column_config_frozen` — cannot modify after construction - -### 2. `test_datagram.py` — Datagram - -**Construction:** -- `test_datagram_from_dict` — construct from Python dict -- `test_datagram_from_arrow_table` — construct from pa.Table -- `test_datagram_from_record_batch` — construct from pa.RecordBatch -- `test_datagram_with_meta_info` — meta columns stored separately -- `test_datagram_with_python_schema` — explicit schema used over inference -- `test_datagram_with_record_id` — custom record_id stored as datagram_id - -**Dict-like Access:** -- `test_datagram_getitem_existing_key` — returns correct value -- `test_datagram_getitem_missing_key_raises` — raises KeyError -- `test_datagram_contains` — __contains__ returns True/False correctly -- `test_datagram_iter` — __iter__ yields all data column names -- `test_datagram_get_with_default` — get() returns default for missing keys - -**Lazy Conversion (key invariant):** -- `test_datagram_dict_access_uses_dict_backing` — dict access doesn't trigger Arrow conversion -- `test_datagram_as_table_triggers_arrow_conversion` — as_table() produces Arrow table -- `test_datagram_dict_arrow_roundtrip_preserves_data` — dict→Arrow→dict preserves values -- `test_datagram_arrow_dict_roundtrip_preserves_data` — Arrow→dict→Arrow preserves values - -**Schema Methods:** -- `test_datagram_keys_data_only` — keys() returns only data column names by default -- `test_datagram_keys_all_info` — keys(all_info=True) includes meta columns -- `test_datagram_schema_matches_keys` — schema() field names match keys() -- `test_datagram_arrow_schema_type_consistency` — arrow_schema() types match schema() types - -**Format Conversions:** -- `test_datagram_as_dict` — returns plain Python dict -- `test_datagram_as_table` — returns single-row pa.Table -- `test_datagram_as_arrow_compatible_dict` — values are Arrow-compatible - -**Data Operations (immutability):** -- `test_datagram_select_returns_new_instance` — original unchanged -- `test_datagram_drop_returns_new_instance` — original unchanged -- `test_datagram_rename_returns_new_instance` — original unchanged -- `test_datagram_update_existing_columns_only` — update() only changes existing columns -- `test_datagram_with_columns_new_only` — with_columns() only adds new columns -- `test_datagram_copy_creates_independent_copy` — mutations to copy don't affect original - -**Meta Operations:** -- `test_datagram_get_meta_value_auto_prefixed` — get_meta_value() auto-adds prefix -- `test_datagram_with_meta_columns_returns_new` — immutable update -- `test_datagram_drop_meta_columns_returns_new` — immutable drop - -**Content Hashing:** -- `test_datagram_content_hash_deterministic` — same data → same hash -- `test_datagram_content_hash_changes_with_data` — different data → different hash -- `test_datagram_equality_by_content` — equal content → equal datagrams - -### 3. `test_tag.py` — Tag - -- `test_tag_construction_with_system_tags` — system tags stored separately from data -- `test_tag_system_tags_excluded_from_default_keys` — keys() doesn't show system tags -- `test_tag_system_tags_included_with_column_config` — keys(columns={"system_tags": True}) shows them -- `test_tag_as_dict_excludes_system_tags_by_default` — as_dict() only has data -- `test_tag_as_dict_all_info_includes_system_tags` — as_dict(all_info=True) has everything -- `test_tag_as_table_excludes_system_tags_by_default` -- `test_tag_as_table_all_info_includes_system_tags` -- `test_tag_schema_excludes_system_tags_by_default` -- `test_tag_copy_preserves_system_tags` — copy() includes system tags -- `test_tag_as_datagram_conversion` — as_datagram() returns Datagram (not Tag) -- `test_tag_system_tags_method_returns_copy` — system_tags() returns dict copy, not reference - -### 4. `test_data.py` — Data - -- `test_data_construction_with_source_info` — source_info stored per data column -- `test_data_source_info_excluded_from_default_keys` — keys() doesn't show _source_ columns -- `test_data_source_info_included_with_column_config` — keys(columns={"source": True}) -- `test_data_with_source_info_returns_new` — immutable update -- `test_data_rename_updates_source_info_keys` — rename() also renames source_info keys -- `test_data_with_columns_adds_source_info_entry` — new columns get source_info=None -- `test_data_as_datagram_conversion` — as_datagram() returns Datagram -- `test_data_as_dict_excludes_source_columns_by_default` -- `test_data_as_dict_all_info_includes_source_columns` -- `test_data_copy_preserves_source_info` - -### 5. `test_stream.py` — ArrowTableStream - -**Construction:** -- `test_stream_from_table_with_tag_columns` — tag/data column separation -- `test_stream_requires_at_least_one_data_column` — ValueError if no data columns -- `test_stream_with_system_tag_columns` — system tag columns tracked -- `test_stream_with_source_info` — source info attached to data columns -- `test_stream_with_producer` — producer property set -- `test_stream_with_upstreams` — upstreams tuple set - -**Schema & Keys:** -- `test_stream_keys_returns_tag_and_data_keys` — tuple of (tag_keys, data_keys) -- `test_stream_output_schema_returns_two_schemas` — (tag_schema, data_schema) -- `test_stream_schema_matches_actual_data` — output_schema() types match as_table() types -- `test_stream_keys_with_column_config` — ColumnConfig filtering works - -**Iteration:** -- `test_stream_iter_data_yields_tag_data_pairs` — each yield is (Tag, Data) -- `test_stream_iter_data_count_matches_rows` — number of yields = number of rows -- `test_stream_iter_data_tag_keys_correct` — tag column names match -- `test_stream_iter_data_data_keys_correct` — data column names match -- `test_stream_as_table_matches_iter_data` — table materialization consistent with iteration - -**Immutability:** -- `test_stream_immutable` — no mutation methods available - -**Format Conversions:** -- `test_stream_as_polars_df` — converts to Polars DataFrame -- `test_stream_as_pandas_df` — converts to Pandas DataFrame -- `test_stream_as_lazy_frame` — converts to Polars LazyFrame - -### 6. `test_sources.py` — All Source Types - -**ArrowTableSource:** -- `test_arrow_source_from_valid_table` — normal construction succeeds -- `test_arrow_source_empty_table_raises` — ValueError("Table is empty") -- `test_arrow_source_missing_tag_column_raises` — ValueError if tag_columns not in table -- `test_arrow_source_adds_system_tag_column` — system tag column added automatically -- `test_arrow_source_adds_source_info_columns` — _source_ columns added -- `test_arrow_source_source_id_set` — source_id property populated -- `test_arrow_source_producer_is_none` — root sources have no producer -- `test_arrow_source_upstreams_empty` — root sources have no upstreams -- `test_arrow_source_pipeline_identity_structure` — returns (tag_schema, data_schema) -- `test_arrow_source_iter_data_yields_correct_pairs` -- `test_arrow_source_as_table_has_all_columns` - -**DictSource:** -- `test_dict_source_from_dict_of_lists` — constructs correctly -- `test_dict_source_delegates_to_arrow_table_source` — same behavior as ArrowTableSource -- `test_dict_source_with_tag_columns` - -**ListSource:** -- `test_list_source_from_list_of_dicts` — constructs correctly -- `test_list_source_empty_list_raises` — ValueError - -**CSVSource:** -- `test_csv_source_from_file` — reads CSV correctly -- `test_csv_source_with_tag_columns` - -**DataFrameSource:** -- `test_dataframe_source_from_polars` — constructs from Polars DataFrame -- `test_dataframe_source_from_pandas` — constructs from Pandas DataFrame - -**DerivedSource:** -- `test_derived_source_before_run_raises` — ValueError before upstream has computed -- `test_derived_source_after_run_yields_records` — produces records from upstream node - -### 7. `test_source_registry.py` — SourceRegistry - -- `test_registry_register_and_get` — register then retrieve -- `test_registry_register_empty_id_raises` — ValueError -- `test_registry_register_none_source_raises` — ValueError -- `test_registry_register_same_object_idempotent` — re-register same object is no-op -- `test_registry_register_different_object_same_id_keeps_existing` — warns, keeps existing -- `test_registry_replace_overwrites` — replace() unconditionally overwrites -- `test_registry_replace_returns_old` — returns previous source -- `test_registry_unregister_removes` — removes and returns source -- `test_registry_unregister_missing_raises` — KeyError -- `test_registry_get_missing_raises` — KeyError -- `test_registry_get_optional_missing_returns_none` — returns None -- `test_registry_contains` — __contains__ works -- `test_registry_len` — __len__ works -- `test_registry_iter` — __iter__ yields IDs -- `test_registry_clear` — removes all entries -- `test_registry_list_ids` — returns list of registered IDs - -### 8. `test_data_function.py` — PythonDataFunction, CachedDataFunction - -**PythonDataFunction:** -- `test_pf_from_simple_function` — wraps a function with explicit output_keys -- `test_pf_infers_input_schema_from_signature` — type annotations → input_data_schema -- `test_pf_infers_output_schema` — output type annotations or output_keys → output_data_schema -- `test_pf_rejects_variadic_parameters` — *args, **kwargs raise ValueError -- `test_pf_call_transforms_data` — call() applies function to data data -- `test_pf_call_returns_none_if_function_returns_none` — None propagates -- `test_pf_direct_call_bypasses_executor` — direct_call() ignores executor -- `test_pf_call_routes_through_executor` — call() uses executor when set -- `test_pf_version_parsing` — "v1.2" → major_version=1, minor_version_string="2" -- `test_pf_canonical_function_name` — uses function.__name__ or explicit name -- `test_pf_content_hash_deterministic` — same function → same hash -- `test_pf_content_hash_changes_with_function` — different function → different hash -- `test_pf_pipeline_hash_ignores_data` — pipeline_hash based on schema only - -**CachedDataFunction:** -- `test_cached_pf_cache_miss_computes_and_stores` — first call computes + records -- `test_cached_pf_cache_hit_returns_stored` — second call returns cached result -- `test_cached_pf_skip_cache_lookup_always_computes` — skip_cache_lookup=True forces compute -- `test_cached_pf_skip_cache_insert_doesnt_store` — skip_cache_insert=True skips recording -- `test_cached_pf_get_all_cached_outputs` — returns all stored records as table -- `test_cached_pf_record_path_based_on_function_hash` — record path includes function identity - -### 9. `test_function_pod.py` — FunctionPod, FunctionPodStream - -**FunctionPod:** -- `test_function_pod_process_returns_stream` — process() returns FunctionPodStream -- `test_function_pod_validate_inputs_single_stream` — accepts exactly one stream -- `test_function_pod_validate_inputs_multiple_raises` — rejects multiple streams -- `test_function_pod_output_schema_prediction` — output_schema() matches actual output -- `test_function_pod_callable_alias` — __call__ same as process() -- `test_function_pod_never_modifies_tags` — tags pass through unchanged -- `test_function_pod_transforms_data` — data are transformed by function - -**FunctionPodStream:** -- `test_fps_lazy_evaluation` — iter_data() triggers computation -- `test_fps_producer_is_function_pod` — producer property returns the pod -- `test_fps_upstreams_contains_input_stream` -- `test_fps_keys_matches_pod_output_schema` — keys() consistent with pod.output_schema() -- `test_fps_as_table_materialization` — as_table() returns correct table -- `test_fps_clear_cache_forces_recompute` — clear_cache() resets cached state - -**Decorator:** -- `test_function_pod_decorator_creates_pod_attribute` — @function_pod adds .pod -- `test_function_pod_decorator_with_result_database` — wraps in CachedDataFunction - -### 10. `test_operators.py` — All Operators - -**Join (N-ary, commutative):** -- `test_join_two_streams_on_common_tags` — inner join on shared tag columns -- `test_join_non_overlapping_data_columns_required` — InputValidationError on collision -- `test_join_commutative` — join(A, B) == join(B, A) (same rows regardless of order) -- `test_join_three_or_more_streams` — N-ary join works -- `test_join_empty_result_when_no_matches` — disjoint tags → empty stream -- `test_join_system_tag_name_extending` — system tag columns get ::pipeline_hash:position suffix -- `test_join_system_tag_values_sorted_for_commutativity` — canonical ordering of tag values -- `test_join_output_schema_prediction` — output_schema() matches actual output - -**MergeJoin (binary):** -- `test_merge_join_colliding_columns_become_sorted_lists` — same-name data cols → list[T] -- `test_merge_join_requires_identical_types` — different types raise error -- `test_merge_join_non_colliding_columns_pass_through` — unmatched columns kept as-is -- `test_merge_join_system_tag_name_extending` -- `test_merge_join_output_schema_prediction` — predicts list[T] types correctly - -**SemiJoin (binary, non-commutative):** -- `test_semijoin_filters_left_by_right_tags` — keeps left rows matching right tags -- `test_semijoin_non_commutative` — semijoin(A, B) != semijoin(B, A) in general -- `test_semijoin_preserves_left_data_columns` — right data columns dropped -- `test_semijoin_system_tag_name_extending` - -**Batch:** -- `test_batch_groups_rows` — groups rows by tag, aggregates data -- `test_batch_types_become_lists` — data column types become list[T] -- `test_batch_system_tag_type_evolving` — system tag type becomes list[str] -- `test_batch_with_batch_size` — batch_size limits group size -- `test_batch_drop_partial_batch` — drop_partial_batch=True drops incomplete groups -- `test_batch_output_schema_prediction` — predicts list[T] types - -**Column Selection (Select/Drop Tag/Data):** -- `test_select_tag_columns` — keeps only specified tag columns -- `test_select_tag_columns_strict_missing_raises` — strict=True raises on missing column -- `test_select_data_columns` — keeps only specified data columns -- `test_drop_tag_columns` — removes specified tag columns -- `test_drop_data_columns` — removes specified data columns -- `test_column_selection_system_tag_name_preserving` — system tags unchanged - -**MapTags/MapData:** -- `test_map_tags_renames_tag_columns` — renames specified tag columns -- `test_map_tags_drop_unmapped` — drop_unmapped=True removes unrenamed columns -- `test_map_data_renames_data_columns` -- `test_map_preserves_system_tags` — system tag columns unchanged (name-preserving) - -**PolarsFilter:** -- `test_polars_filter_with_predicate` — filters rows matching predicate -- `test_polars_filter_with_constraints` — filters by column=value constraints -- `test_polars_filter_preserves_schema` — output schema same as input -- `test_polars_filter_system_tag_name_preserving` - -**Operator Base Classes:** -- `test_unary_operator_rejects_multiple_inputs` — validate_inputs raises for >1 stream -- `test_binary_operator_rejects_wrong_count` — validate_inputs raises for !=2 streams -- `test_nonzero_input_operator_rejects_zero` — validate_inputs raises for 0 streams - -### 11. `test_nodes.py` — FunctionNode, OperatorNode, Persistent variants - -**FunctionNode:** -- `test_function_node_iter_data` — iterates and transforms all data -- `test_function_node_process_data` — transforms single (tag, data) pair -- `test_function_node_producer_is_function_pod` -- `test_function_node_upstreams` -- `test_function_node_clear_cache` - -**PersistentFunctionNode:** -- `test_persistent_fn_two_phase_iteration` — Phase 1: cached records, Phase 2: compute missing -- `test_persistent_fn_pipeline_path_uses_pipeline_hash` — path includes pipeline_hash -- `test_persistent_fn_caches_computed_results` — computed results stored in DB -- `test_persistent_fn_skips_already_cached` — Phase 2 skips inputs with cached outputs -- `test_persistent_fn_run_eagerly_processes_all` — run() processes all data -- `test_persistent_fn_as_source_returns_derived_source` — as_source() returns DerivedSource - -**OperatorNode:** -- `test_operator_node_delegates_to_operator` -- `test_operator_node_clear_cache` -- `test_operator_node_run` - -**PersistentOperatorNode:** -- `test_persistent_on_cache_mode_off` — always recomputes -- `test_persistent_on_cache_mode_log` — computes and stores -- `test_persistent_on_cache_mode_replay` — loads from DB, no recompute -- `test_persistent_on_as_source_returns_derived_source` - -### 12. `test_hashing.py` — SemanticHasher, TypeHandlerRegistry - -**BaseSemanticHasher:** -- `test_hasher_primitives` — int, str, float, bool, None hashed deterministically -- `test_hasher_structures` — list, dict, tuple, set expanded structurally -- `test_hasher_content_hash_terminal` — ContentHash inputs returned as-is -- `test_hasher_content_identifiable_uses_identity_structure` — resolves via identity_structure() -- `test_hasher_unknown_type_strict_raises` — TypeError in strict mode -- `test_hasher_deterministic` — same input → same hash always -- `test_hasher_different_inputs_different_hashes` — collision resistance -- `test_hasher_nested_structures` — deeply nested dicts/lists hashed correctly - -**TypeHandlerRegistry:** -- `test_registry_register_and_lookup` — register handler, get_handler returns it -- `test_registry_mro_aware_lookup` — subclass falls back to parent handler -- `test_registry_unregister` — remove handler -- `test_registry_has_handler` — boolean check -- `test_registry_registered_types` — list all registered types -- `test_registry_thread_safety` — concurrent register/lookup doesn't crash - -**Built-in Handlers:** -- `test_path_handler_hashes_file_content` — Path → file content hash -- `test_path_handler_missing_file_raises` — FileNotFoundError -- `test_uuid_handler` — UUID → canonical string -- `test_bytes_handler` — bytes → hex string -- `test_function_handler` — function → signature-based identity -- `test_type_object_handler` — type → "type:module.qualname" -- `test_arrow_table_handler` — pa.Table → content hash - -### 13. `test_databases.py` — InMemory, DeltaLake, NoOp - -**InMemoryArrowDatabase:** -- `test_inmemory_add_and_get_record` — add_record + get_record_by_id roundtrip -- `test_inmemory_add_records_batch` — add_records with multiple rows -- `test_inmemory_get_all_records` — returns all at path -- `test_inmemory_get_records_by_ids` — returns subset by IDs -- `test_inmemory_skip_duplicates` — skip_duplicates=True doesn't raise -- `test_inmemory_pending_batch_semantics` — records not visible before flush() -- `test_inmemory_flush_makes_visible` — flush() commits pending records -- `test_inmemory_invalid_path_raises` — ValueError for empty/invalid paths -- `test_inmemory_get_nonexistent_returns_none` — missing path → None - -**NoOpArrowDatabase:** -- `test_noop_all_writes_silently_discarded` — add_record/add_records don't error -- `test_noop_all_reads_return_none` — get_* always returns None -- `test_noop_flush_noop` — flush() doesn't error - -**DeltaTableDatabase (if available):** -- `test_delta_add_and_get_record` — persistence roundtrip -- `test_delta_flush_writes_to_disk` — data survives flush -- `test_delta_path_validation` — invalid paths rejected - -### 14. `test_schema_utils.py` — Schema Utilities - -- `test_extract_function_schemas_from_annotations` — infers schemas from type hints -- `test_extract_function_schemas_rejects_variadic` — ValueError for *args/**kwargs -- `test_verify_data_schema_valid` — matching dict passes -- `test_verify_data_schema_type_mismatch` — mismatched types fail -- `test_check_schema_compatibility` — compatible types pass -- `test_infer_schema_from_dict` — infers types from values -- `test_union_schemas_no_conflict` — merges cleanly -- `test_union_schemas_with_conflict_raises` — TypeError on conflicting types -- `test_intersection_schemas` — returns common fields -- `test_get_compatible_type_int_float` — numeric promotion -- `test_get_compatible_type_incompatible_raises` — TypeError - -### 15. `test_arrow_utils.py` — Arrow Utilities - -- `test_schema_select` — selects subset of arrow schema columns -- `test_schema_select_missing_raises` — KeyError for missing columns -- `test_schema_drop` — drops specified columns -- `test_normalize_to_large_types` — string → large_string, etc. -- `test_pylist_to_pydict` — row-oriented → column-oriented -- `test_pydict_to_pylist` — column-oriented → row-oriented -- `test_pydict_to_pylist_inconsistent_lengths_raises` — ValueError -- `test_hstack_tables` — horizontal concatenation -- `test_hstack_tables_different_row_counts_raises` — ValueError -- `test_hstack_tables_duplicate_columns_raises` — ValueError -- `test_check_arrow_schema_compatibility` — compatible schemas pass -- `test_split_by_column_groups` — splits table into multiple tables - -### 16. `test_arrow_data_utils.py` — System Tags & Source Info - -- `test_add_system_tag_columns` — adds _tag:: prefixed columns -- `test_add_system_tag_columns_empty_table_raises` — ValueError -- `test_add_system_tag_columns_length_mismatch_raises` — ValueError -- `test_append_to_system_tags` — extends existing system tag values -- `test_sort_system_tag_values` — canonical sorting for commutativity -- `test_add_source_info` — adds _source_ prefixed columns -- `test_drop_columns_with_prefix` — removes columns matching prefix -- `test_drop_system_columns` — removes __ and __ prefixed columns - -### 17. `test_semantic_types.py` — UniversalTypeConverter - -- `test_python_to_arrow_type_primitives` — int→int64, str→large_string, etc. -- `test_python_to_arrow_type_list` — list[int]→large_list(int64) -- `test_python_to_arrow_type_dict` — dict→struct -- `test_arrow_to_python_type_roundtrip` — python→arrow→python recovers original -- `test_python_dicts_to_arrow_table` — list of dicts → pa.Table -- `test_arrow_table_to_python_dicts` — pa.Table → list of dicts -- `test_schema_conversion_roundtrip` — Schema→pa.Schema→Schema preserves types - -### 18. `test_contexts.py` — DataContext - -- `test_resolve_context_none_returns_default` — None → default context -- `test_resolve_context_string_version` — "v0.1" → matching context -- `test_resolve_context_datacontext_passthrough` — DataContext returned as-is -- `test_resolve_context_invalid_raises` — ContextResolutionError -- `test_get_available_contexts` — returns sorted version list -- `test_default_context_has_all_components` — type_converter, arrow_hasher, semantic_hasher present - -### 19. `test_tracker.py` — BasicTrackerManager, GraphTracker - -- `test_tracker_manager_register_deregister` — add/remove trackers -- `test_tracker_manager_broadcasts_invocations` — records sent to all active trackers -- `test_tracker_manager_no_tracking_context` — no_tracking() suspends recording -- `test_graph_tracker_records_function_pod_invocation` — node added to graph -- `test_graph_tracker_records_operator_invocation` — node added to graph -- `test_graph_tracker_compile_builds_graph` — compile() produces nx.DiGraph -- `test_graph_tracker_reset_clears_state` - -### 20. `test_lazy_module.py` — LazyModule - -- `test_lazy_module_not_loaded_initially` — is_loaded is False -- `test_lazy_module_loads_on_attribute_access` — accessing attr triggers import -- `test_lazy_module_force_load` — force_load() triggers immediate import -- `test_lazy_module_invalid_module_raises` — ModuleNotFoundError - ---- - -## Integration Test Cases - -### `test_pipeline_flows.py` — End-to-End Pipeline Scenarios - -- `test_source_to_stream_to_single_operator` — Source → Filter → Stream -- `test_source_to_function_pod` — Source → FunctionPod → Stream with transformed data -- `test_multi_source_join` — Two sources → Join → Stream with combined data -- `test_chained_operators` — Source → Filter → Select → MapTags → Stream -- `test_function_pod_then_operator` — Source → FunctionPod → Filter → Stream -- `test_join_then_batch` — Two sources → Join → Batch → Stream -- `test_semijoin_filters_correctly` — Source A semi-joined with Source B -- `test_merge_join_combines_columns` — Two sources with overlapping columns → MergeJoin -- `test_diamond_pipeline` — Source → [branch A, branch B] → Join → Stream -- `test_pipeline_with_multiple_function_pods` — Source → FunctionPod1 → FunctionPod2 - -### `test_caching_flows.py` — DB-Backed Caching Scenarios - -- `test_persistent_function_node_caches_and_replays` — first run computes, second replays -- `test_persistent_function_node_incremental_update` — new input rows only compute missing -- `test_persistent_operator_node_log_mode` — CacheMode.LOG stores results -- `test_persistent_operator_node_replay_mode` — CacheMode.REPLAY loads from DB -- `test_derived_source_reingestion` — PersistentFunctionNode → DerivedSource → further pipeline -- `test_cached_data_function_with_inmemory_db` — end-to-end caching flow - -### `test_hash_invariants.py` — Hash Stability & Merkle Chain Properties - -- `test_content_hash_stability_same_data` — identical data → identical hash across runs -- `test_content_hash_changes_with_data` — different data → different hash -- `test_pipeline_hash_ignores_data_content` — same schema, different data → same pipeline_hash -- `test_pipeline_hash_changes_with_schema` — different schema → different pipeline_hash -- `test_pipeline_hash_merkle_chain` — downstream hash commits to upstream hashes -- `test_commutative_join_pipeline_hash_order_independent` — join(A,B) pipeline_hash == join(B,A) -- `test_non_commutative_semijoin_pipeline_hash_order_dependent` — semijoin(A,B) != semijoin(B,A) - -### `test_provenance.py` — System Tag Lineage Tracking - -- `test_source_creates_system_tag_column` — source adds _tag::source:hash column -- `test_unary_operator_preserves_system_tags` — filter/select/map: name+value unchanged -- `test_join_extends_system_tag_names` — multi-input: column names get ::hash:pos suffix -- `test_join_sorts_system_tag_values` — commutative ops sort tag values -- `test_batch_evolves_system_tag_type` — batch: str → list[str] -- `test_full_pipeline_provenance_chain` — source → join → filter → batch: all rules applied - -### `test_column_config_filtering.py` — ColumnConfig Across All Components - -- `test_datagram_column_config_meta` — meta=True includes __ columns -- `test_datagram_column_config_data_only` — all False = data columns only -- `test_tag_column_config_system_tags` — system_tags=True includes _tag:: columns -- `test_data_column_config_source` — source=True includes _source_ columns -- `test_stream_column_config_all_info` — all_info=True on keys/output_schema/as_table -- `test_stream_column_config_consistency` — keys(), output_schema(), as_table() all respect same config - ---- - -## Property-Based & Advanced Testing (test-objective/property/) - -### `test_schema_properties.py` (using Hypothesis) -- `test_schema_merge_commutative` — merge(A,B) == merge(B,A) when compatible -- `test_schema_select_then_drop_complementary` — select(X) ∪ drop(X) == original -- `test_schema_is_compatible_reflexive` — A.is_compatible_with(A) always True -- `test_schema_optional_fields_subset_of_all_fields` - -### `test_hash_properties.py` (using Hypothesis) -- `test_hash_deterministic` — hash(X) == hash(X) for any X -- `test_hash_changes_with_any_field_mutation` — mutate one value → different hash -- `test_content_hash_string_roundtrip` — from_string(to_string(h)) == h for any h - -### `test_operator_algebra.py` -- `test_join_commutativity` — join(A,B) data == join(B,A) data -- `test_join_associativity` — join(join(A,B),C) data == join(A,join(B,C)) data -- `test_filter_idempotency` — filter(filter(S, P), P) == filter(S, P) -- `test_select_then_select_is_intersection` — select(select(S, X), Y) == select(S, X∩Y) -- `test_drop_then_drop_is_union` — drop(drop(S, X), Y) == drop(S, X∪Y) - ---- - -## Suggestions for More Objective Testing - -### Included in `test-objective/property/`: -1. **Property-based testing** (Hypothesis) — generate random schemas, data, operations and verify algebraic invariants hold -2. **Algebraic property testing** — verify mathematical properties (commutativity of join, idempotency of filter, etc.) - -### Recommended additions (not implemented in this PR, but suggested): -3. **Mutation testing** with `mutmut` — run `uv run mutmut run --paths-to-mutate=src/orcapod/ --tests-dir=test-objective/` to verify tests catch code mutations. A surviving mutant indicates a test gap -4. **Metamorphic testing** — "if I add a row to source A that matches source B's tags, the join output should have one more row" — tests relationships between inputs/outputs without knowing exact expected values -5. **Protocol conformance automation** — use `runtime_checkable` protocols and `isinstance` checks to verify every concrete class satisfies its protocol at import time -6. **Specification oracle** — for each documented behavior in `orcapod-design.md`, create a test that constructs the exact scenario described and verifies the documented outcome -7. **Fuzz testing** — feed malformed inputs (wrong types, extreme sizes, Unicode edge cases) to constructors and verify graceful error handling - ---- - -## Implementation Order - -1. **`conftest.py`** — shared fixtures (reusable sources, streams, data functions, databases) -2. **`unit/test_types.py`** — foundational types (Schema, ContentHash, ColumnConfig) -3. **`unit/test_datagram.py`**, **`test_tag.py`**, **`test_data.py`** — data containers -4. **`unit/test_stream.py`** — stream construction and iteration -5. **`unit/test_sources.py`** + **`test_source_registry.py`** — all source types -6. **`unit/test_hashing.py`** — semantic hasher and handlers -7. **`unit/test_schema_utils.py`** + **`test_arrow_utils.py`** + **`test_arrow_data_utils.py`** — utilities -8. **`unit/test_semantic_types.py`** + **`test_contexts.py`** — type conversion and contexts -9. **`unit/test_databases.py`** — database implementations -10. **`unit/test_data_function.py`** — data function behavior -11. **`unit/test_function_pod.py`** — function pod and streams -12. **`unit/test_operators.py`** — all operators -13. **`unit/test_nodes.py`** — function/operator nodes -14. **`unit/test_tracker.py`** + **`test_lazy_module.py`** — remaining units -15. **`integration/`** — all integration test files -16. **`property/`** — property-based tests - -## Dependencies - -- **hypothesis** — added as a test dependency for property-based testing in `test-objective/property/` -- **pytest** — test runner (already present) -- DeltaTableDatabase tests marked with `@pytest.mark.slow` (skip with `-m "not slow"`) - -## Verification - -Run the full test suite with: -```bash -uv run pytest test-objective/ -v -``` - -Run only unit tests: -```bash -uv run pytest test-objective/unit/ -v -``` - -Run only integration tests: -```bash -uv run pytest test-objective/integration/ -v -``` - -Run only property tests: -```bash -uv run pytest test-objective/property/ -v -``` - -## Key Files to Modify/Create - -- **New:** `TESTING_PLAN.md` (project root) — the test case catalog document (content mirrors this plan) -- **New:** `test-objective/` directory tree — all files listed in the structure above -- **No modifications** to any existing source code or tests diff --git a/bench/bench_file_hasher_cache.py b/bench/bench_file_hasher_cache.py deleted file mode 100644 index e81077ced..000000000 --- a/bench/bench_file_hasher_cache.py +++ /dev/null @@ -1,81 +0,0 @@ -#!/usr/bin/env python -"""Benchmark: cached vs uncached file hashing. - -Creates a ≥100 MB temp file, then times three scenarios: - 1. Uncached hash (baseline) - 2. First cached hash (miss — hash computed + stored) - 3. Second cached hash (hit — lookup only, should be sub-millisecond) - -Run: uv run python bench/bench_file_hasher_cache.py -""" - -import tempfile -import time -from pathlib import Path - -from orcapod.hashing.file_hashers import CachedFileHasher, FileHasher -from orcapod.hashing.hash_cachers import SqliteHashCacher - -FILE_SIZE_MB = 100 -ITERATIONS = 3 - - -def create_large_file(path: Path, size_mb: int) -> None: - chunk = b"\x00" * (1024 * 1024) - with open(path, "wb") as f: - for _ in range(size_mb): - f.write(chunk) - - -def time_call(fn, *args) -> tuple[object, float]: - t0 = time.perf_counter() - result = fn(*args) - elapsed = time.perf_counter() - t0 - return result, elapsed - - -def main() -> None: - with tempfile.TemporaryDirectory() as tmpdir: - tmp = Path(tmpdir) - large_file = tmp / "bench_input.bin" - db_path = tmp / "bench_cache.db" - - print(f"Creating {FILE_SIZE_MB} MB temp file...") - create_large_file(large_file, FILE_SIZE_MB) - - base_hasher = FileHasher(algorithm="sha256") - - # --- Uncached baseline --- - _, uncached_time = time_call(base_hasher.hash_file, large_file) - - # --- Cached: miss --- - cached_hasher = CachedFileHasher( - file_hasher=base_hasher, - cacher=SqliteHashCacher(db_path), - ) - _, miss_time = time_call(cached_hasher.hash_file, large_file) - - # --- Cached: hit (multiple times) --- - hit_times = [] - for _ in range(ITERATIONS): - _, t = time_call(cached_hasher.hash_file, large_file) - hit_times.append(t) - avg_hit = sum(hit_times) / len(hit_times) - - print() - print(f"{'Scenario':<30} {'Time (ms)':>12}") - print("-" * 44) - print(f"{'Uncached (baseline)':<30} {uncached_time * 1000:>12.2f}") - print(f"{'Cached miss (1st call)':<30} {miss_time * 1000:>12.2f}") - print(f"{'Cached hit (avg of 3)':<30} {avg_hit * 1000:>12.3f}") - print() - speedup = uncached_time / avg_hit if avg_hit > 0 else float("inf") - print(f"Cache hit speedup: {speedup:.0f}x") - if avg_hit < 0.001: - print("✓ Sub-millisecond cache hit achieved") - else: - print(f"! Cache hit is {avg_hit * 1000:.2f} ms — expected < 1 ms") - - -if __name__ == "__main__": - main() diff --git a/design/async-execution-implementation-plan.md b/design/async-execution-implementation-plan.md deleted file mode 100644 index 6b6dba235..000000000 --- a/design/async-execution-implementation-plan.md +++ /dev/null @@ -1,331 +0,0 @@ -# Async Execution System — Implementation Plan - -**Design doc:** `design/async-execution-system.md` - ---- - -## Phase 1: Foundation (Channels, Protocols, Config) - -No existing code is modified. All new files. - -### Step 1.1 — Channel primitives - -**New file:** `src/orcapod/core/execution/channels.py` - -- `Channel[T]` — bounded async queue with close/done signaling -- `ReadableChannel[T]` — consumer side: `receive()`, `__aiter__`, `collect()` -- `WritableChannel[T]` — producer side: `send()`, `close()` -- `BroadcastChannel[T]` — fan-out: one writer, multiple independent readers -- `ChannelClosed` exception -- `create_channel(buffer_size: int) -> Channel` - -**Tests:** `tests/test_core/test_execution/test_channels.py` -- Single producer / single consumer -- Backpressure (full buffer blocks send) -- Close semantics (receive after close drains then raises) -- Broadcast (multiple readers get all items) -- Cancellation safety - -### Step 1.2 — Async execution protocol - -**New file:** `src/orcapod/protocols/core_protocols/async_execution.py` - -- `AsyncExecutableProtocol` — single `async_execute(inputs, output)` method -- `NodeConfigProtocol` — `max_concurrency` property - -**Modify:** `src/orcapod/protocols/core_protocols/__init__.py` -- Export new protocol - -### Step 1.3 — Configuration types - -**New file:** `src/orcapod/core/execution/config.py` - -- `ExecutorType` enum: `SYNCHRONOUS`, `ASYNC_CHANNELS` -- `PipelineConfig` frozen dataclass: `executor`, `channel_buffer_size`, `default_max_concurrency` -- `NodeConfig` frozen dataclass: `max_concurrency` -- `resolve_concurrency(node_config, pipeline_config) -> int | None` - -**Tests:** `tests/test_core/test_execution/test_config.py` -- NodeConfig overrides PipelineConfig default -- None means unlimited - -### Step 1.4 — Execution module init - -**New file:** `src/orcapod/core/execution/__init__.py` - -- Re-export public API: `Channel`, `ReadableChannel`, `WritableChannel`, - `PipelineConfig`, `NodeConfig`, `ExecutorType` - ---- - -## Phase 2: Default `async_execute` on Base Classes - -Add default barrier-mode `async_execute` to every base class. No behavioral change to existing -sync execution — this just makes every node async-capable. - -### Step 2.1 — Helper: materialize rows to stream - -**New file:** `src/orcapod/core/execution/materialization.py` - -- `materialize_to_stream(rows: list[tuple[TagProtocol, DataProtocol]]) -> ArrowTableStream` - — converts a list of (tag, data) pairs back into an ArrowTableStream -- `stream_to_rows(stream: StreamProtocol) -> list[tuple[TagProtocol, DataProtocol]]` - — the inverse (thin wrapper around `iter_data`) - -**Tests:** `tests/test_core/test_execution/test_materialization.py` -- Round-trip: stream → rows → stream preserves schema and data -- Empty stream round-trip - -### Step 2.2 — Default `async_execute` on `StaticOutputPod` - -**Modify:** `src/orcapod/core/static_output_pod.py` - -- Add `async_execute(self, inputs, output)` method to `StaticOutputPod`: - - Collects all input channels - - Materializes to streams - - Calls `self.static_process(*streams)` - - Emits results to output channel - - Closes output - -This gives ALL operators (Unary, Binary, NonZeroInput) a working async_execute by default. - -**Tests:** `tests/test_core/test_execution/test_barrier_default.py` -- Run a unary operator (e.g., Batch) through async_execute, compare output to static_process -- Run a binary operator (e.g., MergeJoin) through async_execute -- Run a multi-input operator (e.g., Join) through async_execute -- All should produce identical results to sync mode - -### Step 2.3 — `async_execute` on `_FunctionPodBase` - -**Modify:** `src/orcapod/core/function_pod.py` - -- Add `async_execute` to `_FunctionPodBase` (barrier mode by default) -- Add `async_execute` to `FunctionPod` (streaming mode with semaphore) -- Add `async_execute` to `FunctionNode` (streaming with cache check + semaphore) -- Add `node_config` property (defaults to `NodeConfig()`) - -**Tests:** `tests/test_core/test_execution/test_function_pod_async.py` -- FunctionPod streaming produces same results as sync -- FunctionNode with cache hits emits without semaphore -- max_concurrency=1 preserves ordering -- max_concurrency=N allows N concurrent invocations - -### Step 2.4 — `async_execute` on source nodes - -**Modify:** `src/orcapod/core/tracker.py` (SourceNode) - -- Add `async_execute` to `SourceNode`: iterates `self.stream.iter_data()`, sends to output -- No input channels consumed - -**Tests:** `tests/test_core/test_execution/test_source_async.py` -- Source pushes all rows to output channel -- Empty source closes immediately - ---- - -## Phase 3: Orchestrator - -### Step 3.1 — DAG compilation for async execution - -**New file:** `src/orcapod/core/execution/dag.py` - -- `CompiledDAG` — nodes, edges, topological order, terminal node -- `compile_for_async(tracker: GraphTracker) -> CompiledDAG` - — takes an existing compiled GraphTracker and produces the async DAG structure - — identifies fan-out points (node output feeds multiple downstreams) for broadcast channels - -**Tests:** `tests/test_core/test_execution/test_dag.py` -- Linear pipeline: Source → Op → FunctionPod -- Diamond: Source → [Op1, Op2] → Join -- Fan-out detection - -### Step 3.2 — Async pipeline orchestrator - -**New file:** `src/orcapod/core/execution/orchestrator.py` - -- `AsyncPipelineOrchestrator` - - `run(graph, config) -> StreamProtocol` — entry point, calls `asyncio.run` - - `_run_async(graph, config)` — creates channels, launches tasks, collects result - - Error propagation via TaskGroup - - Timeout support (optional) - -**Tests:** `tests/test_core/test_execution/test_orchestrator.py` -- End-to-end: Source → Filter → FunctionPod via async orchestrator -- End-to-end: two Sources → Join → Map via async orchestrator -- Compare results to synchronous execution -- Error in one node cancels all others -- Backpressure: slow consumer throttles producer - ---- - -## Phase 4: Streaming Overrides for Concrete Operators - -Each step is independent — can be done in any order or in parallel. - -### Step 4.1 — Streaming column selection operators - -**Modify:** `src/orcapod/core/operators/column_selection.py` - -- Override `async_execute` on `SelectTagColumns`, `SelectDataColumns`, - `DropTagColumns`, `DropDataColumns` -- Each: iterate input, project/drop columns per row, emit - -**Tests:** `tests/test_core/test_execution/test_streaming_operators.py` -- Compare streaming async output to sync output for each operator -- Verify row-by-row emission (no buffering) - -### Step 4.2 — Streaming mappers - -**Modify:** `src/orcapod/core/operators/mappers.py` - -- Override `async_execute` on `MapTags`, `MapData` -- Each: iterate input, rename columns per row, emit - -**Tests:** added to `test_streaming_operators.py` - -### Step 4.3 — Streaming filter - -**Modify:** `src/orcapod/core/operators/filters.py` - -- Override `async_execute` on `PolarsFilter` -- Evaluate predicate per row, emit if passes - -**Tests:** added to `test_streaming_operators.py` - -### Step 4.4 — Incremental Join - -**Modify:** `src/orcapod/core/operators/join.py` - -- Override `async_execute` with symmetric hash join -- Concurrent consumption of all inputs via TaskGroup -- Per-row index probing and immediate emission -- System tag extension logic (reuse existing `_extend_system_tag_columns` logic) - -**Tests:** `tests/test_core/test_execution/test_incremental_join.py` -- Same result set as sync join (order may differ, compare as sets) -- Interleaved arrival from multiple inputs -- Single-input join (degenerates to pass-through) - -### Step 4.5 — Incremental MergeJoin - -**Modify:** `src/orcapod/core/operators/merge_join.py` - -- Override `async_execute` with symmetric hash join + list merge for colliding columns - -**Tests:** `tests/test_core/test_execution/test_incremental_merge_join.py` - -### Step 4.6 — Incremental SemiJoin - -**Modify:** `src/orcapod/core/operators/semijoin.py` - -- Override `async_execute`: buffer right side fully, then stream left - -**Tests:** `tests/test_core/test_execution/test_incremental_semijoin.py` - ---- - -## Phase 5: Integration and Wiring - -### Step 5.1 — Pipeline-level API - -**Determine integration point:** How does a user trigger async execution? - -Option A — `GraphTracker` gains a `run(config)` method: -```python -with GraphTracker() as tracker: - result = source | filter_op | func_pod -tracker.run(PipelineConfig(executor=ExecutorType.ASYNC_CHANNELS)) -``` - -Option B — A top-level `run_pipeline` function: -```python -result = run_pipeline(terminal_stream, config=PipelineConfig(...)) -``` - -The exact API will be determined during implementation. The orchestrator internals are -independent of this choice. - -### Step 5.2 — NodeConfig attachment - -Allow `NodeConfig` to be attached to operators/function pods: - -```python -func_pod = FunctionPod(my_func, node_config=NodeConfig(max_concurrency=4)) -filter_op = PolarsFilter(predicate, node_config=NodeConfig(max_concurrency=None)) -``` - -**Modify:** `StaticOutputPod.__init__`, `_FunctionPodBase.__init__` -- Accept optional `node_config: NodeConfig` parameter -- Default: `NodeConfig()` (inherit pipeline default) - -### Step 5.3 — End-to-end integration tests - -**New file:** `tests/test_core/test_execution/test_integration.py` - -- Full pipeline: Source → Filter → FunctionPod → Join → Map - - Run sync, run async, compare results -- Pipeline with mixed strategies: streaming filter + barrier batch + streaming map -- Pipeline with database-backed FunctionNode -- Concurrency behavior: verify max_concurrency limits are respected - ---- - -## Implementation Order and Dependencies - -``` -Phase 1 (Foundation) - ├── 1.1 Channels ──────────────────┐ - ├── 1.2 Protocol ──────────────────┤ - ├── 1.3 Config ────────────────────┤ - └── 1.4 Module init ──────────────┘ - │ -Phase 2 (Defaults) ▼ - ├── 2.1 Materialization helpers ───┐ - ├── 2.2 StaticOutputPod default ───┤ (depends on 1.x + 2.1) - ├── 2.3 FunctionPod async ─────────┤ - └── 2.4 SourceNode async ─────────┘ - │ -Phase 3 (Orchestrator) ▼ - ├── 3.1 DAG compilation ───────────┐ (depends on 2.x) - └── 3.2 Orchestrator ─────────────┘ - │ -Phase 4 (Streaming Overrides) ▼ - ├── 4.1 Column selection ──────────┐ - ├── 4.2 Mappers ───────────────────┤ (all independent, depend on 3.x) - ├── 4.3 Filter ────────────────────┤ - ├── 4.4 Join ──────────────────────┤ - ├── 4.5 MergeJoin ─────────────────┤ - └── 4.6 SemiJoin ──────────────────┘ - │ -Phase 5 (Integration) ▼ - ├── 5.1 Pipeline API ─────────────┐ - ├── 5.2 NodeConfig attachment ─────┤ (depends on 4.x) - └── 5.3 Integration tests ────────┘ -``` - -Phases 1–3 must be sequential. Phase 4 steps are independent of each other. -Phase 5 depends on everything above. - ---- - -## Risk Assessment - -| Risk | Mitigation | -|---|---| -| Row ordering differs between sync/async | Document clearly; `sort_by_tags` provides determinism | -| Incremental Join correctness | Extensive property-based tests comparing to sync | -| Deadlocks from channel misuse | Strict rule: every node MUST close output channel | -| Per-row Datagram operations are slow | Benchmark; fall back to barrier if perf regresses | -| Breaking existing tests | async_execute is additive; sync path unchanged | -| Fan-out channel memory | Bounded buffers + backpressure limit memory | - ---- - -## What's NOT in Scope - -- Distributed execution (network channels, Ray integration) — future work -- Adaptive concurrency tuning — future work -- Checkpointing / fault recovery — future work -- Modifications to `DataFunctionExecutorProtocol` — orthogonal concern, unchanged -- Changes to hashing / identity — unchanged -- Changes to `CacheMode` semantics — unchanged diff --git a/design/async-execution-system.md b/design/async-execution-system.md deleted file mode 100644 index e5e474709..000000000 --- a/design/async-execution-system.md +++ /dev/null @@ -1,529 +0,0 @@ -# Unified Async Channel Execution System - -**Status:** Proposed -**Date:** 2026-03-04 - ---- - -## Motivation - -The current execution model is synchronous and pull-based: each node materializes its full -output before the downstream node begins. This means a pipeline like -`Source → Filter → FunctionPod → Join → Map` processes in discrete stages — Filter waits for -all source rows, FunctionPod waits for all filtered rows, etc. - -This design proposes a **push-based async channel execution model** where every pipeline node -is a coroutine that consumes from input channels and produces to output channels. Rows flow -through the pipeline as soon as they're available, enabling: - -- **Streaming**: row-by-row operators (Filter, Map, Select, FunctionPod) emit immediately - without buffering -- **Incremental computation**: multi-input operators (Join) can emit matches as rows arrive - from any input, using techniques like symmetric hash join -- **Controlled concurrency**: per-node `max_concurrency` limits enable rate-limiting for - external API calls or GPU inference while allowing trivial operators to run unbounded -- **Backpressure**: bounded channels naturally throttle fast producers when downstream - consumers are slow - -Critically, the design is **backwards-compatible** — every existing synchronous operator works -unchanged via a barrier wrapper, and the executor type is selected at the pipeline level. - ---- - -## Core Design: One Interface for All Nodes - -### The Async Execute Protocol - -Every pipeline node — source, operator, or function pod — implements a single method: - -```python -@runtime_checkable -class AsyncExecutableProtocol(Protocol): - async def async_execute( - self, - inputs: Sequence[ReadableChannel[tuple[TagProtocol, DataProtocol]]], - output: WritableChannel[tuple[TagProtocol, DataProtocol]], - ) -> None: - """ - Consume (tag, data) pairs from input channels, produce to output channel. - MUST close output channel when done (signals completion to downstream). - """ - ... -``` - -The orchestrator sees a **homogeneous DAG** — it doesn't need to know whether a node is an -operator, function pod, or source. It just wires up channels and launches tasks. - -### Channel Abstraction - -Channels are bounded async queues with close semantics: - -```python -@dataclass -class Channel(Generic[T]): - """Bounded async channel with close/done signaling.""" - _queue: asyncio.Queue[T | _Sentinel] - _closed: asyncio.Event - - @property - def reader(self) -> ReadableChannel[T]: ... - - @property - def writer(self) -> WritableChannel[T]: ... - - -class ReadableChannel(Protocol[T]): - """Consumer side of a channel.""" - - async def receive(self) -> T: - """Receive next item. Raises ChannelClosed when done.""" - ... - - def __aiter__(self) -> AsyncIterator[T]: ... - async def __anext__(self) -> T: ... - - async def collect(self) -> list[T]: - """Drain all remaining items into a list.""" - ... - - -class WritableChannel(Protocol[T]): - """Producer side of a channel.""" - - async def send(self, item: T) -> None: - """Send an item. Blocks if channel buffer is full (backpressure).""" - ... - - async def close(self) -> None: - """Signal that no more items will be sent.""" - ... -``` - -Bounded channels provide natural backpressure: a fast producer blocks on `send()` when the -buffer is full, automatically throttling without explicit flow control. - -### Thread Safety - -Channels are backed by `asyncio.Queue`, which is **coroutine-safe but not thread-safe**. -This is sufficient because all channel operations happen on the event loop thread: - -- `async_execute` methods are coroutines running on the event loop -- Sync `DataFunction`s run in thread pools via `loop.run_in_executor`, but the result - is awaited back on the event loop before `output.send()` is called — the channel is - never touched from a worker thread -- The `async def` signature on `send()`/`receive()` structurally prevents direct calls - from non-async (thread) contexts - -If a future executor needs to push results directly from worker threads (bypassing the event -loop), channels should be swapped to a dual sync/async queue (e.g., `janus`) or use -`loop.call_soon_threadsafe` to marshal back to the event loop. This is not needed for the -current design. - ---- - -## Three Execution Strategies - -All three strategies implement the same `async_execute` interface. The differences are purely -in **when** the node reads, **how much** it buffers, and **when** it emits. - -### 1. Streaming (Row-by-Row) - -**Applies to:** Filter, MapTags, MapData, Select/Drop columns, FunctionPod - -Zero buffering. Each input row is independently transformed and emitted immediately. - -```python -# Example: PolarsFilter -async def async_execute(self, inputs, output): - async for tag, data in inputs[0]: - if self._evaluate_predicate(tag, data): - await output.send((tag, data)) - await output.close() - -# Example: FunctionPod with concurrency control -async def async_execute(self, inputs, output): - sem = asyncio.Semaphore(self.node_config.max_concurrency or _INF) - - async def process_one(tag, data): - async with sem: - result = await self.data_function.async_call(data) - if result is not None: - await output.send((tag, result)) - - async with asyncio.TaskGroup() as tg: - async for tag, data in inputs[0]: - tg.create_task(process_one(tag, data)) - - await output.close() -``` - -### 2. Incremental (Stateful, Eager Emit) - -**Applies to:** Join, MergeJoin, SemiJoin - -Maintains internal state (hash indexes). Emits matches as soon as they're found. - -```python -# Example: Symmetric Hash Join -async def async_execute(self, inputs, output): - indexes: list[dict[JoinKey, list[Row]]] = [{} for _ in inputs] - - async def consume(i: int, channel): - async for tag, data in channel: - key = self._extract_join_key(tag) - indexes[i].setdefault(key, []).append((tag, data)) - - # Probe all OTHER indexes for matches - other_lists = [indexes[j].get(key, []) for j in range(len(inputs)) if j != i] - for combo in itertools.product(*other_lists): - joined = self._merge_rows((tag, data), *combo) - await output.send(joined) - - async with asyncio.TaskGroup() as tg: - for i, ch in enumerate(inputs): - tg.create_task(consume(i, ch)) - - await output.close() -``` - -For SemiJoin (non-commutative), the right side is buffered first, then left rows are probed: - -```python -async def async_execute(self, inputs, output): - left, right = inputs - - # Phase 1: Build right-side index - right_keys = set() - async for tag, data in right: - key = self._extract_join_key(tag) - right_keys.add(key) - - # Phase 2: Stream left, emit matches - async for tag, data in left: - key = self._extract_join_key(tag) - if key in right_keys: - await output.send((tag, data)) - - await output.close() -``` - -### 3. Barrier (Fully Synchronous, Wrapped) - -**Applies to:** Batch, or any operator that hasn't implemented `async_execute` - -Collects all input, runs existing `static_process`, emits results. This is the **default** -implementation on operator base classes — every existing operator works without modification. - -```python -async def async_execute(self, inputs, output): - # Phase 1: Collect all inputs (the barrier) - collected = [await ch.collect() for ch in inputs] - - # Phase 2: Materialize into streams, run sync logic - streams = [self._materialize(rows) for rows in collected] - result_stream = self.static_process(*streams) - - # Phase 3: Emit results asynchronously - for tag, data in result_stream.iter_data(): - await output.send((tag, data)) - - await output.close() -``` - -The barrier is a **local** bottleneck — upstream streaming nodes still push rows into the -barrier's input channel as they're produced, and downstream nodes receive rows as soon as -the barrier emits them. - ---- - -## Default Implementations (Backwards Compatibility) - -Operator base classes provide a default `async_execute` that wraps `static_process` in the -barrier pattern. Existing operators work without any changes: - -```python -class UnaryOperator(StaticOutputPod): - """Default: barrier mode. Override async_execute for streaming.""" - - async def async_execute(self, inputs, output): - rows = await inputs[0].collect() - stream = self._materialize_to_stream(rows) - result = self.static_process(stream) - for tag, data in result.iter_data(): - await output.send((tag, data)) - await output.close() - - -class BinaryOperator(StaticOutputPod): - async def async_execute(self, inputs, output): - left_rows, right_rows = await asyncio.gather( - inputs[0].collect(), inputs[1].collect() - ) - left_stream = self._materialize_to_stream(left_rows) - right_stream = self._materialize_to_stream(right_rows) - result = self.static_process(left_stream, right_stream) - for tag, data in result.iter_data(): - await output.send((tag, data)) - await output.close() - - -class NonZeroInputOperator(StaticOutputPod): - async def async_execute(self, inputs, output): - all_rows = await asyncio.gather(*(ch.collect() for ch in inputs)) - streams = [self._materialize_to_stream(rows) for rows in all_rows] - result = self.static_process(*streams) - for tag, data in result.iter_data(): - await output.send((tag, data)) - await output.close() -``` - -Concrete operators **opt into** better strategies by overriding `async_execute`. - ---- - -## FunctionPod and FunctionNode - -FunctionPod fits the streaming pattern naturally — it processes data independently: - -```python -class FunctionPod: - async def async_execute(self, inputs, output): - sem = asyncio.Semaphore(self.node_config.max_concurrency or _INF) - - async def process_one(tag, data): - async with sem: - result_data = await self.data_function.async_call(data) - if result_data is not None: - await output.send((tag, result_data)) - - async with asyncio.TaskGroup() as tg: - async for tag, data in inputs[0]: - tg.create_task(process_one(tag, data)) - - await output.close() -``` - -FunctionNode adds DB-backed caching — cache hits emit immediately, misses go through the -semaphore: - -```python -class FunctionNode: - async def async_execute(self, inputs, output): - sem = asyncio.Semaphore(self.node_config.max_concurrency or _INF) - - async def process_one(tag, data): - cache_key = self._compute_cache_key(data) - cached = await self._db_lookup(cache_key) - if cached is not None: - await output.send((tag, cached)) - return - - async with sem: - result = await self.data_function.async_call(data) - await self._db_store(cache_key, result) - if result is not None: - await output.send((tag, result)) - - async with asyncio.TaskGroup() as tg: - async for tag, data in inputs[0]: - tg.create_task(process_one(tag, data)) - - await output.close() -``` - -### Sync DataFunctions - -Existing synchronous `DataFunction`s are bridged via `run_in_executor`: - -```python -class PythonDataFunction: - async def direct_async_call(self, data): - loop = asyncio.get_running_loop() - return await loop.run_in_executor( - self._thread_pool, - self._func, - data, - ) -``` - -CPU-bound functions run in a thread pool. Async-native functions (API calls, I/O) can -override `direct_async_call` directly. - ---- - -## Configuration - -### Two-Level Config - -```python -class ExecutorType(Enum): - SYNCHRONOUS = "synchronous" # Current behavior: static_process chain - ASYNC_CHANNELS = "async_channels" # New: async_execute with channels - -@dataclass(frozen=True) -class PipelineConfig: - executor: ExecutorType = ExecutorType.SYNCHRONOUS - channel_buffer_size: int = 64 - default_max_concurrency: int | None = None # pipeline-wide default - -@dataclass(frozen=True) -class NodeConfig: - max_concurrency: int | None = None # overrides pipeline default - # None = inherit from pipeline default - # 1 = sequential (rate-limited APIs, ordered output) - # N = up to N data in-flight concurrently -``` - -### Concurrency Resolution - -```python -def resolve_concurrency(node_config: NodeConfig, pipeline_config: PipelineConfig) -> int | None: - if node_config.max_concurrency is not None: - return node_config.max_concurrency - return pipeline_config.default_max_concurrency -``` - -Examples: -- `max_concurrency=1`: sequential processing (rate-limited API, preserves ordering) -- `max_concurrency=8`: bounded parallelism (GPU inference, external service) -- `max_concurrency=None` (unlimited): trivial ops (column select, rename) - ---- - -## Orchestrator - -The orchestrator builds the DAG, creates channels, and launches all nodes concurrently: - -```python -class AsyncPipelineOrchestrator: - - def run(self, graph: CompiledGraph, config: PipelineConfig) -> StreamProtocol: - """Entry point — runs async pipeline, returns materialized result.""" - return asyncio.run(self._run_async(graph, config)) - - async def _run_async(self, graph, config): - buf = config.channel_buffer_size - - # Create a channel for each edge in the DAG - channels: dict[EdgeId, Channel] = { - edge: Channel(buffer_size=buf) for edge in graph.edges - } - - # Launch every node as a concurrent task - async with asyncio.TaskGroup() as tg: - for node in graph.nodes: - input_chs = [channels[e].reader for e in node.input_edges] - output_ch = channels[node.output_edge].writer - tg.create_task(node.async_execute(input_chs, output_ch)) - - # Collect terminal output - terminal_rows = await channels[graph.terminal_edge].collect() - return self._materialize(terminal_rows) -``` - -### Source Nodes - -Sources have no input channels — they just push their data onto the output channel: - -```python -class SourceNode: - async def async_execute(self, inputs, output): - # inputs is empty for sources - for tag, data in self.stream.iter_data(): - await output.send((tag, data)) - await output.close() -``` - -### Fan-Out (Multiple Consumers) - -When a node's output feeds multiple downstream nodes, the channel is **broadcast** — each -downstream gets its own reader over a shared sequence. This avoids duplicating computation -while allowing each consumer to read at its own pace. - ---- - -## Operator Classification - -| Operator | Default Strategy | Async Override? | -|---|---|---| -| PolarsFilter | Barrier (inherited) | **Streaming** — evaluate predicate per row | -| MapTags / MapData | Barrier (inherited) | **Streaming** — rename per row | -| SelectTagColumns / SelectDataColumns | Barrier (inherited) | **Streaming** — project per row | -| DropTagColumns / DropDataColumns | Barrier (inherited) | **Streaming** — project per row | -| FunctionPod | N/A (new) | **Streaming** — transform data per row | -| FunctionNode | N/A (new) | **Streaming** — cache check + transform per row | -| Join | Barrier (inherited) | **Incremental** — symmetric hash join | -| MergeJoin | Barrier (inherited) | **Incremental** — symmetric hash join with merge | -| SemiJoin | Barrier (inherited) | **Incremental** — buffer right, stream left | -| Batch | Barrier (inherited) | Barrier (inherent) — needs all rows for grouping | - -All operators work in barrier mode by default. Streaming/incremental overrides are added -incrementally — the system is correct at every step. - ---- - -## Interaction with Existing Execution Models - -### Synchronous Mode (ExecutorType.SYNCHRONOUS) - -Unchanged. The existing `static_process` / `DynamicPodStream` / `iter_data` chain continues -to work exactly as before. `async_execute` is never called. - -### Async Mode (ExecutorType.ASYNC_CHANNELS) - -The orchestrator calls `async_execute` on every node. The existing `static_process` is used -by the barrier wrapper as an implementation detail — it's not called directly by the -orchestrator. - -### DataFunctionExecutorProtocol - -The existing executor protocol (`execute` / `async_execute` for individual data) remains -unchanged. It controls **how a single data function invocation runs** (local, Ray, etc.). -The new `async_execute` on nodes controls **how the node participates in the pipeline DAG**. -These are orthogonal concerns: - -- `DataFunctionExecutorProtocol.async_execute(fn, data)` → single invocation strategy -- `FunctionPod.async_execute(inputs, output)` → pipeline-level data flow - -### GraphTracker - -The `GraphTracker` continues to build the DAG via `record_*_invocation` calls. The compiled -graph it produces is what the `AsyncPipelineOrchestrator` consumes. The tracker doesn't need -to know about async execution — it only records topology. - ---- - -## Row Ordering Considerations - -Streaming and incremental strategies may change row ordering compared to synchronous mode: - -- **Streaming with concurrency**: `max_concurrency > 1` on FunctionPod means data may - complete out of order. If ordering matters, set `max_concurrency=1`. -- **Incremental Join**: rows are emitted as matches are found, which depends on arrival order - from upstream. The result set is identical but row order may differ. -- **Barrier**: row order matches synchronous mode exactly. - -The `sort_by_tags` option in `ColumnConfig` provides deterministic ordering when needed, -independent of execution strategy. - ---- - -## Error Propagation - -When a node raises an exception inside `async_execute`: - -1. The `TaskGroup` propagates the exception, cancelling all other tasks -2. Channel close semantics ensure no deadlocks — cancelled producers don't block consumers -3. The orchestrator surfaces the original exception to the caller - -This is handled naturally by Python's `asyncio.TaskGroup` semantics. - ---- - -## Future Extensions - -- **Distributed execution**: Replace local channels with network channels (e.g., gRPC streams) - while keeping the same `async_execute` interface -- **Adaptive concurrency**: Auto-tune `max_concurrency` based on throughput/latency metrics -- **Checkpointing**: Persist channel state for fault recovery in long-running pipelines -- **Backpressure metrics**: Expose channel fill levels for monitoring and debugging diff --git a/design_issues/ENG-389-UC1.md b/docs/dev/design_issues/ENG-389-UC1.md similarity index 100% rename from design_issues/ENG-389-UC1.md rename to docs/dev/design_issues/ENG-389-UC1.md diff --git a/design_issues/ENG-572-FN1.md b/docs/dev/design_issues/ENG-572-FN1.md similarity index 100% rename from design_issues/ENG-572-FN1.md rename to docs/dev/design_issues/ENG-572-FN1.md diff --git a/design_issues/ENG-601-D8.md b/docs/dev/design_issues/ENG-601-D8.md similarity index 100% rename from design_issues/ENG-601-D8.md rename to docs/dev/design_issues/ENG-601-D8.md diff --git a/design_issues/ENG-952-PS5.md b/docs/dev/design_issues/ENG-952-PS5.md similarity index 100% rename from design_issues/ENG-952-PS5.md rename to docs/dev/design_issues/ENG-952-PS5.md diff --git a/design_issues/ITL-1000-DS1.md b/docs/dev/design_issues/ITL-1000-DS1.md similarity index 100% rename from design_issues/ITL-1000-DS1.md rename to docs/dev/design_issues/ITL-1000-DS1.md diff --git a/design_issues/ITL-1029-FN2.md b/docs/dev/design_issues/ITL-1029-FN2.md similarity index 100% rename from design_issues/ITL-1029-FN2.md rename to docs/dev/design_issues/ITL-1029-FN2.md diff --git a/design_issues/ITL-1039-F17.md b/docs/dev/design_issues/ITL-1039-F17.md similarity index 100% rename from design_issues/ITL-1039-F17.md rename to docs/dev/design_issues/ITL-1039-F17.md diff --git a/design_issues/ITL-1040-DG2.md b/docs/dev/design_issues/ITL-1040-DG2.md similarity index 100% rename from design_issues/ITL-1040-DG2.md rename to docs/dev/design_issues/ITL-1040-DG2.md diff --git a/design_issues/ITL-1042-NS1.md b/docs/dev/design_issues/ITL-1042-NS1.md similarity index 100% rename from design_issues/ITL-1042-NS1.md rename to docs/dev/design_issues/ITL-1042-NS1.md diff --git a/design_issues/ITL-1043-LJ1.md b/docs/dev/design_issues/ITL-1043-LJ1.md similarity index 100% rename from design_issues/ITL-1043-LJ1.md rename to docs/dev/design_issues/ITL-1043-LJ1.md diff --git a/design_issues/ITL-1044-AJ1.md b/docs/dev/design_issues/ITL-1044-AJ1.md similarity index 100% rename from design_issues/ITL-1044-AJ1.md rename to docs/dev/design_issues/ITL-1044-AJ1.md diff --git a/design_issues/ITL-1045-FP1.md b/docs/dev/design_issues/ITL-1045-FP1.md similarity index 100% rename from design_issues/ITL-1045-FP1.md rename to docs/dev/design_issues/ITL-1045-FP1.md diff --git a/design_issues/ITL-1046-IX1.md b/docs/dev/design_issues/ITL-1046-IX1.md similarity index 100% rename from design_issues/ITL-1046-IX1.md rename to docs/dev/design_issues/ITL-1046-IX1.md diff --git a/design_issues/ITL-1052-F18.md b/docs/dev/design_issues/ITL-1052-F18.md similarity index 100% rename from design_issues/ITL-1052-F18.md rename to docs/dev/design_issues/ITL-1052-F18.md diff --git a/design_issues/ITL-1053-PV2.md b/docs/dev/design_issues/ITL-1053-PV2.md similarity index 100% rename from design_issues/ITL-1053-PV2.md rename to docs/dev/design_issues/ITL-1053-PV2.md diff --git a/design_issues/ITL-1054-PV3.md b/docs/dev/design_issues/ITL-1054-PV3.md similarity index 100% rename from design_issues/ITL-1054-PV3.md rename to docs/dev/design_issues/ITL-1054-PV3.md diff --git a/design_issues/ITL-1060-FN1.md b/docs/dev/design_issues/ITL-1060-FN1.md similarity index 100% rename from design_issues/ITL-1060-FN1.md rename to docs/dev/design_issues/ITL-1060-FN1.md diff --git a/design_issues/ITL-1065-F19.md b/docs/dev/design_issues/ITL-1065-F19.md similarity index 100% rename from design_issues/ITL-1065-F19.md rename to docs/dev/design_issues/ITL-1065-F19.md diff --git a/design_issues/ITL-1066-SE1.md b/docs/dev/design_issues/ITL-1066-SE1.md similarity index 100% rename from design_issues/ITL-1066-SE1.md rename to docs/dev/design_issues/ITL-1066-SE1.md diff --git a/design_issues/ITL-1067-CC1.md b/docs/dev/design_issues/ITL-1067-CC1.md similarity index 100% rename from design_issues/ITL-1067-CC1.md rename to docs/dev/design_issues/ITL-1067-CC1.md diff --git a/design_issues/ITL-1068-PH1.md b/docs/dev/design_issues/ITL-1068-PH1.md similarity index 100% rename from design_issues/ITL-1068-PH1.md rename to docs/dev/design_issues/ITL-1068-PH1.md diff --git a/design_issues/ITL-1070-GB2.md b/docs/dev/design_issues/ITL-1070-GB2.md similarity index 100% rename from design_issues/ITL-1070-GB2.md rename to docs/dev/design_issues/ITL-1070-GB2.md diff --git a/design_issues/ITL-1075-AH1.md b/docs/dev/design_issues/ITL-1075-AH1.md similarity index 100% rename from design_issues/ITL-1075-AH1.md rename to docs/dev/design_issues/ITL-1075-AH1.md diff --git a/design_issues/ITL-1080-SA1.md b/docs/dev/design_issues/ITL-1080-SA1.md similarity index 100% rename from design_issues/ITL-1080-SA1.md rename to docs/dev/design_issues/ITL-1080-SA1.md diff --git a/design_issues/ITL-1081-RV1.md b/docs/dev/design_issues/ITL-1081-RV1.md similarity index 100% rename from design_issues/ITL-1081-RV1.md rename to docs/dev/design_issues/ITL-1081-RV1.md diff --git a/design_issues/ITL-1083-OS1.md b/docs/dev/design_issues/ITL-1083-OS1.md similarity index 100% rename from design_issues/ITL-1083-OS1.md rename to docs/dev/design_issues/ITL-1083-OS1.md diff --git a/design_issues/ITL-1088-SJ3.md b/docs/dev/design_issues/ITL-1088-SJ3.md similarity index 100% rename from design_issues/ITL-1088-SJ3.md rename to docs/dev/design_issues/ITL-1088-SJ3.md diff --git a/design_issues/ITL-1091-SE2.md b/docs/dev/design_issues/ITL-1091-SE2.md similarity index 100% rename from design_issues/ITL-1091-SE2.md rename to docs/dev/design_issues/ITL-1091-SE2.md diff --git a/design_issues/ITL-1093-JR1.md b/docs/dev/design_issues/ITL-1093-JR1.md similarity index 100% rename from design_issues/ITL-1093-JR1.md rename to docs/dev/design_issues/ITL-1093-JR1.md diff --git a/design_issues/ITL-1094-LJ2.md b/docs/dev/design_issues/ITL-1094-LJ2.md similarity index 100% rename from design_issues/ITL-1094-LJ2.md rename to docs/dev/design_issues/ITL-1094-LJ2.md diff --git a/design_issues/ITL-1095-CR1.md b/docs/dev/design_issues/ITL-1095-CR1.md similarity index 100% rename from design_issues/ITL-1095-CR1.md rename to docs/dev/design_issues/ITL-1095-CR1.md diff --git a/design_issues/ITL-1102-SC1.md b/docs/dev/design_issues/ITL-1102-SC1.md similarity index 100% rename from design_issues/ITL-1102-SC1.md rename to docs/dev/design_issues/ITL-1102-SC1.md diff --git a/design_issues/ITL-1111-GW1.md b/docs/dev/design_issues/ITL-1111-GW1.md similarity index 100% rename from design_issues/ITL-1111-GW1.md rename to docs/dev/design_issues/ITL-1111-GW1.md diff --git a/design_issues/ITL-1112-BT1.md b/docs/dev/design_issues/ITL-1112-BT1.md similarity index 100% rename from design_issues/ITL-1112-BT1.md rename to docs/dev/design_issues/ITL-1112-BT1.md diff --git a/design_issues/ITL-1121-NV1.md b/docs/dev/design_issues/ITL-1121-NV1.md similarity index 100% rename from design_issues/ITL-1121-NV1.md rename to docs/dev/design_issues/ITL-1121-NV1.md diff --git a/design_issues/ITL-1122-LN1.md b/docs/dev/design_issues/ITL-1122-LN1.md similarity index 100% rename from design_issues/ITL-1122-LN1.md rename to docs/dev/design_issues/ITL-1122-LN1.md diff --git a/design_issues/ITL-1131-ZR2.md b/docs/dev/design_issues/ITL-1131-ZR2.md similarity index 100% rename from design_issues/ITL-1131-ZR2.md rename to docs/dev/design_issues/ITL-1131-ZR2.md diff --git a/design_issues/ITL-1133-ZR3.md b/docs/dev/design_issues/ITL-1133-ZR3.md similarity index 100% rename from design_issues/ITL-1133-ZR3.md rename to docs/dev/design_issues/ITL-1133-ZR3.md diff --git a/design_issues/ITL-1135-SP1.md b/docs/dev/design_issues/ITL-1135-SP1.md similarity index 100% rename from design_issues/ITL-1135-SP1.md rename to docs/dev/design_issues/ITL-1135-SP1.md diff --git a/design_issues/ITL-1137-H6.md b/docs/dev/design_issues/ITL-1137-H6.md similarity index 100% rename from design_issues/ITL-1137-H6.md rename to docs/dev/design_issues/ITL-1137-H6.md diff --git a/design_issues/ITL-1138-LJ3.md b/docs/dev/design_issues/ITL-1138-LJ3.md similarity index 100% rename from design_issues/ITL-1138-LJ3.md rename to docs/dev/design_issues/ITL-1138-LJ3.md diff --git a/design_issues/ITL-1144-NN1.md b/docs/dev/design_issues/ITL-1144-NN1.md similarity index 100% rename from design_issues/ITL-1144-NN1.md rename to docs/dev/design_issues/ITL-1144-NN1.md diff --git a/design_issues/ITL-1152-BH1.md b/docs/dev/design_issues/ITL-1152-BH1.md similarity index 100% rename from design_issues/ITL-1152-BH1.md rename to docs/dev/design_issues/ITL-1152-BH1.md diff --git a/design_issues/ITL-1158-PS6.md b/docs/dev/design_issues/ITL-1158-PS6.md similarity index 100% rename from design_issues/ITL-1158-PS6.md rename to docs/dev/design_issues/ITL-1158-PS6.md diff --git a/design_issues/ITL-1162-CA3.md b/docs/dev/design_issues/ITL-1162-CA3.md similarity index 100% rename from design_issues/ITL-1162-CA3.md rename to docs/dev/design_issues/ITL-1162-CA3.md diff --git a/design_issues/ITL-1165-RN1.md b/docs/dev/design_issues/ITL-1165-RN1.md similarity index 100% rename from design_issues/ITL-1165-RN1.md rename to docs/dev/design_issues/ITL-1165-RN1.md diff --git a/design_issues/ITL-134-DEP1.md b/docs/dev/design_issues/ITL-134-DEP1.md similarity index 100% rename from design_issues/ITL-134-DEP1.md rename to docs/dev/design_issues/ITL-134-DEP1.md diff --git a/design_issues/ITL-186-SP4.md b/docs/dev/design_issues/ITL-186-SP4.md similarity index 100% rename from design_issues/ITL-186-SP4.md rename to docs/dev/design_issues/ITL-186-SP4.md diff --git a/design_issues/ITL-433-H5.md b/docs/dev/design_issues/ITL-433-H5.md similarity index 100% rename from design_issues/ITL-433-H5.md rename to docs/dev/design_issues/ITL-433-H5.md diff --git a/design_issues/ITL-452-UC2.md b/docs/dev/design_issues/ITL-452-UC2.md similarity index 100% rename from design_issues/ITL-452-UC2.md rename to docs/dev/design_issues/ITL-452-UC2.md diff --git a/design_issues/ITL-453-UC3.md b/docs/dev/design_issues/ITL-453-UC3.md similarity index 100% rename from design_issues/ITL-453-UC3.md rename to docs/dev/design_issues/ITL-453-UC3.md diff --git a/design_issues/ITL-527-F15.md b/docs/dev/design_issues/ITL-527-F15.md similarity index 100% rename from design_issues/ITL-527-F15.md rename to docs/dev/design_issues/ITL-527-F15.md diff --git a/design_issues/ITL-539-ON1.md b/docs/dev/design_issues/ITL-539-ON1.md similarity index 100% rename from design_issues/ITL-539-ON1.md rename to docs/dev/design_issues/ITL-539-ON1.md diff --git a/design_issues/ITL-563-CC1.md b/docs/dev/design_issues/ITL-563-CC1.md similarity index 100% rename from design_issues/ITL-563-CC1.md rename to docs/dev/design_issues/ITL-563-CC1.md diff --git a/design_issues/ITL-578-PL1.md b/docs/dev/design_issues/ITL-578-PL1.md similarity index 100% rename from design_issues/ITL-578-PL1.md rename to docs/dev/design_issues/ITL-578-PL1.md diff --git a/design_issues/ITL-611-NC1.md b/docs/dev/design_issues/ITL-611-NC1.md similarity index 100% rename from design_issues/ITL-611-NC1.md rename to docs/dev/design_issues/ITL-611-NC1.md diff --git a/design_issues/ITL-615-PS1.md b/docs/dev/design_issues/ITL-615-PS1.md similarity index 100% rename from design_issues/ITL-615-PS1.md rename to docs/dev/design_issues/ITL-615-PS1.md diff --git a/design_issues/ITL-615-SJN1.md b/docs/dev/design_issues/ITL-615-SJN1.md similarity index 100% rename from design_issues/ITL-615-SJN1.md rename to docs/dev/design_issues/ITL-615-SJN1.md diff --git a/design_issues/ITL-616-PS3.md b/docs/dev/design_issues/ITL-616-PS3.md similarity index 100% rename from design_issues/ITL-616-PS3.md rename to docs/dev/design_issues/ITL-616-PS3.md diff --git a/design_issues/ITL-617-PS4.md b/docs/dev/design_issues/ITL-617-PS4.md similarity index 100% rename from design_issues/ITL-617-PS4.md rename to docs/dev/design_issues/ITL-617-PS4.md diff --git a/design_issues/ITL-625-PS2.md b/docs/dev/design_issues/ITL-625-PS2.md similarity index 100% rename from design_issues/ITL-625-PS2.md rename to docs/dev/design_issues/ITL-625-PS2.md diff --git a/design_issues/ITL-626-HS1.md b/docs/dev/design_issues/ITL-626-HS1.md similarity index 100% rename from design_issues/ITL-626-HS1.md rename to docs/dev/design_issues/ITL-626-HS1.md diff --git a/design_issues/ITL-807-F16.md b/docs/dev/design_issues/ITL-807-F16.md similarity index 100% rename from design_issues/ITL-807-F16.md rename to docs/dev/design_issues/ITL-807-F16.md diff --git a/design_issues/ITL-813-MJ1.md b/docs/dev/design_issues/ITL-813-MJ1.md similarity index 100% rename from design_issues/ITL-813-MJ1.md rename to docs/dev/design_issues/ITL-813-MJ1.md diff --git a/design_issues/ITL-816-ST4.md b/docs/dev/design_issues/ITL-816-ST4.md similarity index 100% rename from design_issues/ITL-816-ST4.md rename to docs/dev/design_issues/ITL-816-ST4.md diff --git a/design_issues/ITL-817-RS1.md b/docs/dev/design_issues/ITL-817-RS1.md similarity index 100% rename from design_issues/ITL-817-RS1.md rename to docs/dev/design_issues/ITL-817-RS1.md diff --git a/design_issues/ITL-817-RS2.md b/docs/dev/design_issues/ITL-817-RS2.md similarity index 100% rename from design_issues/ITL-817-RS2.md rename to docs/dev/design_issues/ITL-817-RS2.md diff --git a/design_issues/ITL-820-O6.md b/docs/dev/design_issues/ITL-820-O6.md similarity index 100% rename from design_issues/ITL-820-O6.md rename to docs/dev/design_issues/ITL-820-O6.md diff --git a/design_issues/ITL-821-NP1.md b/docs/dev/design_issues/ITL-821-NP1.md similarity index 100% rename from design_issues/ITL-821-NP1.md rename to docs/dev/design_issues/ITL-821-NP1.md diff --git a/design_issues/ITL-825-PY313.md b/docs/dev/design_issues/ITL-825-PY313.md similarity index 100% rename from design_issues/ITL-825-PY313.md rename to docs/dev/design_issues/ITL-825-PY313.md diff --git a/design_issues/ITL-826-TOOL1.md b/docs/dev/design_issues/ITL-826-TOOL1.md similarity index 100% rename from design_issues/ITL-826-TOOL1.md rename to docs/dev/design_issues/ITL-826-TOOL1.md diff --git a/design_issues/ITL-827-DEP2.md b/docs/dev/design_issues/ITL-827-DEP2.md similarity index 100% rename from design_issues/ITL-827-DEP2.md rename to docs/dev/design_issues/ITL-827-DEP2.md diff --git a/design_issues/ITL-829-SJ2.md b/docs/dev/design_issues/ITL-829-SJ2.md similarity index 100% rename from design_issues/ITL-829-SJ2.md rename to docs/dev/design_issues/ITL-829-SJ2.md diff --git a/design_issues/ITL-832-MJ2.md b/docs/dev/design_issues/ITL-832-MJ2.md similarity index 100% rename from design_issues/ITL-832-MJ2.md rename to docs/dev/design_issues/ITL-832-MJ2.md diff --git a/design_issues/ITL-832-TC1.md b/docs/dev/design_issues/ITL-832-TC1.md similarity index 100% rename from design_issues/ITL-832-TC1.md rename to docs/dev/design_issues/ITL-832-TC1.md diff --git a/design_issues/ITL-834-DG1.md b/docs/dev/design_issues/ITL-834-DG1.md similarity index 100% rename from design_issues/ITL-834-DG1.md rename to docs/dev/design_issues/ITL-834-DG1.md diff --git a/design_issues/ITL-837-JA1.md b/docs/dev/design_issues/ITL-837-JA1.md similarity index 100% rename from design_issues/ITL-837-JA1.md rename to docs/dev/design_issues/ITL-837-JA1.md diff --git a/design_issues/ITL-845-O3.md b/docs/dev/design_issues/ITL-845-O3.md similarity index 100% rename from design_issues/ITL-845-O3.md rename to docs/dev/design_issues/ITL-845-O3.md diff --git a/design_issues/ITL-847-SJ1.md b/docs/dev/design_issues/ITL-847-SJ1.md similarity index 100% rename from design_issues/ITL-847-SJ1.md rename to docs/dev/design_issues/ITL-847-SJ1.md diff --git a/design_issues/ITL-849-SI1.md b/docs/dev/design_issues/ITL-849-SI1.md similarity index 100% rename from design_issues/ITL-849-SI1.md rename to docs/dev/design_issues/ITL-849-SI1.md diff --git a/design_issues/ITL-864-DW1.md b/docs/dev/design_issues/ITL-864-DW1.md similarity index 100% rename from design_issues/ITL-864-DW1.md rename to docs/dev/design_issues/ITL-864-DW1.md diff --git a/design_issues/ITL-865-O8.md b/docs/dev/design_issues/ITL-865-O8.md similarity index 100% rename from design_issues/ITL-865-O8.md rename to docs/dev/design_issues/ITL-865-O8.md diff --git a/design_issues/ITL-871-TT1.md b/docs/dev/design_issues/ITL-871-TT1.md similarity index 100% rename from design_issues/ITL-871-TT1.md rename to docs/dev/design_issues/ITL-871-TT1.md diff --git a/design_issues/ITL-878-SW1.md b/docs/dev/design_issues/ITL-878-SW1.md similarity index 100% rename from design_issues/ITL-878-SW1.md rename to docs/dev/design_issues/ITL-878-SW1.md diff --git a/design_issues/ITL-879-EP1.md b/docs/dev/design_issues/ITL-879-EP1.md similarity index 100% rename from design_issues/ITL-879-EP1.md rename to docs/dev/design_issues/ITL-879-EP1.md diff --git a/design_issues/ITL-884-DR1.md b/docs/dev/design_issues/ITL-884-DR1.md similarity index 100% rename from design_issues/ITL-884-DR1.md rename to docs/dev/design_issues/ITL-884-DR1.md diff --git a/design_issues/ITL-888-AR1.md b/docs/dev/design_issues/ITL-888-AR1.md similarity index 95% rename from design_issues/ITL-888-AR1.md rename to docs/dev/design_issues/ITL-888-AR1.md index 8b0537595..f33167864 100644 --- a/design_issues/ITL-888-AR1.md +++ b/docs/dev/design_issues/ITL-888-AR1.md @@ -29,5 +29,5 @@ instead. Tighten under a new storage version once nested nullability survives Po **Superseded (ITL-981, November 12, 2026):** the struct storage and the layout-independent hash described above were replaced before any release by `.npy` storage under `orcapod.numpy.ndarray` and a strict value hash with a per-type ignore list; see entry LV1 -(`design_issues/ITL-981-LV1.md`). The refusals, the declared-output check and the v0.2 +(`docs/dev/design_issues/ITL-981-LV1.md`). The refusals, the declared-output check and the v0.2 statements of this entry still hold. diff --git a/design_issues/ITL-892-DX1.md b/docs/dev/design_issues/ITL-892-DX1.md similarity index 100% rename from design_issues/ITL-892-DX1.md rename to docs/dev/design_issues/ITL-892-DX1.md diff --git a/design_issues/ITL-895-FO1.md b/docs/dev/design_issues/ITL-895-FO1.md similarity index 100% rename from design_issues/ITL-895-FO1.md rename to docs/dev/design_issues/ITL-895-FO1.md diff --git a/design_issues/ITL-895-FO2.md b/docs/dev/design_issues/ITL-895-FO2.md similarity index 100% rename from design_issues/ITL-895-FO2.md rename to docs/dev/design_issues/ITL-895-FO2.md diff --git a/design_issues/ITL-895-FO3.md b/docs/dev/design_issues/ITL-895-FO3.md similarity index 100% rename from design_issues/ITL-895-FO3.md rename to docs/dev/design_issues/ITL-895-FO3.md diff --git a/design_issues/ITL-896-OR1.md b/docs/dev/design_issues/ITL-896-OR1.md similarity index 100% rename from design_issues/ITL-896-OR1.md rename to docs/dev/design_issues/ITL-896-OR1.md diff --git a/design_issues/ITL-897-PV1.md b/docs/dev/design_issues/ITL-897-PV1.md similarity index 100% rename from design_issues/ITL-897-PV1.md rename to docs/dev/design_issues/ITL-897-PV1.md diff --git a/design_issues/ITL-904-PJLOAD1.md b/docs/dev/design_issues/ITL-904-PJLOAD1.md similarity index 99% rename from design_issues/ITL-904-PJLOAD1.md rename to docs/dev/design_issues/ITL-904-PJLOAD1.md index 060d257b2..6d501a89d 100644 --- a/design_issues/ITL-904-PJLOAD1.md +++ b/docs/dev/design_issues/ITL-904-PJLOAD1.md @@ -97,4 +97,4 @@ longer raises on a database without its run's records; it returns what the datab file's optional, advisory `run.expected_rows` makes a difference one `OrcapodDatabaseContentWarning` per node. Likewise, a loaded REPLAY operator whose job file records its run's content hash reads an absent cache table as no rows instead of raising. See -`design_issues/ITL-1043-LJ1.md`. +`docs/dev/design_issues/ITL-1043-LJ1.md`. diff --git a/design_issues/ITL-905-DO1.md b/docs/dev/design_issues/ITL-905-DO1.md similarity index 100% rename from design_issues/ITL-905-DO1.md rename to docs/dev/design_issues/ITL-905-DO1.md diff --git a/design_issues/ITL-906-O7.md b/docs/dev/design_issues/ITL-906-O7.md similarity index 100% rename from design_issues/ITL-906-O7.md rename to docs/dev/design_issues/ITL-906-O7.md diff --git a/design_issues/ITL-910-HS2.md b/docs/dev/design_issues/ITL-910-HS2.md similarity index 100% rename from design_issues/ITL-910-HS2.md rename to docs/dev/design_issues/ITL-910-HS2.md diff --git a/design_issues/ITL-912-ZR1.md b/docs/dev/design_issues/ITL-912-ZR1.md similarity index 100% rename from design_issues/ITL-912-ZR1.md rename to docs/dev/design_issues/ITL-912-ZR1.md diff --git a/design_issues/ITL-919-PQ1.md b/docs/dev/design_issues/ITL-919-PQ1.md similarity index 100% rename from design_issues/ITL-919-PQ1.md rename to docs/dev/design_issues/ITL-919-PQ1.md diff --git a/design_issues/ITL-926-SP2.md b/docs/dev/design_issues/ITL-926-SP2.md similarity index 100% rename from design_issues/ITL-926-SP2.md rename to docs/dev/design_issues/ITL-926-SP2.md diff --git a/design_issues/ITL-928-DT1.md b/docs/dev/design_issues/ITL-928-DT1.md similarity index 100% rename from design_issues/ITL-928-DT1.md rename to docs/dev/design_issues/ITL-928-DT1.md diff --git a/design_issues/ITL-928-FN1.md b/docs/dev/design_issues/ITL-928-FN1.md similarity index 94% rename from design_issues/ITL-928-FN1.md rename to docs/dev/design_issues/ITL-928-FN1.md index 361f168e2..4adda65ed 100644 --- a/design_issues/ITL-928-FN1.md +++ b/docs/dev/design_issues/ITL-928-FN1.md @@ -24,4 +24,4 @@ concatenated by name; rows that disagree on a column's Arrow type raise `InputValidationError` naming the column and both types, never a widened type. No stored value, record id or hash changes. The zero-row table of a node that has not run is still built from the Python output schema (the ITL-912 problem, for function nodes). -The Delta database's own type changes are entry DT1 (`design_issues/ITL-928-DT1.md`). +The Delta database's own type changes are entry DT1 (`docs/dev/design_issues/ITL-928-DT1.md`). diff --git a/design_issues/ITL-935-LTI1.md b/docs/dev/design_issues/ITL-935-LTI1.md similarity index 100% rename from design_issues/ITL-935-LTI1.md rename to docs/dev/design_issues/ITL-935-LTI1.md diff --git a/design_issues/ITL-936-SP3.md b/docs/dev/design_issues/ITL-936-SP3.md similarity index 100% rename from design_issues/ITL-936-SP3.md rename to docs/dev/design_issues/ITL-936-SP3.md diff --git a/design_issues/ITL-939-TD1.md b/docs/dev/design_issues/ITL-939-TD1.md similarity index 100% rename from design_issues/ITL-939-TD1.md rename to docs/dev/design_issues/ITL-939-TD1.md diff --git a/design_issues/ITL-940-TD1.md b/docs/dev/design_issues/ITL-940-TD1.md similarity index 100% rename from design_issues/ITL-940-TD1.md rename to docs/dev/design_issues/ITL-940-TD1.md diff --git a/design_issues/ITL-942-WH1.md b/docs/dev/design_issues/ITL-942-WH1.md similarity index 100% rename from design_issues/ITL-942-WH1.md rename to docs/dev/design_issues/ITL-942-WH1.md diff --git a/design_issues/ITL-943-DN1.md b/docs/dev/design_issues/ITL-943-DN1.md similarity index 100% rename from design_issues/ITL-943-DN1.md rename to docs/dev/design_issues/ITL-943-DN1.md diff --git a/design_issues/ITL-944-DC1.md b/docs/dev/design_issues/ITL-944-DC1.md similarity index 100% rename from design_issues/ITL-944-DC1.md rename to docs/dev/design_issues/ITL-944-DC1.md diff --git a/design_issues/ITL-945-HL1.md b/docs/dev/design_issues/ITL-945-HL1.md similarity index 100% rename from design_issues/ITL-945-HL1.md rename to docs/dev/design_issues/ITL-945-HL1.md diff --git a/design_issues/ITL-953-FD1.md b/docs/dev/design_issues/ITL-953-FD1.md similarity index 100% rename from design_issues/ITL-953-FD1.md rename to docs/dev/design_issues/ITL-953-FD1.md diff --git a/design_issues/ITL-954-DC2.md b/docs/dev/design_issues/ITL-954-DC2.md similarity index 100% rename from design_issues/ITL-954-DC2.md rename to docs/dev/design_issues/ITL-954-DC2.md diff --git a/design_issues/ITL-955-GB1.md b/docs/dev/design_issues/ITL-955-GB1.md similarity index 100% rename from design_issues/ITL-955-GB1.md rename to docs/dev/design_issues/ITL-955-GB1.md diff --git a/design_issues/ITL-957-S2.md b/docs/dev/design_issues/ITL-957-S2.md similarity index 100% rename from design_issues/ITL-957-S2.md rename to docs/dev/design_issues/ITL-957-S2.md diff --git a/design_issues/ITL-967-WH2.md b/docs/dev/design_issues/ITL-967-WH2.md similarity index 100% rename from design_issues/ITL-967-WH2.md rename to docs/dev/design_issues/ITL-967-WH2.md diff --git a/design_issues/ITL-972-UCK1.md b/docs/dev/design_issues/ITL-972-UCK1.md similarity index 100% rename from design_issues/ITL-972-UCK1.md rename to docs/dev/design_issues/ITL-972-UCK1.md diff --git a/design_issues/ITL-981-LV1.md b/docs/dev/design_issues/ITL-981-LV1.md similarity index 100% rename from design_issues/ITL-981-LV1.md rename to docs/dev/design_issues/ITL-981-LV1.md diff --git a/design_issues/ITL-988-CP1.md b/docs/dev/design_issues/ITL-988-CP1.md similarity index 100% rename from design_issues/ITL-988-CP1.md rename to docs/dev/design_issues/ITL-988-CP1.md diff --git a/design_issues/ITL-991-PV1.md b/docs/dev/design_issues/ITL-991-PV1.md similarity index 100% rename from design_issues/ITL-991-PV1.md rename to docs/dev/design_issues/ITL-991-PV1.md diff --git a/design_issues/ITL-996-SP5.md b/docs/dev/design_issues/ITL-996-SP5.md similarity index 100% rename from design_issues/ITL-996-SP5.md rename to docs/dev/design_issues/ITL-996-SP5.md diff --git a/design_issues/NOISSUE-B1.md b/docs/dev/design_issues/NOISSUE-B1.md similarity index 100% rename from design_issues/NOISSUE-B1.md rename to docs/dev/design_issues/NOISSUE-B1.md diff --git a/design_issues/NOISSUE-B2.md b/docs/dev/design_issues/NOISSUE-B2.md similarity index 100% rename from design_issues/NOISSUE-B2.md rename to docs/dev/design_issues/NOISSUE-B2.md diff --git a/design_issues/NOISSUE-C1.md b/docs/dev/design_issues/NOISSUE-C1.md similarity index 100% rename from design_issues/NOISSUE-C1.md rename to docs/dev/design_issues/NOISSUE-C1.md diff --git a/design_issues/NOISSUE-CA2.md b/docs/dev/design_issues/NOISSUE-CA2.md similarity index 100% rename from design_issues/NOISSUE-CA2.md rename to docs/dev/design_issues/NOISSUE-CA2.md diff --git a/design_issues/NOISSUE-CFP1.md b/docs/dev/design_issues/NOISSUE-CFP1.md similarity index 100% rename from design_issues/NOISSUE-CFP1.md rename to docs/dev/design_issues/NOISSUE-CFP1.md diff --git a/design_issues/NOISSUE-D1.md b/docs/dev/design_issues/NOISSUE-D1.md similarity index 100% rename from design_issues/NOISSUE-D1.md rename to docs/dev/design_issues/NOISSUE-D1.md diff --git a/design_issues/NOISSUE-D2.md b/docs/dev/design_issues/NOISSUE-D2.md similarity index 100% rename from design_issues/NOISSUE-D2.md rename to docs/dev/design_issues/NOISSUE-D2.md diff --git a/design_issues/NOISSUE-D3.md b/docs/dev/design_issues/NOISSUE-D3.md similarity index 100% rename from design_issues/NOISSUE-D3.md rename to docs/dev/design_issues/NOISSUE-D3.md diff --git a/design_issues/NOISSUE-D4.md b/docs/dev/design_issues/NOISSUE-D4.md similarity index 100% rename from design_issues/NOISSUE-D4.md rename to docs/dev/design_issues/NOISSUE-D4.md diff --git a/design_issues/NOISSUE-D5.md b/docs/dev/design_issues/NOISSUE-D5.md similarity index 100% rename from design_issues/NOISSUE-D5.md rename to docs/dev/design_issues/NOISSUE-D5.md diff --git a/design_issues/NOISSUE-D6.md b/docs/dev/design_issues/NOISSUE-D6.md similarity index 100% rename from design_issues/NOISSUE-D6.md rename to docs/dev/design_issues/NOISSUE-D6.md diff --git a/design_issues/NOISSUE-D7.md b/docs/dev/design_issues/NOISSUE-D7.md similarity index 100% rename from design_issues/NOISSUE-D7.md rename to docs/dev/design_issues/NOISSUE-D7.md diff --git a/design_issues/NOISSUE-ET1.md b/docs/dev/design_issues/NOISSUE-ET1.md similarity index 100% rename from design_issues/NOISSUE-ET1.md rename to docs/dev/design_issues/NOISSUE-ET1.md diff --git a/design_issues/NOISSUE-F1.md b/docs/dev/design_issues/NOISSUE-F1.md similarity index 100% rename from design_issues/NOISSUE-F1.md rename to docs/dev/design_issues/NOISSUE-F1.md diff --git a/design_issues/NOISSUE-F10.md b/docs/dev/design_issues/NOISSUE-F10.md similarity index 100% rename from design_issues/NOISSUE-F10.md rename to docs/dev/design_issues/NOISSUE-F10.md diff --git a/design_issues/NOISSUE-F11.md b/docs/dev/design_issues/NOISSUE-F11.md similarity index 100% rename from design_issues/NOISSUE-F11.md rename to docs/dev/design_issues/NOISSUE-F11.md diff --git a/design_issues/NOISSUE-F12.md b/docs/dev/design_issues/NOISSUE-F12.md similarity index 100% rename from design_issues/NOISSUE-F12.md rename to docs/dev/design_issues/NOISSUE-F12.md diff --git a/design_issues/NOISSUE-F13.md b/docs/dev/design_issues/NOISSUE-F13.md similarity index 100% rename from design_issues/NOISSUE-F13.md rename to docs/dev/design_issues/NOISSUE-F13.md diff --git a/design_issues/NOISSUE-F14.md b/docs/dev/design_issues/NOISSUE-F14.md similarity index 100% rename from design_issues/NOISSUE-F14.md rename to docs/dev/design_issues/NOISSUE-F14.md diff --git a/design_issues/NOISSUE-F2.md b/docs/dev/design_issues/NOISSUE-F2.md similarity index 100% rename from design_issues/NOISSUE-F2.md rename to docs/dev/design_issues/NOISSUE-F2.md diff --git a/design_issues/NOISSUE-F3.md b/docs/dev/design_issues/NOISSUE-F3.md similarity index 100% rename from design_issues/NOISSUE-F3.md rename to docs/dev/design_issues/NOISSUE-F3.md diff --git a/design_issues/NOISSUE-F4.md b/docs/dev/design_issues/NOISSUE-F4.md similarity index 100% rename from design_issues/NOISSUE-F4.md rename to docs/dev/design_issues/NOISSUE-F4.md diff --git a/design_issues/NOISSUE-F5.md b/docs/dev/design_issues/NOISSUE-F5.md similarity index 100% rename from design_issues/NOISSUE-F5.md rename to docs/dev/design_issues/NOISSUE-F5.md diff --git a/design_issues/NOISSUE-F6.md b/docs/dev/design_issues/NOISSUE-F6.md similarity index 100% rename from design_issues/NOISSUE-F6.md rename to docs/dev/design_issues/NOISSUE-F6.md diff --git a/design_issues/NOISSUE-F7.md b/docs/dev/design_issues/NOISSUE-F7.md similarity index 100% rename from design_issues/NOISSUE-F7.md rename to docs/dev/design_issues/NOISSUE-F7.md diff --git a/design_issues/NOISSUE-F8.md b/docs/dev/design_issues/NOISSUE-F8.md similarity index 100% rename from design_issues/NOISSUE-F8.md rename to docs/dev/design_issues/NOISSUE-F8.md diff --git a/design_issues/NOISSUE-F9.md b/docs/dev/design_issues/NOISSUE-F9.md similarity index 100% rename from design_issues/NOISSUE-F9.md rename to docs/dev/design_issues/NOISSUE-F9.md diff --git a/design_issues/NOISSUE-FN1.md b/docs/dev/design_issues/NOISSUE-FN1.md similarity index 100% rename from design_issues/NOISSUE-FN1.md rename to docs/dev/design_issues/NOISSUE-FN1.md diff --git a/design_issues/NOISSUE-G1.md b/docs/dev/design_issues/NOISSUE-G1.md similarity index 100% rename from design_issues/NOISSUE-G1.md rename to docs/dev/design_issues/NOISSUE-G1.md diff --git a/design_issues/NOISSUE-G2.md b/docs/dev/design_issues/NOISSUE-G2.md similarity index 100% rename from design_issues/NOISSUE-G2.md rename to docs/dev/design_issues/NOISSUE-G2.md diff --git a/design_issues/NOISSUE-H1-2.md b/docs/dev/design_issues/NOISSUE-H1-2.md similarity index 100% rename from design_issues/NOISSUE-H1-2.md rename to docs/dev/design_issues/NOISSUE-H1-2.md diff --git a/design_issues/NOISSUE-H1.md b/docs/dev/design_issues/NOISSUE-H1.md similarity index 100% rename from design_issues/NOISSUE-H1.md rename to docs/dev/design_issues/NOISSUE-H1.md diff --git a/design_issues/NOISSUE-H2.md b/docs/dev/design_issues/NOISSUE-H2.md similarity index 100% rename from design_issues/NOISSUE-H2.md rename to docs/dev/design_issues/NOISSUE-H2.md diff --git a/design_issues/NOISSUE-H3.md b/docs/dev/design_issues/NOISSUE-H3.md similarity index 100% rename from design_issues/NOISSUE-H3.md rename to docs/dev/design_issues/NOISSUE-H3.md diff --git a/design_issues/NOISSUE-H4.md b/docs/dev/design_issues/NOISSUE-H4.md similarity index 100% rename from design_issues/NOISSUE-H4.md rename to docs/dev/design_issues/NOISSUE-H4.md diff --git a/design_issues/NOISSUE-O1.md b/docs/dev/design_issues/NOISSUE-O1.md similarity index 100% rename from design_issues/NOISSUE-O1.md rename to docs/dev/design_issues/NOISSUE-O1.md diff --git a/design_issues/NOISSUE-O2.md b/docs/dev/design_issues/NOISSUE-O2.md similarity index 100% rename from design_issues/NOISSUE-O2.md rename to docs/dev/design_issues/NOISSUE-O2.md diff --git a/design_issues/NOISSUE-O4.md b/docs/dev/design_issues/NOISSUE-O4.md similarity index 100% rename from design_issues/NOISSUE-O4.md rename to docs/dev/design_issues/NOISSUE-O4.md diff --git a/design_issues/NOISSUE-O5.md b/docs/dev/design_issues/NOISSUE-O5.md similarity index 100% rename from design_issues/NOISSUE-O5.md rename to docs/dev/design_issues/NOISSUE-O5.md diff --git a/design_issues/NOISSUE-P1.md b/docs/dev/design_issues/NOISSUE-P1.md similarity index 100% rename from design_issues/NOISSUE-P1.md rename to docs/dev/design_issues/NOISSUE-P1.md diff --git a/design_issues/NOISSUE-P2.md b/docs/dev/design_issues/NOISSUE-P2.md similarity index 100% rename from design_issues/NOISSUE-P2.md rename to docs/dev/design_issues/NOISSUE-P2.md diff --git a/design_issues/NOISSUE-P3.md b/docs/dev/design_issues/NOISSUE-P3.md similarity index 100% rename from design_issues/NOISSUE-P3.md rename to docs/dev/design_issues/NOISSUE-P3.md diff --git a/design_issues/NOISSUE-P4.md b/docs/dev/design_issues/NOISSUE-P4.md similarity index 100% rename from design_issues/NOISSUE-P4.md rename to docs/dev/design_issues/NOISSUE-P4.md diff --git a/design_issues/NOISSUE-P5.md b/docs/dev/design_issues/NOISSUE-P5.md similarity index 100% rename from design_issues/NOISSUE-P5.md rename to docs/dev/design_issues/NOISSUE-P5.md diff --git a/design_issues/NOISSUE-P6.md b/docs/dev/design_issues/NOISSUE-P6.md similarity index 100% rename from design_issues/NOISSUE-P6.md rename to docs/dev/design_issues/NOISSUE-P6.md diff --git a/design_issues/NOISSUE-P7.md b/docs/dev/design_issues/NOISSUE-P7.md similarity index 100% rename from design_issues/NOISSUE-P7.md rename to docs/dev/design_issues/NOISSUE-P7.md diff --git a/design_issues/NOISSUE-PF1.md b/docs/dev/design_issues/NOISSUE-PF1.md similarity index 100% rename from design_issues/NOISSUE-PF1.md rename to docs/dev/design_issues/NOISSUE-PF1.md diff --git a/design_issues/NOISSUE-RC1.md b/docs/dev/design_issues/NOISSUE-RC1.md similarity index 100% rename from design_issues/NOISSUE-RC1.md rename to docs/dev/design_issues/NOISSUE-RC1.md diff --git a/design_issues/NOISSUE-S1.md b/docs/dev/design_issues/NOISSUE-S1.md similarity index 100% rename from design_issues/NOISSUE-S1.md rename to docs/dev/design_issues/NOISSUE-S1.md diff --git a/design_issues/NOISSUE-ST1.md b/docs/dev/design_issues/NOISSUE-ST1.md similarity index 100% rename from design_issues/NOISSUE-ST1.md rename to docs/dev/design_issues/NOISSUE-ST1.md diff --git a/design_issues/NOISSUE-ST2.md b/docs/dev/design_issues/NOISSUE-ST2.md similarity index 100% rename from design_issues/NOISSUE-ST2.md rename to docs/dev/design_issues/NOISSUE-ST2.md diff --git a/design_issues/NOISSUE-ST3.md b/docs/dev/design_issues/NOISSUE-ST3.md similarity index 100% rename from design_issues/NOISSUE-ST3.md rename to docs/dev/design_issues/NOISSUE-ST3.md diff --git a/design_issues/NOISSUE-T1.md b/docs/dev/design_issues/NOISSUE-T1.md similarity index 100% rename from design_issues/NOISSUE-T1.md rename to docs/dev/design_issues/NOISSUE-T1.md diff --git a/design_issues/NOISSUE-T2.md b/docs/dev/design_issues/NOISSUE-T2.md similarity index 100% rename from design_issues/NOISSUE-T2.md rename to docs/dev/design_issues/NOISSUE-T2.md diff --git a/design_issues/NOISSUE-U1.md b/docs/dev/design_issues/NOISSUE-U1.md similarity index 100% rename from design_issues/NOISSUE-U1.md rename to docs/dev/design_issues/NOISSUE-U1.md diff --git a/design_issues/NOISSUE-U2.md b/docs/dev/design_issues/NOISSUE-U2.md similarity index 100% rename from design_issues/NOISSUE-U2.md rename to docs/dev/design_issues/NOISSUE-U2.md diff --git a/design_issues/NOISSUE-U3.md b/docs/dev/design_issues/NOISSUE-U3.md similarity index 100% rename from design_issues/NOISSUE-U3.md rename to docs/dev/design_issues/NOISSUE-U3.md diff --git a/design_issues/NOISSUE-U4.md b/docs/dev/design_issues/NOISSUE-U4.md similarity index 100% rename from design_issues/NOISSUE-U4.md rename to docs/dev/design_issues/NOISSUE-U4.md diff --git a/design_issues/PLT-1732-ET2.md b/docs/dev/design_issues/PLT-1732-ET2.md similarity index 100% rename from design_issues/PLT-1732-ET2.md rename to docs/dev/design_issues/PLT-1732-ET2.md diff --git a/design_issues/PLT-1773-SP1.md b/docs/dev/design_issues/PLT-1773-SP1.md similarity index 100% rename from design_issues/PLT-1773-SP1.md rename to docs/dev/design_issues/PLT-1773-SP1.md diff --git a/design_issues/PLT-1795-CA1.md b/docs/dev/design_issues/PLT-1795-CA1.md similarity index 100% rename from design_issues/PLT-1795-CA1.md rename to docs/dev/design_issues/PLT-1795-CA1.md diff --git a/design_issues/PLT-4816-DOC1.md b/docs/dev/design_issues/PLT-4816-DOC1.md similarity index 100% rename from design_issues/PLT-4816-DOC1.md rename to docs/dev/design_issues/PLT-4816-DOC1.md diff --git a/design_issues/PLT-4864-TUT1.md b/docs/dev/design_issues/PLT-4864-TUT1.md similarity index 100% rename from design_issues/PLT-4864-TUT1.md rename to docs/dev/design_issues/PLT-4864-TUT1.md diff --git a/design_issues/README.md b/docs/dev/design_issues/README.md similarity index 82% rename from design_issues/README.md rename to docs/dev/design_issues/README.md index 253340efd..12ecefad6 100644 --- a/design_issues/README.md +++ b/docs/dev/design_issues/README.md @@ -4,6 +4,10 @@ The log of known design problems, bugs and code-quality issues: one file per ent (developer, November 11, 2026; ITL-968). It replaces the single file `DESIGN_ISSUES.md`, so two pull requests that add or update different entries never conflict. +The log was the top-level `design_issues/` until ITL-1169 moved it here. A branch that adds or +edits an entry at the old path fails `--check` after it merges `main`; move the file: +`git mv design_issues/<file> docs/dev/design_issues/`. + ## Reading the log ``` @@ -14,12 +18,12 @@ uv run python scripts/design_issues.py --full # the text of every entry The index gives each entry's id, status, severity, Linear issue, file name and title under its area heading, and ends with a count by status. To find one entry, search this directory for its -id: `ls design_issues/*-GB1.md`. +id: `ls docs/dev/design_issues/*-GB1.md`. ## An entry file -The file is `design_issues/<LINEAR-ISSUE-ID>-<ENTRY-ID>.md`, for example -`design_issues/ITL-955-GB1.md`: +The file is `docs/dev/design_issues/<LINEAR-ISSUE-ID>-<ENTRY-ID>.md`, for example +`docs/dev/design_issues/ITL-955-GB1.md`: ```markdown ## `src/orcapod/core/operators/group_by.py` — tags entering the data group (ITL-955) @@ -39,7 +43,7 @@ What is wrong, where, and what it causes. heading of an existing entry when yours belongs to the same area. - Then a blank line and `### <ENTRY-ID> — <title>` (an em dash). The entry id is a short tag in capital letters and digits, for example `GB1`; pick one that no other entry uses - (`ls design_issues/`). It is the id in the file name. + (`ls docs/dev/design_issues/`). It is the id in the file name. - Directly under the heading: `**Status:**`, `**Severity:**`, `**Issue:**`, in that order. - Status is `open`, `in progress` or `resolved`. A qualification may follow the word (`resolved (local stores); cloud stores remain exposed upstream`). @@ -83,7 +87,7 @@ closed. `tests/test_design_issues.py` runs the same check, so CI rejects a malfo ## Entries older than this convention The entries that were in `DESIGN_ISSUES.md` were moved here with their text unchanged by -`scripts/migrate_design_issues.py`. Three things in them are tolerated and are not for new +a one-shot migration script (ITL-968; removed in ITL-1169). Three things in them are tolerated and are not for new entries: - **No Linear issue.** An entry with no `**Issue:**` line is named `NOISSUE-<ENTRY-ID>.md`. @@ -96,12 +100,13 @@ entries: A branch that still edits an entry in `DESIGN_ISSUES.md` conflicts once when it merges `main` (the file is deleted there). While that merge is in progress, keep the branch's -copy, then: +copy, then take the migration script from a `main` commit that still has it and run it: ``` -uv run python scripts/migrate_design_issues.py --source DESIGN_ISSUES.md +git show 37716c76:scripts/migrate_design_issues.py > /tmp/migrate_design_issues.py +uv run python /tmp/migrate_design_issues.py --source DESIGN_ISSUES.md --out docs/dev/design_issues git rm -f DESIGN_ISSUES.md -git diff MERGE_HEAD --stat -- design_issues/ +git diff MERGE_HEAD --stat -- docs/dev/design_issues/ ``` The script prints `created:` for each entry the branch added and `updated:` for each entry @@ -111,5 +116,5 @@ the last command must list only the entries your branch added or edited. Put eve file back before committing the merge: ``` -git checkout MERGE_HEAD -- design_issues/<file> +git checkout MERGE_HEAD -- docs/dev/design_issues/<file> ``` diff --git a/orcapod-design.md b/docs/dev/orcapod-design.md similarity index 100% rename from orcapod-design.md rename to docs/dev/orcapod-design.md diff --git a/docs/plans/2026-03-26-postgresql-table-source.md b/docs/dev/plans/2026-03-26-postgresql-table-source.md similarity index 100% rename from docs/plans/2026-03-26-postgresql-table-source.md rename to docs/dev/plans/2026-03-26-postgresql-table-source.md diff --git a/docs/design/plans/2026-03-26-sqlite-table-source.md b/docs/dev/plans/2026-03-26-sqlite-table-source.md similarity index 100% rename from docs/design/plans/2026-03-26-sqlite-table-source.md rename to docs/dev/plans/2026-03-26-sqlite-table-source.md diff --git a/docs/plans/2026-03-27-non-active-node-semantics.md b/docs/dev/plans/2026-03-27-non-active-node-semantics.md similarity index 100% rename from docs/plans/2026-03-27-non-active-node-semantics.md rename to docs/dev/plans/2026-03-27-non-active-node-semantics.md diff --git a/docs/metamorphic/plans/2026-06-08-remove-rest-docstring-markup.md b/docs/dev/plans/2026-06-08-remove-rest-docstring-markup.md similarity index 100% rename from docs/metamorphic/plans/2026-06-08-remove-rest-docstring-markup.md rename to docs/dev/plans/2026-06-08-remove-rest-docstring-markup.md diff --git a/docs/metamorphic/plans/2026-06-30-itl-451-op-directory-type.md b/docs/dev/plans/2026-06-30-itl-451-op-directory-type.md similarity index 100% rename from docs/metamorphic/plans/2026-06-30-itl-451-op-directory-type.md rename to docs/dev/plans/2026-06-30-itl-451-op-directory-type.md diff --git a/docs/metamorphic/plans/2026-07-07-itl-474-opfile-url-form-identity.md b/docs/dev/plans/2026-07-07-itl-474-opfile-url-form-identity.md similarity index 100% rename from docs/metamorphic/plans/2026-07-07-itl-474-opfile-url-form-identity.md rename to docs/dev/plans/2026-07-07-itl-474-opfile-url-form-identity.md diff --git a/docs/metamorphic/plans/2026-07-08-itl-10-dataclass-dataframe-tests.md b/docs/dev/plans/2026-07-08-itl-10-dataclass-dataframe-tests.md similarity index 100% rename from docs/metamorphic/plans/2026-07-08-itl-10-dataclass-dataframe-tests.md rename to docs/dev/plans/2026-07-08-itl-10-dataclass-dataframe-tests.md diff --git a/docs/metamorphic/plans/2026-07-08-itl-507-ephemeral-coverage-tests.md b/docs/dev/plans/2026-07-08-itl-507-ephemeral-coverage-tests.md similarity index 100% rename from docs/metamorphic/plans/2026-07-08-itl-507-ephemeral-coverage-tests.md rename to docs/dev/plans/2026-07-08-itl-507-ephemeral-coverage-tests.md diff --git a/docs/metamorphic/plans/2026-07-08-itl-513-stale-entry-cleanup.md b/docs/dev/plans/2026-07-08-itl-513-stale-entry-cleanup.md similarity index 100% rename from docs/metamorphic/plans/2026-07-08-itl-513-stale-entry-cleanup.md rename to docs/dev/plans/2026-07-08-itl-513-stale-entry-cleanup.md diff --git a/docs/metamorphic/plans/2026-07-13-itl-522-match-mtime-flag.md b/docs/dev/plans/2026-07-13-itl-522-match-mtime-flag.md similarity index 100% rename from docs/metamorphic/plans/2026-07-13-itl-522-match-mtime-flag.md rename to docs/dev/plans/2026-07-13-itl-522-match-mtime-flag.md diff --git a/docs/metamorphic/plans/2026-07-21-itl-529-hash-audit-reference.md b/docs/dev/plans/2026-07-21-itl-529-hash-audit-reference.md similarity index 100% rename from docs/metamorphic/plans/2026-07-21-itl-529-hash-audit-reference.md rename to docs/dev/plans/2026-07-21-itl-529-hash-audit-reference.md diff --git a/docs/specs/2026-03-26-postgresql-table-source-design.md b/docs/dev/specs/2026-03-26-postgresql-table-source-design.md similarity index 100% rename from docs/specs/2026-03-26-postgresql-table-source-design.md rename to docs/dev/specs/2026-03-26-postgresql-table-source-design.md diff --git a/docs/design/specs/2026-03-26-sqlite-table-source-design.md b/docs/dev/specs/2026-03-26-sqlite-table-source-design.md similarity index 100% rename from docs/design/specs/2026-03-26-sqlite-table-source-design.md rename to docs/dev/specs/2026-03-26-sqlite-table-source-design.md diff --git a/docs/design/2026-03-27-non-active-node-semantics-design.md b/docs/dev/specs/2026-03-27-non-active-node-semantics-design.md similarity index 100% rename from docs/design/2026-03-27-non-active-node-semantics-design.md rename to docs/dev/specs/2026-03-27-non-active-node-semantics-design.md diff --git a/examples/dataset1/day1.txt b/examples/dataset1/day1.txt deleted file mode 100644 index 1b2ce50ff..000000000 --- a/examples/dataset1/day1.txt +++ /dev/null @@ -1,24 +0,0 @@ -# Server Configuration Settings -host_address = 192.168.1.100 -port = 8080 -max_connections = 500 -timeout_ms = 30000 - -[Database] -db_name = production_db -username = admin -password = ******** -pool_size = 25 -max_retries = 3 - -[Logging] -log_level = INFO -log_path = /var/log/app -rotate_size = 10MB -keep_days = 30 - -[Cache] -enable_cache = true -cache_type = redis -ttl_seconds = 3600 -max_items = 10000 \ No newline at end of file diff --git a/examples/dataset1/day2.txt b/examples/dataset1/day2.txt deleted file mode 100644 index e64df4f43..000000000 --- a/examples/dataset1/day2.txt +++ /dev/null @@ -1,15 +0,0 @@ -# Configuration file for dataset 2 -name = Dataset Day 2 -path = /home/eywalker/workspace/orcabridge/examples/dataset1 -file_type = raw_data -date = 2023-12-02 - -# Processing parameters -batch_size = 32 -sampling_rate = 1000 -channels = 16 - -# Output settings -output_format = binary -compression = enabled -save_path = /output/day2/ \ No newline at end of file diff --git a/examples/dataset1/day3.txt b/examples/dataset1/day3.txt deleted file mode 100644 index b3185f727..000000000 --- a/examples/dataset1/day3.txt +++ /dev/null @@ -1,27 +0,0 @@ -{ - "date": "2024-01-03", - "sessions": [ - { - "name": "session1", - "start_time": "09:00", - "end_time": "12:00", - "data_path": "/path/to/day3/session1", - "metadata": { - "subject_id": "subject1", - "experiment_type": "standard", - "notes": "Day 3 morning session" - } - }, - { - "name": "session2", - "start_time": "14:00", - "end_time": "17:00", - "data_path": "/path/to/day3/session2", - "metadata": { - "subject_id": "subject1", - "experiment_type": "standard", - "notes": "Day 3 afternoon session" - } - } - ] -} \ No newline at end of file diff --git a/examples/dataset1/day4.txt b/examples/dataset1/day4.txt deleted file mode 100644 index 06fad20c2..000000000 --- a/examples/dataset1/day4.txt +++ /dev/null @@ -1,22 +0,0 @@ -# Day 4 Configuration Settings - -input_path: /data/day4/ -output_path: /results/day4/ - -# Processing parameters -batch_size: 32 -max_workers: 4 -processing_mode: sequential - -# Data settings -file_format: csv -delimiter: ',' -skip_header: true - -# Logging -log_level: INFO -enable_debug: false - -# Additional parameters -timeout: 300 # seconds -retry_attempts: 3 \ No newline at end of file diff --git a/examples/dataset1/day6.txt b/examples/dataset1/day6.txt deleted file mode 100644 index 4fd8738c7..000000000 --- a/examples/dataset1/day6.txt +++ /dev/null @@ -1,22 +0,0 @@ -# Day 5 Configuration Settings - -input_path: /data/day5/ -output_path: /results/day5/ - -# Processing parameters -batch_size: 32 -max_workers: 4 -processing_mode: sequential - -# Data settings -file_format: csv -delimiter: ',' -skip_header: true - -# Logging -log_level: INFO -enable_debug: false - -# Additional parameters -timeout: 300 # seconds -retry_attempts: 3 \ No newline at end of file diff --git a/examples/dataset2/info_day1.json b/examples/dataset2/info_day1.json deleted file mode 100644 index 84cbfa5f7..000000000 --- a/examples/dataset2/info_day1.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "name": "Day 1 experiment", - "description": "This is the first day of the experiment.", - "experimenter": "John Doe", - "date": "2023-10-01" -} \ No newline at end of file diff --git a/examples/dataset2/info_day2.json b/examples/dataset2/info_day2.json deleted file mode 100644 index 842cbd89a..000000000 --- a/examples/dataset2/info_day2.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "name": "Day 2 experiment", - "description": "This is the second day of the experiment.", - "experimenter": "John Doe", - "date": "2023-10-02" -} \ No newline at end of file diff --git a/examples/dataset2/info_day3.json b/examples/dataset2/info_day3.json deleted file mode 100644 index 891e4808e..000000000 --- a/examples/dataset2/info_day3.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "name": "Day 3 experiment", - "description": "This is the third day of the experiment.", - "experimenter": "Mary Smith", - "date": "2023-10-05" -} \ No newline at end of file diff --git a/examples/dataset2/info_day4.json b/examples/dataset2/info_day4.json deleted file mode 100644 index 3778fc8a2..000000000 --- a/examples/dataset2/info_day4.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "name": "Day 3 experiment", - "description": "This is the fourth day of the experiment.", - "experimenter": "Mary Smith", - "date": "2023-10-06" -} \ No newline at end of file diff --git a/examples/dataset2/info_day5.json b/examples/dataset2/info_day5.json deleted file mode 100644 index 6cf194c21..000000000 --- a/examples/dataset2/info_day5.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "name": "Day 5 experiment", - "description": "This is the fifth day of the experiment.", - "experimenter": "Paul Brown", - "date": "2023-10-09" -} \ No newline at end of file diff --git a/examples/dataset2/session_day1.bin b/examples/dataset2/session_day1.bin deleted file mode 100644 index 3e5e36976..000000000 --- a/examples/dataset2/session_day1.bin +++ /dev/null @@ -1,2 +0,0 @@ -Œõf?Pñ¿õ81 Ç`å¿ØRèÄÚoÛ? 5ôݷ¿*ۯÜR À‡k§6ÿ\õ?‘.? Æñ?Jm"¢íõ?…ëÝ7¿/ó¿ü;i·³?t‡­ú¦Íô?�fnhY Ñ?„¹‚ë?ñÿjÈØWÇ?>ÈÇF›’ê¿”,Í*–ú¿‘Øèë?3÷:0Œû¿mäöÓ픿ÕÎǿŽýk¾2­õ?è[î)„`æ?r:vÚgç?۶VÅC´±¿'\;Þiµ¿ b/É.'ݿkHí¤æ?¡" ¯Š]ð??SDp -ÓǿÜ%JÉ?ì?¶‚£®ø¿¾žáÛê¿ð?MÄAc¡ À;l¸r”õ¿¡'tÿ3Õã?Qh/ñ®տÔÙˏÆ2å?¸)±GHã?Jf�4bdÀùäŸNVzʿC^úl·¿rðZTuì? \ No newline at end of file diff --git a/examples/dataset2/session_day3.bin b/examples/dataset2/session_day3.bin deleted file mode 100644 index dc3e5cfc6..000000000 Binary files a/examples/dataset2/session_day3.bin and /dev/null differ diff --git a/examples/dataset2/session_day4.bin b/examples/dataset2/session_day4.bin deleted file mode 100644 index b662f84c2..000000000 Binary files a/examples/dataset2/session_day4.bin and /dev/null differ diff --git a/examples/dataset2/session_day5.bin b/examples/dataset2/session_day5.bin deleted file mode 100644 index d45eb957b..000000000 Binary files a/examples/dataset2/session_day5.bin and /dev/null differ diff --git a/function-execution-improvements-plan.md b/function-execution-improvements-plan.md deleted file mode 100644 index 9137f3579..000000000 --- a/function-execution-improvements-plan.md +++ /dev/null @@ -1,300 +0,0 @@ -# Function Execution Chain Improvements — Design & Implementation Plan - -## Overview - -This document captures design decisions for improving the executor integration in the -data function / function pod / function node execution chain. The changes address four -areas: - -1. **`with_options` semantics** — executors become immutable; `with_options()` always returns - a new instance. -2. **`execution_engine_opts` ownership** — removed from FunctionNode; owned exclusively by - the pipeline's executor-assignment logic. -3. **`CachedFunctionPod`** — a new pod-level caching wrapper complementing the existing - `CachedDataFunction` (data-level caching). -4. **Type-safe executor dispatch via `Generic[E]` + `__init_subclass__`** — eliminates - redundant `isinstance` checks in the hot path by resolving the executor protocol once at - class definition time. - ---- - -## 1. `with_options` Always Returns a New Instance - -### Current state - -`DataFunctionExecutorBase.with_options()` returns `self` by default. `RayExecutor` -overrides it to return a new instance. This is inconsistent — callers cannot rely on -`with_options()` being side-effect-free without checking the concrete type. - -### Design decision - -`with_options()` **must always return a new executor instance**, even when no options change. -This makes executors effectively immutable value objects after construction — the same -executor can be safely shared across nodes, and `with_options()` produces a node-specific -variant without mutating the original. - -### Changes - -- **`DataFunctionExecutorBase.with_options()`**: Default implementation returns - `copy.copy(self)` (shallow clone) instead of `self`. Subclasses that carry mutable state - (e.g. Ray handles) override to produce a properly configured new instance. -- **`DataFunctionExecutorProtocol.with_options()`**: Docstring updated to specify "returns - a **new** executor instance". -- **`LocalExecutor.with_options()`**: Returns a new `LocalExecutor()`. Trivial since it - carries no state. - ---- - -## 2. Remove `execution_engine_opts` from FunctionNode - -### Current state - -`FunctionNode.__init__` stores `self.execution_engine_opts: dict[str, Any] | None = None`. -This field is set externally (by the pipeline) and later read back during executor -assignment. The node becomes an awkward intermediary — it holds configuration that logically -belongs to the pipeline's executor-assignment step. - -### Design decision - -`execution_engine_opts` is **removed from FunctionNode entirely**. The pipeline's -`apply_executor` (or equivalent) logic is the sole owner: it reads per-node options from -the pipeline config, calls `executor.with_options(**merged_opts)`, and sets the resulting -executor directly on the data function. The node never sees raw option dicts. - -### Changes - -- **`FunctionNode.__init__`**: Remove `self.execution_engine_opts` attribute. -- **`FunctionNode.from_descriptor`**: Stop reading/writing `execution_engine_opts` from - descriptors. (Backward-compatible break is acceptable per project policy — pre-v0.1.0.) -- **Pipeline executor assignment** (in `pipeline/` module): Merge pipeline-level and - per-node options, call `executor.with_options(**merged)`, then assign the resulting - executor to `node.executor = configured_executor`. - ---- - -## 3. `CachedFunctionPod` — Pod-Level Caching - -### Current state - -Caching exists only at the data-function level (`CachedDataFunction`), which wraps -`call()` / `async_call()` with DB lookup/insert. This works but cannot leverage tag -information (which is invisible to data functions). - -### Design decision - -Add a **`CachedFunctionPod`** that wraps a `FunctionPod` and intercepts at the -`process_data(tag, data)` level. This complements `CachedDataFunction`: - -| Layer | `CachedDataFunction` | `CachedFunctionPod` | -|-------|------------------------|---------------------| -| Intercepts at | `call(data)` | `process_data(tag, data)` | -| Has tag access | No | Yes | -| Cache key includes | Data content hash | Tag + data content hash | -| Delegates to | Wrapped `DataFunction.call()` | Inner `FunctionPod.process_data()` | - -Both are useful: `CachedDataFunction` deduplicates purely on data content; -`CachedFunctionPod` can incorporate tag metadata into cache decisions. - -### Implementation sketch - -```python -class CachedFunctionPod(WrappedFunctionPod): - """Pod-level caching wrapper that intercepts process_data().""" - - def __init__( - self, - function_pod: FunctionPodProtocol, - result_database: ArrowDatabaseProtocol, - record_path_prefix: tuple[str, ...] = (), - **kwargs, - ) -> None: - super().__init__(function_pod, **kwargs) - self._result_database = result_database - self._record_path_prefix = record_path_prefix - - def process_data( - self, tag: TagProtocol, data: DataProtocol - ) -> tuple[TagProtocol, DataProtocol | None]: - # Cache key incorporates both tag and data content - cache_key = self._compute_cache_key(tag, data) - cached = self._lookup(cache_key) - if cached is not None: - return tag, cached - tag, output = self._function_pod.process_data(tag, data) - if output is not None: - self._store(cache_key, tag, output) - return tag, output -``` - -### Changes - -- **New file**: `src/orcapod/core/cached_function_pod.py` containing `CachedFunctionPod`. -- **`function_pod` decorator**: Add `pod_cache_database` parameter that wraps the pod in - `CachedFunctionPod` when provided (distinct from `result_database` which wraps the data - function in `CachedDataFunction`). - ---- - -## 4. Type-Safe Executor Dispatch via `Generic[E]` + `__init_subclass__` - -### Problem - -Currently, each `DataFunctionBase` subclass that cares about executor-specific capabilities -must do `isinstance` checks in the hot path (`call()` / `direct_call()`). This is both -verbose and error-prone — forgetting to check means silent misuse. - -In Rust, an `enum Executor { Python(PythonExecutor), Container(ContainerExecutor) }` with -`match` would give exhaustive, zero-cost dispatch. Python has no sum types with exhaustiveness -checking, but we can get close. - -### Design decision - -Use `Generic[E]` on `DataFunctionBase` combined with `__init_subclass__` to resolve the -concrete executor protocol **once at class definition time**. The single `isinstance` check -moves to `set_executor()` (assignment boundary), and the hot path (`call()`) is clean. - -### Mechanism - -```python -from typing import Generic, TypeVar - -E = TypeVar("E", bound=DataFunctionExecutorProtocol) - -class DataFunctionBase(TraceableBase, Generic[E]): - _resolved_executor_protocol: ClassVar[type] # auto-set by __init_subclass__ - _executor: E | None = None - - def __init_subclass__(cls, **kwargs: Any) -> None: - super().__init_subclass__(**kwargs) - for base in cls.__orig_bases__: - origin = typing.get_origin(base) - if origin is DataFunctionBase: - args = typing.get_args(base) - if args and not isinstance(args[0], TypeVar): - cls._resolved_executor_protocol = args[0] - return - - def set_executor(self, executor: DataFunctionExecutorProtocol) -> None: - """Single isinstance check at assignment boundary.""" - proto = getattr(type(self), '_resolved_executor_protocol', None) - if proto is not None and not isinstance(executor, proto): - raise TypeError( - f"{type(self).__name__} requires {proto.__name__}, " - f"got {type(executor).__name__}" - ) - self._executor = executor # type: ignore[assignment] -``` - -Subclasses declare the executor type **once** via the generic parameter: - -```python -class PythonDataFunction(DataFunctionBase[PythonExecutorProtocol]): - # No _executor_protocol ClassVar needed — __init_subclass__ extracts it - # from Generic[PythonExecutorProtocol] automatically. - ... -``` - -### Why this works - -- **`__orig_bases__`** is set by Python's type machinery on every class that inherits from - a `Generic`. It contains the parameterized base (e.g. - `DataFunctionBase[PythonExecutorProtocol]`). -- **`typing.get_args()`** extracts the type parameters. -- **`__init_subclass__`** runs at class definition time (import), not at instance creation. - Zero per-instance overhead. -- The `isinstance(args[0], TypeVar)` guard skips intermediate abstract subclasses that - haven't bound `E` yet (e.g. `DataFunctionWrapper(DataFunctionBase[E])`). - -### Requirements - -- Executor protocols used as type parameters **must** be decorated with - `@runtime_checkable` (already the case for `DataFunctionExecutorProtocol`). -- Any new executor protocol (e.g. `PythonExecutorProtocol`) needs `@runtime_checkable` too. - -### Hot path after this change - -```python -def call(self, data: DataProtocol) -> DataProtocol | None: - if self._executor is not None: - # self._executor is statically typed as E (e.g. PythonExecutorProtocol). - # No isinstance check needed — validated at set_executor() time. - return self._executor.execute(self, data) - return self.direct_call(data) -``` - -### Changes - -- **`DataFunctionBase`**: Add `Generic[E]`, `__init_subclass__` resolver, - `set_executor()` method. Existing `executor` property setter delegates to `set_executor()`. -- **`PythonDataFunction`**: Change to `DataFunctionBase[PythonExecutorProtocol]` - (or a more specific `PythonExecutorProtocol` if we introduce one). -- **`DataFunctionWrapper`**: Change to `DataFunctionBase[E]` (remains generic, passes - through). -- **`CachedDataFunction`**: Inherits from `DataFunctionWrapper` — no changes needed - since executor delegation already targets the wrapped leaf function. -- **Executor protocols**: Ensure `@runtime_checkable` on all protocols that will be used as - generic parameters. - ---- - -## 5. `FunctionPod.data_function` Remains a Read-Only Property - -### Decision - -`FunctionPod.data_function` stays as a property on the protocol (as currently implemented). -It is understood to be **read-only** — callers should not replace the data function after -pod construction. The property exists for introspection and executor wiring, not mutation. - -No code changes needed — this is a documentation/convention clarification. - ---- - -## Implementation Plan - -### Phase 1: Executor immutability + remove `execution_engine_opts` - -1. Update `DataFunctionExecutorBase.with_options()` default to return a shallow copy. -2. Update `LocalExecutor.with_options()` to return `LocalExecutor()`. -3. Verify `RayExecutor.with_options()` already returns a new instance (it does). -4. Remove `self.execution_engine_opts` from `FunctionNode.__init__`. -5. Remove `execution_engine_opts` from `FunctionNode.from_descriptor` read-only state. -6. Update pipeline executor-assignment logic to merge options externally and pass the - configured executor in. -7. Update affected tests. - -### Phase 2: Type-safe executor dispatch - -1. Add `Generic[E]` and `__init_subclass__` to `DataFunctionBase`. -2. Update `executor` setter to delegate to `set_executor()` with `__init_subclass__`-resolved - protocol check. -3. Parameterize `PythonDataFunction` as `DataFunctionBase[DataFunctionExecutorProtocol]` - (or a narrower protocol if we introduce executor-type-specific protocols later). -4. Parameterize `DataFunctionWrapper` as `DataFunctionBase[E]`. -5. Ensure all executor protocols are `@runtime_checkable`. -6. Update tests to verify type checking at assignment time. - -### Phase 3: `CachedFunctionPod` - -1. Create `src/orcapod/core/cached_function_pod.py`. -2. Implement `CachedFunctionPod(WrappedFunctionPod)` with tag-aware cache key computation. -3. Add `pod_cache_database` parameter to `function_pod` decorator. -4. Add tests for pod-level vs data-level caching interaction. - -### Phase 4: Documentation and cleanup - -1. Update `orcapod-design.md` with the new execution chain design. -2. Update `CLAUDE.md` architecture section if needed. -3. Check `DESIGN_ISSUES.md` for any resolved issues. - ---- - -## Open Questions - -- **Executor-type-specific protocols**: Currently all data functions accept the base - `DataFunctionExecutorProtocol`. If we later want `PythonDataFunction` to only accept - executors with a `PythonExecutorProtocol` (which might require `execute(func, args)` - rather than `execute(pf, data)`), the `Generic[E]` mechanism already supports this — - just parameterize with the narrower protocol. -- **`CachedFunctionPod` cache key design**: The exact composition of the cache key (which - tag columns to include, whether to include system tags) needs detailed design during - implementation. A reasonable default is tag content hash + data content hash. diff --git a/mkdocs.yml b/mkdocs.yml index 412aa3a5a..b034cf587 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,11 @@ site_name: Orcapod site_description: Intuitive and powerful library for highly reproducible scientific data pipelines +# docs/dev holds developer material (the design issues log, the design specification); it is +# not part of the published site. +exclude_docs: | + dev/ + theme: name: material features: diff --git a/notebooks/old_tutorials/01_orcapod_core_concepts copy.ipynb b/notebooks/old_tutorials/01_orcapod_core_concepts copy.ipynb deleted file mode 100644 index 01badab7c..000000000 --- a/notebooks/old_tutorials/01_orcapod_core_concepts copy.ipynb +++ /dev/null @@ -1,85 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Core concepts" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In this notebook, I will introduce and define the core concepts relevant for Orcabridge and Orcapod. These concepts will be used throughout the Orca ecosystem and in the other tutorial notebooks, with many having directly corresponding Python classes/objects." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Below I define few critical concepts for Orcapod.\n", - "\n", - "* `Data` -- In Orcapod, the smallest unit of `data` is a single `file`. Unlike many other computation pipeline system, Orcapod pipeline in principle does **not** operate on `data` that's not a file. In other words, `Oracpod` pipeline will **not** pass a data in memory from one node to another. Consequently, all operations and processing in Orcapod pipeline revolves around `file` (NOTE: this is a particularly strong/restrictive version of Oracpod pipeline. We may consider extending data to things like environment variable and command line arguments)\n", - "* `Pathset` -- a unit of data that can be passed into a pod. A `pathset` consists of a file, a directory, or a collection of one or more file and directories.\n", - "* `Data` -- a single concrete instance of key-value pair, mapping data key to a single `pathset`.\n", - "* `Stream` -- a series of one or more `data` flowing from a `data producer` to a `data consumer`. In a directed acyclic graph represneing an Orcapod `pipeline`, a `stream` corresponds to a *directed* edge connecting from a data source into a `data consumer` (e.g., `pod`)\n", - "* `Data producer` and `data consumer` -- in the Orcapod data pipeline, data (in form of `data` of data flowing inside a `stream`) flows from a `data producer` to a `data consumer`. Consequentially, a `data consumer` may in turn act as a `data producer` downstream\n", - "* `Data source` -- Root level `data producer` (that is, the data originates from this `data producer` and it is not a `data consumer` of any stream). Typically `data source` is tied to a data storage, although you could have *procedural* `data source` where data data are produced programatically.\n", - "* `Tag` -- each `Data` in a stream *may be* associated with a `tag` that helps to assign semantic identity to the particular `data`. For example, a data `data` for an experimental data may be associated with a `tag` of session ID. Note that while `tag` provides a convenient and often meaningful ways of identifying and referring to specific data within a stream, it should **not** be considered to be the defining identity of the `data`. Identity of the `data` is strictly determined by the exact data content of the `data`, and not by how you refer to it. Consequently, it may be that two data with an identical content (and thus shared identity) are associated with distinct `tags` in a `stream`. Conversely, an identical `tag` may be associated with two distinct `data` in a stream. Typically, one would associate a unique `tag` for each data in the stream.\n", - "* `Operation` -- A *node* in the directed acyclic graph representing an Orcapod `pipeline`, corresponding to a step of data processing/transformation/computation. An `Operation` receives can be classified into either a `mapper` or a `pod` based on their role in `data provenance`.\n", - "* `Mapper` -- A class of `operation` that does **not** result in creation/alteration of a new data -- that is, `operation` does **not** every create or modify a file *content*. More specifically, `Mapper` operation can not produce a path that was not already present in the input streams to the `mapper`. This feature ensures that a `mapper` is fundamentally not involved in the reproducibility of computation. Consequently, `mapper` information is not necessary for the maintenance of proper `data provenance` in a tree of computation. However, `mapper` plays critical role in the actual execution of a data pipeline, determining which data `data` will be fed into operations in the pipeline directed acyclic graph (DAG). Note that as long as it doesn't modify the content of any file, a `mapper` may inspect the content of any file in a `data` it receives and alter its behavior based on the content of the file. In other words, `mapper` may alter what data file(s) gets passed around without changing/creating any file based on a rule that depends on `tag`, `data` key (`argument` name) and/or file content.\n", - "* `Pod` (e.g. FunctionPod) -- fundamental unit of computation in Orcapod. `Pod` is the only class of `operation` that may create a new file. Critically, when operating within an Orcapod `pipeline`, a `pod` will **not** receive the `tag` information. Rather, `pod` must strictly operate on a single `data`. An ideal `pod` will have completely deterministic behavior that only depends on the `data` identity (that is, data keys and `pathset` contents)." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## What is Orcabrdige?" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "`Orcabridge` provide prototypal implementation of the above-defined key concepts in `orcapod`, with particular focus given to `stream`, `data`, `tag`, `operation` (`pod` and `mapper`). This package provides the reference implementation of both synchronous and asynchronous `streams` as a sequence of `data` associated with a `tag`. " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "\n", - "### Key limitations\n", - "Being a very basic reference implementation with a goal of serving as a playground for conceptual and algorithmic development, there are a few notable limitations in `orcabridge`, lacking some important features that would be found in the full implementation of `orcapod`.\n", - "\n", - "* Limited `pathset` -- Only a very rudimentary implementation of a `pathset` can be found, where a typical `data` would be a simple key-value pair where the value is a single file path. \n", - "* `FunctionPod` in place of `pod` -- A ideal `pod` will represent a completely reproducible unit of computation with strict dependence on the input `data` to the `pod`. However, in `orcabridge` is equivalated to a Python function -- even more specifically, the name assigned to the Python function. In otherwords, two `FunctionPods` are considered identical if they share the same function name. Quite obviously this is a gross simplification that can be trivially violated. However, for the intended purpose of `orcabridge`, this rather simplistic implementation/definition of `pod` should suffice to test all features in the `pipeline`. Consequently, to ensure that the pipeline operates as expected, **do not use the same name for two distinct functions**. Doing so will break the fundamental assumption of `FunctionPod` and lead to completely erradic behavior. On the other hand, it is ok to have one or more name used to refer to an identical function.\n", - "* Different pipeline DAG defintion -- In `orcapod` the directed acyclic graph (DAG) for the `pipeline` should be defined using YAML file (or less frequently using API on `pipeline` struct in the Rust library). In `orcabridge` you will find that a `pipeline` DAG is defined dynamically through a series of application of `operation`. This is very much akin to how some DAG-based neural network library like TensorFlow defines a computation graph. While this works well for simple examples, it is rather difficult to track changes to the pipeline defined dynamically/programmatically using version control system. Since *how* you define the pipeline DAG is strictly speaking an orthogonal problem to the everything else that concerns the operation of the `pipeline`, no effort will be given to align the DAG definition in `orcabridge` and `orcapod`.\n", - "* Limited usage of a `stream` -- Currently `orcabrdige` only support single producer single consumer (SCSP) `stream`x, whereas in `orcapod`, `stream` should support single producer multiple consumer (SPMC) paradigm. While the same stream can be used in multiple downstream operations, each iteration of the stream actually results in recomputations of the entire chain of pipeline leading up to that stream. This inefficiency can be ameliorated by `CacheStream` operation after particularly computationally expensive segment of the pipeline. Using storage-backed `FunctionPod` will also help ameliorate the cost of recomputation by retrieving memoized computation result instead of recomputing." - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "venv", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.12" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/notebooks/old_tutorials/02_orcapod_basic_usage copy.ipynb b/notebooks/old_tutorials/02_orcapod_basic_usage copy.ipynb deleted file mode 100644 index 97af83dc5..000000000 --- a/notebooks/old_tutorials/02_orcapod_basic_usage copy.ipynb +++ /dev/null @@ -1,2856 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Using Orcabridge" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In this notebook, we will explore the basic usage of Orcabridge library." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Below we explore the usage of `orcabridge` package, enumerating the core components. Many of these will correspond directly to [core concepts](./01_orcabridge_core_concepts%20copy.ipynb) introduced in in [part 1](./01_orcabridge_core_concepts%20copy.ipynb)." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [], - "source": [ - "%load_ext autoreload\n", - "%autoreload\n", - "# import orcabridge package\n", - "import orcabridge as ob\n", - "import polars as pl\n", - "import pyarrow as pa" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from orcabridge.pod import TypedFunctionPod\n", - "from orcabridge.hashing.semantic_arrow_hasher import SemanticArrowHasher\n", - "from orcabridge.pod.core import CachedFunctionPod\n", - "from orcabridge.hashing.object_hashers import LegacyObjectHasher\n", - "from orcabridge.hashing.function_info_extractors import FunctionSignatureExtractor\n", - "from orcabridge.core.streams import SyncStreamFromLists\n", - "from orcabridge.types.registry import *" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [], - "source": [ - "from orcabridge.store.arrow_data_stores import (\n", - " ParquetArrowDataStore,\n", - " demo_single_row_constraint,\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "INFO:orcabridge.store.arrow_data_stores:Loading metadata index...\n", - "INFO:orcabridge.store.arrow_data_stores:Loaded metadata for 0 records\n", - "INFO:orcabridge.store.arrow_data_stores:Initialized lazy ParquetArrowDataStore at /tmp/tmprez6xpqd\n", - "WARNING:orcabridge.store.arrow_data_stores:User data contains 'entry_id' column. Consider removing it since '__entry_id' is tracked automatically.\n", - "INFO:orcabridge.store.arrow_data_stores:Added record experiments:dataset_A:entry_001_abcdef1234567890abcdef1234567890 with 1 rows\n", - "ERROR:orcabridge.store.arrow_data_stores:Schema mismatch for experiments/dataset_A:\n", - "ERROR:orcabridge.store.arrow_data_stores: Existing user columns: ['_user_entry_id', 'timestamp', 'value', 'category']\n", - "ERROR:orcabridge.store.arrow_data_stores: New user columns: ['entry_id', 'timestamp', 'value', 'category']\n", - "ERROR:orcabridge.store.arrow_data_stores: Missing in new: {'_user_entry_id'}\n", - "ERROR:orcabridge.store.arrow_data_stores: Extra in new: {'entry_id'}\n", - "INFO:orcabridge.store.arrow_data_stores:Shutting down ParquetArrowDataStore...\n", - "INFO:orcabridge.store.arrow_data_stores:Synced 1 dirty caches to disk\n", - "INFO:orcabridge.store.arrow_data_stores:Shutdown complete\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Testing Single-Row Constraint...\n", - "\n", - "=== Testing Valid Single-Row Records ===\n", - "✓ Added single-row record entry_001_abcdef... (value: 100.0)\n" - ] - }, - { - "ename": "ValueError", - "evalue": "Schema mismatch for experiments/dataset_A. Existing data has columns ['_user_entry_id', 'timestamp', 'value', 'category'], but new data has columns ['entry_id', 'timestamp', 'value', 'category']. All records in a source must have the same schema.", - "output_type": "error", - "traceback": [ - "\u001b[31m---------------------------------------------------------------------------\u001b[39m", - "\u001b[31mValueError\u001b[39m Traceback (most recent call last)", - "\u001b[36mCell\u001b[39m\u001b[36m \u001b[39m\u001b[32mIn[4]\u001b[39m\u001b[32m, line 4\u001b[39m\n\u001b[32m 1\u001b[39m \u001b[38;5;28;01mimport\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[34;01mlogging\u001b[39;00m\n\u001b[32m 3\u001b[39m logging.basicConfig(level=logging.INFO)\n\u001b[32m----> \u001b[39m\u001b[32m4\u001b[39m \u001b[43mdemo_single_row_constraint\u001b[49m\u001b[43m(\u001b[49m\u001b[43m)\u001b[49m\n", - "\u001b[36mFile \u001b[39m\u001b[32m~/workspace/orcabridge/src/orcabridge/store/arrow_data_stores.py:959\u001b[39m, in \u001b[36mdemo_single_row_constraint\u001b[39m\u001b[34m()\u001b[39m\n\u001b[32m 957\u001b[39m \u001b[38;5;28;01mfor\u001b[39;00m i, entry_id \u001b[38;5;129;01min\u001b[39;00m \u001b[38;5;28menumerate\u001b[39m(valid_entries):\n\u001b[32m 958\u001b[39m data = create_single_row_record(entry_id, value=\u001b[32m100.0\u001b[39m + i)\n\u001b[32m--> \u001b[39m\u001b[32m959\u001b[39m result = \u001b[43mstore\u001b[49m\u001b[43m.\u001b[49m\u001b[43madd_record\u001b[49m\u001b[43m(\u001b[49m\u001b[33;43m\"\u001b[39;49m\u001b[33;43mexperiments\u001b[39;49m\u001b[33;43m\"\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[33;43m\"\u001b[39;49m\u001b[33;43mdataset_A\u001b[39;49m\u001b[33;43m\"\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mentry_id\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mdata\u001b[49m\u001b[43m)\u001b[49m\n\u001b[32m 960\u001b[39m \u001b[38;5;28mprint\u001b[39m(\n\u001b[32m 961\u001b[39m \u001b[33mf\u001b[39m\u001b[33m\"\u001b[39m\u001b[33m✓ Added single-row record \u001b[39m\u001b[38;5;132;01m{\u001b[39;00mentry_id[:\u001b[32m16\u001b[39m]\u001b[38;5;132;01m}\u001b[39;00m\u001b[33m... (value: \u001b[39m\u001b[38;5;132;01m{\u001b[39;00m\u001b[32m100.0\u001b[39m\u001b[38;5;250m \u001b[39m+\u001b[38;5;250m \u001b[39mi\u001b[38;5;132;01m}\u001b[39;00m\u001b[33m)\u001b[39m\u001b[33m\"\u001b[39m\n\u001b[32m 962\u001b[39m )\n\u001b[32m 964\u001b[39m \u001b[38;5;28mprint\u001b[39m(\u001b[33mf\u001b[39m\u001b[33m\"\u001b[39m\u001b[38;5;130;01m\\n\u001b[39;00m\u001b[33mTotal records stored: \u001b[39m\u001b[38;5;132;01m{\u001b[39;00m\u001b[38;5;28mlen\u001b[39m(store._record_metadata)\u001b[38;5;132;01m}\u001b[39;00m\u001b[33m\"\u001b[39m)\n", - "\u001b[36mFile \u001b[39m\u001b[32m~/workspace/orcabridge/src/orcabridge/store/arrow_data_stores.py:690\u001b[39m, in \u001b[36mParquetArrowDataStore.add_record\u001b[39m\u001b[34m(self, source_name, source_id, entry_id, arrow_data)\u001b[39m\n\u001b[32m 687\u001b[39m logger.error(\u001b[33mf\u001b[39m\u001b[33m\"\u001b[39m\u001b[33m Missing in new: \u001b[39m\u001b[38;5;132;01m{\u001b[39;00m\u001b[38;5;28mset\u001b[39m(existing_cols)\u001b[38;5;250m \u001b[39m-\u001b[38;5;250m \u001b[39m\u001b[38;5;28mset\u001b[39m(new_cols)\u001b[38;5;132;01m}\u001b[39;00m\u001b[33m\"\u001b[39m)\n\u001b[32m 688\u001b[39m logger.error(\u001b[33mf\u001b[39m\u001b[33m\"\u001b[39m\u001b[33m Extra in new: \u001b[39m\u001b[38;5;132;01m{\u001b[39;00m\u001b[38;5;28mset\u001b[39m(new_cols)\u001b[38;5;250m \u001b[39m-\u001b[38;5;250m \u001b[39m\u001b[38;5;28mset\u001b[39m(existing_cols)\u001b[38;5;132;01m}\u001b[39;00m\u001b[33m\"\u001b[39m)\n\u001b[32m--> \u001b[39m\u001b[32m690\u001b[39m \u001b[38;5;28;01mraise\u001b[39;00m \u001b[38;5;167;01mValueError\u001b[39;00m(\n\u001b[32m 691\u001b[39m \u001b[33mf\u001b[39m\u001b[33m\"\u001b[39m\u001b[33mSchema mismatch for \u001b[39m\u001b[38;5;132;01m{\u001b[39;00msource_name\u001b[38;5;132;01m}\u001b[39;00m\u001b[33m/\u001b[39m\u001b[38;5;132;01m{\u001b[39;00msource_id\u001b[38;5;132;01m}\u001b[39;00m\u001b[33m. \u001b[39m\u001b[33m\"\u001b[39m\n\u001b[32m 692\u001b[39m \u001b[33mf\u001b[39m\u001b[33m\"\u001b[39m\u001b[33mExisting data has columns \u001b[39m\u001b[38;5;132;01m{\u001b[39;00mexisting_cols\u001b[38;5;132;01m}\u001b[39;00m\u001b[33m, \u001b[39m\u001b[33m\"\u001b[39m\n\u001b[32m 693\u001b[39m \u001b[33mf\u001b[39m\u001b[33m\"\u001b[39m\u001b[33mbut new data has columns \u001b[39m\u001b[38;5;132;01m{\u001b[39;00mnew_cols\u001b[38;5;132;01m}\u001b[39;00m\u001b[33m. \u001b[39m\u001b[33m\"\u001b[39m\n\u001b[32m 694\u001b[39m \u001b[33mf\u001b[39m\u001b[33m\"\u001b[39m\u001b[33mAll records in a source must have the same schema.\u001b[39m\u001b[33m\"\u001b[39m\n\u001b[32m 695\u001b[39m )\n\u001b[32m 697\u001b[39m now = datetime.now()\n\u001b[32m 698\u001b[39m record_key = \u001b[38;5;28mself\u001b[39m._get_record_key(source_name, source_id, entry_id)\n", - "\u001b[31mValueError\u001b[39m: Schema mismatch for experiments/dataset_A. Existing data has columns ['_user_entry_id', 'timestamp', 'value', 'category'], but new data has columns ['entry_id', 'timestamp', 'value', 'category']. All records in a source must have the same schema." - ] - } - ], - "source": [ - "import logging\n", - "\n", - "logging.basicConfig(level=logging.INFO)\n", - "demo_single_row_constraint()" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "INFO:orcabridge.store.arrow_data_stores:Loading metadata index...\n", - "INFO:orcabridge.store.arrow_data_stores:Loaded metadata for 1 records\n", - "INFO:orcabridge.store.arrow_data_stores:Initialized lazy ParquetArrowDataStore at ./data\n" - ] - } - ], - "source": [ - "from datetime import datetime, timedelta\n", - "\n", - "# Initialize store with single-row constraint enforcement\n", - "store = ParquetArrowDataStore(base_path=\"./data\", duplicate_entry_behavior=\"overwrite\")\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "INFO:orcabridge.store.arrow_data_stores:Added record experiments:dataset_A:entry_123d... with 1 rows\n" - ] - } - ], - "source": [ - "# This works - single row\n", - "single_row_data = pa.table({\"value\": [46.0], \"timestamp\": [datetime.now()]})\n", - "store.add_record(\"experiments\", \"dataset_A\", \"entry_1245d...\", single_row_data)\n", - "\n", - "# This fails - multiple rows\n", - "multi_row_data = pa.table({\"value\": [1.0, 2.0, 3.0], \"timestamp\": [datetime.now()] * 3})" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [], - "source": [ - "store.force_sync()" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "/home/eywalker/workspace/orcabridge/src/orcabridge/store/arrow_data_stores.py:786: PerformanceWarning: Determining the column names of a LazyFrame requires resolving its schema, which is a potentially expensive operation. Use `LazyFrame.collect_schema().names()` to get the column names without this warning.\n", - " user_columns = [col for col in lazy_frame.columns if col not in system_cols]\n" - ] - } - ], - "source": [ - "data = store.get_all_records_as_polars(\"experiments\", \"dataset_A\")" - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "<div><style>\n", - ".dataframe > thead > tr,\n", - ".dataframe > tbody > tr {\n", - " text-align: right;\n", - " white-space: pre-wrap;\n", - "}\n", - "</style>\n", - "<small>shape: (2, 2)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>value</th><th>timestamp</th></tr><tr><td>f64</td><td>datetime[μs]</td></tr></thead><tbody><tr><td>42.0</td><td>2025-06-16 09:05:29.641098</td></tr><tr><td>42.0</td><td>2025-06-16 09:06:46.449592</td></tr></tbody></table></div>" - ], - "text/plain": [ - "shape: (2, 2)\n", - "┌───────┬────────────────────────────┐\n", - "│ value ┆ timestamp │\n", - "│ --- ┆ --- │\n", - "│ f64 ┆ datetime[μs] │\n", - "╞═══════╪════════════════════════════╡\n", - "│ 42.0 ┆ 2025-06-16 09:05:29.641098 │\n", - "│ 42.0 ┆ 2025-06-16 09:06:46.449592 │\n", - "└───────┴────────────────────────────┘" - ] - }, - "execution_count": 12, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "data.collect()" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "<div><style>\n", - ".dataframe > thead > tr,\n", - ".dataframe > tbody > tr {\n", - " text-align: right;\n", - " white-space: pre-wrap;\n", - "}\n", - "</style>\n", - "<small>shape: (0, 3)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>value</th><th>timestamp</th><th>entry_id</th></tr><tr><td>f64</td><td>datetime[μs]</td><td>cat</td></tr></thead><tbody></tbody></table></div>" - ], - "text/plain": [ - "shape: (0, 3)\n", - "┌───────┬──────────────┬──────────┐\n", - "│ value ┆ timestamp ┆ entry_id │\n", - "│ --- ┆ --- ┆ --- │\n", - "│ f64 ┆ datetime[μs] ┆ cat │\n", - "╞═══════╪══════════════╪══════════╡\n", - "└───────┴──────────────┴──────────┘" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "data.collect()" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [ - { - "ename": "ValueError", - "evalue": "Each record must contain exactly 1 row, got 3 rows. This constraint ensures that for each source_name/source_id combination, there is only one valid entry per entry_id.", - "output_type": "error", - "traceback": [ - "\u001b[31m---------------------------------------------------------------------------\u001b[39m", - "\u001b[31mValueError\u001b[39m Traceback (most recent call last)", - "\u001b[36mCell\u001b[39m\u001b[36m \u001b[39m\u001b[32mIn[9]\u001b[39m\u001b[32m, line 1\u001b[39m\n\u001b[32m----> \u001b[39m\u001b[32m1\u001b[39m \u001b[43mstore\u001b[49m\u001b[43m.\u001b[49m\u001b[43madd_record\u001b[49m\u001b[43m(\u001b[49m\u001b[33;43m\"\u001b[39;49m\u001b[33;43mexperiments\u001b[39;49m\u001b[33;43m\"\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[33;43m\"\u001b[39;49m\u001b[33;43mdataset_A\u001b[39;49m\u001b[33;43m\"\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[33;43m\"\u001b[39;49m\u001b[33;43mentry_123abc...\u001b[39;49m\u001b[33;43m\"\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mmulti_row_data\u001b[49m\u001b[43m)\u001b[49m\n", - "\u001b[36mFile \u001b[39m\u001b[32m~/workspace/orcabridge/src/orcabridge/store/arrow_data_stores.py:541\u001b[39m, in \u001b[36mParquetArrowDataStore.add_record\u001b[39m\u001b[34m(self, source_name, source_id, entry_id, arrow_data)\u001b[39m\n\u001b[32m 539\u001b[39m \u001b[38;5;66;03m# CRITICAL: Enforce single-row constraint\u001b[39;00m\n\u001b[32m 540\u001b[39m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28mlen\u001b[39m(arrow_data) != \u001b[32m1\u001b[39m:\n\u001b[32m--> \u001b[39m\u001b[32m541\u001b[39m \u001b[38;5;28;01mraise\u001b[39;00m \u001b[38;5;167;01mValueError\u001b[39;00m(\n\u001b[32m 542\u001b[39m \u001b[33mf\u001b[39m\u001b[33m\"\u001b[39m\u001b[33mEach record must contain exactly 1 row, got \u001b[39m\u001b[38;5;132;01m{\u001b[39;00m\u001b[38;5;28mlen\u001b[39m(arrow_data)\u001b[38;5;132;01m}\u001b[39;00m\u001b[33m rows. \u001b[39m\u001b[33m\"\u001b[39m\n\u001b[32m 543\u001b[39m \u001b[33mf\u001b[39m\u001b[33m\"\u001b[39m\u001b[33mThis constraint ensures that for each source_name/source_id combination, \u001b[39m\u001b[33m\"\u001b[39m\n\u001b[32m 544\u001b[39m \u001b[33mf\u001b[39m\u001b[33m\"\u001b[39m\u001b[33mthere is only one valid entry per entry_id.\u001b[39m\u001b[33m\"\u001b[39m\n\u001b[32m 545\u001b[39m )\n\u001b[32m 547\u001b[39m \u001b[38;5;66;03m# Validate entry_id format (assuming 8+ char identifier)\u001b[39;00m\n\u001b[32m 548\u001b[39m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;129;01mnot\u001b[39;00m entry_id \u001b[38;5;129;01mor\u001b[39;00m \u001b[38;5;28mlen\u001b[39m(entry_id) < \u001b[32m8\u001b[39m:\n", - "\u001b[31mValueError\u001b[39m: Each record must contain exactly 1 row, got 3 rows. This constraint ensures that for each source_name/source_id combination, there is only one valid entry per entry_id." - ] - } - ], - "source": [ - "store.add_record(\"experiments\", \"dataset_A\", \"entry_123abc...\", multi_row_data)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "INFO:orcabridge.store.arrow_data_stores:Loading metadata index...\n", - "INFO:orcabridge.store.arrow_data_stores:Loaded metadata for 0 records\n", - "INFO:orcabridge.store.arrow_data_stores:Initialized lazy ParquetArrowDataStore at ./dataset\n" - ] - } - ], - "source": [ - "data_store = ParquetArrowDataStore(\n", - " \"./dataset\", sync_interval_seconds=10, max_loaded_sources=30\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "data_store.add_record()" - ] - }, - { - "cell_type": "code", - "execution_count": 19, - "metadata": {}, - "outputs": [], - "source": [ - "from pathlib import Path\n", - "from orcabridge.types.default import default_registry\n", - "from orcabridge.types.registry import DataConverter\n", - "\n", - "type_spec = {\"name\": str, \"file\": Path}\n", - "example_data = {\"name\": \"Edgar\", \"file\": \"sample.txt\"}\n", - "example_data = [\n", - " {\"name\": \"Edgar\", \"file\": \"sample.txt\"},\n", - " {\"name\": \"Alice\", \"file\": \"sample2.txt\"},\n", - "]" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [], - "source": [ - "converter = DataConverter(type_spec, registry=default_registry)" - ] - }, - { - "cell_type": "code", - "execution_count": 20, - "metadata": {}, - "outputs": [], - "source": [ - "table = converter.to_arrow_table(example_data)" - ] - }, - { - "cell_type": "code", - "execution_count": 21, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "pyarrow.Table\n", - "name: string\n", - "file: string\n", - "----\n", - "name: [[\"Edgar\",\"Alice\"]]\n", - "file: [[\"sample.txt\",\"sample2.txt\"]]" - ] - }, - "execution_count": 21, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "table" - ] - }, - { - "cell_type": "code", - "execution_count": 22, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "'2cda22e1527ecf01d1555ed90a0f0a2b40ec7f1034387b5f0f93afb38cf041cf'" - ] - }, - "execution_count": 22, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "hasher.hash_table(table)" - ] - }, - { - "cell_type": "code", - "execution_count": 23, - "metadata": {}, - "outputs": [], - "source": [ - "processed_table = hasher._process_table_columns(table)" - ] - }, - { - "cell_type": "code", - "execution_count": 25, - "metadata": {}, - "outputs": [], - "source": [ - "import inspect" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "def test(a: int = 5):\n", - " return 5" - ] - }, - { - "cell_type": "code", - "execution_count": 29, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "a a: int = 5\n" - ] - } - ], - "source": [ - "for k, v in inspect.signature(test).parameters.items():\n", - " print(k, v)" - ] - }, - { - "cell_type": "code", - "execution_count": 33, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "'a'" - ] - }, - "execution_count": 33, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "v.name" - ] - }, - { - "cell_type": "code", - "execution_count": 24, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "pyarrow.Table\n", - "name: string\n", - "file: string\n", - "----\n", - "name: [[\"Edgar\",\"Alice\"]]\n", - "file: [[\"3a1f868f16c70867afdff05d9c7de3a6e573d2ade1ce6a48293d973f8ad68504\",\"3a1f868f16c70867afdff05d9c7de3a6e573d2ade1ce6a48293d973f8ad68504\"]]" - ] - }, - "execution_count": 24, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "processed_table" - ] - }, - { - "cell_type": "code", - "execution_count": 15, - "metadata": {}, - "outputs": [], - "source": [ - "z = hasher._sort_table_columns(processed_table)" - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "pyarrow.Table\n", - "name: string\n", - "file: string\n", - "----\n", - "name: [[\"Edgar\"]]\n", - "file: [[\"f8efdb6bc4c7dc8eb7b439ba9b3d132733f0e73c4aa83748bb13f25133a43633\"]]" - ] - }, - "execution_count": 16, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "processed_table" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "'99ca6c8b436a17d888d65051ba7977eeec93323746e619db5b1c9ab53171566d'" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "hasher.hash_table(table)" - ] - }, - { - "cell_type": "code", - "execution_count": 18, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "'35d6c3043e95f2176c36188849655ac2a412562c6ccfcbec3a7a8a29a3a1eb44'" - ] - }, - "execution_count": 18, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "hasher.hash_table(table)" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [], - "source": [ - "function_info_extractor = FunctionSignatureExtractor()\n", - "object_hasher = LegacyObjectHasher(function_info_extractor=function_info_extractor)" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [], - "source": [ - "def product(x: float, y: int) -> float:\n", - " return x * y" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [], - "source": [ - "class ArrowDataHasher:\n", - " def hash_data(self, data):\n", - " print(f\"Requested to hash data {data}\")\n", - " return \"test\"\n", - "\n", - " def hash_arrow_data(self, data):\n", - " print(f\"Requested to hash arrow data {data}\")\n", - " return \"test_arrow\"\n", - "\n", - "\n", - "class MyArrowDataStore:\n", - " def add_record(\n", - " self,\n", - " source_name: str,\n", - " source_id: str,\n", - " entry_id: str,\n", - " arrow_data: pa.Table,\n", - " ) -> pa.Table:\n", - " print(\n", - " f\"Adding record to Arrow data store: {source_name}, {source_id}, {entry_id}: {arrow_data}\"\n", - " )\n", - " return arrow_data\n", - "\n", - " def get_record(\n", - " self, source_name: str, source_id: str, entry_id: str\n", - " ) -> pa.Table | None:\n", - " return None\n", - "\n", - " def get_all_records(self, source_name: str, source_id: str) -> pa.Table | None:\n", - " \"\"\"Retrieve all records for a given source as a single table.\"\"\"\n", - " return None\n", - "\n", - " def get_all_records_as_polars(\n", - " self, source_name: str, source_id: str\n", - " ) -> pl.LazyFrame | None:\n", - " \"\"\"Retrieve all records for a given source as a single Polars DataFrame.\"\"\"\n", - " return None\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "pod = TypedFunctionPod(product, \"result\")" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "('TypedFunctionPod',\n", - " <function __main__.product(x: float, y: int) -> float>,\n", - " ('result',))" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "pod.identity_structure()" - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "metadata": {}, - "outputs": [], - "source": [ - "stream = SyncStreamFromLists(\n", - " [\n", - " {\"id\": 0},\n", - " {\"id\": 1},\n", - " {\"id\": 2},\n", - " ],\n", - " [{\"x\": 3.0, \"y\": 4}, {\"x\": 5.0, \"y\": 6}, {\"x\": 7.0, \"y\": 8}],\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'id': 0}, Data: {'result': 12.0}\n", - "Tag: {'id': 1}, Data: {'result': 30.0}\n", - "Tag: {'id': 2}, Data: {'result': 56.0}\n" - ] - } - ], - "source": [ - "for tag, data in pod(stream):\n", - " print((f\"Tag: {tag}, Data: {data}\"))" - ] - }, - { - "cell_type": "code", - "execution_count": 14, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "[{'result': 56.0}]" - ] - }, - "execution_count": 14, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "pod.output_converter.from_arrow_table(pod.output_converter.to_arrow_table(data))" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "cached_pod = CachedFunctionPod(\n", - " pod,\n", - " object_hasher=object_hasher,\n", - " arrow_hasher=ArrowDataHasher(),\n", - " result_store=MyArrowDataStore(),\n", - " tag_store=MyArrowDataStore(),\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "12.0" - ] - }, - "execution_count": 16, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "cached_pod.function_pod.function(3.0, 4)" - ] - }, - { - "cell_type": "code", - "execution_count": 17, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "12.0" - ] - }, - "execution_count": 17, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "cached_pod.function_pod.function(3.0, 4)" - ] - }, - { - "cell_type": "code", - "execution_count": 18, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Requested to hash arrow data pyarrow.Table\n", - "x: double\n", - "y: int64\n", - "----\n", - "x: [[3]]\n", - "y: [[4]]\n", - "Requested to hash arrow data pyarrow.Table\n", - "id: int64\n", - "__data_key: string\n", - "----\n", - "id: [[0]]\n", - "__data_key: [[\"test_arrow\"]]\n", - "Adding record to Arrow data store: product, e9487308f083ecc170e2fe679ce0d30b70e7c9d7c59b532118944e461e40ba1f, test_arrow: pyarrow.Table\n", - "id: int64\n", - "__data_key: string\n", - "----\n", - "id: [[0]]\n", - "__data_key: [[\"test_arrow\"]]\n", - "Requested to hash arrow data pyarrow.Table\n", - "x: double\n", - "y: int64\n", - "----\n", - "x: [[3]]\n", - "y: [[4]]\n", - "Adding record to Arrow data store: product, e9487308f083ecc170e2fe679ce0d30b70e7c9d7c59b532118944e461e40ba1f, test_arrow: pyarrow.Table\n", - "result: double\n", - "----\n", - "result: [[12]]\n", - "Tag: {'id': 0}, Data: {'result': 12.0}\n", - "Requested to hash arrow data pyarrow.Table\n", - "x: double\n", - "y: int64\n", - "----\n", - "x: [[5]]\n", - "y: [[6]]\n", - "Requested to hash arrow data pyarrow.Table\n", - "id: int64\n", - "__data_key: string\n", - "----\n", - "id: [[1]]\n", - "__data_key: [[\"test_arrow\"]]\n", - "Adding record to Arrow data store: product, e9487308f083ecc170e2fe679ce0d30b70e7c9d7c59b532118944e461e40ba1f, test_arrow: pyarrow.Table\n", - "id: int64\n", - "__data_key: string\n", - "----\n", - "id: [[1]]\n", - "__data_key: [[\"test_arrow\"]]\n", - "Requested to hash arrow data pyarrow.Table\n", - "x: double\n", - "y: int64\n", - "----\n", - "x: [[5]]\n", - "y: [[6]]\n", - "Adding record to Arrow data store: product, e9487308f083ecc170e2fe679ce0d30b70e7c9d7c59b532118944e461e40ba1f, test_arrow: pyarrow.Table\n", - "result: double\n", - "----\n", - "result: [[30]]\n", - "Tag: {'id': 1}, Data: {'result': 30.0}\n", - "Requested to hash arrow data pyarrow.Table\n", - "x: double\n", - "y: int64\n", - "----\n", - "x: [[7]]\n", - "y: [[8]]\n", - "Requested to hash arrow data pyarrow.Table\n", - "id: int64\n", - "__data_key: string\n", - "----\n", - "id: [[2]]\n", - "__data_key: [[\"test_arrow\"]]\n", - "Adding record to Arrow data store: product, e9487308f083ecc170e2fe679ce0d30b70e7c9d7c59b532118944e461e40ba1f, test_arrow: pyarrow.Table\n", - "id: int64\n", - "__data_key: string\n", - "----\n", - "id: [[2]]\n", - "__data_key: [[\"test_arrow\"]]\n", - "Requested to hash arrow data pyarrow.Table\n", - "x: double\n", - "y: int64\n", - "----\n", - "x: [[7]]\n", - "y: [[8]]\n", - "Adding record to Arrow data store: product, e9487308f083ecc170e2fe679ce0d30b70e7c9d7c59b532118944e461e40ba1f, test_arrow: pyarrow.Table\n", - "result: double\n", - "----\n", - "result: [[56]]\n", - "Tag: {'id': 2}, Data: {'result': 56.0}\n" - ] - } - ], - "source": [ - "for tag, data in cached_pod(stream):\n", - " print((f\"Tag: {tag}, Data: {data}\"))" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [], - "source": [ - "from pathlib import Path\n", - "\n", - "\n", - "@typed_function_pod([\"sum\", \"difference\", \"info_path\"])\n", - "def add_and_subtract(a: int, b: int) -> tuple[int, int, Path]:\n", - " \"\"\"\n", - " Adds and subtracts two integers.\n", - "\n", - " :param a: First integer.\n", - " :param b: Second integer.\n", - " :return: A tuple containing the sum and the difference of a and b.\n", - " \"\"\"\n", - " return a + b, a - b, Path(\"local_info.json\")" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [], - "source": [ - "stream = SyncStreamFromLists(\n", - " [{\"name\": \"Edgar\"}, {\"name\": \"Alice\"}, {\"name\": \"Bob\"}],\n", - " [{\"a\": 5, \"b\": 3}, {\"a\": 10, \"b\": 2}, {\"a\": 7, \"b\": 4}],\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [], - "source": [ - "converter = DataConverter(\n", - " add_and_subtract.function_output_types, add_and_subtract.registry\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [], - "source": [ - "data = [p for t, p in add_and_subtract(stream).flow()]" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [], - "source": [ - "table = converter.to_arrow_table(data)" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "pyarrow.Table\n", - "sum: int64\n", - "difference: int64\n", - "info_path: string\n", - "----\n", - "sum: [[8,12,11]]\n", - "difference: [[2,8,3]]\n", - "info_path: [[\"local_info.json\",\"local_info.json\",\"local_info.json\"]]" - ] - }, - "execution_count": 8, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "table" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [], - "source": [ - "import pyarrow as pa" - ] - }, - { - "cell_type": "code", - "execution_count": 20, - "metadata": {}, - "outputs": [], - "source": [ - "tag = {\"name\": [\"Edgar\", \"Names\"], \"age\": 37}" - ] - }, - { - "cell_type": "code", - "execution_count": 21, - "metadata": {}, - "outputs": [], - "source": [ - "tag[\"__data_key\"] = \"some_unique_key\"\n" - ] - }, - { - "cell_type": "code", - "execution_count": 22, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "'51d2a5483d1623ba4582fb372a73bb7726caf1a9756af32778cbac1b8c16f6c1'" - ] - }, - "execution_count": 22, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "from orcabridge.hashing.defaults import LegacyObjectHasher\n", - "\n", - "LegacyObjectHasher().hash_to_hex(tag)\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - }, - { - "cell_type": "code", - "execution_count": 23, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "pyarrow.Table\n", - "name: list<item: string>\n", - " child 0, item: string\n", - "age: int64\n", - "__data_key: string\n", - "----\n", - "name: [[[\"Edgar\",\"Names\"]]]\n", - "age: [[37]]\n", - "__data_key: [[\"some_unique_key\"]]" - ] - }, - "execution_count": 23, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "pa.Table.from_pylist([tag])" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "[{'sum': 8, 'difference': 2, 'info_path': PosixPath('local_info.json')},\n", - " {'sum': 12, 'difference': 8, 'info_path': PosixPath('local_info.json')},\n", - " {'sum': 11, 'difference': 3, 'info_path': PosixPath('local_info.json')}]" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "converter.from_arrow_table(table)" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "{}\n", - "{}\n", - "{b'semantic_type': b'path'}\n" - ] - } - ], - "source": [ - "for field in table.schema:\n", - " print(field.metadata)" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [], - "source": [ - "import pyarrow as pa" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "metadata": {}, - "outputs": [ - { - "ename": "AttributeError", - "evalue": "module 'pyarrow' has no attribute 'type'", - "output_type": "error", - "traceback": [ - "\u001b[31m---------------------------------------------------------------------------\u001b[39m", - "\u001b[31mAttributeError\u001b[39m Traceback (most recent call last)", - "\u001b[36mCell\u001b[39m\u001b[36m \u001b[39m\u001b[32mIn[13]\u001b[39m\u001b[32m, line 1\u001b[39m\n\u001b[32m----> \u001b[39m\u001b[32m1\u001b[39m \u001b[43mpa\u001b[49m\u001b[43m.\u001b[49m\u001b[43mtype\u001b[49m(\u001b[38;5;28mint\u001b[39m)\n", - "\u001b[31mAttributeError\u001b[39m: module 'pyarrow' has no attribute 'type'" - ] - } - ], - "source": [ - "pa.type(int)" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "pyarrow.Table\n", - "sum: int64\n", - "difference: int64\n", - "info_path: string\n", - "----\n", - "sum: [[8]]\n", - "difference: [[2]]\n", - "info_path: [[\"local_info.json\"]]" - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "table = converter.to_arrow_table(data[0])\n", - "table" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import pyarrow as pa\n", - "import time\n", - "\n", - "\n", - "def benchmark_conversions():\n", - " # Create test tables\n", - " single_row = pa.table({\"x\": [42], \"y\": [\"hello\"], \"z\": [3.14]})\n", - " multi_row = pa.table(\n", - " {\"x\": list(range(1000)), \"y\": [f\"item_{i}\" for i in range(1000)]}\n", - " )\n", - "\n", - " # Method 1: to_pydict() + post-processing\n", - " def method1(table):\n", - " pydict = table.to_pydict()\n", - " if len(table) == 1:\n", - " return {key: values[0] for key, values in pydict.items()}\n", - " return pydict\n", - "\n", - " # Method 2: Direct scalar extraction\n", - " def method2(table):\n", - " if len(table) == 1:\n", - " return {\n", - " col_name: table.column(col_name)[0].as_py()\n", - " for col_name in table.column_names\n", - " }\n", - " return table.to_pydict()\n", - "\n", - " # Method 3: Using pandas intermediate (generally slower)\n", - " def method3(table):\n", - " df = table.to_pandas()\n", - " if len(df) == 1:\n", - " return df.iloc[0].to_dict()\n", - " return df.to_dict(\"list\")\n", - "\n", - " # Benchmark single row\n", - " print(\"Single row benchmarks:\")\n", - " for i, method in enumerate([method1, method2, method3], 1):\n", - " start = time.time()\n", - " for _ in range(10000):\n", - " result = method(single_row)\n", - " end = time.time()\n", - " print(f\"Method {i}: {end - start:.4f}s\")\n", - "\n", - " print(\"\\nMulti-row benchmarks:\")\n", - " for i, method in enumerate([method1, method2, method3], 1):\n", - " start = time.time()\n", - " for _ in range(1000):\n", - " result = method(multi_row)\n", - " end = time.time()\n", - " print(f\"Method {i}: {end - start:.4f}s\")\n" - ] - }, - { - "cell_type": "code", - "execution_count": 24, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Single row benchmarks:\n", - "Method 1: 0.3935s\n", - "Method 2: 0.2222s\n", - "Method 3: 4.3977s\n", - "\n", - "Multi-row benchmarks:\n", - "Method 1: 2.4562s\n", - "Method 2: 2.4976s\n", - "Method 3: 1.6264s\n" - ] - } - ], - "source": [ - "benchmark_conversions()" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "[{'sum': 8, 'difference': 2, 'info_path': PosixPath('local_info.json')}]" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "converter.from_arrow_table(table)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "True" - ] - }, - "execution_count": 18, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "b\"semantic_type\" in table.schema[2].metadata" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "k" - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'sum': TypeInfo(python_type=<class 'int'>, arrow_type=DataType(int64), semantic_type='int'),\n", - " 'difference': TypeInfo(python_type=<class 'int'>, arrow_type=DataType(int64), semantic_type='int'),\n", - " 'info_path': TypeInfo(python_type=<class 'pathlib._local.Path'>, arrow_type=DataType(string), semantic_type='path')}" - ] - }, - "execution_count": 12, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "converter.storage_type_info" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "[{'sum': 8, 'difference': 2, 'info_path': PosixPath('local_info.json')},\n", - " {'sum': 12, 'difference': 8, 'info_path': PosixPath('local_info.json')},\n", - " {'sum': 11, 'difference': 3, 'info_path': PosixPath('local_info.json')}]" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "data" - ] - }, - { - "cell_type": "code", - "execution_count": 44, - "metadata": {}, - "outputs": [], - "source": [ - "store_data = to_store(data)" - ] - }, - { - "cell_type": "code", - "execution_count": 45, - "metadata": {}, - "outputs": [], - "source": [ - "arrow_data = convert_data_to_arrow_table(\n", - " data, add_and_subtract.function_output_types, add_and_subtract.registry\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 46, - "metadata": {}, - "outputs": [ - { - "ename": "NameError", - "evalue": "name 'convert_arrow_tablet_to_data' is not defined", - "output_type": "error", - "traceback": [ - "\u001b[31m---------------------------------------------------------------------------\u001b[39m", - "\u001b[31mNameError\u001b[39m Traceback (most recent call last)", - "\u001b[36mCell\u001b[39m\u001b[36m \u001b[39m\u001b[32mIn[46]\u001b[39m\u001b[32m, line 1\u001b[39m\n\u001b[32m----> \u001b[39m\u001b[32m1\u001b[39m \u001b[43mconvert_arrow_tablet_to_data\u001b[49m\n", - "\u001b[31mNameError\u001b[39m: name 'convert_arrow_tablet_to_data' is not defined" - ] - } - ], - "source": [ - "convert_arrow_tablet_to_data" - ] - }, - { - "cell_type": "code", - "execution_count": 71, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "sum: int64\n", - "difference: int64\n", - "info_path: string" - ] - }, - "execution_count": 71, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "arrow_data.schema" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "with pa.OSFile(\"arraydata.arrow\", \"wb\") as sink:\n", - " with pa.ipc.new_file(sink, schema=arrow_data.schema) as writer:\n", - " writer.write(batch)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [ - { - "ename": "AttributeError", - "evalue": "module 'pyarrow' has no attribute 'save_table'", - "output_type": "error", - "traceback": [ - "\u001b[31m---------------------------------------------------------------------------\u001b[39m", - "\u001b[31mAttributeError\u001b[39m Traceback (most recent call last)", - "\u001b[36mCell\u001b[39m\u001b[36m \u001b[39m\u001b[32mIn[70]\u001b[39m\u001b[32m, line 1\u001b[39m\n\u001b[32m----> \u001b[39m\u001b[32m1\u001b[39m \u001b[43mpa\u001b[49m\u001b[43m.\u001b[49m\u001b[43msave_table\u001b[49m(arrow_data, \u001b[33m\"\u001b[39m\u001b[33moutput.arrow\u001b[39m\u001b[33m\"\u001b[39m)\n", - "\u001b[31mAttributeError\u001b[39m: module 'pyarrow' has no attribute 'save_table'" - ] - } - ], - "source": [] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "pyarrow.Table\n", - "sum: int64\n", - "difference: int64\n", - "info_path: string\n", - "----\n", - "sum: [[8]]\n", - "difference: [[2]]\n", - "info_path: [[\"local_info.json\"]]" - ] - }, - "execution_count": 47, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "arrow_data" - ] - }, - { - "cell_type": "code", - "execution_count": 50, - "metadata": {}, - "outputs": [], - "source": [ - "from deltalake import write_deltalake, DeltaTable\n", - "\n", - "write_deltalake(\"tmp/another-table\", arrow_data, mode=\"append\")\n", - "\n", - "table = DeltaTable(\"tmp/another-table\")" - ] - }, - { - "cell_type": "code", - "execution_count": 55, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "<div><style>\n", - ".dataframe > thead > tr,\n", - ".dataframe > tbody > tr {\n", - " text-align: right;\n", - " white-space: pre-wrap;\n", - "}\n", - "</style>\n", - "<small>shape: (1, 3)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>sum</th><th>difference</th><th>info_path</th></tr><tr><td>i64</td><td>i64</td><td>str</td></tr></thead><tbody><tr><td>8</td><td>2</td><td>"local_info.json"</td></tr></tbody></table></div>" - ], - "text/plain": [ - "shape: (1, 3)\n", - "┌─────┬────────────┬─────────────────┐\n", - "│ sum ┆ difference ┆ info_path │\n", - "│ --- ┆ --- ┆ --- │\n", - "│ i64 ┆ i64 ┆ str │\n", - "╞═════╪════════════╪═════════════════╡\n", - "│ 8 ┆ 2 ┆ local_info.json │\n", - "└─────┴────────────┴─────────────────┘" - ] - }, - "execution_count": 55, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "pl.DataFrame(table.to_pyarrow_table())" - ] - }, - { - "cell_type": "code", - "execution_count": 23, - "metadata": {}, - "outputs": [], - "source": [ - "import polars as pl" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [ - { - "ename": "AttributeError", - "evalue": "'deltalake._internal.Schema' object has no attribute 'to_pyarrow'", - "output_type": "error", - "traceback": [ - "\u001b[31m---------------------------------------------------------------------------\u001b[39m", - "\u001b[31mAttributeError\u001b[39m Traceback (most recent call last)", - "\u001b[36mCell\u001b[39m\u001b[36m \u001b[39m\u001b[32mIn[24]\u001b[39m\u001b[32m, line 1\u001b[39m\n\u001b[32m----> \u001b[39m\u001b[32m1\u001b[39m \u001b[43mpl\u001b[49m\u001b[43m.\u001b[49m\u001b[43mread_delta\u001b[49m\u001b[43m(\u001b[49m\u001b[33;43m\"\u001b[39;49m\u001b[33;43mtmp/some-table\u001b[39;49m\u001b[33;43m\"\u001b[39;49m\u001b[43m)\u001b[49m\n", - "\u001b[36mFile \u001b[39m\u001b[32m~/workspace/orcabridge/.venv/lib/python3.13/site-packages/polars/io/delta.py:149\u001b[39m, in \u001b[36mread_delta\u001b[39m\u001b[34m(source, version, columns, rechunk, storage_options, credential_provider, delta_table_options, use_pyarrow, pyarrow_options)\u001b[39m\n\u001b[32m 26\u001b[39m \u001b[38;5;28;01mdef\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[34mread_delta\u001b[39m(\n\u001b[32m 27\u001b[39m source: \u001b[38;5;28mstr\u001b[39m | DeltaTable,\n\u001b[32m 28\u001b[39m *,\n\u001b[32m (...)\u001b[39m\u001b[32m 36\u001b[39m pyarrow_options: \u001b[38;5;28mdict\u001b[39m[\u001b[38;5;28mstr\u001b[39m, Any] | \u001b[38;5;28;01mNone\u001b[39;00m = \u001b[38;5;28;01mNone\u001b[39;00m,\n\u001b[32m 37\u001b[39m ) -> DataFrame:\n\u001b[32m 38\u001b[39m \u001b[38;5;250m \u001b[39m\u001b[33;03m\"\"\"\u001b[39;00m\n\u001b[32m 39\u001b[39m \u001b[33;03m Reads into a DataFrame from a Delta lake table.\u001b[39;00m\n\u001b[32m 40\u001b[39m \n\u001b[32m (...)\u001b[39m\u001b[32m 147\u001b[39m \u001b[33;03m ... ) # doctest: +SKIP\u001b[39;00m\n\u001b[32m 148\u001b[39m \u001b[33;03m \"\"\"\u001b[39;00m\n\u001b[32m--> \u001b[39m\u001b[32m149\u001b[39m df = \u001b[43mscan_delta\u001b[49m\u001b[43m(\u001b[49m\n\u001b[32m 150\u001b[39m \u001b[43m \u001b[49m\u001b[43msource\u001b[49m\u001b[43m=\u001b[49m\u001b[43msource\u001b[49m\u001b[43m,\u001b[49m\n\u001b[32m 151\u001b[39m \u001b[43m \u001b[49m\u001b[43mversion\u001b[49m\u001b[43m=\u001b[49m\u001b[43mversion\u001b[49m\u001b[43m,\u001b[49m\n\u001b[32m 152\u001b[39m \u001b[43m \u001b[49m\u001b[43mstorage_options\u001b[49m\u001b[43m=\u001b[49m\u001b[43mstorage_options\u001b[49m\u001b[43m,\u001b[49m\n\u001b[32m 153\u001b[39m \u001b[43m \u001b[49m\u001b[43mcredential_provider\u001b[49m\u001b[43m=\u001b[49m\u001b[43mcredential_provider\u001b[49m\u001b[43m,\u001b[49m\n\u001b[32m 154\u001b[39m \u001b[43m \u001b[49m\u001b[43mdelta_table_options\u001b[49m\u001b[43m=\u001b[49m\u001b[43mdelta_table_options\u001b[49m\u001b[43m,\u001b[49m\n\u001b[32m 155\u001b[39m \u001b[43m \u001b[49m\u001b[43muse_pyarrow\u001b[49m\u001b[43m=\u001b[49m\u001b[43muse_pyarrow\u001b[49m\u001b[43m,\u001b[49m\n\u001b[32m 156\u001b[39m \u001b[43m \u001b[49m\u001b[43mpyarrow_options\u001b[49m\u001b[43m=\u001b[49m\u001b[43mpyarrow_options\u001b[49m\u001b[43m,\u001b[49m\n\u001b[32m 157\u001b[39m \u001b[43m \u001b[49m\u001b[43mrechunk\u001b[49m\u001b[43m=\u001b[49m\u001b[43mrechunk\u001b[49m\u001b[43m,\u001b[49m\n\u001b[32m 158\u001b[39m \u001b[43m \u001b[49m\u001b[43m)\u001b[49m\n\u001b[32m 160\u001b[39m \u001b[38;5;28;01mif\u001b[39;00m columns \u001b[38;5;129;01mis\u001b[39;00m \u001b[38;5;129;01mnot\u001b[39;00m \u001b[38;5;28;01mNone\u001b[39;00m:\n\u001b[32m 161\u001b[39m df = df.select(columns)\n", - "\u001b[36mFile \u001b[39m\u001b[32m~/workspace/orcabridge/.venv/lib/python3.13/site-packages/polars/io/delta.py:376\u001b[39m, in \u001b[36mscan_delta\u001b[39m\u001b[34m(***failed resolving arguments***)\u001b[39m\n\u001b[32m 372\u001b[39m \u001b[38;5;28;01mraise\u001b[39;00m DeltaProtocolError(msg)\n\u001b[32m 374\u001b[39m \u001b[38;5;66;03m# Requires conversion through pyarrow table because there is no direct way yet to\u001b[39;00m\n\u001b[32m 375\u001b[39m \u001b[38;5;66;03m# convert a delta schema into a polars schema\u001b[39;00m\n\u001b[32m--> \u001b[39m\u001b[32m376\u001b[39m delta_schema = \u001b[43mdl_tbl\u001b[49m\u001b[43m.\u001b[49m\u001b[43mschema\u001b[49m\u001b[43m(\u001b[49m\u001b[43m)\u001b[49m\u001b[43m.\u001b[49m\u001b[43mto_pyarrow\u001b[49m(as_large_types=\u001b[38;5;28;01mTrue\u001b[39;00m)\n\u001b[32m 377\u001b[39m polars_schema = from_arrow(pa.Table.from_pylist([], delta_schema)).schema \u001b[38;5;66;03m# type: ignore[union-attr]\u001b[39;00m\n\u001b[32m 378\u001b[39m partition_columns = dl_tbl.metadata().partition_columns\n", - "\u001b[31mAttributeError\u001b[39m: 'deltalake._internal.Schema' object has no attribute 'to_pyarrow'" - ] - } - ], - "source": [ - "pl." - ] - }, - { - "cell_type": "code", - "execution_count": 28, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "<div><style>\n", - ".dataframe > thead > tr,\n", - ".dataframe > tbody > tr {\n", - " text-align: right;\n", - " white-space: pre-wrap;\n", - "}\n", - "</style>\n", - "<small>shape: (3, 2)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>sum</th><th>difference</th></tr><tr><td>i64</td><td>i64</td></tr></thead><tbody><tr><td>8</td><td>2</td></tr><tr><td>8</td><td>2</td></tr><tr><td>8</td><td>2</td></tr></tbody></table></div>" - ], - "text/plain": [ - "shape: (3, 2)\n", - "┌─────┬────────────┐\n", - "│ sum ┆ difference │\n", - "│ --- ┆ --- │\n", - "│ i64 ┆ i64 │\n", - "╞═════╪════════════╡\n", - "│ 8 ┆ 2 │\n", - "│ 8 ┆ 2 │\n", - "│ 8 ┆ 2 │\n", - "└─────┴────────────┘" - ] - }, - "execution_count": 28, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "pl.DataFrame(table.to_pyarrow_table())" - ] - }, - { - "cell_type": "code", - "execution_count": 27, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "pyarrow.Table\n", - "sum: int64\n", - "difference: int64\n", - "----\n", - "sum: [[8],[8],[8]]\n", - "difference: [[2],[2],[2]]" - ] - }, - "execution_count": 27, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "table.to_pyarrow_table()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "read_" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "<orcabridge.types.registry.TypeRegistry at 0x7f80285901a0>" - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "add_and_subtract.registry" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "[({'name': 'Edgar'}, {'sum': 8, 'difference': 2}),\n", - " ({'name': 'Alice'}, {'sum': 12, 'difference': 8}),\n", - " ({'name': 'Bob'}, {'sum': 11, 'difference': 3})]" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "add_and_subtract(stream).flow()" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "FunctionPod:module:__main__ name:_original_add_and_subtract params:(a: int, b: int) returns:tuple[int, int] ⇒ ['sum', 'difference']" - ] - }, - "execution_count": 6, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "add_and_subtract" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "add_and_subtract." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "<orcabridge.streams.SyncStreamFromGenerator at 0x7fe79052c050>" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Working with streams" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "`Stream` is fundamental to Orcapod data pipeline, representing *edges* in a directed acyclic graph (DAG) of an Orcapod pipeline. `Stream` is best thought of as a flowing stream of `data` -- a unit of data in Oracpod. A `data` is essentially a ditionary mapping argument names to a `pathset` (that is, one or more files with arbitrary nesting). Ultimately, a pod will receive and work on the `data`, looking up the pathset that matches the expected argument names defined as the inputs into the pod. Before we explore creating and using `pod`, we will create a very basic `stream` called `GlobStream`, sourcing from a directory. A data is formed for each file that matches the specified *glob* pattern." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Let's create a data source out of all `*.txt` files found in the folder `examples/dataset1`" - ] - }, - { - "cell_type": "code", - "execution_count": 15, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "\u001b[0m\u001b[01;32mday1.txt\u001b[0m* \u001b[01;32mday2.txt\u001b[0m* \u001b[01;32mday3.txt\u001b[0m* \u001b[01;32mday4.txt\u001b[0m* \u001b[01;32mday6.txt\u001b[0m*\n" - ] - } - ], - "source": [ - "%ls ../examples/dataset1" - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "metadata": {}, - "outputs": [], - "source": [ - "dataset1 = ob.GlobSource(\"txt_file\", \"../examples/dataset1\", \"*.txt\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We can then obtain `stream` from a `source` by invoking the source with `Source()`. The return `stream` acts as an iterator over the `data` and its `tag`.\n", - "For convenience, `source` can be treated synonymously with a `stream`, allowing you to directly iterate over the content." - ] - }, - { - "cell_type": "code", - "execution_count": 17, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Data {'txt_file': PosixPath('../examples/dataset1/day1.txt')} with tag {'file_name': 'day1'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day2.txt')} with tag {'file_name': 'day2'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day3.txt')} with tag {'file_name': 'day3'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day4.txt')} with tag {'file_name': 'day4'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day6.txt')} with tag {'file_name': 'day6'}\n" - ] - } - ], - "source": [ - "for tag, data in dataset1():\n", - " print(f\"Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "code", - "execution_count": 18, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Data {'txt_file': PosixPath('../examples/dataset1/day1.txt')} with tag {'file_name': 'day1'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day2.txt')} with tag {'file_name': 'day2'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day3.txt')} with tag {'file_name': 'day3'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day4.txt')} with tag {'file_name': 'day4'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day6.txt')} with tag {'file_name': 'day6'}\n" - ] - } - ], - "source": [ - "# equivalent to above but more natural without the need to call `dataset1()`\n", - "for tag, data in dataset1:\n", - " print(f\"Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "A few things to note. When creating the `GlobSource` we pass in the argument name to be associated with the `pathset` matching our glob pattern (`*.txt` in this case). By default, the `GlobSource` tags each data with a key of `file_name` and value of the name of the file that was matched (minus the file extension). This behavior can be easily changed by passing in a custom function for tag generation at the time of `GlobSource` creation." - ] - }, - { - "cell_type": "code", - "execution_count": 19, - "metadata": {}, - "outputs": [], - "source": [ - "from pathlib import Path\n", - "\n", - "dataset1_custom = ob.GlobSource(\n", - " \"data\",\n", - " \"../examples/dataset1\",\n", - " \"*.txt\",\n", - " tag_function=lambda x: {\"date\": Path(x).stem},\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 20, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Data {'data': PosixPath('../examples/dataset1/day1.txt')} with tag {'date': 'day1'}\n", - "Data {'data': PosixPath('../examples/dataset1/day2.txt')} with tag {'date': 'day2'}\n", - "Data {'data': PosixPath('../examples/dataset1/day3.txt')} with tag {'date': 'day3'}\n", - "Data {'data': PosixPath('../examples/dataset1/day4.txt')} with tag {'date': 'day4'}\n", - "Data {'data': PosixPath('../examples/dataset1/day6.txt')} with tag {'date': 'day6'}\n" - ] - } - ], - "source": [ - "for tag, data in dataset1_custom:\n", - " print(f\"Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Custom tag function would allow one to extract information useful in controlling the flow of the data pipeline from the file path or even the file content. We will return to this a bit later." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In general, a data is generated and starts flowing into a `stream` **only** when you ask for it by iterating through the elements. This allows for a series of streams and pods to be chained together without immediately invoking any computation." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Let's go ahead and load another source from a folder containing multiple `*.bin` files, representing data collected on different days." - ] - }, - { - "cell_type": "code", - "execution_count": 21, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Data {'bin_data': PosixPath('../examples/dataset2/session_day1.bin')} with tag {'file_name': 'session_day1'}\n", - "Data {'bin_data': PosixPath('../examples/dataset2/session_day3.bin')} with tag {'file_name': 'session_day3'}\n", - "Data {'bin_data': PosixPath('../examples/dataset2/session_day4.bin')} with tag {'file_name': 'session_day4'}\n", - "Data {'bin_data': PosixPath('../examples/dataset2/session_day5.bin')} with tag {'file_name': 'session_day5'}\n" - ] - } - ], - "source": [ - "dataset2 = ob.GlobSource(\"bin_data\", \"../examples/dataset2\", \"*.bin\")\n", - "\n", - "for tag, data in dataset2:\n", - " print(f\"Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Now we have two streams to work with, let's explore how we can manipulate/control the flow of streams using `operations` and, specifically, `mapper` operations." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Manipulating streams with `operations`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "As defined ealier in the [core concepts](./01_orcabridge_core_concepts%20copy.ipynb#core-concepts), we refer to any computation/transformation that works on stream(s) as `operations` in the pipeline. If the Orcapod pipeline were to be viewed as a DAG, the `streams` would be the edges connecting *nodes* that are the `operations`. " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "`Operations` can be divided into three categories based on their roles in the processing and manipulating streams. `Source`, `Mappers` and `Pods`. We have already seen an example of `Source` earlier when we worked with `GlobSource`. Officially, `Source` is an `operation` that produces a `stream` without taking in any inputs. They are best thought of as entry points of data into the pipeline.\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "\n", - "`Mappers` are `operations` that controls and alter the streams but *without generating or modifying new data files*. As we will see shortly, `mappers` work to alter the stream by alterning data tags and/or data content, but critically will never create or modify new files that were not already present somewhere in the stream feeding into the `mapper` node. While this might sound like an unnecessary restriction on what `mappers` can do, we will see that this property guarantees that *mappers can not ever alter the reproducibility of computational chains*." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The third category of `operations` are `Pods`, these operations are **allowed to generate and flow new files into the streams** *based on* inputs they receive from other streams. Aside from `Source`, which takes no inputs, `Pods` are the only operations that can introduce new files into the stream.\n", - "\n", - "We will explore pods in great detail later. First let's get to know `mappers`." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Controling data streams with `Mappers`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Once you have created a `source` from which streams can be formed, you can alter the stream by applying various `mappers`. More precisely, a `mapper` can work on tags and/or data." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Map data\n", - "Likely one of the most common mapper operation to be found in Orcapod pipeline is `MapData` mapper. As the name implies, it let's you alter the keys (argument names) found in the `data`." - ] - }, - { - "cell_type": "code", - "execution_count": 22, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Before mapping:\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day1.txt')} with tag {'file_name': 'day1'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day2.txt')} with tag {'file_name': 'day2'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day3.txt')} with tag {'file_name': 'day3'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day4.txt')} with tag {'file_name': 'day4'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day6.txt')} with tag {'file_name': 'day6'}\n", - "After mapping:\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day1.txt')} with tag {'file_name': 'day1'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day2.txt')} with tag {'file_name': 'day2'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day3.txt')} with tag {'file_name': 'day3'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day4.txt')} with tag {'file_name': 'day4'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day6.txt')} with tag {'file_name': 'day6'}\n" - ] - } - ], - "source": [ - "print(\"Before mapping:\")\n", - "for tag, data in dataset1:\n", - " print(f\"Data {data} with tag {tag}\")\n", - "\n", - "\n", - "# create a new stream mapping data keys 'txt_file' to 'content'\n", - "data_mapper = ob.MapData(key_map={\"txt_file\": \"content\"})\n", - "\n", - "print(\"After mapping:\")\n", - "for tag, data in data_mapper(dataset1):\n", - " print(f\"Mapped Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "You'd notice that for each data, the key `txt_file` was replaced with `content` without altering the pointed `path` or the associated tag. As the keys of the data will be used as the name of arguments when invoking pods on a stream, we will see that `MapData` are commonly used to *map* the correct path to the argument." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Map tags\n", - "As we have already seen, each data in the stream is associated with a tag, often derived from the data source. In the case of `GlobFileSource`, the tags are by default the name of the file that formed the data. These tags are used to *transiently* identify the data and will be used when matching data across multiple streams (as we will see shortly in `Join` operation). You can manipulate the tags using `MapTags` operation, much like `MapKeys` but operating on the tags for each packaet under a uniform renaming rule." - ] - }, - { - "cell_type": "code", - "execution_count": 23, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "{'day': 'day1'} {'txt_file': PosixPath('../examples/dataset1/day1.txt')}\n", - "{'day': 'day2'} {'txt_file': PosixPath('../examples/dataset1/day2.txt')}\n", - "{'day': 'day3'} {'txt_file': PosixPath('../examples/dataset1/day3.txt')}\n", - "{'day': 'day4'} {'txt_file': PosixPath('../examples/dataset1/day4.txt')}\n", - "{'day': 'day6'} {'txt_file': PosixPath('../examples/dataset1/day6.txt')}\n" - ] - } - ], - "source": [ - "tag_mapper = ob.MapTags(key_map={\"file_name\": \"day\"})\n", - "\n", - "for tag, data in tag_mapper(dataset1):\n", - " print(tag, data)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Chaining operations" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "As you might expect, you can chain multiple operations one after another to construct a more complex stream. Below, we first apply the key mapping and then map tags." - ] - }, - { - "cell_type": "code", - "execution_count": 24, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Mapped Data {'content': PosixPath('../examples/dataset1/day1.txt')} with tag {'day': 'day1'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day2.txt')} with tag {'day': 'day2'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day3.txt')} with tag {'day': 'day3'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day4.txt')} with tag {'day': 'day4'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day6.txt')} with tag {'day': 'day6'}\n" - ] - } - ], - "source": [ - "data_mapper = ob.MapData(key_map={\"txt_file\": \"content\"})\n", - "key_mapped_stream = data_mapper(dataset1)\n", - "\n", - "tag_mapper = ob.MapTags(key_map={\"file_name\": \"day\"})\n", - "tag_and_data_mapped = tag_mapper(key_mapped_stream)\n", - "\n", - "for tag, data in tag_and_data_mapped:\n", - " print(f\"Mapped Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "It's worth emphasizing again that all computations are triggered only when you iterate through the final stream `tag_and_key_mapped`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Although not recommended as it reduces readability, you can create and immediately apply `mapper` to achieve the same processing in a fewer lines of code (albeit, with worse readability):" - ] - }, - { - "cell_type": "code", - "execution_count": 25, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Mapped Data {'content': PosixPath('../examples/dataset1/day1.txt')} with tag {'day': 'day1'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day2.txt')} with tag {'day': 'day2'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day3.txt')} with tag {'day': 'day3'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day4.txt')} with tag {'day': 'day4'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day6.txt')} with tag {'day': 'day6'}\n" - ] - } - ], - "source": [ - "# totally valid, but difficult to read and thus not recommended\n", - "for tag, data in ob.MapTags(key_map={\"file_name\": \"day\"})(\n", - " ob.MapData(key_map={\"txt_file\": \"content\"})(dataset1)\n", - "):\n", - " print(f\"Mapped Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Joining multiple streams into a single stream\n", - "Now that we have looked at how you can manipulate a single stream, let's turn our eyes to how you can work with more than one streams together.\n", - "\n", - "By the far the most common multi-stream operations will be to join two (or more) streams into a single, bigger stream. \n", - "You can combine multiple streams into one by using `Join` operation, matching data from each stream based on the matching tags. If tags from two streams have shared key, the value must be identical for all shared keys for the two data to be matched. The matched data are then merged into a one (typically larger) data and shipped to the output stream." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Let's see what happens if we join `dataset1` and `dataset2`, where:" - ] - }, - { - "cell_type": "code", - "execution_count": 26, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Dataset 1:\n", - "Tag: {'file_name': 'day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day1.txt')}\n", - "Tag: {'file_name': 'day2'}, Data: {'txt_file': PosixPath('../examples/dataset1/day2.txt')}\n", - "Tag: {'file_name': 'day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day3.txt')}\n", - "Tag: {'file_name': 'day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day4.txt')}\n", - "Tag: {'file_name': 'day6'}, Data: {'txt_file': PosixPath('../examples/dataset1/day6.txt')}\n", - "\n", - "Dataset 2:\n", - "Tag: {'file_name': 'session_day1'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "Tag: {'file_name': 'session_day3'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "Tag: {'file_name': 'session_day4'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "Tag: {'file_name': 'session_day5'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n" - ] - } - ], - "source": [ - "# dataset 1\n", - "print(\"Dataset 1:\")\n", - "for tag, data in dataset1:\n", - " print(f\"Tag: {tag}, Data: {data}\")\n", - "\n", - "# dataset 2\n", - "print(\"\\nDataset 2:\")\n", - "for tag, data in dataset2:\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Any guess what would happen?" - ] - }, - { - "cell_type": "code", - "execution_count": 27, - "metadata": {}, - "outputs": [], - "source": [ - "join_op = ob.Join()\n", - "\n", - "for tag, data in join_op(dataset1, dataset2):\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "You may be surprised to see that the joined stream is completely empty! This is because data from both streams were tagged with key `file_name`, causing the `Join` to combine data only if the value of `file_name` matches exactly. Since no filenames matched, the resulting stream was empty!" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "This is where we can make use of the other `mappers` to our advantage and achieve more useful join." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "First, let's completely rename the tag key for one of the streams and see what would happen." - ] - }, - { - "cell_type": "code", - "execution_count": 28, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "01 Tag: {'day': 'day1', 'file_name': 'session_day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day1.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "02 Tag: {'day': 'day1', 'file_name': 'session_day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day1.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "03 Tag: {'day': 'day1', 'file_name': 'session_day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day1.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "04 Tag: {'day': 'day1', 'file_name': 'session_day5'}, Data: {'txt_file': PosixPath('../examples/dataset1/day1.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n", - "05 Tag: {'day': 'day2', 'file_name': 'session_day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day2.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "06 Tag: {'day': 'day2', 'file_name': 'session_day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day2.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "07 Tag: {'day': 'day2', 'file_name': 'session_day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day2.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "08 Tag: {'day': 'day2', 'file_name': 'session_day5'}, Data: {'txt_file': PosixPath('../examples/dataset1/day2.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n", - "09 Tag: {'day': 'day3', 'file_name': 'session_day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day3.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "10 Tag: {'day': 'day3', 'file_name': 'session_day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day3.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "11 Tag: {'day': 'day3', 'file_name': 'session_day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day3.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "12 Tag: {'day': 'day3', 'file_name': 'session_day5'}, Data: {'txt_file': PosixPath('../examples/dataset1/day3.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n", - "13 Tag: {'day': 'day4', 'file_name': 'session_day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day4.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "14 Tag: {'day': 'day4', 'file_name': 'session_day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day4.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "15 Tag: {'day': 'day4', 'file_name': 'session_day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day4.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "16 Tag: {'day': 'day4', 'file_name': 'session_day5'}, Data: {'txt_file': PosixPath('../examples/dataset1/day4.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n", - "17 Tag: {'day': 'day6', 'file_name': 'session_day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day6.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "18 Tag: {'day': 'day6', 'file_name': 'session_day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day6.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "19 Tag: {'day': 'day6', 'file_name': 'session_day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day6.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "20 Tag: {'day': 'day6', 'file_name': 'session_day5'}, Data: {'txt_file': PosixPath('../examples/dataset1/day6.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n" - ] - } - ], - "source": [ - "dataset1_retagged = ob.MapTags(key_map={\"file_name\": \"day\"})(dataset1)\n", - "\n", - "for i, (tag, data) in enumerate(join_op(dataset1_retagged, dataset2)):\n", - " print(f\"{i + 1:02d} Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We are now getting something -- in fact, quite a few things. If you look carefully at the `data`, you'll notice that it now contains two keys/arguments -- `txt_file` and `bin_data`, combining the data from the two datasets. \n", - "\n", - "The `tags` also now contain two keys `day` from the re-tagged dataset1 stream and `file_name` from unchanged dataset2 stream.\n", - "\n", - "Since the two streams share no common tags, the `Join` operation results in *full-multiplexing* of two streams. With the streams from dataset1 and dataset2 containing 5 data and 4 data, respectively, you get $5 \\times 4 = 20$ data" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "However, it is not all too useful if all `Join` can do is to produce either 0 data or a full combination of data from two streams. The true value of `Join` lies in its ability to match two data that are *related* to each other. \n", - "\n", - "In our example datasets, you likely noticed that files from both datasets are associated with a day. Let's now try to join the two dataset streams by matching by the day!" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Although we could achieve the desired effect by changing how we load the source, passing in custom `tag_function` into `GlobSource`, let's achieve the same by using another `mapper` called `Transform`. `Transform` effectively combines `MapKey` and `MapTag` but further allows you to provide a function that will receive the tag and data, one at a time, and return a (potentially modified) tag and/or data, achieving the desired transformation." - ] - }, - { - "cell_type": "code", - "execution_count": 30, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'day': 'day1'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "Tag: {'day': 'day3'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "Tag: {'day': 'day4'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "Tag: {'day': 'day5'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n" - ] - } - ], - "source": [ - "def transform_dataset2(tag, data):\n", - " # Extract the second half of the filename containing day\n", - " new_tag = {\"day\": tag[\"file_name\"].split(\"_\")[1]}\n", - " return new_tag, data\n", - "\n", - "\n", - "# Speical mappers like transform can be found in the orcabridge.mapper module\n", - "dataset2_transformer = ob.mapper.Transform(transform_dataset2)\n", - "\n", - "retagged_dataset2 = dataset2_transformer(dataset2)\n", - "\n", - "for tag, data in retagged_dataset2:\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Now we have dataset2 data tagged with `day`, let's `join`` with a mapped dataset1!" - ] - }, - { - "cell_type": "code", - "execution_count": 31, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'day': 'day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day1.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "Tag: {'day': 'day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day3.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "Tag: {'day': 'day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day4.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n" - ] - } - ], - "source": [ - "# change filename to day for dataset1\n", - "tag_mapper = ob.MapTags(key_map={\"file_name\": \"day\"})\n", - "retagged_dataset1 = tag_mapper(dataset1)\n", - "\n", - "join_op = ob.Join()\n", - "joined_stream = join_op(retagged_dataset1, retagged_dataset2)\n", - "\n", - "for tag, data in joined_stream:\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Nice! We have now formed a stream where data from two streams are paired meaningfully based on matching `day`!" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Now we have explored quite a bit on how to manipulate data stream using `mapper` operations, it's time to turn to the other half ot he operations: `pods`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Introducing new files into stream with `Pod`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "While `mapper` operations are useful in altering tags, data, and in combining multiple streams, a data pipeline is not really useful if it cannot produce new resultsin the form of new data -- that is, introduce new files into the stream. This is precisely where `Pod` operations come in!\n", - "\n", - "In fact, we have already been working with a `pod` all along -- `sources`. If you think about it, `sources` also introduce files into the stream. It is just special in that it takes no input streams (hence the name, `source`).\n", - "\n", - "We now will explore how you can create a more common type of pod -- a *function* `pod` that takes in a stream and return a new stream potentially introducing entirely new data file!" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Working with `FunctionPod`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The easiest way to create a function-like `pod` is to create a `FunctionPod`, passing in a Python function. Let's start by creating a pod that will count the number of lines in a file.\n", - "\n", - "We first define the function." - ] - }, - { - "cell_type": "code", - "execution_count": 32, - "metadata": {}, - "outputs": [], - "source": [ - "from os import PathLike\n", - "\n", - "\n", - "def count_lines(txt_file: PathLike) -> None:\n", - " with open(txt_file, \"r\") as f:\n", - " lines = f.readlines()\n", - " print(f\"File {txt_file} has {len(lines)} lines.\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Next we instantiate a function pod from the function." - ] - }, - { - "cell_type": "code", - "execution_count": 33, - "metadata": {}, - "outputs": [], - "source": [ - "# create a function pod\n", - "function_pod = ob.FunctionPod(count_lines, output_keys=[])" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Once function pod is available, you can execute it on any compatible stream" - ] - }, - { - "cell_type": "code", - "execution_count": 34, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "File ../examples/dataset1/day1.txt has 24 lines.\n", - "Tag: {'file_name': 'day1'}, Data: {}\n", - "File ../examples/dataset1/day2.txt has 15 lines.\n", - "Tag: {'file_name': 'day2'}, Data: {}\n", - "File ../examples/dataset1/day3.txt has 27 lines.\n", - "Tag: {'file_name': 'day3'}, Data: {}\n", - "File ../examples/dataset1/day4.txt has 22 lines.\n", - "Tag: {'file_name': 'day4'}, Data: {}\n", - "File ../examples/dataset1/day6.txt has 22 lines.\n", - "Tag: {'file_name': 'day6'}, Data: {}\n" - ] - } - ], - "source": [ - "# apply the function pod on a stream\n", - "processed_stream = function_pod(dataset1)\n", - "\n", - "for tag, data in processed_stream:\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Notice that the returned `data` is empty because the function returns no values. Such a function pod may still be useful for achieving computations/processing via *side effects* (e.g., submitting HTTP requests in the function body)l, but it is not the standard approach in performing computations where you'd want the results to persis.\n", - "\n", - "Next, let's see how to achieve more common scenario where you perform some computation and you now would like to save the result into a file. Dataset2 binary actually contains a list of floats values. Let's define a function to compute a few statistics and save them to a file in a temporary directory." - ] - }, - { - "cell_type": "code", - "execution_count": 35, - "metadata": {}, - "outputs": [], - "source": [ - "import json\n", - "import tempfile\n", - "\n", - "import numpy as np\n", - "\n", - "\n", - "def compute_stats(bin_file: PathLike, output_file=None):\n", - " print(\"Computing stats for file:\", bin_file)\n", - " # create a temporary file to store the status and return the file path\n", - " with open(bin_file, \"rb\") as f:\n", - " data = f.read()\n", - " data = np.frombuffer(data)\n", - " print(data)\n", - " data_stats = {}\n", - " data_stats[\"mean\"] = np.mean(data)\n", - " data_stats[\"std\"] = np.std(data)\n", - " data_stats[\"min\"] = np.min(data)\n", - " data_stats[\"max\"] = np.max(data)\n", - " data_stats[\"n_elements\"] = len(data)\n", - "\n", - " # if output_file is none, create a temporary file. Else, use the given output_file to save the data_stats\n", - " if output_file is None:\n", - " output_file = Path(tempfile.mkdtemp()) / \"statistics.json\"\n", - " # write as json\n", - " with open(output_file, \"w\") as f:\n", - " json.dump(data_stats, f)\n", - " return output_file" - ] - }, - { - "cell_type": "code", - "execution_count": 36, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Computing stats for file: ../examples/dataset2/session_day1.bin\n", - "[-1.08209134 -0.66806394 0.42870206 -0.09321731 -3.14078305 1.33520433\n", - " 1.11085152 1.31931842 -1.19915697 0.07701737 1.30020807 0.27541194\n", - " 0.84430062 0.18236837 -0.83039631 -1.66166191 0.8720775 -1.72170657\n", - " -0.01962253 -0.18050553 1.35478472 0.69928177 0.7314272 -0.06915687\n", - " -0.08364667 -0.45551653 0.70752188 1.02283734 -0.18612795 0.8767394\n", - " -1.542636 1.04685484 -2.1311672 -1.34874222 0.61977577 -0.33880262\n", - " 0.6624482 0.60257325 -3.04901544 -0.20685843 -0.08997232 0.88932232]\n", - "Tag: {'file_name': 'session_day1'}, Data: {'stats': PosixPath('/tmp/tmpm2wka6il/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day3.bin\n", - "[ 0.56114059 -1.34902274 1.0665563 0.71890802 0.65244834 1.04369548\n", - " 0.54872876 2.19365207 0.53864286 -1.44108823 -0.55651539 0.1603561\n", - " -0.93869224 0.64645323 -1.08815337 1.40972393 -0.14662931 1.34692375\n", - " 0.38400938 -1.23004316 1.34426647 -0.07620065 -0.91983972 0.23537101\n", - " 0.91515395 0.8064348 0.81470895 -1.04466683 -0.25893558 -1.46253167\n", - " 1.39972807 -0.13940519]\n", - "Tag: {'file_name': 'session_day3'}, Data: {'stats': PosixPath('/tmp/tmplkmx65ll/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day4.bin\n", - "[ 0.70078854 1.18137906 -0.44361437 -0.389409 0.29719038 0.2523247\n", - " -0.97418716 0.49301127 0.07900351 -0.29965042 -0.25810762 -2.78777445\n", - " -1.24321702 0.13011593 1.07826637 -0.33177479 -0.78337033 -1.30075356\n", - " -0.15710138 0.51927589 0.08671884 0.02058063 0.20778149 -1.40382559\n", - " -0.69978105 -1.10525753 0.1945444 0.82623748 0.17467868]\n", - "Tag: {'file_name': 'session_day4'}, Data: {'stats': PosixPath('/tmp/tmpxajrzctd/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day5.bin\n", - "[ 1.9125739 -0.05252076 0.33347618 0.31627214 0.47141153 -0.71088615\n", - " -0.74745805 0.53959117 -0.14395142 -0.28713782 -0.29422236 -1.00231383\n", - " 0.69566576 -0.25895608 -0.9660761 -0.78504297 -1.91668262 0.89452296\n", - " -0.82748688 -0.19792482 0.07305616 0.36133414 1.7164791 0.64364619\n", - " -0.73146429 0.96324864 -1.05981222 -0.59502066 0.15084192]\n", - "Tag: {'file_name': 'session_day5'}, Data: {'stats': PosixPath('/tmp/tmp67rthfe1/statistics.json')}\n" - ] - } - ], - "source": [ - "fp_stats = ob.FunctionPod(compute_stats, output_keys=[\"stats\"])\n", - "\n", - "# change the key from 'bin_data' to 'bin_file', matching the function's input\n", - "mapped_dataset2 = ob.MapData(key_map={\"bin_data\": \"bin_file\"})(dataset2)\n", - "\n", - "for tag, data in fp_stats(mapped_dataset2):\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Note that in our function `compute_stats`, the computed stats are saved as `json` file into a temporary file. While this works to pass data from one to another within the pipeline, the result cannot be easily retrieved outside of the immediate usage. In fact, the computation result is very likely to disappear in some time (afterall, it's a temporary file). In fact, if you were to execute the same computation by iterating the second time over `stats_stream`, you will see that it invokes the functions yet again, and produces an entirely different set of temporary files. Since the content of computation didn't change, this is cearly quite wasteful!" - ] - }, - { - "cell_type": "code", - "execution_count": 37, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Computing stats for file: ../examples/dataset2/session_day1.bin\n", - "[-1.08209134 -0.66806394 0.42870206 -0.09321731 -3.14078305 1.33520433\n", - " 1.11085152 1.31931842 -1.19915697 0.07701737 1.30020807 0.27541194\n", - " 0.84430062 0.18236837 -0.83039631 -1.66166191 0.8720775 -1.72170657\n", - " -0.01962253 -0.18050553 1.35478472 0.69928177 0.7314272 -0.06915687\n", - " -0.08364667 -0.45551653 0.70752188 1.02283734 -0.18612795 0.8767394\n", - " -1.542636 1.04685484 -2.1311672 -1.34874222 0.61977577 -0.33880262\n", - " 0.6624482 0.60257325 -3.04901544 -0.20685843 -0.08997232 0.88932232]\n", - "Tag: {'file_name': 'session_day1'}, Data: {'stats': PosixPath('/tmp/tmpciwa2xl_/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day3.bin\n", - "[ 0.56114059 -1.34902274 1.0665563 0.71890802 0.65244834 1.04369548\n", - " 0.54872876 2.19365207 0.53864286 -1.44108823 -0.55651539 0.1603561\n", - " -0.93869224 0.64645323 -1.08815337 1.40972393 -0.14662931 1.34692375\n", - " 0.38400938 -1.23004316 1.34426647 -0.07620065 -0.91983972 0.23537101\n", - " 0.91515395 0.8064348 0.81470895 -1.04466683 -0.25893558 -1.46253167\n", - " 1.39972807 -0.13940519]\n", - "Tag: {'file_name': 'session_day3'}, Data: {'stats': PosixPath('/tmp/tmpkq824j5b/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day4.bin\n", - "[ 0.70078854 1.18137906 -0.44361437 -0.389409 0.29719038 0.2523247\n", - " -0.97418716 0.49301127 0.07900351 -0.29965042 -0.25810762 -2.78777445\n", - " -1.24321702 0.13011593 1.07826637 -0.33177479 -0.78337033 -1.30075356\n", - " -0.15710138 0.51927589 0.08671884 0.02058063 0.20778149 -1.40382559\n", - " -0.69978105 -1.10525753 0.1945444 0.82623748 0.17467868]\n", - "Tag: {'file_name': 'session_day4'}, Data: {'stats': PosixPath('/tmp/tmp7ii2nd6e/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day5.bin\n", - "[ 1.9125739 -0.05252076 0.33347618 0.31627214 0.47141153 -0.71088615\n", - " -0.74745805 0.53959117 -0.14395142 -0.28713782 -0.29422236 -1.00231383\n", - " 0.69566576 -0.25895608 -0.9660761 -0.78504297 -1.91668262 0.89452296\n", - " -0.82748688 -0.19792482 0.07305616 0.36133414 1.7164791 0.64364619\n", - " -0.73146429 0.96324864 -1.05981222 -0.59502066 0.15084192]\n", - "Tag: {'file_name': 'session_day5'}, Data: {'stats': PosixPath('/tmp/tmpz23q61gg/statistics.json')}\n" - ] - } - ], - "source": [ - "# everytime you run the following loop, new computations are performed and\n", - "# saved in a different set of temporary files\n", - "for tag, data in fp_stats(mapped_dataset2):\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In the next section we will see how we can have the computation restuls stored using storage-backed function pods." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### [Technical aside] Caching stream" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "**NOTE**: This section concerns an implementation detail of `Oracbridge` that is not fundamentally related to the design of the system. In particular, the issue described in this section (and the associated *solution*) is not relevant to the full-implementation that `Orcapod` will be. If you are reading this document primarily to understand the concepts essential to Orcapod, you are advised to skip this section entirely. However, if you intend to make use of `oracabridge` in an actual application, read on to learn critical limitations associated with single-producer single-consumer (SPSC) design of the `orcabridge` and how you can ameloiorate this using `CacheStream` mapper effectively within your pipeline." - ] - }, - { - "cell_type": "code", - "execution_count": 38, - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "HashableMixin.__hash__ called on CacheStream instance without identity_structure() implementation. Falling back to super().__hash__() which is not stable across sessions.\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Computing stats for file: ../examples/dataset2/session_day1.bin\n", - "[-1.08209134 -0.66806394 0.42870206 -0.09321731 -3.14078305 1.33520433\n", - " 1.11085152 1.31931842 -1.19915697 0.07701737 1.30020807 0.27541194\n", - " 0.84430062 0.18236837 -0.83039631 -1.66166191 0.8720775 -1.72170657\n", - " -0.01962253 -0.18050553 1.35478472 0.69928177 0.7314272 -0.06915687\n", - " -0.08364667 -0.45551653 0.70752188 1.02283734 -0.18612795 0.8767394\n", - " -1.542636 1.04685484 -2.1311672 -1.34874222 0.61977577 -0.33880262\n", - " 0.6624482 0.60257325 -3.04901544 -0.20685843 -0.08997232 0.88932232]\n", - "Tag: {'file_name': 'session_day1'}, Data: {'stats': PosixPath('/tmp/tmpukvddhuv/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day3.bin\n", - "[ 0.56114059 -1.34902274 1.0665563 0.71890802 0.65244834 1.04369548\n", - " 0.54872876 2.19365207 0.53864286 -1.44108823 -0.55651539 0.1603561\n", - " -0.93869224 0.64645323 -1.08815337 1.40972393 -0.14662931 1.34692375\n", - " 0.38400938 -1.23004316 1.34426647 -0.07620065 -0.91983972 0.23537101\n", - " 0.91515395 0.8064348 0.81470895 -1.04466683 -0.25893558 -1.46253167\n", - " 1.39972807 -0.13940519]\n", - "Tag: {'file_name': 'session_day3'}, Data: {'stats': PosixPath('/tmp/tmpat3rm4dk/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day4.bin\n", - "[ 0.70078854 1.18137906 -0.44361437 -0.389409 0.29719038 0.2523247\n", - " -0.97418716 0.49301127 0.07900351 -0.29965042 -0.25810762 -2.78777445\n", - " -1.24321702 0.13011593 1.07826637 -0.33177479 -0.78337033 -1.30075356\n", - " -0.15710138 0.51927589 0.08671884 0.02058063 0.20778149 -1.40382559\n", - " -0.69978105 -1.10525753 0.1945444 0.82623748 0.17467868]\n", - "Tag: {'file_name': 'session_day4'}, Data: {'stats': PosixPath('/tmp/tmpuj3tiu8k/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day5.bin\n", - "[ 1.9125739 -0.05252076 0.33347618 0.31627214 0.47141153 -0.71088615\n", - " -0.74745805 0.53959117 -0.14395142 -0.28713782 -0.29422236 -1.00231383\n", - " 0.69566576 -0.25895608 -0.9660761 -0.78504297 -1.91668262 0.89452296\n", - " -0.82748688 -0.19792482 0.07305616 0.36133414 1.7164791 0.64364619\n", - " -0.73146429 0.96324864 -1.05981222 -0.59502066 0.15084192]\n", - "Tag: {'file_name': 'session_day5'}, Data: {'stats': PosixPath('/tmp/tmp6yohu0pw/statistics.json')}\n" - ] - } - ], - "source": [ - "# create a cache stream operation\n", - "cache_stream = ob.mapper.CacheStream()\n", - "# change the key from 'bin_data' to 'bin_file', matching the function's input\n", - "mapped_dataset2 = ob.MapData(key_map={\"bin_data\": \"bin_file\"})(dataset2)\n", - "stats_stream = fp_stats(mapped_dataset2)\n", - "\n", - "# now cache the stream\n", - "cached_stream = cache_stream(stats_stream)\n", - "\n", - "# iterate over the cached stream\n", - "for tag, data in cached_stream:\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The first time we iterate over the `cached_stream`, you see that the function `compute_stats` is getting executed as we'd expect. However, it's when running it the second time you'd notice something is different." - ] - }, - { - "cell_type": "code", - "execution_count": 40, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'session_day1'}, Data: {'stats': PosixPath('/tmp/tmpukvddhuv/statistics.json')}\n", - "Tag: {'file_name': 'session_day3'}, Data: {'stats': PosixPath('/tmp/tmpat3rm4dk/statistics.json')}\n", - "Tag: {'file_name': 'session_day4'}, Data: {'stats': PosixPath('/tmp/tmpuj3tiu8k/statistics.json')}\n", - "Tag: {'file_name': 'session_day5'}, Data: {'stats': PosixPath('/tmp/tmp6yohu0pw/statistics.json')}\n" - ] - } - ], - "source": [ - "for tag, data in cached_stream:\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Since the output data from `stats_stream` have been cached, iterating through `cached_stream` for the second time simply returned the cached data without causing new computation. Although this may sound like a good way to prevent recomputing the same thing more than once, `CacheStream` comes with significant demerits. Since all observed data are stored in memory, having too many `CacheStream` in the pipeline may be very memory resource heavy. Also, unlike store-backed function, as we'll see shortly, `CacheStream` stores the data as seen from one iteration of the underlying stream. If the underlying stream would have produced new and diffirent data (e.g., because additional `bin` files are added to the dataset), `CacheStream` won't be able to update itself without you explicitly clearing the cache. Finally, unlike storage backed function pod, computation is *not memoized* and thus same exact computation may still take place if two or more data are identical in the content and thus would have yielded identical output." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Using storage-backed function pod" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Although the simple `FunctionPod` worked as expected, it's lack of ability to store computation results significantly limits its utility. You certainly wouldn't want to be computing everything from scratch if it can be avoided.\n", - "\n", - "The good news is that you can easily equip a function pod with an ability to store and retrieve previously stored data. All you have to do is create an instance of `DataStore` and pass it in at the construction of the `FunctionPod`.\n", - "\n", - "Here we are going to configure and use `DirDataStore` where all `data` and output `data` contents are stored in a designated directory." - ] - }, - { - "cell_type": "code", - "execution_count": 41, - "metadata": {}, - "outputs": [], - "source": [ - "data_store = ob.DirDataStore(\"./pod_data\")" - ] - }, - { - "cell_type": "code", - "execution_count": 42, - "metadata": {}, - "outputs": [], - "source": [ - "# use default storage directory of './pod_data'. You could specify a different directory by passing `store_dir` argument\n", - "fp_stats_stored = ob.FunctionPod(\n", - " compute_stats, output_keys=[\"stats\"], data_store=data_store\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Now your `FunctionPod` is equipped with an ability to store and retrieve stored data!" - ] - }, - { - "cell_type": "code", - "execution_count": 43, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'session_day1'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-c63c34c5fefaa0f2e9bba3edcf6c861c/statistics.json'}\n", - "Tag: {'file_name': 'session_day3'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-9dfef842f88463f5145ab0d4c06e3938/statistics.json'}\n", - "Tag: {'file_name': 'session_day4'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-4f3dfa71356fe8f226be66aa8dffbc55/statistics.json'}\n", - "Tag: {'file_name': 'session_day5'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-26bffc293c82e14cde904274e0c63afd/statistics.json'}\n" - ] - } - ], - "source": [ - "for tag, data in fp_stats_stored(mapped_dataset2):\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "As before, the very first time you run, all computations take place. Now watch what happens when you run it again." - ] - }, - { - "cell_type": "code", - "execution_count": 44, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'session_day1'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-c63c34c5fefaa0f2e9bba3edcf6c861c/statistics.json'}\n", - "Tag: {'file_name': 'session_day3'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-9dfef842f88463f5145ab0d4c06e3938/statistics.json'}\n", - "Tag: {'file_name': 'session_day4'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-4f3dfa71356fe8f226be66aa8dffbc55/statistics.json'}\n", - "Tag: {'file_name': 'session_day5'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-26bffc293c82e14cde904274e0c63afd/statistics.json'}\n" - ] - } - ], - "source": [ - "for tag, data in fp_stats_stored(mapped_dataset2):\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Notice that this time, the function `compute_stats` was **not** invoked. Rather the computation results from the previous run were *memoized* and *retrieved*, sparing us the unecessary computation!" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "orcabridge", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.13.3" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/notebooks/old_tutorials/02_orcapod_basic_usage.ipynb b/notebooks/old_tutorials/02_orcapod_basic_usage.ipynb deleted file mode 100644 index bb8b302b8..000000000 --- a/notebooks/old_tutorials/02_orcapod_basic_usage.ipynb +++ /dev/null @@ -1,1190 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Using Orcabridge" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In this notebook, we will explore the basic usage of Orcabridge library." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Below we explore the usage of `orcabridge` package, enumerating the core components. Many of these will correspond directly to [core concepts](./01_orcabridge_core_concepts%20copy.ipynb) introduced in in [part 1](./01_orcabridge_core_concepts%20copy.ipynb)." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [], - "source": [ - "# import orcabridge package\n", - "import orcabridge as ob" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Working with streams" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "`Stream` is fundamental to Orcapod data pipeline, representing *edges* in a directed acyclic graph (DAG) of an Orcapod pipeline. `Stream` is best thought of as a flowing stream of `data` -- a unit of data in Oracpod. A `data` is essentially a ditionary mapping argument names to a `pathset` (that is, one or more files with arbitrary nesting). Ultimately, a pod will receive and work on the `data`, looking up the pathset that matches the expected argument names defined as the inputs into the pod. Before we explore creating and using `pod`, we will create a very basic `stream` called `GlobStream`, sourcing from a directory. A data is formed for each file that matches the specified *glob* pattern." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Let's create a data source out of all `*.txt` files found in the folder `examples/dataset1`" - ] - }, - { - "cell_type": "code", - "execution_count": 15, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "\u001b[0m\u001b[01;32mday1.txt\u001b[0m* \u001b[01;32mday2.txt\u001b[0m* \u001b[01;32mday3.txt\u001b[0m* \u001b[01;32mday4.txt\u001b[0m* \u001b[01;32mday6.txt\u001b[0m*\n" - ] - } - ], - "source": [ - "%ls ../examples/dataset1" - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "metadata": {}, - "outputs": [], - "source": [ - "dataset1 = ob.GlobSource(\"txt_file\", \"../examples/dataset1\", \"*.txt\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We can then obtain `stream` from a `source` by invoking the source with `Source()`. The return `stream` acts as an iterator over the `data` and its `tag`.\n", - "For convenience, `source` can be treated synonymously with a `stream`, allowing you to directly iterate over the content." - ] - }, - { - "cell_type": "code", - "execution_count": 17, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Data {'txt_file': PosixPath('../examples/dataset1/day1.txt')} with tag {'file_name': 'day1'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day2.txt')} with tag {'file_name': 'day2'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day3.txt')} with tag {'file_name': 'day3'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day4.txt')} with tag {'file_name': 'day4'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day6.txt')} with tag {'file_name': 'day6'}\n" - ] - } - ], - "source": [ - "for tag, data in dataset1():\n", - " print(f\"Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "code", - "execution_count": 18, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Data {'txt_file': PosixPath('../examples/dataset1/day1.txt')} with tag {'file_name': 'day1'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day2.txt')} with tag {'file_name': 'day2'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day3.txt')} with tag {'file_name': 'day3'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day4.txt')} with tag {'file_name': 'day4'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day6.txt')} with tag {'file_name': 'day6'}\n" - ] - } - ], - "source": [ - "# equivalent to above but more natural without the need to call `dataset1()`\n", - "for tag, data in dataset1:\n", - " print(f\"Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "A few things to note. When creating the `GlobSource` we pass in the argument name to be associated with the `pathset` matching our glob pattern (`*.txt` in this case). By default, the `GlobSource` tags each data with a key of `file_name` and value of the name of the file that was matched (minus the file extension). This behavior can be easily changed by passing in a custom function for tag generation at the time of `GlobSource` creation." - ] - }, - { - "cell_type": "code", - "execution_count": 19, - "metadata": {}, - "outputs": [], - "source": [ - "from pathlib import Path\n", - "\n", - "dataset1_custom = ob.GlobSource(\n", - " \"data\",\n", - " \"../examples/dataset1\",\n", - " \"*.txt\",\n", - " tag_function=lambda x: {\"date\": Path(x).stem},\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 20, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Data {'data': PosixPath('../examples/dataset1/day1.txt')} with tag {'date': 'day1'}\n", - "Data {'data': PosixPath('../examples/dataset1/day2.txt')} with tag {'date': 'day2'}\n", - "Data {'data': PosixPath('../examples/dataset1/day3.txt')} with tag {'date': 'day3'}\n", - "Data {'data': PosixPath('../examples/dataset1/day4.txt')} with tag {'date': 'day4'}\n", - "Data {'data': PosixPath('../examples/dataset1/day6.txt')} with tag {'date': 'day6'}\n" - ] - } - ], - "source": [ - "for tag, data in dataset1_custom:\n", - " print(f\"Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Custom tag function would allow one to extract information useful in controlling the flow of the data pipeline from the file path or even the file content. We will return to this a bit later." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In general, a data is generated and starts flowing into a `stream` **only** when you ask for it by iterating through the elements. This allows for a series of streams and pods to be chained together without immediately invoking any computation." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Let's go ahead and load another source from a folder containing multiple `*.bin` files, representing data collected on different days." - ] - }, - { - "cell_type": "code", - "execution_count": 21, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Data {'bin_data': PosixPath('../examples/dataset2/session_day1.bin')} with tag {'file_name': 'session_day1'}\n", - "Data {'bin_data': PosixPath('../examples/dataset2/session_day3.bin')} with tag {'file_name': 'session_day3'}\n", - "Data {'bin_data': PosixPath('../examples/dataset2/session_day4.bin')} with tag {'file_name': 'session_day4'}\n", - "Data {'bin_data': PosixPath('../examples/dataset2/session_day5.bin')} with tag {'file_name': 'session_day5'}\n" - ] - } - ], - "source": [ - "dataset2 = ob.GlobSource(\"bin_data\", \"../examples/dataset2\", \"*.bin\")\n", - "\n", - "for tag, data in dataset2:\n", - " print(f\"Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Now we have two streams to work with, let's explore how we can manipulate/control the flow of streams using `operations` and, specifically, `mapper` operations." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Manipulating streams with `operations`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "As defined ealier in the [core concepts](./01_orcabridge_core_concepts%20copy.ipynb#core-concepts), we refer to any computation/transformation that works on stream(s) as `operations` in the pipeline. If the Orcapod pipeline were to be viewed as a DAG, the `streams` would be the edges connecting *nodes* that are the `operations`. " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "`Operations` can be divided into three categories based on their roles in the processing and manipulating streams. `Source`, `Mappers` and `Pods`. We have already seen an example of `Source` earlier when we worked with `GlobSource`. Officially, `Source` is an `operation` that produces a `stream` without taking in any inputs. They are best thought of as entry points of data into the pipeline.\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "\n", - "`Mappers` are `operations` that controls and alter the streams but *without generating or modifying new data files*. As we will see shortly, `mappers` work to alter the stream by alterning data tags and/or data content, but critically will never create or modify new files that were not already present somewhere in the stream feeding into the `mapper` node. While this might sound like an unnecessary restriction on what `mappers` can do, we will see that this property guarantees that *mappers can not ever alter the reproducibility of computational chains*." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The third category of `operations` are `Pods`, these operations are **allowed to generate and flow new files into the streams** *based on* inputs they receive from other streams. Aside from `Source`, which takes no inputs, `Pods` are the only operations that can introduce new files into the stream.\n", - "\n", - "We will explore pods in great detail later. First let's get to know `mappers`." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Controling data streams with `Mappers`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Once you have created a `source` from which streams can be formed, you can alter the stream by applying various `mappers`. More precisely, a `mapper` can work on tags and/or data." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Map data\n", - "Likely one of the most common mapper operation to be found in Orcapod pipeline is `MapData` mapper. As the name implies, it let's you alter the keys (argument names) found in the `data`." - ] - }, - { - "cell_type": "code", - "execution_count": 22, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Before mapping:\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day1.txt')} with tag {'file_name': 'day1'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day2.txt')} with tag {'file_name': 'day2'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day3.txt')} with tag {'file_name': 'day3'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day4.txt')} with tag {'file_name': 'day4'}\n", - "Data {'txt_file': PosixPath('../examples/dataset1/day6.txt')} with tag {'file_name': 'day6'}\n", - "After mapping:\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day1.txt')} with tag {'file_name': 'day1'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day2.txt')} with tag {'file_name': 'day2'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day3.txt')} with tag {'file_name': 'day3'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day4.txt')} with tag {'file_name': 'day4'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day6.txt')} with tag {'file_name': 'day6'}\n" - ] - } - ], - "source": [ - "print(\"Before mapping:\")\n", - "for tag, data in dataset1:\n", - " print(f\"Data {data} with tag {tag}\")\n", - "\n", - "\n", - "# create a new stream mapping data keys 'txt_file' to 'content'\n", - "data_mapper = ob.MapData(key_map={\"txt_file\": \"content\"})\n", - "\n", - "print(\"After mapping:\")\n", - "for tag, data in data_mapper(dataset1):\n", - " print(f\"Mapped Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "You'd notice that for each data, the key `txt_file` was replaced with `content` without altering the pointed `path` or the associated tag. As the keys of the data will be used as the name of arguments when invoking pods on a stream, we will see that `MapData` are commonly used to *map* the correct path to the argument." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Map tags\n", - "As we have already seen, each data in the stream is associated with a tag, often derived from the data source. In the case of `GlobFileSource`, the tags are by default the name of the file that formed the data. These tags are used to *transiently* identify the data and will be used when matching data across multiple streams (as we will see shortly in `Join` operation). You can manipulate the tags using `MapTags` operation, much like `MapKeys` but operating on the tags for each packaet under a uniform renaming rule." - ] - }, - { - "cell_type": "code", - "execution_count": 23, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "{'day': 'day1'} {'txt_file': PosixPath('../examples/dataset1/day1.txt')}\n", - "{'day': 'day2'} {'txt_file': PosixPath('../examples/dataset1/day2.txt')}\n", - "{'day': 'day3'} {'txt_file': PosixPath('../examples/dataset1/day3.txt')}\n", - "{'day': 'day4'} {'txt_file': PosixPath('../examples/dataset1/day4.txt')}\n", - "{'day': 'day6'} {'txt_file': PosixPath('../examples/dataset1/day6.txt')}\n" - ] - } - ], - "source": [ - "tag_mapper = ob.MapTags(key_map={\"file_name\": \"day\"})\n", - "\n", - "for tag, data in tag_mapper(dataset1):\n", - " print(tag, data)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Chaining operations" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "As you might expect, you can chain multiple operations one after another to construct a more complex stream. Below, we first apply the key mapping and then map tags." - ] - }, - { - "cell_type": "code", - "execution_count": 24, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Mapped Data {'content': PosixPath('../examples/dataset1/day1.txt')} with tag {'day': 'day1'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day2.txt')} with tag {'day': 'day2'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day3.txt')} with tag {'day': 'day3'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day4.txt')} with tag {'day': 'day4'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day6.txt')} with tag {'day': 'day6'}\n" - ] - } - ], - "source": [ - "data_mapper = ob.MapData(key_map={\"txt_file\": \"content\"})\n", - "key_mapped_stream = data_mapper(dataset1)\n", - "\n", - "tag_mapper = ob.MapTags(key_map={\"file_name\": \"day\"})\n", - "tag_and_data_mapped = tag_mapper(key_mapped_stream)\n", - "\n", - "for tag, data in tag_and_data_mapped:\n", - " print(f\"Mapped Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "It's worth emphasizing again that all computations are triggered only when you iterate through the final stream `tag_and_key_mapped`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Although not recommended as it reduces readability, you can create and immediately apply `mapper` to achieve the same processing in a fewer lines of code (albeit, with worse readability):" - ] - }, - { - "cell_type": "code", - "execution_count": 25, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Mapped Data {'content': PosixPath('../examples/dataset1/day1.txt')} with tag {'day': 'day1'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day2.txt')} with tag {'day': 'day2'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day3.txt')} with tag {'day': 'day3'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day4.txt')} with tag {'day': 'day4'}\n", - "Mapped Data {'content': PosixPath('../examples/dataset1/day6.txt')} with tag {'day': 'day6'}\n" - ] - } - ], - "source": [ - "# totally valid, but difficult to read and thus not recommended\n", - "for tag, data in ob.MapTags(key_map={\"file_name\": \"day\"})(\n", - " ob.MapData(key_map={\"txt_file\": \"content\"})(dataset1)\n", - "):\n", - " print(f\"Mapped Data {data} with tag {tag}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Joining multiple streams into a single stream\n", - "Now that we have looked at how you can manipulate a single stream, let's turn our eyes to how you can work with more than one streams together.\n", - "\n", - "By the far the most common multi-stream operations will be to join two (or more) streams into a single, bigger stream. \n", - "You can combine multiple streams into one by using `Join` operation, matching data from each stream based on the matching tags. If tags from two streams have shared key, the value must be identical for all shared keys for the two data to be matched. The matched data are then merged into a one (typically larger) data and shipped to the output stream." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Let's see what happens if we join `dataset1` and `dataset2`, where:" - ] - }, - { - "cell_type": "code", - "execution_count": 26, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Dataset 1:\n", - "Tag: {'file_name': 'day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day1.txt')}\n", - "Tag: {'file_name': 'day2'}, Data: {'txt_file': PosixPath('../examples/dataset1/day2.txt')}\n", - "Tag: {'file_name': 'day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day3.txt')}\n", - "Tag: {'file_name': 'day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day4.txt')}\n", - "Tag: {'file_name': 'day6'}, Data: {'txt_file': PosixPath('../examples/dataset1/day6.txt')}\n", - "\n", - "Dataset 2:\n", - "Tag: {'file_name': 'session_day1'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "Tag: {'file_name': 'session_day3'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "Tag: {'file_name': 'session_day4'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "Tag: {'file_name': 'session_day5'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n" - ] - } - ], - "source": [ - "# dataset 1\n", - "print(\"Dataset 1:\")\n", - "for tag, data in dataset1:\n", - " print(f\"Tag: {tag}, Data: {data}\")\n", - "\n", - "# dataset 2\n", - "print(\"\\nDataset 2:\")\n", - "for tag, data in dataset2:\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Any guess what would happen?" - ] - }, - { - "cell_type": "code", - "execution_count": 27, - "metadata": {}, - "outputs": [], - "source": [ - "join_op = ob.Join()\n", - "\n", - "for tag, data in join_op(dataset1, dataset2):\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "You may be surprised to see that the joined stream is completely empty! This is because data from both streams were tagged with key `file_name`, causing the `Join` to combine data only if the value of `file_name` matches exactly. Since no filenames matched, the resulting stream was empty!" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "This is where we can make use of the other `mappers` to our advantage and achieve more useful join." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "First, let's completely rename the tag key for one of the streams and see what would happen." - ] - }, - { - "cell_type": "code", - "execution_count": 28, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "01 Tag: {'day': 'day1', 'file_name': 'session_day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day1.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "02 Tag: {'day': 'day1', 'file_name': 'session_day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day1.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "03 Tag: {'day': 'day1', 'file_name': 'session_day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day1.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "04 Tag: {'day': 'day1', 'file_name': 'session_day5'}, Data: {'txt_file': PosixPath('../examples/dataset1/day1.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n", - "05 Tag: {'day': 'day2', 'file_name': 'session_day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day2.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "06 Tag: {'day': 'day2', 'file_name': 'session_day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day2.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "07 Tag: {'day': 'day2', 'file_name': 'session_day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day2.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "08 Tag: {'day': 'day2', 'file_name': 'session_day5'}, Data: {'txt_file': PosixPath('../examples/dataset1/day2.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n", - "09 Tag: {'day': 'day3', 'file_name': 'session_day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day3.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "10 Tag: {'day': 'day3', 'file_name': 'session_day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day3.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "11 Tag: {'day': 'day3', 'file_name': 'session_day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day3.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "12 Tag: {'day': 'day3', 'file_name': 'session_day5'}, Data: {'txt_file': PosixPath('../examples/dataset1/day3.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n", - "13 Tag: {'day': 'day4', 'file_name': 'session_day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day4.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "14 Tag: {'day': 'day4', 'file_name': 'session_day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day4.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "15 Tag: {'day': 'day4', 'file_name': 'session_day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day4.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "16 Tag: {'day': 'day4', 'file_name': 'session_day5'}, Data: {'txt_file': PosixPath('../examples/dataset1/day4.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n", - "17 Tag: {'day': 'day6', 'file_name': 'session_day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day6.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "18 Tag: {'day': 'day6', 'file_name': 'session_day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day6.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "19 Tag: {'day': 'day6', 'file_name': 'session_day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day6.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "20 Tag: {'day': 'day6', 'file_name': 'session_day5'}, Data: {'txt_file': PosixPath('../examples/dataset1/day6.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n" - ] - } - ], - "source": [ - "dataset1_retagged = ob.MapTags(key_map={\"file_name\": \"day\"})(dataset1)\n", - "\n", - "for i, (tag, data) in enumerate(join_op(dataset1_retagged, dataset2)):\n", - " print(f\"{i + 1:02d} Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We are now getting something -- in fact, quite a few things. If you look carefully at the `data`, you'll notice that it now contains two keys/arguments -- `txt_file` and `bin_data`, combining the data from the two datasets. \n", - "\n", - "The `tags` also now contain two keys `day` from the re-tagged dataset1 stream and `file_name` from unchanged dataset2 stream.\n", - "\n", - "Since the two streams share no common tags, the `Join` operation results in *full-multiplexing* of two streams. With the streams from dataset1 and dataset2 containing 5 data and 4 data, respectively, you get $5 \\times 4 = 20$ data" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "However, it is not all too useful if all `Join` can do is to produce either 0 data or a full combination of data from two streams. The true value of `Join` lies in its ability to match two data that are *related* to each other. \n", - "\n", - "In our example datasets, you likely noticed that files from both datasets are associated with a day. Let's now try to join the two dataset streams by matching by the day!" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Although we could achieve the desired effect by changing how we load the source, passing in custom `tag_function` into `GlobSource`, let's achieve the same by using another `mapper` called `Transform`. `Transform` effectively combines `MapKey` and `MapTag` but further allows you to provide a function that will receive the tag and data, one at a time, and return a (potentially modified) tag and/or data, achieving the desired transformation." - ] - }, - { - "cell_type": "code", - "execution_count": 30, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'day': 'day1'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "Tag: {'day': 'day3'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "Tag: {'day': 'day4'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n", - "Tag: {'day': 'day5'}, Data: {'bin_data': PosixPath('../examples/dataset2/session_day5.bin')}\n" - ] - } - ], - "source": [ - "def transform_dataset2(tag, data):\n", - " # Extract the second half of the filename containing day\n", - " new_tag = {\"day\": tag[\"file_name\"].split(\"_\")[1]}\n", - " return new_tag, data\n", - "\n", - "\n", - "# Speical mappers like transform can be found in the orcabridge.mapper module\n", - "dataset2_transformer = ob.mapper.Transform(transform_dataset2)\n", - "\n", - "retagged_dataset2 = dataset2_transformer(dataset2)\n", - "\n", - "for tag, data in retagged_dataset2:\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Now we have dataset2 data tagged with `day`, let's `join`` with a mapped dataset1!" - ] - }, - { - "cell_type": "code", - "execution_count": 31, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'day': 'day1'}, Data: {'txt_file': PosixPath('../examples/dataset1/day1.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day1.bin')}\n", - "Tag: {'day': 'day3'}, Data: {'txt_file': PosixPath('../examples/dataset1/day3.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day3.bin')}\n", - "Tag: {'day': 'day4'}, Data: {'txt_file': PosixPath('../examples/dataset1/day4.txt'), 'bin_data': PosixPath('../examples/dataset2/session_day4.bin')}\n" - ] - } - ], - "source": [ - "# change filename to day for dataset1\n", - "tag_mapper = ob.MapTags(key_map={\"file_name\": \"day\"})\n", - "retagged_dataset1 = tag_mapper(dataset1)\n", - "\n", - "join_op = ob.Join()\n", - "joined_stream = join_op(retagged_dataset1, retagged_dataset2)\n", - "\n", - "for tag, data in joined_stream:\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Nice! We have now formed a stream where data from two streams are paired meaningfully based on matching `day`!" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Now we have explored quite a bit on how to manipulate data stream using `mapper` operations, it's time to turn to the other half ot he operations: `pods`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Introducing new files into stream with `Pod`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "While `mapper` operations are useful in altering tags, data, and in combining multiple streams, a data pipeline is not really useful if it cannot produce new resultsin the form of new data -- that is, introduce new files into the stream. This is precisely where `Pod` operations come in!\n", - "\n", - "In fact, we have already been working with a `pod` all along -- `sources`. If you think about it, `sources` also introduce files into the stream. It is just special in that it takes no input streams (hence the name, `source`).\n", - "\n", - "We now will explore how you can create a more common type of pod -- a *function* `pod` that takes in a stream and return a new stream potentially introducing entirely new data file!" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Working with `FunctionPod`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The easiest way to create a function-like `pod` is to create a `FunctionPod`, passing in a Python function. Let's start by creating a pod that will count the number of lines in a file.\n", - "\n", - "We first define the function." - ] - }, - { - "cell_type": "code", - "execution_count": 32, - "metadata": {}, - "outputs": [], - "source": [ - "from os import PathLike\n", - "\n", - "\n", - "def count_lines(txt_file: PathLike) -> None:\n", - " with open(txt_file, \"r\") as f:\n", - " lines = f.readlines()\n", - " print(f\"File {txt_file} has {len(lines)} lines.\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Next we instantiate a function pod from the function." - ] - }, - { - "cell_type": "code", - "execution_count": 33, - "metadata": {}, - "outputs": [], - "source": [ - "# create a function pod\n", - "function_pod = ob.FunctionPod(count_lines, output_keys=[])" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Once function pod is available, you can execute it on any compatible stream" - ] - }, - { - "cell_type": "code", - "execution_count": 34, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "File ../examples/dataset1/day1.txt has 24 lines.\n", - "Tag: {'file_name': 'day1'}, Data: {}\n", - "File ../examples/dataset1/day2.txt has 15 lines.\n", - "Tag: {'file_name': 'day2'}, Data: {}\n", - "File ../examples/dataset1/day3.txt has 27 lines.\n", - "Tag: {'file_name': 'day3'}, Data: {}\n", - "File ../examples/dataset1/day4.txt has 22 lines.\n", - "Tag: {'file_name': 'day4'}, Data: {}\n", - "File ../examples/dataset1/day6.txt has 22 lines.\n", - "Tag: {'file_name': 'day6'}, Data: {}\n" - ] - } - ], - "source": [ - "# apply the function pod on a stream\n", - "processed_stream = function_pod(dataset1)\n", - "\n", - "for tag, data in processed_stream:\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Notice that the returned `data` is empty because the function returns no values. Such a function pod may still be useful for achieving computations/processing via *side effects* (e.g., submitting HTTP requests in the function body)l, but it is not the standard approach in performing computations where you'd want the results to persis.\n", - "\n", - "Next, let's see how to achieve more common scenario where you perform some computation and you now would like to save the result into a file. Dataset2 binary actually contains a list of floats values. Let's define a function to compute a few statistics and save them to a file in a temporary directory." - ] - }, - { - "cell_type": "code", - "execution_count": 35, - "metadata": {}, - "outputs": [], - "source": [ - "import json\n", - "import tempfile\n", - "\n", - "import numpy as np\n", - "\n", - "\n", - "def compute_stats(bin_file: PathLike, output_file=None):\n", - " print(\"Computing stats for file:\", bin_file)\n", - " # create a temporary file to store the status and return the file path\n", - " with open(bin_file, \"rb\") as f:\n", - " data = f.read()\n", - " data = np.frombuffer(data)\n", - " print(data)\n", - " data_stats = {}\n", - " data_stats[\"mean\"] = np.mean(data)\n", - " data_stats[\"std\"] = np.std(data)\n", - " data_stats[\"min\"] = np.min(data)\n", - " data_stats[\"max\"] = np.max(data)\n", - " data_stats[\"n_elements\"] = len(data)\n", - "\n", - " # if output_file is none, create a temporary file. Else, use the given output_file to save the data_stats\n", - " if output_file is None:\n", - " output_file = Path(tempfile.mkdtemp()) / \"statistics.json\"\n", - " # write as json\n", - " with open(output_file, \"w\") as f:\n", - " json.dump(data_stats, f)\n", - " return output_file" - ] - }, - { - "cell_type": "code", - "execution_count": 36, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Computing stats for file: ../examples/dataset2/session_day1.bin\n", - "[-1.08209134 -0.66806394 0.42870206 -0.09321731 -3.14078305 1.33520433\n", - " 1.11085152 1.31931842 -1.19915697 0.07701737 1.30020807 0.27541194\n", - " 0.84430062 0.18236837 -0.83039631 -1.66166191 0.8720775 -1.72170657\n", - " -0.01962253 -0.18050553 1.35478472 0.69928177 0.7314272 -0.06915687\n", - " -0.08364667 -0.45551653 0.70752188 1.02283734 -0.18612795 0.8767394\n", - " -1.542636 1.04685484 -2.1311672 -1.34874222 0.61977577 -0.33880262\n", - " 0.6624482 0.60257325 -3.04901544 -0.20685843 -0.08997232 0.88932232]\n", - "Tag: {'file_name': 'session_day1'}, Data: {'stats': PosixPath('/tmp/tmpm2wka6il/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day3.bin\n", - "[ 0.56114059 -1.34902274 1.0665563 0.71890802 0.65244834 1.04369548\n", - " 0.54872876 2.19365207 0.53864286 -1.44108823 -0.55651539 0.1603561\n", - " -0.93869224 0.64645323 -1.08815337 1.40972393 -0.14662931 1.34692375\n", - " 0.38400938 -1.23004316 1.34426647 -0.07620065 -0.91983972 0.23537101\n", - " 0.91515395 0.8064348 0.81470895 -1.04466683 -0.25893558 -1.46253167\n", - " 1.39972807 -0.13940519]\n", - "Tag: {'file_name': 'session_day3'}, Data: {'stats': PosixPath('/tmp/tmplkmx65ll/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day4.bin\n", - "[ 0.70078854 1.18137906 -0.44361437 -0.389409 0.29719038 0.2523247\n", - " -0.97418716 0.49301127 0.07900351 -0.29965042 -0.25810762 -2.78777445\n", - " -1.24321702 0.13011593 1.07826637 -0.33177479 -0.78337033 -1.30075356\n", - " -0.15710138 0.51927589 0.08671884 0.02058063 0.20778149 -1.40382559\n", - " -0.69978105 -1.10525753 0.1945444 0.82623748 0.17467868]\n", - "Tag: {'file_name': 'session_day4'}, Data: {'stats': PosixPath('/tmp/tmpxajrzctd/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day5.bin\n", - "[ 1.9125739 -0.05252076 0.33347618 0.31627214 0.47141153 -0.71088615\n", - " -0.74745805 0.53959117 -0.14395142 -0.28713782 -0.29422236 -1.00231383\n", - " 0.69566576 -0.25895608 -0.9660761 -0.78504297 -1.91668262 0.89452296\n", - " -0.82748688 -0.19792482 0.07305616 0.36133414 1.7164791 0.64364619\n", - " -0.73146429 0.96324864 -1.05981222 -0.59502066 0.15084192]\n", - "Tag: {'file_name': 'session_day5'}, Data: {'stats': PosixPath('/tmp/tmp67rthfe1/statistics.json')}\n" - ] - } - ], - "source": [ - "fp_stats = ob.FunctionPod(compute_stats, output_keys=[\"stats\"])\n", - "\n", - "# change the key from 'bin_data' to 'bin_file', matching the function's input\n", - "mapped_dataset2 = ob.MapData(key_map={\"bin_data\": \"bin_file\"})(dataset2)\n", - "\n", - "for tag, data in fp_stats(mapped_dataset2):\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Note that in our function `compute_stats`, the computed stats are saved as `json` file into a temporary file. While this works to pass data from one to another within the pipeline, the result cannot be easily retrieved outside of the immediate usage. In fact, the computation result is very likely to disappear in some time (afterall, it's a temporary file). In fact, if you were to execute the same computation by iterating the second time over `stats_stream`, you will see that it invokes the functions yet again, and produces an entirely different set of temporary files. Since the content of computation didn't change, this is cearly quite wasteful!" - ] - }, - { - "cell_type": "code", - "execution_count": 37, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Computing stats for file: ../examples/dataset2/session_day1.bin\n", - "[-1.08209134 -0.66806394 0.42870206 -0.09321731 -3.14078305 1.33520433\n", - " 1.11085152 1.31931842 -1.19915697 0.07701737 1.30020807 0.27541194\n", - " 0.84430062 0.18236837 -0.83039631 -1.66166191 0.8720775 -1.72170657\n", - " -0.01962253 -0.18050553 1.35478472 0.69928177 0.7314272 -0.06915687\n", - " -0.08364667 -0.45551653 0.70752188 1.02283734 -0.18612795 0.8767394\n", - " -1.542636 1.04685484 -2.1311672 -1.34874222 0.61977577 -0.33880262\n", - " 0.6624482 0.60257325 -3.04901544 -0.20685843 -0.08997232 0.88932232]\n", - "Tag: {'file_name': 'session_day1'}, Data: {'stats': PosixPath('/tmp/tmpciwa2xl_/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day3.bin\n", - "[ 0.56114059 -1.34902274 1.0665563 0.71890802 0.65244834 1.04369548\n", - " 0.54872876 2.19365207 0.53864286 -1.44108823 -0.55651539 0.1603561\n", - " -0.93869224 0.64645323 -1.08815337 1.40972393 -0.14662931 1.34692375\n", - " 0.38400938 -1.23004316 1.34426647 -0.07620065 -0.91983972 0.23537101\n", - " 0.91515395 0.8064348 0.81470895 -1.04466683 -0.25893558 -1.46253167\n", - " 1.39972807 -0.13940519]\n", - "Tag: {'file_name': 'session_day3'}, Data: {'stats': PosixPath('/tmp/tmpkq824j5b/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day4.bin\n", - "[ 0.70078854 1.18137906 -0.44361437 -0.389409 0.29719038 0.2523247\n", - " -0.97418716 0.49301127 0.07900351 -0.29965042 -0.25810762 -2.78777445\n", - " -1.24321702 0.13011593 1.07826637 -0.33177479 -0.78337033 -1.30075356\n", - " -0.15710138 0.51927589 0.08671884 0.02058063 0.20778149 -1.40382559\n", - " -0.69978105 -1.10525753 0.1945444 0.82623748 0.17467868]\n", - "Tag: {'file_name': 'session_day4'}, Data: {'stats': PosixPath('/tmp/tmp7ii2nd6e/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day5.bin\n", - "[ 1.9125739 -0.05252076 0.33347618 0.31627214 0.47141153 -0.71088615\n", - " -0.74745805 0.53959117 -0.14395142 -0.28713782 -0.29422236 -1.00231383\n", - " 0.69566576 -0.25895608 -0.9660761 -0.78504297 -1.91668262 0.89452296\n", - " -0.82748688 -0.19792482 0.07305616 0.36133414 1.7164791 0.64364619\n", - " -0.73146429 0.96324864 -1.05981222 -0.59502066 0.15084192]\n", - "Tag: {'file_name': 'session_day5'}, Data: {'stats': PosixPath('/tmp/tmpz23q61gg/statistics.json')}\n" - ] - } - ], - "source": [ - "# everytime you run the following loop, new computations are performed and\n", - "# saved in a different set of temporary files\n", - "for tag, data in fp_stats(mapped_dataset2):\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In the next section we will see how we can have the computation restuls stored using storage-backed function pods." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### [Technical aside] Caching stream" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "**NOTE**: This section concerns an implementation detail of `Oracbridge` that is not fundamentally related to the design of the system. In particular, the issue described in this section (and the associated *solution*) is not relevant to the full-implementation that `Orcapod` will be. If you are reading this document primarily to understand the concepts essential to Orcapod, you are advised to skip this section entirely. However, if you intend to make use of `oracabridge` in an actual application, read on to learn critical limitations associated with single-producer single-consumer (SPSC) design of the `orcabridge` and how you can ameloiorate this using `CacheStream` mapper effectively within your pipeline." - ] - }, - { - "cell_type": "code", - "execution_count": 38, - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "HashableMixin.__hash__ called on CacheStream instance without identity_structure() implementation. Falling back to super().__hash__() which is not stable across sessions.\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Computing stats for file: ../examples/dataset2/session_day1.bin\n", - "[-1.08209134 -0.66806394 0.42870206 -0.09321731 -3.14078305 1.33520433\n", - " 1.11085152 1.31931842 -1.19915697 0.07701737 1.30020807 0.27541194\n", - " 0.84430062 0.18236837 -0.83039631 -1.66166191 0.8720775 -1.72170657\n", - " -0.01962253 -0.18050553 1.35478472 0.69928177 0.7314272 -0.06915687\n", - " -0.08364667 -0.45551653 0.70752188 1.02283734 -0.18612795 0.8767394\n", - " -1.542636 1.04685484 -2.1311672 -1.34874222 0.61977577 -0.33880262\n", - " 0.6624482 0.60257325 -3.04901544 -0.20685843 -0.08997232 0.88932232]\n", - "Tag: {'file_name': 'session_day1'}, Data: {'stats': PosixPath('/tmp/tmpukvddhuv/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day3.bin\n", - "[ 0.56114059 -1.34902274 1.0665563 0.71890802 0.65244834 1.04369548\n", - " 0.54872876 2.19365207 0.53864286 -1.44108823 -0.55651539 0.1603561\n", - " -0.93869224 0.64645323 -1.08815337 1.40972393 -0.14662931 1.34692375\n", - " 0.38400938 -1.23004316 1.34426647 -0.07620065 -0.91983972 0.23537101\n", - " 0.91515395 0.8064348 0.81470895 -1.04466683 -0.25893558 -1.46253167\n", - " 1.39972807 -0.13940519]\n", - "Tag: {'file_name': 'session_day3'}, Data: {'stats': PosixPath('/tmp/tmpat3rm4dk/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day4.bin\n", - "[ 0.70078854 1.18137906 -0.44361437 -0.389409 0.29719038 0.2523247\n", - " -0.97418716 0.49301127 0.07900351 -0.29965042 -0.25810762 -2.78777445\n", - " -1.24321702 0.13011593 1.07826637 -0.33177479 -0.78337033 -1.30075356\n", - " -0.15710138 0.51927589 0.08671884 0.02058063 0.20778149 -1.40382559\n", - " -0.69978105 -1.10525753 0.1945444 0.82623748 0.17467868]\n", - "Tag: {'file_name': 'session_day4'}, Data: {'stats': PosixPath('/tmp/tmpuj3tiu8k/statistics.json')}\n", - "Computing stats for file: ../examples/dataset2/session_day5.bin\n", - "[ 1.9125739 -0.05252076 0.33347618 0.31627214 0.47141153 -0.71088615\n", - " -0.74745805 0.53959117 -0.14395142 -0.28713782 -0.29422236 -1.00231383\n", - " 0.69566576 -0.25895608 -0.9660761 -0.78504297 -1.91668262 0.89452296\n", - " -0.82748688 -0.19792482 0.07305616 0.36133414 1.7164791 0.64364619\n", - " -0.73146429 0.96324864 -1.05981222 -0.59502066 0.15084192]\n", - "Tag: {'file_name': 'session_day5'}, Data: {'stats': PosixPath('/tmp/tmp6yohu0pw/statistics.json')}\n" - ] - } - ], - "source": [ - "# create a cache stream operation\n", - "cache_stream = ob.mapper.CacheStream()\n", - "# change the key from 'bin_data' to 'bin_file', matching the function's input\n", - "mapped_dataset2 = ob.MapData(key_map={\"bin_data\": \"bin_file\"})(dataset2)\n", - "stats_stream = fp_stats(mapped_dataset2)\n", - "\n", - "# now cache the stream\n", - "cached_stream = cache_stream(stats_stream)\n", - "\n", - "# iterate over the cached stream\n", - "for tag, data in cached_stream:\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The first time we iterate over the `cached_stream`, you see that the function `compute_stats` is getting executed as we'd expect. However, it's when running it the second time you'd notice something is different." - ] - }, - { - "cell_type": "code", - "execution_count": 40, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'session_day1'}, Data: {'stats': PosixPath('/tmp/tmpukvddhuv/statistics.json')}\n", - "Tag: {'file_name': 'session_day3'}, Data: {'stats': PosixPath('/tmp/tmpat3rm4dk/statistics.json')}\n", - "Tag: {'file_name': 'session_day4'}, Data: {'stats': PosixPath('/tmp/tmpuj3tiu8k/statistics.json')}\n", - "Tag: {'file_name': 'session_day5'}, Data: {'stats': PosixPath('/tmp/tmp6yohu0pw/statistics.json')}\n" - ] - } - ], - "source": [ - "for tag, data in cached_stream:\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Since the output data from `stats_stream` have been cached, iterating through `cached_stream` for the second time simply returned the cached data without causing new computation. Although this may sound like a good way to prevent recomputing the same thing more than once, `CacheStream` comes with significant demerits. Since all observed data are stored in memory, having too many `CacheStream` in the pipeline may be very memory resource heavy. Also, unlike store-backed function, as we'll see shortly, `CacheStream` stores the data as seen from one iteration of the underlying stream. If the underlying stream would have produced new and diffirent data (e.g., because additional `bin` files are added to the dataset), `CacheStream` won't be able to update itself without you explicitly clearing the cache. Finally, unlike storage backed function pod, computation is *not memoized* and thus same exact computation may still take place if two or more data are identical in the content and thus would have yielded identical output." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Using storage-backed function pod" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Although the simple `FunctionPod` worked as expected, it's lack of ability to store computation results significantly limits its utility. You certainly wouldn't want to be computing everything from scratch if it can be avoided.\n", - "\n", - "The good news is that you can easily equip a function pod with an ability to store and retrieve previously stored data. All you have to do is create an instance of `DataStore` and pass it in at the construction of the `FunctionPod`.\n", - "\n", - "Here we are going to configure and use `DirDataStore` where all `data` and output `data` contents are stored in a designated directory." - ] - }, - { - "cell_type": "code", - "execution_count": 41, - "metadata": {}, - "outputs": [], - "source": [ - "data_store = ob.DirDataStore(\"./pod_data\")" - ] - }, - { - "cell_type": "code", - "execution_count": 42, - "metadata": {}, - "outputs": [], - "source": [ - "# use default storage directory of './pod_data'. You could specify a different directory by passing `store_dir` argument\n", - "fp_stats_stored = ob.FunctionPod(\n", - " compute_stats, output_keys=[\"stats\"], data_store=data_store\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Now your `FunctionPod` is equipped with an ability to store and retrieve stored data!" - ] - }, - { - "cell_type": "code", - "execution_count": 43, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'session_day1'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-c63c34c5fefaa0f2e9bba3edcf6c861c/statistics.json'}\n", - "Tag: {'file_name': 'session_day3'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-9dfef842f88463f5145ab0d4c06e3938/statistics.json'}\n", - "Tag: {'file_name': 'session_day4'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-4f3dfa71356fe8f226be66aa8dffbc55/statistics.json'}\n", - "Tag: {'file_name': 'session_day5'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-26bffc293c82e14cde904274e0c63afd/statistics.json'}\n" - ] - } - ], - "source": [ - "for tag, data in fp_stats_stored(mapped_dataset2):\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "As before, the very first time you run, all computations take place. Now watch what happens when you run it again." - ] - }, - { - "cell_type": "code", - "execution_count": 44, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'session_day1'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-c63c34c5fefaa0f2e9bba3edcf6c861c/statistics.json'}\n", - "Tag: {'file_name': 'session_day3'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-9dfef842f88463f5145ab0d4c06e3938/statistics.json'}\n", - "Tag: {'file_name': 'session_day4'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-4f3dfa71356fe8f226be66aa8dffbc55/statistics.json'}\n", - "Tag: {'file_name': 'session_day5'}, Data: {'stats': 'pod_data/compute_stats/15da3b08791f51d9/sha256-26bffc293c82e14cde904274e0c63afd/statistics.json'}\n" - ] - } - ], - "source": [ - "for tag, data in fp_stats_stored(mapped_dataset2):\n", - " print(f\"Tag: {tag}, Data: {data}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Notice that this time, the function `compute_stats` was **not** invoked. Rather the computation results from the previous run were *memoized* and *retrieved*, sparing us the unecessary computation!" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "venv", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.12" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/notebooks/old_tutorials/03_orcacapod_qol_features.ipynb b/notebooks/old_tutorials/03_orcacapod_qol_features.ipynb deleted file mode 100644 index d83b8da9b..000000000 --- a/notebooks/old_tutorials/03_orcacapod_qol_features.ipynb +++ /dev/null @@ -1,580 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "58c56103", - "metadata": {}, - "source": [ - "# QoL Improving Features of `orcabridge`" - ] - }, - { - "cell_type": "markdown", - "id": "b16b1b64", - "metadata": {}, - "source": [ - "In the [previous notebook](./02-02-advanced-usage.ipynb), we explored the `orcabridge` package and learned how to build and execute a simple pipeline using concepts like `streams`, `operations` and `pods`." - ] - }, - { - "cell_type": "markdown", - "id": "90a30ec7", - "metadata": {}, - "source": [ - "For an example, we saw that we can define a function pod to wrap a function and to feed in a stream with the data keys properly mapped into argument names expected by the pod:" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "f5339f87", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'day1'}, Data: {'output_data': 'path/to/result/file'}\n", - "Tag: {'file_name': 'day2'}, Data: {'output_data': 'path/to/result/file'}\n", - "Tag: {'file_name': 'day3'}, Data: {'output_data': 'path/to/result/file'}\n", - "Tag: {'file_name': 'day4'}, Data: {'output_data': 'path/to/result/file'}\n", - "Tag: {'file_name': 'day6'}, Data: {'output_data': 'path/to/result/file'}\n" - ] - } - ], - "source": [ - "import orcabridge as ob\n", - "\n", - "source = ob.GlobSource(\"text_file\", \"../examples/dataset1\", \"*.txt\")\n", - "\n", - "\n", - "def process_data(data):\n", - " # perform data processing on data\n", - " # return result file path\n", - " return \"path/to/result/file\"\n", - "\n", - "\n", - "fp_process = ob.FunctionPod(process_data, [\"output_data\"])\n", - "\n", - "data_mapper = ob.MapData({\"text_file\": \"data\"}) # map data key text_file to data\n", - "\n", - "# chain them together into a pipeline\n", - "mapped_stream = data_mapper(source)\n", - "processed_data_stream = fp_process(mapped_stream)\n", - "\n", - "processed_data_stream.head() # see the first 5 data" - ] - }, - { - "cell_type": "markdown", - "id": "d9b7f902", - "metadata": {}, - "source": [ - "While separately creating all `mapper` and `pods` and then chaining them helps to rigorously define the data pipeline, admittedly it can get quite verbose and cumbersome.\n", - "\n", - "Fortunately, `orcabrdige` has a number of quality-of-life (QoL) improving features that will help you much more quickly create and combine `operations` and `streams` to define your pipeline without losing the full expressivity. In this notebook, we will explore such QoL improvement features together." - ] - }, - { - "cell_type": "markdown", - "id": "78e8c206", - "metadata": {}, - "source": [ - "## `function_pod` decorator for simple `FunctionPod` creation" - ] - }, - { - "cell_type": "markdown", - "id": "f398fcfd", - "metadata": {}, - "source": [ - "We saw that we can use `FunctionPod` class to wrap an existing function and to associate `output_keys` to rigorously define a `FunctionPod` object that can be used to perform computations on streams of data.\n", - "\n", - "Often, you'd want to define a function intending to only use it as a `FunctionPod`. In that case, you can simplify the `FunctionPod` creation by decorating the function with the `function_pod` decorator:" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "9703d751", - "metadata": {}, - "outputs": [], - "source": [ - "import json\n", - "import tempfile\n", - "from pathlib import Path\n", - "\n", - "from orcabridge.pod import function_pod\n", - "\n", - "json_source = ob.GlobSource(\"json_file\", \"../examples/dataset2\", \"*.json\")\n", - "\n", - "\n", - "@function_pod([\"output_data\"])\n", - "def extract_name_from_json(json_file):\n", - " with open(json_file, \"r\") as f:\n", - " data = json.load(f)\n", - " output_data = {\"info\": \"\"}\n", - " if \"name\" in data:\n", - " output_data[\"info\"] = data[\"name\"]\n", - " output_path = Path(tempfile.mkdtemp()) / \"output.json\"\n", - " with open(output_path, \"w\") as f:\n", - " json.dump(output_data, f)\n", - " return output_path" - ] - }, - { - "cell_type": "markdown", - "id": "f3ffe3d6", - "metadata": {}, - "source": [ - "With the above code, the decorator takes the decorated function and creates a FunctionPod with the specified output arguments (\"output_data\" in this case).\n", - "\n", - "The name `extract_name_from_json` now holds the resulting `FunctionPod` that can be immeidately applied to a stream." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "1e2b5d86", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'info_day1'}, Data: {'output_data': PosixPath('/tmp/tmpb0q3mj9m/output.json')}\n", - "Tag: {'file_name': 'info_day2'}, Data: {'output_data': PosixPath('/tmp/tmpt79_hpoe/output.json')}\n", - "Tag: {'file_name': 'info_day3'}, Data: {'output_data': PosixPath('/tmp/tmp_rq1b2rq/output.json')}\n", - "Tag: {'file_name': 'info_day4'}, Data: {'output_data': PosixPath('/tmp/tmp4dyoqbix/output.json')}\n", - "Tag: {'file_name': 'info_day5'}, Data: {'output_data': PosixPath('/tmp/tmpc9a1bxx4/output.json')}\n" - ] - } - ], - "source": [ - "extract_name_from_json(json_source).head() # preview the first 5 data" - ] - }, - { - "cell_type": "markdown", - "id": "1ca2aa60", - "metadata": {}, - "source": [ - "If you need to access the original function, it can be retrieved by accessing the `function` attribute" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "c5dc8a46", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "{'info': 'Day 2 experiment'}\n" - ] - } - ], - "source": [ - "output_path = extract_name_from_json.function(\"../examples/dataset2/info_day2.json\")\n", - "\n", - "with open(output_path, \"r\") as f:\n", - " data = json.load(f)\n", - " print(data) # {'info': 'John Doe'}" - ] - }, - { - "cell_type": "markdown", - "id": "bea0880a", - "metadata": {}, - "source": [ - "## Mapping tags and data with `>>` operator" - ] - }, - { - "cell_type": "markdown", - "id": "7a1e38e4", - "metadata": {}, - "source": [ - "As you chain multiple pods together forming a complex pipeline, you are bound to make frequent use of `MapData` to *rename* the output argument from one pod into another argunemt name for the next pod. We have already seen how this can be achieved by creating a specific instance of `MapData`, initializing the object with a dictionary defining the name mapping." - ] - }, - { - "cell_type": "markdown", - "id": "af660c4f", - "metadata": {}, - "source": [ - "Consider the following data source and function pod:" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "c30e1e4a", - "metadata": {}, - "outputs": [], - "source": [ - "json_files = ob.GlobSource(\"json_file\", \"../examples/dataset2\", \"*.json\")\n", - "\n", - "\n", - "@ob.function_pod([\"line_count\"])\n", - "def count_lines(text_file):\n", - " with open(text_file, \"r\") as f:\n", - " lines = f.readlines()\n", - " line_count = len(lines)\n", - " output_path = Path(tempfile.mkdtemp()) / \"line_count.json\"\n", - " with open(output_path, \"w\") as f:\n", - " json.dump({\"line_count\": line_count}, f)\n", - " return output_path" - ] - }, - { - "cell_type": "markdown", - "id": "6788ff05", - "metadata": {}, - "source": [ - "If I want to apply the function pod to count and save the number of lines present in the JSON files from the data source, I will have to create a `MapData` that renames the output argument `\"json_file\"` itno `\"text_file\"` expected by the `count_lines` function." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "2d171b0e", - "metadata": {}, - "outputs": [], - "source": [ - "json_to_text = ob.MapData(\n", - " {\"json_file\": \"text_file\"}\n", - ") # map data key json_file to text_file" - ] - }, - { - "cell_type": "markdown", - "id": "c7994b9b", - "metadata": {}, - "source": [ - "Finally we can chain them together into a functional pipeline:" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "d48fc20c", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'info_day1'}, Data: {'line_count': PosixPath('/tmp/tmpl9kxw4yn/line_count.json')}\n", - "Tag: {'file_name': 'info_day2'}, Data: {'line_count': PosixPath('/tmp/tmpa0d08oym/line_count.json')}\n", - "Tag: {'file_name': 'info_day3'}, Data: {'line_count': PosixPath('/tmp/tmp_9r0cryr/line_count.json')}\n", - "Tag: {'file_name': 'info_day4'}, Data: {'line_count': PosixPath('/tmp/tmpygwfjha9/line_count.json')}\n", - "Tag: {'file_name': 'info_day5'}, Data: {'line_count': PosixPath('/tmp/tmph_5zgk6j/line_count.json')}\n" - ] - } - ], - "source": [ - "line_info = count_lines(json_to_text(json_files))\n", - "\n", - "line_info.head() # preview the first 5 data" - ] - }, - { - "cell_type": "markdown", - "id": "09d9da59", - "metadata": {}, - "source": [ - "This is all fine until you start having many more `Pods` and `streams` in your pipeline that needs to be connected together. Many of these connection would need the `MapData` `mapper` to be inserted for the function to work properly -- that could be a lot of `MapData` you have to create!" - ] - }, - { - "cell_type": "markdown", - "id": "063cc9e7", - "metadata": {}, - "source": [ - "Because `MapData` is such a common operation, `orcabridge` provides a very simple shortcut for creating a *mapped stream* from another stream using right shift (`>>`) operator." - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "10437185", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'info_day1'}, Data: {'text_file': PosixPath('../examples/dataset2/info_day1.json')}\n", - "Tag: {'file_name': 'info_day2'}, Data: {'text_file': PosixPath('../examples/dataset2/info_day2.json')}\n", - "Tag: {'file_name': 'info_day3'}, Data: {'text_file': PosixPath('../examples/dataset2/info_day3.json')}\n", - "Tag: {'file_name': 'info_day4'}, Data: {'text_file': PosixPath('../examples/dataset2/info_day4.json')}\n", - "Tag: {'file_name': 'info_day5'}, Data: {'text_file': PosixPath('../examples/dataset2/info_day5.json')}\n", - "Tag: {'file_name': 'info_day1'}, Data: {'line_count': PosixPath('/tmp/tmpskhgsexk/line_count.json')}\n", - "Tag: {'file_name': 'info_day2'}, Data: {'line_count': PosixPath('/tmp/tmp7oto9nav/line_count.json')}\n", - "Tag: {'file_name': 'info_day3'}, Data: {'line_count': PosixPath('/tmp/tmpushxubr1/line_count.json')}\n", - "Tag: {'file_name': 'info_day4'}, Data: {'line_count': PosixPath('/tmp/tmpb2fhgner/line_count.json')}\n", - "Tag: {'file_name': 'info_day5'}, Data: {'line_count': PosixPath('/tmp/tmpnujrqytb/line_count.json')}\n" - ] - } - ], - "source": [ - "mapped_stream = json_files >> {\"json_file\": \"text_file\"}\n", - "\n", - "mapped_stream.head()\n", - "\n", - "count_lines(mapped_stream).head()" - ] - }, - { - "cell_type": "markdown", - "id": "3cd02672", - "metadata": {}, - "source": [ - "That's it! Hopefully you'd agree that this is far more convenient than having to define your own `MapData` mapper! Using the `>>` operator, the whole pipeline would have looked like:" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "9be9f86d", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'info_day1'}, Data: {'line_count': PosixPath('/tmp/tmp4ny0gm34/line_count.json')}\n", - "Tag: {'file_name': 'info_day2'}, Data: {'line_count': PosixPath('/tmp/tmpegxyuceg/line_count.json')}\n", - "Tag: {'file_name': 'info_day3'}, Data: {'line_count': PosixPath('/tmp/tmpwzvjhte9/line_count.json')}\n", - "Tag: {'file_name': 'info_day4'}, Data: {'line_count': PosixPath('/tmp/tmpf0loiyqs/line_count.json')}\n", - "Tag: {'file_name': 'info_day5'}, Data: {'line_count': PosixPath('/tmp/tmp9vatjy_m/line_count.json')}\n" - ] - } - ], - "source": [ - "# preview the first 5 data\n", - "count_lines(json_files >> {\"json_file\": \"text_file\"}).head()" - ] - }, - { - "cell_type": "markdown", - "id": "24a4d11e", - "metadata": {}, - "source": [ - "Not only is this simpler to type, we believe it actually makes the pipeline creation more intuitive and expressive of your intention!" - ] - }, - { - "cell_type": "markdown", - "id": "18ec64f3", - "metadata": {}, - "source": [ - "### Mapping tags and advanced mapping" - ] - }, - { - "cell_type": "markdown", - "id": "05e8ff25", - "metadata": {}, - "source": [ - "We just saw how the rightshift operator can be used to simplify the `MapData` operation creation. How about `MapTags`? We can get `MapTags` equivalent operation also by using the rightshift (`>>`) operator, but with the help of an additional function: `tag()`." - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "id": "b0164e6e", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'experiment_day': 'info_day1'}, Data: {'json_file': PosixPath('../examples/dataset2/info_day1.json')}\n", - "Tag: {'experiment_day': 'info_day2'}, Data: {'json_file': PosixPath('../examples/dataset2/info_day2.json')}\n", - "Tag: {'experiment_day': 'info_day3'}, Data: {'json_file': PosixPath('../examples/dataset2/info_day3.json')}\n", - "Tag: {'experiment_day': 'info_day4'}, Data: {'json_file': PosixPath('../examples/dataset2/info_day4.json')}\n", - "Tag: {'experiment_day': 'info_day5'}, Data: {'json_file': PosixPath('../examples/dataset2/info_day5.json')}\n" - ] - } - ], - "source": [ - "# use ob.tag to specifically map the tag key\n", - "(json_files >> ob.tag({\"file_name\": \"experiment_day\"})).head()" - ] - }, - { - "cell_type": "markdown", - "id": "ac34eed4", - "metadata": {}, - "source": [ - "Now if you were to closely inspect `MapData` and `MapData`, you would know that it is capable of taking in some additional arguments such as `drop_unmapped`. Using `tag()` and `data()` helper functions would let you specify those arguments as well while using the `>>` operator." - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "id": "b366b19c", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'info_day1'}, Data: {}\n", - "Tag: {'file_name': 'info_day2'}, Data: {}\n", - "Tag: {'file_name': 'info_day3'}, Data: {}\n", - "Tag: {'file_name': 'info_day4'}, Data: {}\n", - "Tag: {'file_name': 'info_day5'}, Data: {}\n" - ] - } - ], - "source": [ - "# no data key matches `data_file`: by default, this will lead to an empty data\n", - "(json_files >> {\"data_file\": \"file_path\"}).head()" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "id": "b3920086", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'info_day1'}, Data: {'json_file': PosixPath('../examples/dataset2/info_day1.json')}\n", - "Tag: {'file_name': 'info_day2'}, Data: {'json_file': PosixPath('../examples/dataset2/info_day2.json')}\n", - "Tag: {'file_name': 'info_day3'}, Data: {'json_file': PosixPath('../examples/dataset2/info_day3.json')}\n", - "Tag: {'file_name': 'info_day4'}, Data: {'json_file': PosixPath('../examples/dataset2/info_day4.json')}\n", - "Tag: {'file_name': 'info_day5'}, Data: {'json_file': PosixPath('../examples/dataset2/info_day5.json')}\n" - ] - } - ], - "source": [ - "# you can preseve unmapped data key by using `data` function with `drop_unmapped=False`\n", - "(json_files >> ob.data({\"data_file\": \"file_path\"}, drop_unmapped=False)).head()" - ] - }, - { - "cell_type": "markdown", - "id": "4b207473", - "metadata": {}, - "source": [ - "### Join streams with `*`" - ] - }, - { - "cell_type": "markdown", - "id": "e0907330", - "metadata": {}, - "source": [ - "We have seen joining two streams using `ob.Join()` mapper, for example joining two streams from different data sources." - ] - }, - { - "cell_type": "code", - "execution_count": 21, - "id": "a1fc0641", - "metadata": {}, - "outputs": [], - "source": [ - "dataset1 = ob.GlobSource(\"text_file\", \"../examples/dataset1\", \"*.txt\")\n", - "dataset2 = ob.GlobSource(\"json_file\", \"../examples/dataset2\", \"*.json\")" - ] - }, - { - "cell_type": "code", - "execution_count": 22, - "id": "700d29bd", - "metadata": {}, - "outputs": [], - "source": [ - "mapped_dataset1 = dataset1 >> ob.tag({\"file_name\": \"txt_file\"})\n", - "mapped_dataset2 = dataset2 >> ob.tag({\"file_name\": \"json_file\"})" - ] - }, - { - "cell_type": "code", - "execution_count": 23, - "id": "77caa110", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'txt_file': 'day1', 'json_file': 'info_day1'}, Data: {'text_file': PosixPath('../examples/dataset1/day1.txt'), 'json_file': PosixPath('../examples/dataset2/info_day1.json')}\n", - "Tag: {'txt_file': 'day1', 'json_file': 'info_day2'}, Data: {'text_file': PosixPath('../examples/dataset1/day1.txt'), 'json_file': PosixPath('../examples/dataset2/info_day2.json')}\n", - "Tag: {'txt_file': 'day1', 'json_file': 'info_day3'}, Data: {'text_file': PosixPath('../examples/dataset1/day1.txt'), 'json_file': PosixPath('../examples/dataset2/info_day3.json')}\n", - "Tag: {'txt_file': 'day1', 'json_file': 'info_day4'}, Data: {'text_file': PosixPath('../examples/dataset1/day1.txt'), 'json_file': PosixPath('../examples/dataset2/info_day4.json')}\n", - "Tag: {'txt_file': 'day1', 'json_file': 'info_day5'}, Data: {'text_file': PosixPath('../examples/dataset1/day1.txt'), 'json_file': PosixPath('../examples/dataset2/info_day5.json')}\n" - ] - } - ], - "source": [ - "join_op = ob.Join()\n", - "\n", - "joined_stream = join_op(mapped_dataset1, mapped_dataset2)\n", - "joined_stream.head() # preview the first 5 data" - ] - }, - { - "cell_type": "markdown", - "id": "571af914", - "metadata": {}, - "source": [ - "It can be quite cumbersome to create a `join_op = ob.Join()` everytime you want to join two streams. While you can actually create the instance of `ob.Join` once and reuse it everywhere you need `join`, there is a more convenient way to join two streams: use `*`!" - ] - }, - { - "cell_type": "code", - "execution_count": 24, - "id": "7e6959a1", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'txt_file': 'day1', 'json_file': 'info_day1'}, Data: {'text_file': PosixPath('../examples/dataset1/day1.txt'), 'json_file': PosixPath('../examples/dataset2/info_day1.json')}\n", - "Tag: {'txt_file': 'day1', 'json_file': 'info_day2'}, Data: {'text_file': PosixPath('../examples/dataset1/day1.txt'), 'json_file': PosixPath('../examples/dataset2/info_day2.json')}\n", - "Tag: {'txt_file': 'day1', 'json_file': 'info_day3'}, Data: {'text_file': PosixPath('../examples/dataset1/day1.txt'), 'json_file': PosixPath('../examples/dataset2/info_day3.json')}\n", - "Tag: {'txt_file': 'day1', 'json_file': 'info_day4'}, Data: {'text_file': PosixPath('../examples/dataset1/day1.txt'), 'json_file': PosixPath('../examples/dataset2/info_day4.json')}\n", - "Tag: {'txt_file': 'day1', 'json_file': 'info_day5'}, Data: {'text_file': PosixPath('../examples/dataset1/day1.txt'), 'json_file': PosixPath('../examples/dataset2/info_day5.json')}\n" - ] - } - ], - "source": [ - "# the following is equivalent to running join_op(mapped_dataset1, mapped_dataset2)\n", - "joined_stream = mapped_dataset1 * mapped_dataset2\n", - "joined_stream.head() # preview the first 5 data" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "venv", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.12" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/notebooks/old_tutorials/04_orcapod_tracker.ipynb b/notebooks/old_tutorials/04_orcapod_tracker.ipynb deleted file mode 100644 index fd96408c0..000000000 --- a/notebooks/old_tutorials/04_orcapod_tracker.ipynb +++ /dev/null @@ -1,439 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "d698bea9", - "metadata": {}, - "source": [ - "## Using Tracker" - ] - }, - { - "cell_type": "markdown", - "id": "5be82e8a", - "metadata": {}, - "source": [ - "In this notebook, I'll demonstrate using `Tracker` and related features of `orcabridge` to keep *track* of all `operations` you are using in a pipeline and to automatically construct computation graph based on it." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "f28a62af", - "metadata": {}, - "outputs": [], - "source": [ - "from orcabridge.pod import function_pod\n", - "from orcabridge.source import GlobSource\n", - "from orcabridge.store import DirDataStore\n", - "from orcabridge.tracker import Tracker" - ] - }, - { - "cell_type": "markdown", - "id": "110970a8", - "metadata": {}, - "source": [ - "As before let's construct a simple data pipeline that reads files and counts the number of lines, saving that information into another file. We will then chain it with another function that converts JSON to YAML." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "56136d16", - "metadata": {}, - "outputs": [], - "source": [ - "data_source = GlobSource(\"data_file\", \"../examples/dataset1\", \"*.txt\")" - ] - }, - { - "cell_type": "markdown", - "id": "8137ce66", - "metadata": {}, - "source": [ - "We are also going to define a few functions to serve as function pods. We are using convenience function `function_pod` to decorate the function to immediately turn them into a `FunctionPod` as was covered [in previous notebook](./03_orcabridge_qol_features.ipynb)." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "c32938d6", - "metadata": {}, - "outputs": [], - "source": [ - "import json\n", - "import tempfile\n", - "from pathlib import Path\n", - "\n", - "import yaml\n", - "\n", - "# use default data store location of `./pod_data`\n", - "data_store = DirDataStore()\n", - "\n", - "\n", - "# function to count lines in a file and save it as JSON\n", - "@function_pod([\"stats\"], data_store=data_store)\n", - "def count_lines(file: str):\n", - " with open(file, \"r\") as f:\n", - " n = len(f.readlines())\n", - " tmp_dir = tempfile.mkdtemp()\n", - " data_file = Path(tmp_dir) / \"data.json\"\n", - " data = dict(lines=n)\n", - " with open(data_file, \"w\") as f:\n", - " json.dump(data, f)\n", - " return data_file\n", - "\n", - "\n", - "@function_pod([\"yaml_file\"], data_store=data_store)\n", - "def json_to_yaml(json_file: str):\n", - " with open(json_file, \"r\") as f:\n", - " data = json.load(f)\n", - " tmp_dir = tempfile.mkdtemp()\n", - " yaml_path = Path(tmp_dir) / Path(json_file).with_suffix(\".yaml\").name\n", - " with open(yaml_path, \"w\") as f:\n", - " yaml.dump(data, f)\n", - " return yaml_path\n", - "\n", - "\n", - "# function to extract keys from a JSON file and save them as a list in another JSON file\n", - "@function_pod([\"key_info\"], data_store=data_store)\n", - "def extract_keys(json_file: str):\n", - " with open(json_file, \"r\") as f:\n", - " data = json.load(f)\n", - " keys = list(data.keys())\n", - " tmp_dir = tempfile.mkdtemp()\n", - " keys_file = Path(tmp_dir) / \"keys.json\"\n", - " with open(keys_file, \"w\") as f:\n", - " json.dump(keys, f)\n", - " return keys_file" - ] - }, - { - "cell_type": "markdown", - "id": "787b26ca", - "metadata": {}, - "source": [ - "With all steps defined, let's chain them together to form a full pipeline. Note that we are using the `>>` operator to map data keys on the fly to match expected arguments for each pod." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "3cdc6e7f", - "metadata": {}, - "outputs": [], - "source": [ - "line_info_json = count_lines(data_source >> {\"data_file\": \"file\"})\n", - "line_info_yaml = json_to_yaml(line_info_json >> {\"stats\": \"json_file\"})\n", - "line_info_keys = extract_keys(line_info_json >> {\"stats\": \"json_file\"})" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "71d18d81", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'day1'}, Data: {'key_info': 'pod_data/extract_keys/cf978f9c23318c91/c4c3939c-aced-18ac-8a7c-330f07780bbd/keys.json'}\n", - "Tag: {'file_name': 'day2'}, Data: {'key_info': 'pod_data/extract_keys/cf978f9c23318c91/61e78af0-346a-00f7-df3d-f2ec1693a84e/keys.json'}\n", - "Tag: {'file_name': 'day3'}, Data: {'key_info': 'pod_data/extract_keys/cf978f9c23318c91/92fbcba4-a642-4105-8be2-c01ce9c3e12e/keys.json'}\n", - "Tag: {'file_name': 'day4'}, Data: {'key_info': 'pod_data/extract_keys/cf978f9c23318c91/9e7da977-1ed3-03a2-ffd5-a3d626c286d8/keys.json'}\n" - ] - } - ], - "source": [ - "line_info_keys.head()" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "2950e1d5", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'day1'}, Data: {'yaml_file': 'pod_data/json_to_yaml/0a2282eda2b641e6/c4c3939c-aced-18ac-8a7c-330f07780bbd/data.yaml'}\n", - "Tag: {'file_name': 'day2'}, Data: {'yaml_file': 'pod_data/json_to_yaml/0a2282eda2b641e6/61e78af0-346a-00f7-df3d-f2ec1693a84e/data.yaml'}\n", - "Tag: {'file_name': 'day3'}, Data: {'yaml_file': 'pod_data/json_to_yaml/0a2282eda2b641e6/92fbcba4-a642-4105-8be2-c01ce9c3e12e/data.yaml'}\n", - "Tag: {'file_name': 'day4'}, Data: {'yaml_file': 'pod_data/json_to_yaml/0a2282eda2b641e6/9e7da977-1ed3-03a2-ffd5-a3d626c286d8/data.yaml'}\n" - ] - } - ], - "source": [ - "line_info_yaml.head()" - ] - }, - { - "cell_type": "markdown", - "id": "ff85672b", - "metadata": {}, - "source": [ - "We have now defined a nontrivial data pipeline that counts the number of lines in files and output that info to JSON. We then convert the JSON files into YAML files. On the other branch of the pipeline, we take the JSON files and extract a list of keys found in the JSON and save it as yet another JSON file." - ] - }, - { - "cell_type": "markdown", - "id": "1abdf7d6", - "metadata": {}, - "source": [ - "As your pipeline grows, it can get qutie tricky to keep track of exactly who connects to what and it can be easy to lose sight of exactly what's going on in the pipeline. This is exactly where `Tracker` comes in handy. As the name suggeests, a `Tracker` can keep track of all pipeline-defining computations you have run, and then generate helpful information such as graphs or plot the graph as an image for visualization." - ] - }, - { - "cell_type": "markdown", - "id": "27346fa5", - "metadata": {}, - "source": [ - "You may think that the sensible next step is to create and setup a `Tracker` to keep track of the pipeline. It turns out that `orcabridge` comes with a default tracker that has been tracking all of the pipeline-defining operation all this time, secretly without you knowing!\n", - "\n", - "Let's access and use the default tracker." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "2cdf8d30", - "metadata": {}, - "outputs": [], - "source": [ - "from orcabridge import DEFAULT_TRACKER" - ] - }, - { - "cell_type": "markdown", - "id": "19a999a7", - "metadata": {}, - "source": [ - "As we will see shortly, `DEFAULT_TRACKER` is just an ordinary instance of `Tracker` that has been instantiated and activated at the time of the first import of `orcabridge`. Consequently, it has been keeping track of all `operation` execution that you have performed thus far. Let's use its `draw_graph()` to display the computation graph it has detected." - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "7a91ffaa", - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "/home/eywalker/workspace/orcabridge/src/orcabridge/tracker.py:92: UserWarning: This figure includes Axes that are not compatible with tight_layout, so results might be incorrect.\n", - " plt.tight_layout()\n" - ] - }, - { - "data": { - "image/png": "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", - "text/plain": [ - "<Figure size 640x480 with 1 Axes>" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "DEFAULT_TRACKER.draw_graph()" - ] - }, - { - "cell_type": "markdown", - "id": "3b8fd7d0", - "metadata": {}, - "source": [ - "Does that match what you thought of the pipeline thus far? You might notice that while we used the convenience operator `>>` to map data keys, the corresponding `MapData` mapper actually shows up in the graph. Remember that `>>` is just for convenience, making the creation of `MapData` and `MapTags` more accesible." - ] - }, - { - "cell_type": "markdown", - "id": "3c02d58c", - "metadata": {}, - "source": [ - "## Explicitly tracking computation pipeline with a tracker" - ] - }, - { - "cell_type": "markdown", - "id": "db480859", - "metadata": {}, - "source": [ - "While the `DEFAULT_TRACKER` can serve as a nice catch-all tracker, sometimes you'd want to explicitly control what gets tracked so that you can visualize specific section of the entire computation graph. \n", - "\n", - "To do so, you would want to create your own tracker, and define the computation using the tracker's context manager. Let's see an example." - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "f678050e", - "metadata": {}, - "outputs": [], - "source": [ - "# instantiate a new tracker\n", - "tracker = Tracker()\n", - "\n", - "# start a context manager to track the pipeline\n", - "with tracker:\n", - " line_info_json = count_lines(data_source >> {\"data_file\": \"file\"})\n", - " line_info_keys = extract_keys(line_info_json >> {\"stats\": \"json_file\"})\n", - "\n", - "# perform the conversion outside of the tracker\n", - "line_info_yaml = json_to_yaml(line_info_json >> {\"stats\": \"json_file\"})" - ] - }, - { - "cell_type": "markdown", - "id": "f7d3484f", - "metadata": {}, - "source": [ - "In the example above, you would notice that only first half of the pipeline is chained together within the `tracker` context manager. Let's now see what the graph looks like." - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "id": "b3bf152b", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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RETUIAyURERERNQgDJRERERE1CAMlERERETUIAyURERERNQgDJRERERE1CAMlERERETUIAyURERERNQgDJRERERE1CAMlERERETUIAyURERERNQgDJRERERE1CAMlERERETUIAyURERERNQgDJRERERE1CAMlERERETUIAyURERERNQgDJRERERE1CAMlERERETUIAyURERERNQgWmcXQETUVPz+++8oKCiotOzMmTMAgPXr11da3qJFC3Tu3Pmy1UZE1JQpIiLOLoKIyNkyMzMRExNTr2327t2L6OjoS1QREZHrYJc3ERGAqKgoJCQkQFGUC66r0WiQkJCAqKioy1AZEVHTx0BJRARAURQ8//zzqEunjc1mw6xZs+oUPomImgN2eRMR/UlE0KlTJ6Snp8Nms1W7jkajQVxcHHbs2MFASUT0J7ZQEhH9ydFKWVOYBNg6SURUHbZQEhFVUFsrJVsniYiqxxZKIqIKamulZOskEVH12EJJRHSe6lop2TpJRFQztlASEZ2nulZKtk4SEdWMLZRERNVwtFLu2rULAJCQkMDWSSKiGrCFkoioGo5WSge2ThIR1YwtlERENRARBAQEAAByc3MZKImIasBASUR0HpsISixWlNsEx7KzIYqCkKAgaBQFWo0Cb50HNAyXREQqBkoiatZsIigoLUd+qQX55yzINVtQUGpBzbc2t48VaqHXIcCgg8lLB5NehxZ6LUMmETVbDJRE1CzlmstwIL8ERwvNsP35KagAqM8HYsX1NQoQajQg0t8b/l6ejVssEVETx0BJRM2G1SY4UmjG/rxinC0tr3eAvBDH/vz0WkT5+yDUaICHhq2WROT+GCiJyO1ZbYKMM0XYn1+Mctvl+8jTahRE+vsgNsCXwZKI3BoDJRG5tTPmMmzOyUexxeq0Gnx0HkgKNiHAwK5wInJPDJRE5JasNkH66UJk5hU3etd2fTmOH+3vg7iWRrZWEpHbYaAkIreTay7DJie3StaErZVE5I4YKInIrRwrNCMtOx+Ac1sla+Jom+wRYkJbo8GptRARNRYGSiJyG1n5Jdh64qyzy6izxCA/hPt5O7sMIqIG43d5E5FbcLUwCQBbj59F1tkSZ5dBRNRgDJRE5PKOFZpdLkw6bD1+FscKzc4ug4ioQRgoicil5ZrL1DGTriotOx+55jJnl0FEdNEYKInIZVltgk05+c4uo1FsysmH9TLedJ2IqDExUBKRy0o/XYhii7VJzuauDwFQbLEi/XShs0shIrooDJRE5JLOmMuQmVfs7DIaVWZeMbu+icglMVASkcux2gSbc/Lhbt83o4Bd30TkmhgoicjlZOQWuUVX9/kcXd8ZuUXOLoWIqF4YKInIpVhtgv1u1tV9vv15xWylJCKXwkBJRC7laKEZ5W4etsptgqO8NyURuRAGSiJyKfvcvHXSobmcJxG5BwZKInIZueYynC0td3YZl8XZ0nLO+CYil8FASUQu40B+idvN7K6JAvv5EhG5AgZKInIJNrGPK3Tv0ZN/EdjHi9qkuZwxEbkyBkoicgkFpeVw87k4VdgEKGwmXfxE5NoYKInIJeSXWpxdglPkNdPzJiLXwkBJRACAtWvXQlEUKIqCrKwsp9by448/QlEU9O3bV12Wf87SbMZPAsDJo0cwLDYE7U0+WLt2rbPLqdacOXMQFhYGDw8PKIqCtWvXIiUlBYqiYMyYMQCArKws9bqq73n07dsXiqLgxx9/bPziiahRMVASUaM7P1TU17Rp0wAATz75pLos12ypdfzkrtQNGBYbgmGxITh59Ei9j+kIcMNiQ7ArdUO9t29sOk9PRHdORMcu3dCiRQtnl1PF1q1b8fTTT+Pw4cMIDw9HcnIyWrRogbi4OCQnJyMyMrLBx5g0aRKAv64HImq6tM4ugIiooq1btyI1NRX+/v4YNGgQAPuEnLPNrOvXv3UbvPj5MmgAdIkJcnY5VaSnp1f6t16vBwC8+eabjXaMG264Af7+/khNTcW2bdvQtWvXRts3ETUutlASNWHh4eFQFAWTJ0/Go48+ioCAAPj5+eGRRx5BaWmput7kyZMRHx8Pk8kEnU6HkJAQjB49Gjk5OZX2t3nzZgwZMgSBgYHQ6/WIiIjAK6+8UuPxn3rqKSiKAm9vb6xatQoAkJqaikGDBsFkMsHLywuJiYlYvHixuo2iKFi3bh0AYNGiRZW60YuKivDwww+jXbt20Ov1aNWqFXr16oVFixap23/66acA7GFCp9MBAEosVuzZvgUzxozA6OR43NGpPR66tgdeHD8Wxw9n4fPX52D66NvUfTzcPxnDYkPw+uSJAIDvFr6Np27pj9HJcRiRcAXGXp2Alx+7F9kH9wMAVn/1OR7un6xuP330bRgWG4Jpdw8DAOyt5dj1ZbPZsOLj91FuqT0gO1pMh8aGYOWq1QCA48eP46677kJwcDD0ej2CgoJw7bXXYvny5ep2hw8fxj333IOgoCDodDqEhobikUceQW5urrrOmDFjoCgKUlJS8MYbbyA8PBxGoxE333wzjh8/fsFzGDNmDO6++271/15eXuprXNfW6QtdRwCg0+kwcOBAAH9dF0TUNDFQErmAuXPn4rPPPoPJZEJBQQHmz5+PKVOmqD//4YcfcOzYMbRr1w5RUVE4fvw4PvjgAwwZMkRdZ8OGDejVqxe+/fZbFBUVITo6GgUFBVi/fn21x5w2bRpeffVVeHt7Y9myZejfvz9+/fVX9O7dGytWrIDBYEB4eDi2bduG4cOH44MPPgAAJCcnw2g0AgBatmyJ5ORkJCcnQ6/XY9q0aXjrrbdw6tQpxMfHw2g0IjU1FWvWrFGP+8svvwAAkpKS1GVl5Vb886F7sHPjL9DqtAiNjELpOTM2/W8lTudkIzAoGKGR0er67TvGI7pzIoKuCAMA7N70G44fzoKpZSu0bR+FooKzSP1pBWaMHYGy0nPwCwhE+47x6vahkdGI7pyI0KgY2Gy2Wo9dk1PZR3Hy6JEqj81rfsR7s57Fq08+dMFQ6WD989ZBjzzyCD755BMUFRUhISEBnp6eWLt2LdLS0gAAJ0+exNVXX40PP/wQ+fn5iImJwYkTJzB//nz07dsX586dq7TfDRs2YNKkSfD09ERRURG+//57PPXUUxesJzIyEhEREer/K77GdVGX68ihR48eAFDjdUpETYQQUZMVFhYmACQ6OloKCgpERGTkyJECQDw9PSU/P19ERHbs2CFWq1Xd7p133hHYb2Uo+/btExGRfv36CQAxmUyyZ88eERGxWq2yfft2ERFZs2aNus348eMFgHh7e8vq1avV/aakpAgAGTBggFgsFhERmThxogCQ0NBQdb2+ffsKABk9enSl87n55psFgMyaNUtddubMGbUGEZHAwEABIF999ZW6LPNItlrb2+u2yJKMbFmSkS2vfbdGFvy6Q5ZkZMtzixar68xflaqusyQjW+YuWyuf7zyk/n/ags/Udae//7ksyciW+atS1WXPLVqsrrvwt10XPHZ1D6PJX3Se+hofiqJI8oAbK9VV8VGxnm9++FFERBISEgSAfPTRR+pzk52dLX/88YeIiEybNk0AiEajkS1btoiIyNKlS9X9LFiwQERERo8era7neO6HDh0qAKRNmzZ1uTTl/fffV/db0fmv/cGDB9X11qxZU6/rSERkyZIlAkBatmxZp7qIyDk4hpLIBdx8881qq98dd9yBTz/9FGVlZdi7dy+SkpKwfft2jBkzBnv27EFxceXvgM7OzkZkZCRSU1MBALfddhtiYmIAABqNBp07d65yvDfeeAOAvZuxX79+6nJHS9hPP/2kdkc7HD16FMeOHUPbtm1rPI/Bgwdj2bJlmDp1Kt5++23ExsaiZ8+eePDBB9V1zp49CwDq+QKAKSAAHbp0w57tW/Do9b0QdEU42kV3QLeU/uh989ALPHv21sK3pj2NQ3v+wLmSYkiFm4XnnjxR67ZG/4s79sKNu2vd7wezn8c3783HoT1/IDKhU63rOuodPHgwdu3ahdGjR2P69OmIjY1F37591edv06ZNAIAOHTogMTERAHDLLbfA29sbJSUl2Lx5M8aOHavu98orr1Rf/7i4OCxduhQnTtT+fDSG+lxHjglJjuuCiJomBkoiF/fLL79g9OjREBEEBgYiLi4ORUVF+OOPPwAAVqu13vv09fVFUVER5syZgwEDBsBgMFT6edu2bREaGlplu/Ly2m/C/cADDyA2Nhbffvstdu7ciS1btuDHH3/El19+iV27dgGwB4jc3FwUFRWp22kUBdMXfoH1y5Ziz9ZNOLI/Ext//B6/Lv8GeadO4JZ7H6nxmMePHMJL48eh3FIGg48vIuI7wWYtx8E/7IHPVofn52KOfVdiFM6V1P7ViT1vHIzwCl3tNVEU+w2TXnjhBfTq1QsrV67Erl278PPPP+P777/H2rVr8f33319wP+czmUzqv7Xay//roC7XUUFBAQA0yZnuRPQXjqEkcgHff/+9GrC++OILAICnpydiYmKQmpqqtmDt3LkTaWlpuOeee6rsIznZPulkyZIl2LdvHwB7y9eOHTuqrPvBBx/AaDRi/fr1GDFihPoL3jGuMSwsDGvWrMHGjRuxceNGLF68GFOmTEFYmH3More3NwBUaS1NS0tDfHw85syZg5UrV2LZsmUAgN27d+PMmTMAgOho+1jIQ4cOqdspAPZs24x+Q2/H+H++hhc/X4brho0EAKRv2ggA0FcIvefMfwW5g+m7UG4pAwBMffcTvLx4BW65b3yVc664fWmF7UXkgseuzps/bcS767dXeTz7zsdQFAVX3zAYE2e/AQ8Pjxr34aD5M1D++uuv6Nu3L+bNm4fVq1fj7bffBgD8/PPPAP56ffbs2YOtW7cCAL7++muU/Blsu3fvfsFjXQ51vY6Av64Dx3VBRE0TWyiJXMCxY8fQvn17tGjRAgcOHAAAPPzww/Dz80OnTn91l1555ZVo1aoVTp48WWUfs2bNQr9+/ZCXl4f4+HjExMTg+PHj6NWrF77++utK63bt2hVfffUVBg0ahGXLlmHcuHFYtGgRZs6cieuuuw4bNmxAcHAw2rdvj1OnTiE7Oxt9+vRRJwHFxsZixYoV+Oqrr5CYmIjWrVvjhx9+wLx58/D5558jNDQUAQEBarBt27YtAgICAAC9e/dGamoqNm/erNajiA3Pjb0dBh9fBAaHQKNocHT/XgBAWIc4AEBQuzBodTqUWyx4btztaBUSiiFjH0K7mA7QeHjAZrVi1v13oWVwW+Sfrvr8tAgIhNHkj8L8PMz7++MIDmuPPoNvxcCRoy947Or4BbasdrmpZSs8MOMlXDfsDnjUsVXQ489AOXnyZGzatAnt2rWDn5+f2grtuAbGjx+Pd955Bzk5OejZsyeioqKwZ88eAEBCQgJGjhxZp+NdanW9joC/usd79+7trHKJqA7YQknkAiZMmIBRo0YhLy8PRqMRDz74IF588UUAwIABA/DSSy8hJCQEZrMZsbGxmD9/fpV99OzZE7/++isGDx4MX19f7NmzB76+vrjmmmuqPWb//v2xYMECKIqCDz/8EBMnTkSfPn3w888/48Ybb4SiKEhPT4dOp8OwYcPUm1AD9htS9+/fH97e3ti2bZsaDm+66Sb07t0bZrMZO3fuhJeXFwYPHozly5er3bqO0PPDDz+oLaNGL08MvOMetA69ArknjuP44Sy0atsO/zfuIYwY/4R9Hf8AjHvmebQMDsHZ06eQ+ftW5J0+idCIaIx/4VW0Dr0C5RYLjP4BmPhK1XslKoqCh5+fg6Cw9igpKkTmjm04lX0UGg8PXH+BY9eHoii4/vZRdQ6TAGDwtK97++23o3v37igoKMDOnTthMpnUMbUA0Lp1a2zcuBF33303TCYT9uzZgzZt2uChhx7CunXr4OXlVe96L4W6XkcWiwUrV64EgCYThomoeopUHJ1ORE1KeHg4Dh06hOnTp2PGjBnOLueyueqqq5Camopvv/0WgwcPBgCszjrdrL7Pe+/vWzHl9psB2LuwHROpmpNvv/0WQ4YMwVVXXYXffvvN2eUQUS3Y5U1ETc7MmTMxcOBAzJkzRw2UAQYdzpbW/vWL7mLx/LlY/dXnAIDQsPBK93y8XIYOHVrlxvgOS5cuRXBw8CWvYc6cOQDs1wMRNW0MlETU5Fx//fU4v/PE5KVrFmESAHZsWI8zx3MQ3akrXp33ulNmYG/btq3SxKiKKn5L06XkmGxERE0fu7yJyCXkn7Ng9aHTzi7jsrsurCX8vHQXXpGIyIk4KYeIXEILvRYaxdlVXF4aBTDq2ZFERE0fAyURuQSNoiDUaEBzyZQKgFCjQb0HJRFRU8ZASUQuI8Lk3WzGUQqASH9vZ5dBRFQnDJRE5DICDJ7wayZdwH56Lfy9PJ1dBhFRnTBQEpFLifL3cXYJl0VzOU8icg8MlETkUkKNBmjdfHaOVmMfL0pE5CoYKInIpXhoFES6eetdpL8PPNw8NBORe2GgJCKXExvgCx+dh9vN+FYA+Og8EBvg6+xSiIjqhYGSiFyOh0ZB92CT2834FgBJwSa2ThKRy2GgJCKXFGjwRLSbdX1H+/sgwMCZ3UTkehgoichlxbU0ukXXt6OrO66l0dmlEBFdFAZKInJZHhoFScEmZ5fRKNjVTUSujIGSiFxagMETPUJMzi6jQXqEmNjVTUQujYGSiFxeW6MBiUF+zi7joiQG+aEt7zlJRC6OgZKI3EK4n7fLhcrEID+E+/H7uonI9Ski4m533iCiZuxYoRlp2fkA0CRvK+QYJdkjxMSWSSJyGwyUROR2cs1l2JSTj2KL1dmlVOGj80BSMMdMEpF7YaAkIrdktQnSTxciM68YCpzbWuk4frS/D+JaGjmbm4jcDgMlEbm1M+YybHZyayVbJYnI3TFQEpHbs9oEGblF2J9XjHLb5fvI02oURPr7IDbAl62SROTWGCiJqNmw2gRHC83Yl1eMs6Xljd4V7tifSa9FpL8PQo0GBkkiahYYKImoWco1l+FAfgmOFprhaLSsb8CsuL5GAUKNBkT6e8Pfi13bRNS8MFASUbNmE0FhaTnySi3IP2dBrtmCglILbLVsowHQQq9DgEEHk5cO/nodjHotNApbI4moeWKgJCI6j00EJRYrym2CJ596Ch5aHV568V/QKAq0GgXeOg+GRyKiCrTOLoCIqKnRKAp8Pe0fj6ePZAEAZ2gTEdWCX71IRERERA3CQElEREREDcJASUREREQNwkBJRERERA3CQElEREREDcJASUREREQNwkBJRERERA3CQElEREREDcJASUREREQNwkBJRERERA3CQElEREREDcJASUREREQNwkBJRERERA3CQElEREREDcJASUREREQNwkBJRERERA3CQElEREREDcJASUREREQNwkBJRERERA3CQElEREREDaJ1dgFERE1FSUkJysrKKi2zWCwAgPz8/ErLPT094e3tfblKIyJq0hQREWcXQUTkbFlZWYiJiVED5IXodDrs3bsX4eHhl7YwIiIXwC5vIiIAISEhaNWqVZ3Xb926NUJCQi5hRUREroOBkogI9i7s6dOn13n96dOnw9PT8xJWRETkOtjlTUT0p7KyMrRv3x45OTmo6aNRURSEhITgwIEDDJRERH9iCyUR0Z8crZS1/Z0tImydJCI6D1soiYgqqK2Vkq2TRETVYwslEVEFtbVSsnWSiKh6bKEkIjpPda2UbJ0kIqoZWyiJiM5TXSslWyeJiGrGFkoiomo4Wimzs7MBAG3btmXrJBFRDdhCSURUjfPvS8nWSSKimrGFkoioBmVlZfDz8wMAnD17loGSiKgGWmcXQETU1NhEUGKxotymYPH3P0AUBUVWQHPOAq1GgbfOAxpFcXaZRERNBlsoiahZs4mgoLQc+aUW5J+zINdsQUGpBbZattEAaKHXIcCgg8lLB5NehxZ6LUMmETVbDJRE1CzlmstwIL8ERwvNsP35KagAqM8HYsX1NQoQajQg0t8b/l7sGiei5oWBkoiaDatNcKTQjP15xThbWl7vAHkhjv356bWI8vdBqNEADw1bLYnI/TFQEpHbs9oEGWeKsD+/GOW2y/eRp9UoiPT3QWyAL4MlEbk1BkoicmtnzGXYnJOPYovVaTX46DyQFGxCgIFd4UTknhgoicgtWW2C9NOFyMwrbvSu7fpyHD/a3wdxLY1srSQit8NASURuJ9dchk1ObpWsCVsricgdMVASkVs5VmhGWnY+AOe2StbE0TbZI8SEtkaDU2shImosDJRE5Day8kuw9cRZZ5dRZ4lBfgj383Z2GUREDcbv8iYit+BqYRIAth4/i6yzJc4ug4iowRgoicjlHSs0u1yYdNh6/CyOFZqdXQYRUYMwUBKRS8s1l6ljJl1VWnY+cs1lzi6DiOiiMVASkcuy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", - "text/plain": [ - "<Figure size 640x480 with 1 Axes>" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "tracker.draw_graph()" - ] - }, - { - "cell_type": "markdown", - "id": "73992089", - "metadata": {}, - "source": [ - "As you can see, the tracker only tracked one branch of the computation graph, leaving the other branch outside of the computation graph it has constructed and visualized." - ] - }, - { - "cell_type": "markdown", - "id": "8a02717c", - "metadata": {}, - "source": [ - "## Labeling operations" - ] - }, - { - "cell_type": "markdown", - "id": "74984946", - "metadata": {}, - "source": [ - "All operations accept `label` keyword argument when creating and also has property `.label` where you can change it at any time you like. If `label` attribute of an operation is not `None`, the value will be used instead to label the operation node in the graph. In fact, you can change the label after the pipeline construction, and the change will still be reflected the next time you draw the graph!" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "id": "b5ea2dde", - "metadata": {}, - "outputs": [], - "source": [ - "data_source.label = \"LocalDataStore\"\n", - "\n", - "count_lines.label = \"CountLines\"" - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "id": "cfc2e1c3", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "iVBORw0KGgoAAAANSUhEUgAAApQAAAHzCAYAAACe1o1DAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjEsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvc2/+5QAAAAlwSFlzAAAPYQAAD2EBqD+naQAAZs5JREFUeJzt3Xlc1HX+B/DXd5hhGGBgAA9AlBsR8UKR1FRKzbJcLcuyy6O2NNvNLXd/WeuRWWtlx+aWbe2adltq5lpmmfcFnnkgCioqgicM5wDDzOf3xzhfQQ7BQYfv8Ho+HvN44Mz3eH9nhvHF+/P9fEcSQggQEREREV0nlbMLICIiIiJlY6AkIiIiIocwUBIRERGRQxgoiYiIiMghDJRERERE5BAGSiIiIiJyCAMlERERETmEgZKIiIiIHMJASUREREQOYaAkIiIiIocwUBIRERGRQxgoiYiIiMghDJRERERE5BAGSiIiIiJyCAMlERERETmEgZKIiIiIHMJASUREREQOYaAkIiIiIoeonV0AEVFzYxUCpWYLKq0CVmG7qSQJKkmCWiXBU+MGlSQ5u0wiomaDgZKIWjSrECgsr4Sx3AxjmRl5JjMKy82w1rOOCoCPVgN/nQYGDw0MWg18tGqGTCJqsSQhhHB2EUREN1ueqQLHjaXILjLBevlTUALQmA/EqsurJCBEr0Oknyf8PNybtlgiomaOgZKIWgyLVeB0kQnH8ktQUF7Z6AB5Lfbt+WrViPLzQoheBzcVu5ZE5PoYKInI5VmsAumXinHMWIJK6837yFOrJET6eSHW35vBkohcGgMlEbm0S6YK7Mo1osRscVoNXho3JAYZ4K/jUDgRuSYGSiJySRarQNrFImTklzT50HZj2fcf7eeFuFZ6diuJyOUwUBKRy8kzVWCnk7uSdWG3kohcEQMlEbmUM0UmpOYYATi3K1kXe2+yd7AB7fQ6p9ZCRNRUGCiJyGVkGUux51yBs8tosIRAX4T5ejq7DCIih/GrF4nIJSgtTALAnrMFyCoodXYZREQOY6AkIsU7U2RSXJi023O2AGeKTM4ug4jIIQyURKRoeaYK+ZxJpUrNMSLPVOHsMoiIrhsDJREplsUqsDPX6OwymsTOXCMsN/Gi60RETYmBkogUK+1iEUrMlmY5m7sxBIASswVpF4ucXQoR0XVhoCQiRbpkqkBGfomzy2hSGfklHPomIkVioCQixbFYBXblGuFq3zcjgUPfRKRMDJREpDjpecUuMdR9NfvQd3pesbNLISJqFAZKIlIUi1XgmIsNdV/tWH4Ju5REpCgMlESkKNlFJlS6eNiqtApk89qURKQgDJREpCiZLt6dtGspx0lEroGBkogUI89UgYLySmeXcVMUlFdyxjcRKQYDJREpxnFjqcvN7K6LBNvxEhEpAQMlESmCVdjOK3TtsyevELCdL2oVLeWIiUjJGCiJSBEKyyvh4nNxarAKoKiFDPETkbIxUBKRIhjLzc4uwSnyW+hxE5GyMFASkSIYy8x1nj85/8UpGBUbjBmPjbqpNd1oEmzHTUTU3KmdXQARKVNycjI2btyI0NBQZGVl3fD95ZnMjTp/cuLtvXEhJxsAoHJzg4enF1oFBiMu8Rbc/fiTCA6LaHQNMx4bhUM7tyN55Gj8ae57jV7fXFGBlQs/wqb/LcOFnGyoVG7wDWiFDjGxePDZFxAW2xmALSBvWPEtOif2wfvfrmz0foiIbjZ2KImo2bMKgYLrHPrVeXkjIq4LNO7uOJWRjp+/WoSp9w7B7g1rm7jKa/vsrVfx1XtzkX0sA/5tgtC6XXsUXLqI1LU/IzfrRK3rFJabm2RiTkUFL0FERDcOAyUR3RAmkwkvv/wyoqKi4O7uDn9/f4wcORIHDhyotlxGRgYefvhhBAYGwt3dHSEhIZg6dar8+NixYxETHYOHE6LxYJdQPH17Iv475+8oLS5qUB0RcV3wxnc/YeHW/Zj+n6/g5eOLcpMJ702djKL8PADAicMHMWvcaDzRvzse7BKGh3tE4m/334WNK5fJ2xkVG4xDO7cDADas+BajYoMxKjYY57NP49LZHMx56lE8ldwTY7pFYEy3CEwZfhtWLf4EokoY3Lba1m184Jm/4F9rtuDdlb/h811H8NpXKxAaGwfA1lndsOJbAMChndtxb2ww3FQqbNiwAQBw6tQpPP744wgMDIRGo0FISAieeeYZ5OXlyfsZN24cJElCcnIy3nzzTYSEhMDDw0N+/IsvvkBiYiI8PT2h1+tx5513Yt++fQ16PomIasNASUQ3xB/+8Ae8/vrrOH78OCIjI2E2m/HDDz+gb9++SE9PBwBkZmaid+/e+Prrr3Hx4kVERUXBYrFg7dor3cMffvgB+cZ8BHYIRUBgMC7mnMFPXyzEhy+/0Oiaut+ajNHP2tYrLS7Clp9+AACcP3Mah1K3QaNxR/voGGjctTh28He8/7c/yZ3M6G4J0Hl5AwB8/PwR3S0B0d0SoHF3R2F+HvZuWgcAaBcZBZ23N05nHMGn/5iJn79aJO/farUCAH7fugm71v8K48ULkCQJsQm95SH48Lh4+Pj5A7B1V6O7JaBXYm/4+Pjg/Pnz6NOnDz7//HMYjUbExMTg3LlzWLBgAQYOHIiysrJqx7t9+3ZMmzYNPj4+8Pe3bfPNN9/EY489hl27dqF9+/bw8fHBmjVrcOutt+Lw4cONfk6JiAAGSiK6AdavXy+HwnfeeQeHDx/G4cOH4e3tjeLiYvzjH/8AALz++uswGo3QaDTYtGkT0tLSkJubi08//VTe1saNG5FxOgdvr1iLD3/djlETnwMApP72MyrKy2ru/BrievaWf84+dhQAENOtJz7ZtBcfrUvFvOW/4JNNexAYGg4Acuicu2QVIuK6AAASBg7G3CWrMHfJKvi1aYs2IR2wYG0KPt6wG/OW/4L/bN6HuF63AAC2Xl4fAO4cMxYAcPT33fjHpLF44tZu+NNd/fHdh+/Kx/J//1qIhIGDAdi6q3OXrMKajZuRkJCADz74ADk5OVCpVNi2bRsOHTqE7777DgBw8OBBfP3119WOtaKiAqtWrUJaWhrOnTuH0tJSvPLKKwCAV155BUeOHMHJkyfRq1cvlJSU4PXXX2/080lEBHBSDhHdADt37pR/fvjhhwEAISEh6N+/P1avXo1du3YBAFJSUgAAAwcORN++feV1evToIf+8du1a/GfMwzh+/Hi1AGmprERh3iW0CmrXqNqstVzMUpIkLH7jFRzYsRUFeRdhtVjkx/LPn7vmNt3c1Fjx3w+xe+Na5J8/B0vllWtH5lVZ/8E/TUVYbGesW/4N0nbuQGlxEXJOHMM377+Fs6dO1jnRx34Opf157dixIxISEgAAI0eOhKenJ0pLS7Fr1y6MHz9eXq9jx4646667LtfohkOHDqG01PbtOzNnzsTMmTOr7WfHjh3XPFYiotowUBJRs/Xll1/K51P6tW6L0KBOKMzPw7nTJwEAVou10ds8vDtF/jkkMgYA8M+/PYv92zZDkiSERMXAw9ML2ZlHYSoprhYu6/LpP2Zg7XdfAQCCQiPgbTDg3KksFObn1Vg/achdSBpyF6xWK44f2o8PXn4Bp44eRupvP9e5fZV0fV842bZt2zof69SpE3x8fKrdFxAQcF37ISLikDcROUQIgbKysmq3nj17yo9/9ZUtaGVnZ2Pz5s0AgF69egEAkpKSANiGte3dSgD4/fffAVzpmOn1eiz4bQfmfvsjuvUbeN21/r51I7778F0AgKe3Hv2G/QEAcHTfHgDA4AcewXv/W4+X//05PDy9aqzvrtMBAMpN1b9j275+t34D8a81WzD7s6XwbxtYY/2v3nsDJw4fBACoVCpEdekunzvpqdfLy2kv76fs8n7sgTIxMREAcOTIEezZY9vnihUr5K6j/Xm1k64Kop07d4bu8rbvvPNObN++HTt27MCOHTuwYMECvPzyyzWfNCKihhBERNdh4MCBAravnK5xe/fdd8XgwYMFACFJkujUqZPQ6/UCgPD29haHDx8WQgiRkZEhDAaDACDc3NxEXFycCA4OFt26dRNCCPHxxx/L2/RvEyjahHQQ3r5+8n0L1qaIZek5InnkaAFAdE7sI5al54hl6TmidXCIACB0Xt4iqkt3YWjVWl5Pq9OJlz76TF62Y49eAoBQqVQiJCpGePn4Cm9fQ41t3jP2KXm58Lh40f3WZLEsPUf0v+deedvBYRHCx89frrN1cIi8vr0GHz9/ERHXRQQEBsnr3fvHZ+XlJrw0W76/Q3Ss6NW7tygtLRXnzp0TQUG2dbRarejcubNQq9UCgIiPjxcmk0kIIcTYsWMFADFw4MAar9vrr79+pdbLz7W/v78AIGbOnHmT3j1E5GrYoSSiG2LlypV46aWXEB4ejoyMDKjVaowYMQLbtm1DbGwsACAqKgqpqakYM2YMAgICkJGRAQAYNGgQAOCJJ57A888/j1atWsFUUoz43n3w0J+n1rnP2phKinH80H5UlJUhJCoGdz48Fm+vWIueyYPlZZ79x3uIT+oHjVaLCpMJ46e9gtCYTjW2NWLCRHTt2x/uHjqcSDuIYwdtndRxL85C4qCh8PD0gqmkBCOemIRetw2psf6Y5/5mW87LG2dOZKLg0iUEh0di9OTnMea5v8nL3T5qDG6542546n1wKiMdu1JTYbFY0KZNG+zYsQOPPfYYDAYDjhw5grZt22LixInYuHFjtUsD1WXatGlYvHgxEhMTkZ+fj8zMTLRp0wYTJ07Efffd16jnlojIThKiCa6YS0R0g63Lutgiv8/boNXg9rBWzi6DiKhe7FASkSL46zR1fpe3q5JgO24iouaOgZKIFMHgoWnUd3m7AgHbcRMRNXcMlESkCAZtywxWfi30uIlIWRgoiUgRfLRqqFrYmLdKAvRaXi6YiJo/BkoiUgSVJCFEr2sx51FKAEL0uuu+qDkR0c3EQElEihFh8Gwx51EKAJF+ns4ug4ioQRgoiUgx/HXu8G0hQ8C+WjX8PNydXQYRUYMwUBKRokT51fxKRFfUUo6TiFwDAyURKUqIXge1i8/OUats54sSESkFAyURKYqbSkKki3fvIv284ObioZmIXAsDJREpTqy/N7w0bi4341sC4KVxQ6y/t7NLISJqFAZKIlIcN5WEXkEGl5vxLQAkBhnYnSQixWGgJCJFCtC5I9rFhr6j/bzgr+PMbiJSHgZKIlKsuFZ6lxj6tg91x7XSO7sUIqLrwkBJRIrlppKQGGRwdhlNgkPdRKRkDJREpGj+Onf0DjY4uwyH9A42cKibiBSNgZKIFK+dXoeEQF9nl3FdEgJ90Y7XnCQihWOgJCKXEObrqbhQmRDoizBffl83ESmfJIRwtStvEFELdqbIhNQcIwA0y8sK2c+S7B1sYGeSiFwGAyURuZw8UwV25hpRYrY4u5QavDRuSAziOZNE5FoYKInIJVmsAmkXi5CRXwIJzu1W2vcf7eeFuFZ6zuYmIpfDQElELu2SqQK7nNytZFeSiFwdAyURuTyLVSA9rxjH8ktQab15H3lqlYRIPy/E+nuzK0lELo2BkohaDItVILvIhMz8EhSUVzb5ULh9ewatGpF+XgjR6xgkiahFYKAkohYpz1SB48ZSZBeZYG9aNjZgVl1eJQEheh0i/Tzh58GhbSJqWRgoiahFswqBovJK5JebYSwzI89kRmG5GdZ61lEB8NFq4K/TwOChgZ9WA71WDZXEbiQRtUwMlEREV7EKgVKzBZVWgedfeAFuag3emPsPqCQJapUET40bwyMRURVqZxdARNTcqCQJ3u62j8eLp7MAgDO0iYjqwa9eJCIiIiKHMFASERERkUMYKImIiIjIIQyUREREROQQBkoiIiIicggDJRERERE5hIGSiIiIiBzCQElEREREDmGgJCIiIiKHMFASERERkUMYKImIiIjIIQyUREREROQQBkoiIiIicggDJRERERE5hIGSiIiIiBzCQElEREREDmGgJCIiIiKHMFASERERkUMYKImIiIjIIQyUREREROQQSQghnF0EEZGzFRcXY86cOSgsLKx2/08//QQAGDZsWLX7fXx88Pe//x3e3t43rUYiouaKgZKICEBOTg7at28PIQTUarV8f2VlJQDUuE+SJJw+fRrBwcE3vVYiouaGQ95ERACCg4Px0EMPwc3NDWazWb4JISCEqHafm5sbxowZwzBJRHQZO5RERJcdOXIEnTp1wrU+FiVJQnp6OmJiYm5SZUREzRs7lEREl3Xs2BFjxoypNrx9NbVajYcffphhkoioCnYoiYiquFaXkt1JIqKa2KEkIqqivi4lu5NERLVjh5KI6Cp1dSnZnSQiqh07lEREV6mtS8nuJBFR3dihJCKqxdVdSnYniYjqxg4lEVEt7F1KSZIgSRK7k0RE9WCHkoioDkeOHEFsbKz8MwMlEVHtGCiJiOqRnJwMANiwYYNT6yAias4YKImIrmIVAqVmCyqtAlZhu6kkCSpJglolwVPjBpUkObtMIqJmo+6vgyAiagGsQqCwvBLGcjOMZWbkmcwoLDfDWs86KgA+Wg38dRoYPDQwaDXw0aoZMomoxWKHkohapDxTBY4bS5FdZIL18qegBKAxH4hVl1dJQIheh0g/T/h5uDdtsUREzRwDJRG1GBarwOkiE47ll6CgvLLRAfJa7Nvz1aoR5eeFEL0Obip2LYnI9TFQEpHLs1gF0i8V45ixBJXWm/eRp1ZJiPTzQqy/N4MlEbk0BkoicmmXTBXYlWtEidnitBq8NG5IDDLAX8ehcCJyTQyUROSSLFaBtItFyMgvafKh7cay7z/azwtxrfTsVhKRy2GgJCKXk2eqwE4ndyXrwm4lEbkiBkoicilnikxIzTECcG5Xsi723mTvYAPa6XVOrYWIqKkwUBKRy8gylmLPuQJnl9FgCYG+CPP1dHYZREQOUzm7ACKipqC0MAkAe84WIKug1NllEBE5jIGSiBTvTJFJcWHSbs/ZApwpMjm7DCIihzBQEpGi5Zkq5HMmlSo1x4g8U4WzyyAium4MlESkWBarwM5co7PLaBI7c42w3MSLrhMRNSUGSiJSrLSLRSgxW5rlbO7GEABKzBakXSxydilERNeFgZKIFOmSqQIZ+SXOLqNJZeSXcOibiBSJgZKIFMdiFdiVa4Srfd+MBA59E5EyMVASkeKk5xW7xFD31exD3+l5xc4uhYioURgoiUhRLFaBYy421H21Y/kl7FISkaIwUBKRomQXmVDp4mGr0iqQzWtTEpGCMFASkaJkunh30q6lHCcRuQYGSiJSjDxTBQrKK51dxk1RUF7JGd9EpBgMlESkGMeNpS43s7suEmzHS0SkBAyURKQIVmE7r9C1z568QsB2vqhVtJQjJiIlY6AkIkUoLK+Ei8/FqcEqgKIWMsRPRMrGQElEimAsNzu7BKfIb6HHTUTKwkBJRPXasGEDJEmCJEnIyspyWh3GMjN+37IBo2KDMf3R++pddv6LUzAqNhgTb+99k6prmNyTJzBr/Gg82jMGo2KDMeOxUTiYsg2jYoMxKjYY57NPA7hS/4zHRsFY5vxAeeHCBdx3333w9/eHJEkICwtDVlaW/L7YsGEDAGDWrFny442RmZkJNzc3hIeHo6KCE5GIlIiBkohumuTkZEiShHHjxjV63TyTGV/PnwcAGD7+qSauzOZ89mk53B1M2dbk21/8xis4sH0LLJWViOrSHSFRMfD09kZ0twREd0uAxt29xjp5JucHyjlz5uD7779HYWEhevbsiR49ekCr1SIpKQlJSUnw8fFxaPtRUVEYOXIksrKysHDhwiaqmohuJrWzCyAiuharENizZzcyft8Db18DEgYMcnZJ1+V05lEAwN2PP4lHX3hJvn/uklV1rlNYboZVCKgk581vP3ToEADggQcewNdffy3fv2PHjibbx8MPP4zly5djwYIFmDhxYpNtl4huDnYoiRQoLCwMkiThxRdfxLPPPgt/f3/4+vrimWeeQXl5ubzciy++iM6dO8NgMECj0SA4OBhjx45Fbm5ute3t2rULI0aMQEBAALRaLSIiIvD222/Xuf8XXngBkiTB09MTa9euBQCkpKRg2LBhMBgM8PDwQEJCApYuXSqvI0kSNm7cCABYvHhxtWH04uJiTJo0Ce3bt4dWq0Xr1q3Rr18/LF68GABQarZg848rAADdb02GWqORt2uuKMdHM/6GR3vGYHzfLvj2X28DtcyM/t+ij/HCyMEYmxSH0fEdML5PPN780xPIOXEMALBu+RJMGpwkLz9z7P3ysDMAbPrfcvzfA8Mw7pbOGB3fAY/37oTZT4xBxv6913y97J3Ps6eyAADff/IvjIoNxvwXp9Q65F2V9fLxl5eXY+bMmYiOjoa7uzvatGmDCRMm4OLFi9fcf22sVis++OADmM31d0AlScJvv/0GAPjmm28gSRKSk5NrHfKuaz///Oc/ER8fDw8PD/j5+eGBBx7AiRMnqi131113wc3NDfv370daWtp1HRMROQ8DJZGCvffee/jmm29gMBhQWFiIBQsWYNq0afLjP//8M86cOYP27dsjKioKZ8+exWeffYYRI0bIy2zbtg39+vXDypUrUVxcjOjoaBQWFmLz5s217nPGjBl455134OnpiVWrVmHw4MHYunUr+vfvj9WrV0On0yEsLAx79+7FAw88gM8++wwAkJSUBL1eDwBo1aqVPFyq1WoxY8YMfPTRR7hw4QI6d+4MvV6PlJQUrF+/HoDtqwjTd+8EAER16V6tni/fmYtfv/0CppJi6Ly8seqz/2DHrz/WqPvQzu04eyoLhlat0S48CsWFBUj5dTVmjR+NivIy+PoHILxTZ3n5kMhoRHdLQEhUDAAg88A+nDqaDr3BD+2jYlBRVobft27EK+MfRP6F8/W+Thp3d0R3S4BaYxvS9m8bhOhuCQjsEFrvenaVVoH77rsPs2fPxokTJ9CpUyeUl5fj008/xcCBA2Ey1f01jadOnUJWVlaN2//+9z/86U9/woMPPlhvqKztdYuLi2tQ3QDw7LPPYsqUKTh06BCioqLg5uaGpUuXom/fvjh//srz5unpic6dbc9/Xe89ImrGBBEpTmhoqAAgoqOjRWFhoRBCiDFjxggAwt3dXRiNRiGEEPv37xcWi0Ve75NPPhGwXeJQZGZmCiGEuO222wQAYTAYxJEjR4QQQlgsFrFv3z4hhBDr16+X15k8ebIAIDw9PcW6devk7SYnJwsAYsiQIcJsNgshhJgyZYoAIEJCQuTlBg4cKACIsWPHVjuee+65RwAQc+bMke+7dOmSXMOl0nKhN/gJAOJv8/8rlqXniGXpOeLLPZlC464VAES/YSPEsvQcsXDbAeHta1u2dXCIvOx7qzaIJQdOyv+esfAb+bhmfrpELEvPEQvWpsj3vbJ4qbzssvQcMf/nLeKrvZnyv/+1Zqu87KQ586otW9etdXCIACBGT35evu+VxUvl7SxYmyKWpeeI5JGjBQDRObGPWJaeI1au+VVeZuPGjUIIIXJycoROpxMAxH/+85863ysBAQFCq9XWeZMkSdx7772ioqKizm3U9rqdOHFCrmn9+vVCCCFmzpwpAIjQ0FAhhBDHjx8XkiQJAGLx4sVCCCGKiopESIjtefj73/9ebT/Dhw8XAMTUqVPrrIWImid2KIkU7J577pG7Rw899BAAoKKiAkeP2s7V27dvHxITE+Ht7Q1JkvDHP/5RXjcnJweAbagaAO6//37ExNi6cSqVCt26dauxvw8++AAA8PXXX+O2226T709NTQUA/Prrr9BoNJAkCe+99x4AIDs7G2fOnKn3OIYPHw4AmD59OkJDQzF06FDMnz8fbdu2BWA7h7K0uAgA4OHlJa939nQWzBW2If5b7hgGAPD1D0Dn3n1q7ONCTjZmjr0fj/aMwf2d2mH2hIfkx/LOn6u3PgAoKSzA3MnjMTYpDvd3aodnh/aTH8tvwPqO2L1zp/zzwIEDIUkSgoOD5c5kfecyXrx4EWVlZXXepk6diu+//x779+9v8rp37doFcfn0g7Fjx0KSJOj1emRnZ9dat31yT0FBQZPXQkQ3FiflELmoLVu2YOzYsRBCICAgAHFxcSguLsbhw4cBABaLpdHb9Pb2RnFxMebNm4chQ4ZAp9NVe7xdu3YICQmpsV5lZf0X537qqacQGxuLlStX4sCBA9i9ezd++eUXfPfddzh48CBUkgSdlx7FBfkoKy1pdN1nT5/EG5MnoNJcAZ2XNyI6d4XVUokTh22TTazXeC5MJSV49cmHUVJYAHetB8I7xcNNo0HG73satL6jqs7HSUpKqvF4YGBgnet6e3ujpKT+52z06NHo3r379ZbXIN27d4dWq612X2ho9SH/wsJCAHB41jgR3XzsUBIp2I8//oji4mIAwLfffgsAcHd3R0xMDFJSUuTu0IEDB5CamorHH3+8xjbsAWXZsmXIzMwEAAghau1YffbZZ9Dr9di8eTNGjx4tB8XExEQAtoCwfv167NixAzt27MDSpUsxbdo0OTh4enoCQI2Ak5qais6dO2PevHlYs2YNVq2yzXo+dOgQLl26BJUkISgsHABwIedKtzOwfRg07raQkrr2ZwBAYf4lHErdXm37J9IOotJsu77h9P98hTeXrsbIJyfXOD5tlYBcbrryPdo5J46hpNDWNXvmtbfx1vI1mDDtlRrr3yg9eyXKP0+bNk1+frds2YJZs2bhiSeeqHPd48ePIzc3t8Zt9erVkCQJDzzwAL788ku4ubk1fd09e0K6nIbHjRsn1719+3a89dZb+POf/1xt+ZMnTwIAoqOjm7wWIrqxGCiJFOzMmTMIDw9HZGQkvvzySwDApEmT4Ovri65du8rLdenSBZ06dcJbb71VYxtz5syBu7s78vPz0blzZ3Tp0gVt2rTBjBkzaizbo0cPLF++HBqNBqtWrcKECRMghMDs2bOhVquxbds2BAUFoUePHggJCUGHDh3w7rvvyuvHxsYCAJYvX46EhATceeedAID3338fgYGBCA8PR8+ePTF06FAAto6nv78/1CoJnXraLlJ+7ODv8vY8PD0xdIwtJG9e9T0m39EXf7qzf7UwCADto2OguhyY5vzxEfxl+O3475y/1zg+H/8A6A1+tpr+7894cfTd+Onz/6Jt+w7wuByGP/z7C/jLHwbhjWcn1P3CNLHk5GT5ORk5ciRiY2Pl2ft33XVXvRecb9OmDQIDA2vchg4dio8++ghfffUV1OobM1gVEREhn2YxZcoUREREoGvXrjAYDBgwYAD27NkjL1taWipfnqh///43pB4iunEYKIkU7LnnnsOjjz6K/Px86PV6PP3005g7dy4AYMiQIXjjjTfkc+1iY2OxYMGCGtvo27cvtm7diuHDh8Pb2xtHjhyBt7c3br311lr3OXjwYCxcuBCSJOHzzz/HlClTMGDAAGzatAl33XUXJElCWloaNBoNRo0ahalTp8rrTp06FYMHD4anpyf27t2LXbt2AQDuvvtu9O/fHyaTCQcOHICHhweGDx+On376yXZ5Io0b+t89EgCwb/N6WKoMoT/y/DQMfuBheHh6oaSwAINHP4K+dw2vVnNIRDQmv/YO2oR0QKXZDL2fP6a8/WGNY5MkCZNenYfA0HCUFhchY/9eXMjJhrevAS+89zFComIgrAIajQbTFixu3It1nVQAPDVuWLFiBWbMmIHo6GgcP34cZ8+eRadOnfD3v/8d8fHxjd6uJEl46qmnbliYtFuwYAHeffdddOnSBTk5OTh58iTCwsLw/PPPIzk5WV5u9erVsFgs6Nq1a6NmkRNR8yAJUcsF24ioWQsLC8PJkycxc+ZMzJo1y9nl3BTrsi5i4sihyPh9D178cBESb7/D2SXdFAatBreHtXJ2GTfcfffdh++//x4fffQRnn76aWeXQ0SNxEk5RKQI/joNxvxpKmY/+TBWLvyo2QXK3RvW4rsF79X6WM+Bg/DAM39p9DYl2I7b1WVmZuKHH35AWFgYJky4eacSEFHTYaAkIkUweGjQ7dZkLEvPcXYptSrIuyTP+r5au/Co69qmgO24XV1UVNR1XXWAiJoPDnkTkSIYy8xYd/L6vmZQyQaFtoJvCwiVRKRsnJRDRIrgo1VDJV17OVeikgC9lgNJRNT8MVASkSKoJAkheh1aSqaUAITodVBJLeWIiUjJGCiJSDEiDJ5oKefoCACRfp7OLoOIqEEYKIlIMfx17vBtIUPAvlo1/DzcnV0GEVGDMFASkaJE+Xk5u4SboqUcJxG5BgZKIlKUEL0OahefnaNW2c4XJSJSCgZKIlIUN5WESBfv3kX6ecHNxUMzEbkWBkoiUpxYf294adxcbsa3BMBL44ZYf29nl0JE1CgMlESkOG4qCb2CDC4341sASAwysDtJRIrDQElEihSgc0e0iw19R/t5wV/Hmd1EpDwMlESkWHGt9C4x9G0f6o5rpXd2KURE14WBkogUy00lITHI4OwymgSHuolIyRgoiUjR/HXu6B1scHYZDukdbOBQNxEpGgMlESleO70OCYG+zi7juiQE+qIdrzlJRArHQElELiHM11NxoTIh0Bdhvvy+biJSPkkI4WpX3iCiFuxMkQmpOUYAaJaXFbKfJdk72MDOJBG5DAZKInI5eaYK7Mw1osRscXYpNXhp3JAYxHMmici1MFASkUuyWAXSLhYhI78EEpzbrbTvP9rPC3Gt9JzNTUQuh4GSiFzaJVMFdjm5W8muJBG5OgZKInJ5FqtAel4xjuWXoNJ68z7y1CoJkX5eiPX3ZleSiFwaAyURtRgWq0B2kQmZ+SUoKK9s8qFw+/YMWjUi/bwQotcxSBJRi8BASUQtUp6pAseNpcguMsHetGxswKy6vEoCQvQ6RPp5ws+DQ9tE1LIwUBJRi2YVAkXllcgvN8NYZkaeyYzCcjOs9ayjAuCj1cBfp4HBQwM/rQZ6rRoqid1IImqZGCiJiK5iFQKlZgsqrQLPv/AC3NQavDH3H1BJEtQqCZ4aN4ZHIqIq1M4ugIiouVFJErzdbR+PF09nAQBnaBMR1YNfvUhEREREDmGgJCIiIiKHMFASERERkUMYKImIiIjIIQyUREREROQQBkoiIiIicggDJRERERE5hIGSiIiIiBzCQElEREREDmGgJCIiIiKHMFASERERkUMYKImIiIjIIQyUREREROQQBkoiIiIicggDJRERERE5hIGSiIiIiBzCQElEREREDmGgJCIiIiKHMFASERERkUMYKImIiIjIIWpnF0BE1ByYzWZ8++23KCwsrHZ/VlYWAGDBggXV7vfx8cHo0aOh0WhuVolERM2WJIQQzi6CiMjZTpw4gYiICACAJEny/faPyNruO378OMLDw29ilUREzROHvImIAISHh2PQoEFwc3ODEEK+2VW9z83NDYMGDWKYJCK6jB1KIqLLtm3bhn79+jVo2a1bt6Jv3743uCIiImVgh5KI6LK+ffvKXcq62LuTDJNERFewQ0lEVEVDupTsThIRVccOJRFRFfV1KdmdJCKqHTuURERXqa9Lye4kEVFN7FASEV2lti4lu5NERHVjh5KIqBa1dSnZnSQiqh07lEREtbB3KSVJgiRJ7E4SEdWDHUoiojpU7VKyO0lEVDcGSiKieti/DefEiRNOroSIqPlioCQiuopVCJSaLai0ClRaLLACUKtUUEkS1CoJnho3qKp8tzcRUUundnYBRETOZBUCheWVMJabYSwzI89kRmG5GdZ61lEB8NFq4K/TwOChgUGrgY9WzZBJRC0WO5RE1CLlmSpw3FiK7CITrJc/BSUAjflArLq8SgJC9DpE+nnCz8O9aYslImrmGCiJqMWwWAVOF5lwLL8EBeWVjQ6Q12Lfnq9WjSg/L4TodXBTsWtJRK6PgZKIXJ7FKpB+qRjHjCWotN68jzy1SkKknxdi/b0ZLInIpTFQEpFLu2SqwK5cI0rMFqfV4KVxQ2KQAf46DoUTkWtioCQil2SxCqRdLEJGfkmTD203ln3/0X5eiGulZ7eSiFwOAyURuZw8UwV2OrkrWRd2K4nIFTFQEpFLOVNkQmqOEYBzu5J1sfcmewcb0E6vc2otRERNhYGSiFxGlrEUe84VOLuMBksI9EWYr6ezyyAicpjK2QUQETUFpYVJANhztgBZBaXOLoOIyGEMlESkeGeKTIoLk3Z7zhbgTJHJ2WUQETmEgZKIFC3PVCGfM6lUqTlG5JkqnF0GEdF1Y6AkIsWyWAV25hqdXUaT2JlrhOUmXnSdiKgpMVASkWKlXSxCidnSLGdzN4YAUGK2IO1ikbNLISK6LgyURKRIl0wVyMgvcXYZTSojv4RD30SkSAyURKQ4FqvArlwjXO37ZiRw6JuIlImBkogUJz2v2CWGuq9mH/pOzyt2dilERI3CQElEimKxChxzsaHuqx3LL2GXkogUhYGSiBQlu8iEShcPW5VWgWxem5KIFISBkogUJdPFu5N2LeU4icg1MFASkWLkmSpQUF7p7DJuioLySs74JiLFYKAkIsU4bix1uZnddZFgO14iIiVgoCQiRbAK23mFrn325BUCtvNFraKlHDERKRkDJREpQmF5JVx8Lk4NVgEUtZAhfiJSNgZKIlIEY7nZ2SU4RX4LPW4iUhYGSiJSBGOZWTHnT854bBRGxQZj/otTHNqOBNtxExE1dwyURORUZWVleOedd5CUlAQfHx94enoiJiYGTz/9NI4fPy4vl2cy39TzJ0fFBmNUbDDWLV9S7f4l8+fJj53PPl3ruiFRMYjuloDADqEO1SBgO24iouZO7ewCiKjlys/Px6BBg7B3714AgF6vR2RkJE6dOoWPP/4Yffr0QUREBKxCoEBBQ79PzfxHk22rsNwMqxBQSUrpzxJRS8QOJRE5zbPPPiuHyb/+9a/Iy8vDgQMHUFBQgI0bN6Jjx44AgO+Wr8BLD4/AIwlReKhrOKbeOwRrl35VbVu1dRSvHno+n3262nKvP/04xnSPwKRBSfL2DqZsw6jYYHkbH7z0F4yKDcbE23s3+LiuZ792eefO4oOX/oIn+/fAg11C8fTgWzDzldmorLwyOWfHjh0YNGgQAgIC4OHhgbCwMIwcORLHjh1rcI1ERE2JgZKInKKgoADffvstAKBbt2544403oFZfGTQZMGAA+vTpgy+++AIP3X8f0vfshIenFwytWuPE4UNY8PepWPrRP697//+e+TeczjwCtVqD82dO498z/obs4xnw9PZGdLcEebm27UMR3S0B4XHx13+wDdgvABTl52HaQ/dg3fIlKCstQbuIaFw6m4M5r8zCU089BQCwWq245557sG7dOmg0GnTq1AmlpaX44YcfcPp07UPwREQ3GgMlETnF0aNH5a5b//79IdUxpPvyyy8DAKK7JeCjdalY8FsKkobcBQBY9tE/UW66vot/J94+FB+u3YFXv/wegC2oHUrdjojOXTF3ySp5ufsnTcHcJavwf/9aeF37aeh+AWD1l5/iYm4ODK1a44Nft+OdH9Zi6j8/BgAsWrQImZmZyM/Px6VLlwAAu3fvxt69e3H+/HkcPHgQcXFxTVIjEVFjMVASkVOIKhfsritMnj9/HqdOnQIA3DLkLmjctZAkCf2GjQAAVJSV4XTm0evaf//h90KSJLSPjJHvK7h44bq21VT7zTiwDwBgvHgBE/p2wajYYLwxeQIA2/OVkpKCgIAA9OnTBwAQFRWFLl26YMyYMdi7dy9atWp1w+snIqoNJ+UQkVN07NgRarUalZWV2LJlC4QQdQbLxrBaLfLPpcWFdS7npfcFALhVGWYXN+FbaRqyX52XN0KirgROH3c11CoJnp6eAIDffvsNX331FbZu3Yq0tDQsXboU33zzDXJzc/HXv/71hh8DEdHV2KEkIqfw9fXF6NGjAQB79+7FSy+9VG3iydq1a5GZmYkOHToAAHb8uhrminIIIbD1px8AAO4eHmh/OXj5Bti6c7lZtksNZR/PwMmj6dddn7uHBwDUO6RurihHRXmZfKs0OzYTPSq+GwBb2Hz+7QWYu2QV5i5Zhe9/XI1nnnkG9957L4QQ2LZtG8aNG4eFCxdix44deOKJJwAAmzZtcmj/RETXix1KInKa+fPnIy0tDfv27cPcuXPx4YcfIiwsDKdPn0Z+fj4+/fRTvPbaa3jssceQ8fseTLy9NzTuWlzIyQYAjJr4HLQ6W9euyy23YsuPK7Dy038jY/8+ZKUfAhzoOLaLiMKJtIP44u3XsWHFd+japz8eeX5atWX+PGxAtX8nDhqKFz/49Lr3eecj47F26dfIO5eLP93VHyGRUTCVlCDvbA7MZjMef/xxWCwWDB48GHq9Hu3bt4dKpUJaWhoAoGvXrte9byIiR7BDSURO4+/vj+3bt2PevHlITEyE1WrFkSNH4OfnhyeffBIDBgzAo48+iu9XrEBsQiJMJcUwXryA8E6dMWnOPNw/8Tl5W+NenIWeAwfDXeuBc6ezcN/Tf0JsQsMv9XO1J15+FR1iOqHSbEbmgX3IyTp+7ZUc5OsfgLlL/ofb73sQeoMfTmceRUVZGfr37493330XAODm5oaJEyciPDwcZ86cQWZmJsLCwjB16lTMmDHjhtdIRFQbSdyMk4aIiBy0Lutii/w+b4NWg9vDONmGiJo3diiJSBH8dRrFfJd3U5FgO24iouaOgZKIFMHgobmp3+XdHAjYjpuIqLljoCQiRTBoW2aw8muhx01EysJASUSK4KNVQ9XCxrxVEqDX8mIcRNT8MVASkSKoJAkhel2LOY9SAhCi10HVBBd7JyK60RgoiUgxIgyeLeY8SgEg0s/T2WUQETUIAyURKYa/zh2+LWQI2Ferhp+Hu7PLICJqEAZKIlKUKD8vZ5dwU7SU4yQi18BASUSKEqLXQe3is3PUKtv5okRESsFASUSK4qaSEOni3btIPy+4uXhoJiLXwkBJRIoT6+8NL42by834lgB4adwQ6+/t7FKIiBqFgZKIFMdNJaFXkMHlZnwLAIlBBnYniUhxGCiJSJECdO6IdrGh72g/L/jrOLObiJSHgZKIFCuuld4lhr7tQ91xrfTOLoWI6LowUBKRYrmpJCQGGZxdRpPgUDcRKRkDJREpmr/OHb2DDc4uwyG9gw0c6iYiRWOgJCLFa6fXISHQ19llXJeEQF+04zUniUjhGCiJyCWE+XoqLlQmBPoizJff101EyicJIVztyhtE1IKdKTIhNccIAM3yskL2syR7BxvYmSQil8FASUQuJ89UgZ25RpSYLc4upQYvjRsSg3jOJBG5FgZKInJJFqtA2sUiZOSXQIJzu5X2/Uf7eSGulZ6zuYnI5TBQEpFLu2SqwC4ndyvZlSQiV8dASUQuz2IVSM8rxrH8ElRab95HnlolIdLPC7H+3uxKEpFLY6AkohbDYhXILjIhM78EBeWVTT4Ubt+eQatGpJ8XQvQ6BkkiahEYKImoRcozVeC4sRTZRSbYm5aNDZhVl1dJQIheh0g/T/h5cGibiFoWBkoiatGsQqCovBL55WYYy8zIM5lRWG6GtZ51VAB8tBr46zQweGjgp9VAr1VDJbEbSUQtEwMlEdFVrEKg1GxBpVXg+RdegJtagzfm/gMqSYJaJcFT48bwSERUhdrZBRARNTcqSYK3u+3j8eLpLADgDG0ionrwqxeJiIiIyCEMlERERETkEAZKIiIiInIIAyUREREROYSBkoiIiIgcwkBJRERERA5hoCQiIiIihzBQEhEREZFDGCiJiIiIyCEMlERERETkEAZKIiIiInIIAyUREREROYSBkoiIiIgcwkBJRERERA5hoCQiIiIihzBQEhEREZFDGCiJiIiIyCEMlERERETkEAZKIiIiInIIAyUREREROUTt7AKIiJqL33//HYWFhdXuu3TpEgBg8+bN1e738fFBt27dblptRETNmSSEEM4ugojI2TIyMhATE9OodY4ePYro6OgbVBERkXJwyJuICEBUVBTi4+MhSdI1l1WpVIiPj0dUVNRNqIyIqPljoCQiAiBJEl599VU0ZNDGarVizpw5DQqfREQtAYe8iYguE0Kga9euSEtLg9VqrXUZlUqFuLg47N+/n4GSiOgydiiJiC6zdynrCpMAu5NERLVhh5KIqIr6upTsThIR1Y4dSiKiKurrUrI7SURUO3YoiYiuUluXkt1JIqK6sUNJRHSV2rqU7E4SEdWNHUoiolrYu5QHDx4EAMTHx7M7SURUB3YoiYhqYe9S2rE7SURUN3YoiYjqIISAv78/ACAvL4+BkoioDgyURERXsQqBUrMFlVaBMzk5EJKE4MBAqCQJapUET40bVAyXREQyBkoiatGsQqCwvBLGcjOMZWbkmcwoLDej7kub284V8tFq4K/TwOChgUGrgY9WzZBJRC0WAyURtUh5pgocN5Yiu8gE6+VPQQlAYz4Qqy6vkoAQvQ6Rfp7w83Bv2mKJiJo5BkoiajEsVoHTRSYcyy9BQXllowPktdi356tVI8rPCyF6HdxU7FoSketjoCQil2exCqRfKsYxYwkqrTfvI0+tkhDp54VYf28GSyJyaQyUROTSLpkqsCvXiBKzxWk1eGnckBhkgL+OQ+FE5JoYKInIJVmsAmkXi5CRX9LkQ9uNZd9/tJ8X4lrp2a0kIpfDQElELifPVIGdTu5K1oXdSiJyRQyURORSzhSZkJpjBODcrmRd7L3J3sEGtNPrnFoLEVFTYaAkIpeRZSzFnnMFzi6jwRICfRHm6+nsMoiIHMbv8iYil6C0MAkAe84WIKug1NllEBE5jIGSiBTvTJFJcWHSbs/ZApwpMjm7DCIihzBQEpGi5Zkq5HMmlSo1x4g8U4WzyyAium4MlESkWBarwM5co7PLaBI7c42w3MSLrhMRNSUGSiJSrLSLRSgxW5rlbO7GEABKzBakXSxydilERNeFgZKIFOmSqQIZ+SXOLqNJZeSXcOibiBSJgZKIFMdiFdiVa4Srfd+MBA59E5EyMVASkeKk5xW7xFD31exD3+l5xc4uhYioURgoiUhRLFaBYy421H21Y/kl7FISkaIwUBKRomQXmVDp4mGr0iqQzWtTEpGCMFASkaJkunh30q6lHCcRuQYGSiJSjDxTBQrKK51dxk1RUF7JGd9EpBgMlESkGMeNpS43s7suEmzHS0SkBAyURKQIVmE7r9C1z568QsB2vqhVtJQjJiIlY6AkIkUoLK+Ei8/FqcEqgKIWMsRPRMrGQElEimAsNzu7BKfIb6HHTUTKwkBJRACADRs2QJIkSJKErKwsp9byyy+/QJIkDBw4UL7PWGZuMedPAsD57NMYFRuMcIMXNmzY4OxyajVv3jyEhobCzc0NkiRhw4YNSE5OhiRJGDduHAAgKytLfl819jgGDhwISZLwyy+/NH3xRNSkGCiJqMldHSoaa8aMGQCA559/Xr4vz2Su9/zJgynbMCo2GKNig3E++3Sj92kPcKNig3EwZVuj129qGnd3RHdLQKfuPeHj4+PscmrYs2cP/vrXv+LUqVMICwtDUlISfHx8EBcXh6SkJERGRjq8j6lTpwK48n4gouZL7ewCiIiq2rNnD1JSUuDn54dhw4YBsE3IKWhhQ79+bdpi7pJVUAHoHhPo7HJqSEtLq/azVqsFAHz44YdNto8777wTfn5+SElJwd69e9GjR48m2zYRNS12KImasbCwMEiShBdffBHPPvss/P394evri2eeeQbl5eXyci+++CI6d+4Mg8EAjUaD4OBgjB07Frm5udW2t2vXLowYMQIBAQHQarWIiIjA22+/Xef+X3jhBUiSBE9PT6xduxYAkJKSgmHDhsFgMMDDwwMJCQlYunSpvI4kSdi4cSMAYPHixdWG0YuLizFp0iS0b98eWq0WrVu3Rr9+/bB48WJ5/a+//hqALUxoNBoAQKnZgiP7dmPWuNEYm9QZD3UNx8Tbe2Pu5PE4eyoLS+bPw8yx98vbmDQ4CaNigzH/xSkAgP8t+hgvjByMsUlxGB3fAeP7xOPNPz2BnBPHAADrli/BpMFJ8vozx96PUbHBmPHYKADA0Xr23VhWqxWrv/wUleb6A7K9Y3pvbDDWrF0HADh79iweeeQRBAUFQavVIjAwELfffjt++ukneb1Tp07h8ccfR2BgIDQaDUJCQvDMM88gLy9PXmbcuHGQJAnJycn44IMPEBYWBr1ej3vuuQdnz5695jGMGzcOjz32mPxvDw8P+TVuaHf6Wu8jANBoNBg6dCiAK+8LImqeGCiJFOC9997DN998A4PBgMLCQixYsADTpk2TH//5559x5swZtG/fHlFRUTh79iw+++wzjBgxQl5m27Zt6NevH1auXIni4mJER0ejsLAQmzdvrnWfM2bMwDvvvANPT0+sWrUKgwcPxtatW9G/f3+sXr0aOp0OYWFh2Lt3Lx544AF89tlnAICkpCTo9XoAQKtWrZCUlISkpCRotVrMmDEDH330ES5cuIDOnTtDr9cjJSUF69evl/e7ZcsWAEBiYqJ8X0WlBa9PfBwHdmyBWqNGSGQUystM2PnbGlzMzUFAYBBCIqPl5cM7dUZ0twQEdggFABzauR1nT2XB0Ko12oVHobiwACm/rsas8aNRUV4GX/8AhHfqLK8fEhmN6G4JCImKgdVqrXffdbmQk43z2adr3Hat/wX/nfN3vPP8xGuGSjvL5UsHPfPMM/jqq69QXFyM+Ph4uLu7Y8OGDUhNTQUAnD9/Hn369MHnn38Oo9GImJgYnDt3DgsWLMDAgQNRVlZWbbvbtm3D1KlT4e7ujuLiYvz444944YUXrllPZGQkIiIi5H9XfY0boiHvI7vevXsDQJ3vUyJqJgQRNVuhoaECgIiOjhaFhYVCCCHGjBkjAAh3d3dhNBqFEELs379fWCwWeb1PPvlEwHYpQ5GZmSmEEOK2224TAITBYBBHjhwRQghhsVjEvn37hBBCrF+/Xl5n8uTJAoDw9PQU69atk7ebnJwsAIghQ4YIs9kshBBiypQpAoAICQmRlxs4cKAAIMaOHVvteO655x4BQMyZM0e+79KlS3INQggREBAgAIjly5fL92WczpFr+3jjbrEsPUcsS88R7/5vvVi4db9Ylp4jXlm8VF5mwdoUeZll6TnivVUbxJIDJ+V/z1j4jbzszE+XiGXpOWLB2hT5vlcWL5WXXbT94DX3XdtNb/ATGndtnTdJkkTSkLuq1VX1VrWeH37+RQghRHx8vAAgvvjiC/m5ycnJEYcPHxZCCDFjxgwBQKhUKrF7924hhBDff/+9vJ2FCxcKIYQYO3asvJz9ub/33nsFANG2bduGvDXFp59+Km+3qqtf+xMnTsjLrV+/vlHvIyGEWLZsmQAgWrVq1aC6iMg5eA4lkQLcc889ctfvoYcewtdff42KigocPXoUiYmJ2LdvH8aNG4cjR46gpKT6d0Dn5OQgMjISKSkpAID7778fMTExAACVSoVu3brV2N8HH3wAwDbMeNttt8n32zthv/76qzwcbZednY0zZ86gXbt2dR7H8OHDsWrVKkyfPh0ff/wxYmNj0bdvXzz99NPyMgUFBQAgHy8AGPz90bF7TxzZtxvP3tEPgR3C0D66I3omD0b/e+69xrNn6xZ+NOOvOHnkMMpKSyCqXCw87/y5etfV+13fvhftOFTvdj9761X88N8FOHnkMCLju9a7rL3e4cOH4+DBgxg7dixmzpyJ2NhYDBw4UH7+du7cCQDo2LEjEhISAAAjR46Ep6cnSktLsWvXLowfP17ebpcuXeTXPy4uDt9//z3Onav/+WgKjXkf2Sck2d8XRNQ8MVASKdyWLVswduxYCCEQEBCAuLg4FBcX4/DhwwAAi8XS6G16e3ujuLgY8+bNw5AhQ6DT6ao93q5dO4SEhNRYr7Ky/otwP/XUU4iNjcXKlStx4MAB7N69G7/88gu+++47HDx4EIAtQOTl5aG4uFheTyVJmLnoW2xe9T2O7NmJ08cysOOXH7H1px+Qf+EcRj7xTJ37PHv6JN6YPAGV5grovLwR0bkrrJZKnDhsC3zWBjw/17PvRxKiUFZa/1cn9r1rOMKqDLXXRZJsF0x67bXX0K9fP6xZswYHDx7Epk2b8OOPP2LDhg348ccfr7mdqxkMBvlntfrm/3fQkPdRYWEhADTLme5EdAXPoSRSgB9//FEOWN9++y0AwN3dHTExMUhJSZE7WAcOHEBqaioef/zxGttISrJNOlm2bBkyMzMB2Dpf+/fvr7HsZ599Br1ej82bN2P06NHyf/D28xpDQ0Oxfv167NixAzt27MDSpUsxbdo0hIbazln09PQEgBrd0tTUVHTu3Bnz5s3DmjVrsGrVKgDAoUOHcOnSJQBAdLTtXMiTJ0/K60kAjuzdhdvufRCTX38Xc5eswqBRYwAAaTt3AAC0VUJvmelKkDuRdhCV5goAwPT/fIU3l67GyCcn1zjmquuXV1lfCHHNfdfmw1934D+b99W4/f2TLyFJEvrcORxT3voAbm5udW7DTnU5UG7duhUDBw7E+++/j3Xr1uHjjz8GAGzatAnAldfnyJEj2LNnDwBgxYoVKL0cbHv16nXNfd0MDX0fAVfeB/b3BRE1T+xQEinAmTNnEB4eDh8fHxw/fhwAMGnSJPj6+qJr1yvDpV26dEHr1q1x/vz5GtuYM2cObrvtNuTn56Nz586IiYnB2bNn0a9fP6xYsaLasj169MDy5csxbNgwrFq1ChMmTMDixYsxe/ZsDBo0CNu2bUNQUBDCw8Nx4cIF5OTkYMCAAfIkoNjYWKxevRrLly9HQkIC2rRpg59//hnvv/8+lixZgpCQEPj7+8vBtl27dvD39wcA9O/fHykpKdi1a5dcjySseGX8g9B5eSMgKBgqSYXsY0cBAKEd4wAAge1DodZoUGk245UJD6J1cAhGjJ+I9jEdoXJzg9ViwZw/PoJWQe1gvFjz+fHxD4De4IciYz7e/78/Iyg0HAOG34ehY8Zec9+18Q1oVev9hlat8dSsNzBo1ENwa2BX0O1yoHzxxRexc+dOtG/fHr6+vnIX2v4emDx5Mj755BPk5uaib9++iIqKwpEjRwAA8fHxGDNmTIP2d6M19H0EXBke79+/v7PKJaIGYIeSSAGee+45PProo8jPz4der8fTTz+NuXPnAgCGDBmCN954A8HBwTCZTIiNjcWCBQtqbKNv377YunUrhg8fDm9vbxw5cgTe3t649dZba93n4MGDsXDhQkiShM8//xxTpkzBgAEDsGnTJtx1112QJAlpaWnQaDQYNWqUfBFqwHZB6sGDB8PT0xN79+6Vw+Hdd9+N/v37w2Qy4cCBA/Dw8MDw4cPx008/ycO69tDz888/y51RvYc7hj70ONqEdEDeubM4eyoLrdu1xx8mTMToyX+xLePnjwkvv4pWQcEouHgBGb/vQf7F8wiJiMbk195Bm5AOqDSboffzx5S3a14rUZIkTHp1HgJDw1FaXISM/XtxIScbKjc33HGNfTeGJEm448FHGxwmAUDnblv2wQcfRK9evVBYWIgDBw7AYDDI59QCQJs2bbBjxw489thjMBgMOHLkCNq2bYuJEydi48aN8PDwaHS9N0JD30dmsxlr1qwBgGYThomodpKoenY6ETUrYWFhOHnyJGbOnIlZs2Y5u5yb5pZbbkFKSgpWrlyJ4cOHAwDWZV1sUd/nffT3PZj24D0AbEPY9olULcnKlSsxYsQI3HLLLdi+fbuzyyGienDIm4iandmzZ2Po0KGYN2+eHCj9dRoUlNf/9YuuYumC97Bu+RIAQEhoWLVrPt4s9957b40L49t9//33CAoKuuE1zJs3D4Dt/UBEzRsDJRE1O3fccQeuHjwxeGhaRJgEgP3bNuPS2VxEd+2Bd96f75QZ2Hv37q02Maqqqt/SdCPZJxsRUfPHIW8iUgRjmRnrTl50dhk33aDQVvD10Fx7QSIiJ+KkHCJSBB+tGirJ2VXcXCoJ0Gs5kEREzR8DJREpgkqSEKLXoaVkSglAiF4nX4OSiKg5Y6AkIsWIMHi2mPMoBYBIP09nl0FE1CAMlESkGP46d/i2kCFgX60afh7uzi6DiKhBGCiJSFGi/LycXcJN0VKOk4hcAwMlESlKiF4HtYvPzlGrbOeLEhEpBQMlESmKm0pCpIt37yL9vODm4qGZiFwLAyURKU6svze8NG4uN+NbAuClcUOsv7ezSyEiahQGSiJSHDeVhF5BBpeb8S0AJAYZ2J0kIsVhoCQiRQrQuSPaxYa+o/284K/jzG4iUh4GSiJSrLhWepcY+rYPdce10ju7FCKi68JASUSK5aaSkBhkcHYZTYJD3USkZAyURKRo/jp39A42OLsMh/QONnCom4gUjYGSiBSvnV6HhEBfZ5dxXRICfdGO15wkIoVjoCQilxDm66m4UJkQ6IswX35fNxEpnySEcLUrbxBRC3amyITUHCMANMvLCtnPkuwdbGBnkohcBgMlEbmcPFMFduYaUWK2OLuUGrw0bkgM4jmTRORaGCiJyCVZrAJpF4uQkV8CCc7tVtr3H+3nhbhWes7mJiKXw0BJRC7tkqkCu5zcrWRXkohcHQMlEbk8i1UgPa8Yx/JLUGm9eR95apWESD8vxPp7sytJRC6NgZKIWgyLVSC7yITM/BIUlFc2+VC4fXsGrRqRfl4I0esYJImoRWCgJKIWKc9UgePGUmQXmWBvWjY2YFZdXiUBIXodIv084efBoW0ialkYKImoRbMKgaLySuSXm2EsMyPPZEZhuRnWetZRAfDRauCv08DgoYGfVgO9Vg2VxG4kEbVMDJRERFexCoFSswWVVoHnX3gBbmoN3pj7D6gkCWqVBE+NG8MjEVEVamcXQETU3KgkCd7uto/Hi6ezAIAztImI6sGvXiQiIiIihzBQEhEREZFDGCiJiIiIyCEMlERERETkEAZKIiIiInIIAyUREREROYSBkoiIiIgcwkBJRERERA5hoCQiIiIihzBQEhEREZFDGCiJiIiIyCEMlERERETkEAZKIiIiInIIAyUREREROYSBkoiIiIgcwkBJRERERA5hoCQiIiIihzBQEhEREZFDGCiJiIiIyCEMlERERETkELWzCyAiai5KS0tRUVFR7T6z2QwAMBqN1e53d3eHp6fnzSqNiKhZk4QQwtlFEBE5W1ZWFmJiYuQAeS0ajQZHjx5FWFjYjS2MiEgBOORNRAQgODgYrVu3bvDybdq0QXBw8A2siIhIORgoiYhgG8KeOXNmg5efOXMm3N3db2BFRETKwSFvIqLLKioqEB4ejtzcXNT10ShJEoKDg3H8+HEGSiKiy9ihJCK6zN6lrO/vbCEEu5NERFdhh5KIqIr6upTsThIR1Y4dSiKiKurrUrI7SURUO3YoiYiuUluXkt1JIqK6sUNJRHSV2rqU7E4SEdWNHUoiolrYu5Q5OTkAgHbt2rE7SURUB3YoiYhqcfV1KdmdJCKqGzuURER1qKiogK+vLwCgoKCAgZKIqA5qZxdARNTcWIVAqdmCSquEpT/+DCFJKLYAqjIz1CoJnho3qCTJ2WUSETUb7FASUYtmFQKF5ZUwlpthLDMjz2RGYbkZ1nrWUQHw0Wrgr9PA4KGBQauBj1bNkElELRYDJRG1SHmmChw3liK7yATr5U9BCUBjPhCrLq+SgBC9DpF+nvDz4NA4EbUsDJRE1GJYrAKni0w4ll+CgvLKRgfIa7Fvz1erRpSfF0L0Orip2LUkItfHQElELs9iFUi/VIxjxhJUWm/eR55aJSHSzwux/t4MlkTk0hgoicilXTJVYFeuESVmi9Nq8NK4ITHIAH8dh8KJyDUxUBKRS7JYBdIuFiEjv6TJh7Yby77/aD8vxLXSs1tJRC6HgZKIXE6eqQI7ndyVrAu7lUTkihgoicilnCkyITXHCMC5Xcm62HuTvYMNaKfXObUWIqKmwkBJRC4jy1iKPecKnF1GgyUE+iLM19PZZRAROYzf5U1ELkFpYRIA9pwtQFZBqbPLICJyGAMlESnemSKT4sKk3Z6zBThTZHJ2GUREDmGgJCJFyzNVyOdMKlVqjhF5pgpnl0FEdN0YKIlIsSxWgZ25RmeX0SR25hphuYkXXSciakoMlESkWGkXi1BitjTL2dyNIQCUmC1Iu1jk7FKIiK4LAyURKdIlUwUy8kucXUaTysgv4dA3ESkSAyURKY7FKrAr1whX+74ZCRz6JiJlYqAkIsVJzyt2iaHuq9mHvtPzip1dChFRozBQEpGiWKwCx1xsqPtqx/JL2KUkIkVhoCQiRckuMqHSxcNWpVUgm9emJCIFYaAkIkXJdPHupF1LOU4icg0MlESkGHmmChSUVzq7jJuioLySM76JSDEYKIlIMY4bS11uZnddJNiOl4hICRgoiUgRrMJ2XqFrnz15hYDtfFGraClHTERKxkBJRIpQWF4JF5+LU4NVAEUtZIifiJSNgZKIFMFYbnZ2CU6R30KPm4iUhYGSXM6sWbMgSRLCwsKcXcp1W7RoESRJgiRJyMrKcnY5zYKxzFzj/MkZj43CqNhgzH9xijNKqtUvS76w1fR/z8n3Tby9N0bFBmPJ/HmN2pYE23HfaGvWrEHXrl3h4eEBSZIwa9asWn+PwsLC5McbY+bMmZAkCS+99FLTFl4He53224oVK2pdbsOGDc3m98xex6JFixq9bm2v3/UaN25ctefOkW1Ry8JASQ2SnJxc7UOmIR/WN1pd/7mFhIQgKSkJPXr0uCH7rfqfkP2m1+vRuXNnzJkzByUlyrzcS9UQe7NlZWXJ+96wYUOty+SZzM3+/MlKsxnLPnoPADB8/FPy/eFx8YjuloCAwKBGbU/Adtw3ktVqxUMPPYQDBw5Ar9cjKSkJISEhTfp79Oyzz0Kr1eL999/HxYsXm6DqhomIiEBSUhL8/f0BXHmP1/Uec6akpCQkJSWhdevWjVqvrtevoewB0i4yMhJJSUnQ6/WNqoNI7ewCSFnc3d1r/Adj/7BuLp588kk8+eSTN2VfERERaN26NU6dOoW0tDRMnz4dqampWLly5U3ZvzNVVFTA3d39puzLKgQKFDD0u2v9r7iYm4MO0bEIi+0s3/9//1p43dssLDfDKgRUNyjo5+TkwGg0AgC++OILDB06VH6sqX6PWrdujSFDhmDVqlX4/PPP8Ze//KVJtnst06dPx7hx427Kvhy1Y8eO61qvvtfvekyfPh3Tp09HcnIyNm7c6NC2qGVhh5IaJSgoCDt27Kh2GzBgQJ0dpqu7iFW7ez/88AMGDBgAnU6H2NhYrFq1qtq+MjIy8PDDDyMwMBDu7u4ICQnB1KlT5X2dPHkSAPDKK69U66zVNlRnsVjw9ttvIy4uDlqtFr6+vhgyZAg2b94sL9OY2uymT5+OHTt24PTp00hKSgIA/O9//0N+fj4AIC8vD5MnT0b79u2h0WjQtm1bPProozh16lS17cyfPx/t2rWDl5cXHnnkERQUFNTYV9X6qj7HBQUFeO655xAaGio/T88//zxKS22XnDl16hQMBgMkScIrr7wCADhz5ox834wZMzBu3DiMHz9e3ubVw132f7/55pu477774O3tjaeesnXgxo4di+joaOj1eri7uyM0NBR//vOfUVhYWK3+X3/9FYMHD4avry88PDwQGxuLL774AosWLUJ4eLi83G233QZJkpCcnCzfV9rA7+3OyTqOJ/p3x6jYYLw+8XGYK8phrijHN++/hclD++HBLqEY37cLPnjpLyjMvwQA2L99M0bFBmNUbDByso7L2/rp8/9iVGwwHkuMRUV5GfIvnMd7Uyfjif7d8WCXMDxxazfMHPsAdm/8TV5ny48rAAC9bhtSra6rh7wtFgu+ePt1TBp8Cx7qGo6xSXH426g7seK/H8rrlJeZ8OW7czHpjr7w0Grh7++PkSNH4sCBA/IyVbvK69evR0JCAnQ6HRISEhoUUBYtWoT27dvL/77zzjvlYdeGnjqSk5ODCRMmIDg4GO7u7oiIiMCrr76Kysrqk4nuueceAMDXX399zbrq8sknn6CoqOi612+IF154AZIkwdPTE2vXrgUApKSkYNiwYTAYDPDw8EBCQgKWLl0qr9O/f39IkoRHH31Uvs9isaBNmzaQJAlz58695n6vHvJuyGtb3+sHAFu2bMHQoUPh6+sLrVaLTp064a233oLFYnH0aSKqSRA1wMCBAwUAERoaWuvjJ06cELCN0In169fL94eGhgoAYubMmUIIIdavXy8vp9FoRHR0tNDpdAKA0Ov14tKlS0IIITIyMoTBYBAAhJubm+jUqZMIDAwU3bp1Ezk5OSIpKUm4u7sLAKJdu3YiKSlJJCUlCSGEmDlzZo1an3jiCXm/UVFRwt/fXwAQarVabNiwoVG1VV3u008/FUIIUVlZKZKSkuT78/LyhMlkEvHx8fJ+4uLihIeHhwAggoODxfnz54UQQqxcuVJer3Xr1qJ9+/bCy8tLvu/EiRM19mt/jsvLy0X37t0FAOHh4SG6du0q7+P2228XVqtVCCHEF198IQAId3d3cfDgQXH33XcLAKJ3797CbDaL2bNni4iICHn79ufzk08+EUII+X53d3fh4+Mj4uPjxR//+EchhBC+vr4iICBAdOvWrdo27r//fvn5//bbb4UkSQKA0Ol0Ij4+Xvj4+IjnnntOrFq1Sj4GAKJTp04iKSlJTJo0SV4/31QhlqXn1Lh1TuwjAIjkkaPFgt9SRaugYAFAJN5+h/hmf5ZYlp4jEgYOEgCEys1NhHaME57eegFAhETFiK/2HRNLD58RwWG2uu976k81tj1k9KNiWXqOSBpyl+159vQSEXFdRKugYCFJkhg9+Xl5HUPrNgKA+Nv8/1ars3VwiAAgLzvhpdnVagoMDRdqjbvonNhHXqdr3/4CgJAkScR07Ci8vb0FAOHt7S0OHz4shBDi008/lZ83rVYrOnbsKNRqtfz+N5vN9f5e1/Xcr1q1qtbfo6t/ny9evCjat28v/4507dpV3v/48eOr7WvPnj3y70JxcXGdNZ05c0acOHGixm3btm1Cq9WKPn36iMLCwnqPy16n/ffTzv582X9/qv5OnThxQkyfPl0AEJ6enuK3334TQgixZcsWodFoBAARGBgoOnbsKK+zePFiIYQQX375pfzeNhqN1batUqnE6dOn661XiCu/Y/aaG/La1vf6rV+/Xl7ez89PREdHy8s9+eST8n7Hjh0raosC9s98+2tNdC0MlNQg9g+X2m5CXF+gfP7554UQQvzwww/yfatXrxZCCDF+/Hg52G3dulXe3p49e+rctt3V/xFmZmbKYea5554TQghhNBrl9QcMGNCo2qouFxERIZKSkkRQUJB83/Dhw4UQQixcuFC+7/vvvxdCCLF7926hUqkEADFjxgwhhBC33nqrACAiIyNFUVGRqKysFMnJyTUCZUpKiujYsaPo2LGjSElJEUIIsWjRIjnoHT16VAghxL59++R1165dKz8vDz74oAAg2rZtKwAILy8veR0hqv8HdjX7/bGxsSIvL08IYQvR9v1V9fLLL8vBwWQyCSGECA8Pl48xNzdXCGELwwcPHhRC1P3+sbtUWl5voOx+a7II7BBmC5ODhoolB06KZek5YvZny+Ttzv58uViWniP+s2mvcL8cuifNmSeWpeeIcS/OEgCEf9sg8e2h02Lh1v3y6/TaVyvEsvQc0SE61vYeeutf8v7/s2mv+OdPG8Wy9Bzxxe4MeV9vLV9Tb6C86xHb+3vwAw/Ly3yxO0O88d1PYll6jpi16Dt5W+OnvSIulZaL06dPy6Hy8ccfr/Gavf/++0IIIf75z3/K99mDZ33qeu4bEihnzZolv6fsfyCtWLFCDsIZGRlXXsNLl+T92F/32iQkJAitVlvnTaVSXTNU1hUor1b1d3ny5MlymFy3bp28jP13cciQIXJAnzJliu2PkpAQIYTtvdy6dWsBQCxYsEAIIcSzzz5re40HD663Brv6AmV9r21dr9+AAQPk1y8/P18IIcRzzz0nvzbHjh2rtx4GSmosDnlTo7i7u8snj9tv1+uxxx4DAMTFxcn3nTt3DoBtiAkABg4ciL59+8qPX88Egd27d0Ncvjj0ww8/DADw9fXFsGHDAAC7du1qVG1VHT9+HCkpKSgsLERcXBxmz54tD+nt3LkTAODp6YmRI0cCABISEtCxY8dq+z106BAAYOjQofD29oabmxvuu+++Gvvq3bs30tPTkZ6ejt69ewMAUlNTAdjOZ4yJiYEkSejevbu8TtVhzwULFiA4OFg+jnnz5iE6OrqOZ612Y8eOhZ+fHwDAzc0NALB27VrEx8dDp9NBkiS89tprAIDKykpcuHABFy5cwIkTJwAA48ePR2BgIADbe6lz58617KWma13ce9+WDTh7KgvRXXtg6nsfQ63RAAAyDuyVl5nx2H0YFRuMJwf0QEVZme3x3/cAAG67dzTcPTyQdy4X+7ZsQMran2G1WhEYGo7YBNtzbR/Gnv/ic5h8R1+8/vTj2Pi/ZfBvYzue0uIrQ/w6L+966+2ZPASSJGHtd1/hjwMSMOPx+7H0o/fg7WsAABw7uE9etv8998IqBEJCQtC/f38Ajr1nm5L9/Xfu3Dl5eNf+XhdCyL/HAODj4yP/XNspHXa7d+9GWVlZnbf58+dj+/bt+OWXX5r0WD744AMAtiH52267Tb7ffoy//vorNBoNJEnCe++9BwDIzs7GmTNn4O7ujgkTJgAAFi5cCCEEvv/+ewC23xlHXc9ra//8sQ/VA1c+/4QQ2L17t8N1EVXFSTnUKPZzKK9WdZZg1fNz6vuPw/4hp1ZfeRuKawSHm6WhtX366afN4qT/2iZLAZDDH2A7n7PqeY2ZmZmN3k/btm2r/fvLL7/E1KlTAdjeG+3bt8fFixdx/LjtXMSmOlfrWhNSPDy9UFZagmOH9mPPpt/Qe9CdNZaJ7pZQ4z5DqzYAAG9fA24dNgLrli/B+uVLUFpsO08vecT98rIP/+VFxCYkYt+WDTiVcQRpu3Zg98a1OJS6HS//+3N4el2ZFVtWWv9M/x79k/HW8jXY9vMqnExPw4nDB3EodRs2fP8t/rVmW6OPH3Du75Ner68Wduw8PT3ln6u+96qGy6vFx8fLf2TVZcCAAbjzzpqvsSO8vb1RXFyMefPmYciQIdDpdNUeb9euXa2zp+3nik6cOBFvvfUWdu7cif/+9784c+YM9Hp9rX8cNlZz/qwksmOHkppEmzZt5J+PHj0KwNa5ss8+bCx753Pjxo3Vuhy///67/LP9P6trXaanZ8+ecuD96quvANiC7k8//QQA6NWr13XVeC2JiYkAgNLSUvnSSnv27MGRI0eq7dfepfvll19QUlICi8UidzeqSk1NRWxsLGJjY+WuiX0fFosFH374oTxRasOGDfjrX/8qdyQsFgsee+wxFBcXo1u3bpAkCe+++261WZxV//Ov6zm9+pJC9j8u9Ho9Tpw4gZSUFNxxxx3VlmndurU86WbRokU4f/48AMBsNiMtLa1B+75WoLplyDAMHHE/rBYL3n3+GRxK3Q4AiIrvLi9z31PPYu6SVZi7ZBVe+3IFHnz2BQwaNUZ+fOgYWydp57pfcCh1GyRJwsA/XAmU6XtSEZfYB0/8fQ5eWfwdJs5+EwCQttP2HOi8vWFoZbvky4Wc7HrrzTqSBh//ADzylxfx0r8/w5vLfgYAGC9eQM6JY4isUvfmVd9DJUnIzs6WJ5HdqPdsY9nff2q1Gt988438/vv111/xzDPP4N5775WXtU+iU6vV1SZhXW3jxo3Izc2tcduzZw88PDzQv39//PTTT/Dy8mrSY/nss8+g1+uxefNmjB49Wg6K9mMMDQ3F+vXr5WNcunQppk2bhtDQUAC2CYj2kDtlyhQAwKhRo6q9t28me90//fST/DlsHz2RJAk9e/Z0Sl3kuhgoqUnodDr06dMHgG2W5O23344RI0ZApbq+t9hLL70Eg8EAs9mMfv36oXPnzmjXrl214aPY2FgAwPvvv4/ExMRqs5SrioyMlIej/vnPfyI6OhoRERE4efIk1Gq1PPO5qY0ZMwbx8fEAgAceeACdO3dGv379YLVaERwcjGeffRYA5A5fZmYmIiIiEBERgW3banapSktLceTIERw5ckSewT1mzBh07doVFosFiYmJiI+PR8eOHWEwGHD//ffL/5H84x//wPbt2+Hn54fVq1fj6aefhtVqxdixY+XOkf35BGxDa7fccgu2bt1a7zF27doVAFBUVCTX/u2339ZY7o033oAkScjMzER4eDi6du2K1q1b4+OPPwZgC50BAQEAbMN7SUlJmD9/vry+WnWNDp0k4Zk5b6Nb3wGoKC/D3GfG4fih/YhP6ovutybbapg8AX+6qz+euycZj/eOxZw/PoLzZ07Lm4jq0h2Rnbui0lyBSrMZcb1uQZuQKzNov3j7dYy7pTMm39EXf71vKD54+XkAQGjHTvIynXra/hA6dnB/veVuW/0/PJ3cC0/f1gt/vW8onv/D7QAArU6HwA6h6HJLP3TtaxveXjR3Fm7p0Q1xcXEoLi6Gt7c3pk2bVv/zcZNMnjwZ7dq1Q35+Pjp27Iju3bsjMjISAQEBNYZ67X8E9ejRo94wGBAQgMDAwBq3Hj16YMGCBTckTNrrWr58OTQaDVatWoUJEyZACIHZs2dDrVZj27ZtCAoKQo8ePRASEoIOHTrg3XffrbaNSZMmAbjyR1FTDHdfr1deeQVqtRonT55EREQEYmJi5KH6J554AhEREU6rjVwTAyU1mUWLFsnneGVnZ+PDDz+sdkmLxoiKikJqairGjBmDgIAAZGRkAAAGDRokLzNnzhzccsstUKlU2LVrV7XLqVzt3//+N9566y106tQJp06dgtlsxuDBg7Fu3bpql6dpSh4eHti4cSOeeeYZBAYG4ujRo9Dr9XjkkUewfft2+QLGI0aMwLvvvovAwEAUFRWhV69emDNnToP2odVqsXHjRvz5z39G+/btcfToUeTn56NXr1547bXX0LZtW+zevRuzZ88GYAvUQUFBeOuttxAeHo6TJ0/KwbZr166YPn062rZti1OnTiElJUW+/FFdnnjiCTz//PNo1aoVioqKkJycLO+rqgceeABr1qzB7bffDrVajaNHj6Jt27Zyp02SJHzyySeIiopCYWEhUlNT5Y4WAHhq3Gp8S87V1BoN/vr+fxAR1wWlxUV49Y+PIOfEMfzfBwvxwDN/QVBoBM5nn4LxwgW0i4jG/ZOmoENMx2rbGPrwlQAwcOT91R7rd9cfEBnfFaXFRTiVkQ4vvS/6DRuBv7x95VI/t949EgCwa33t5/dJl//AiuuVhO79b4PVKnAq4wiEEOhyy614+eMv4eXjCwB48cNFuO/pP6NNSAccy8yAWq3GiBEjsG3btmrh35lat26NHTt2YPz48QgICMChQ4dgMpnQv3//GmHLfumtMWPG1LapBhk3bhy8ves/P9URgwcPxsKFCyFJEj7//HNMmTIFAwYMwKZNm3DXXXdBkiSkpaVBo9Fg1KhR8h+DdsOGDZM7lqGhoRg4cOANq/VakpOTsX79egwZMgQWiwVZWVmIjY3FG2+8gY8++shpdZHrkgRPxCAiBViXdfGGf5/30X27Me2h4fDw9MR/Nu2DrpHhpdJsxuQ7+uBibg7e+eE3hHbsBEtlJR7v3QllpSV4+pU3cceDj157Q1UYtBrcHtaqUes0NxcuXJCvxZqVlSV3o2+UsLAwuTPXunVrvPnmmxgwYMAN3afdnXfeiTVr1mD69Om1/nHV3L366qv48ccfkZaWhqKiIsycOZNfv0gNwkk5RNRs3XvvvcjNzQVgu7h5mcUqP/Z/8/8LvzZt61q1UbKPZeC7D99F2i7b+bpDRj/W6DAJ2LqkoyZOwb9n/g0rF36ExEFDseK/H6KstAQqNzfEJ/W99kaqkAD46zSNrqMqe0CozfTp03H33Xc7tP2GmD9/PsrLy/HCCy/c8DBZ1fHjx3H8+HHk5eXd8H299tpr2LRpE3755Rd4enpi8uTJ8mO5ubnVzietKigoqNZzpp3l2LFj1c5bJ2oodiiJqNmyd5pqs2BtSrVzHB1xMGUbZo69Hx6eXuiZPBiTX38HWg/dtVe8hiXz52HpgvfQJqQDHvzTVAwY3vgZvwmBvgjzvf6JHePGjcPixYtrfay5XKXAFSQnJ2Pz5s2IjIzEu+++Wy2oZ2Vl1TkRKTQ0FFlZWTepSqIbh4GSiBTBWGbGupMXnV3GTTcotBV8PRzrUhIR3WiclENEiuCjVeNak71djUoC9FqemUREzR8DJREpgkqSEKLXXXO2t6uQAITodQ26qDkRkbMxUBKRYkQYPNFSztERACL9nHNRbCKixmKgJCLF8Ne5w7eFDAH7atXw83B3dhlERA3CQElEihLl1/TfktIctZTjJCLXwEBJRIoSotdd+6sYFU6tsp0vSkSkFAyURKQobioJkS7evYv084Kbi4dmInItDJREpDix/t7wasD3eyuNBMBL44ZY/xv3fdVERDcCAyURKY6bSkKvIIPLzfgWABKDDOxOEpHiMFASkSIF6NwR7WJD39F+XvDXcWY3ESkPAyURKVZcK71LDH3bh7rjWumdXQoR0XVhoCQixXJTSUgMMji7jCbBoW4iUjIGSiJSNH+dO3oHG5xdhkN6Bxs41E1EisZASUSK106vQ0Kgr7PLuC4Jgb5ox2tOEpHCMVASkUsI8/VUXKhMCPRFmC+/r5uIlE8SQrjalTeIqAU7U2RCao4RAJrlZYXsZ0n2DjawM0lELoOBkohcTp6pAjtzjSgxW5xdSg1eGjckBvGcSSJyLQyUROSSLFaBtItFyMgvgQTndivt+4/280JcKz1ncxORy2GgJCKXdslUgV1O7layK0lEro6BkohcnsUqkJ5XjGP5Jai03ryPPLVKQqSfF2L9vdmVJCKXxkBJRC2GxSqQXWRCZn4JCsorm3wo3L49g1aNSD8vhOh1DJJE1CIwUBJRi5RnqsBxYymyi0ywNy0bGzCrLq+SgBC9DpF+nvDz4NA2EbUsDJRE1KJZhUBReSXyy80wlpmRZzKjsNwMaz3rqAD4aDXw12lg8NDAT6uBXquGSmI3kohaJgZKIqKrWIVAqdmCSquAVdhuKkmCSpKgVknw1LgxPBIRVcFASUREREQO4VcvEhEREZFDGCiJiIiIyCEMlERERETkEAZKIiIiInIIAyUREREROYSBkoiIiIgcwkBJRERERA5hoCQiIiIihzBQEhEREZFDGCiJiIiIyCEMlERERETkEAZKIiIiInIIAyUREREROYSBkoiIiIgcwkBJRERERA5hoCQiIiIihzBQEhEREZFDGCiJiIiIyCH/D9ry/LwfC4QeAAAAAElFTkSuQmCC", - "text/plain": [ - "<Figure size 640x480 with 1 Axes>" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "tracker.draw_graph()" - ] - }, - { - "cell_type": "markdown", - "id": "7482ce7f", - "metadata": {}, - "source": [ - "You can always get the orginal label back by setting label to `None`:" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "id": "8d4664a1", - "metadata": {}, - "outputs": [], - "source": [ - "count_lines.label = None" - ] - }, - { - "cell_type": "code", - "execution_count": 14, - "id": "1ac44e76", - "metadata": {}, - "outputs": [ - { - "data": { - "image/png": "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", - "text/plain": [ - "<Figure size 640x480 with 1 Axes>" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "tracker.draw_graph()" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "venv", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.12" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/notebooks/old_tutorials/05_orcabridge_dj_integration.ipynb b/notebooks/old_tutorials/05_orcabridge_dj_integration.ipynb deleted file mode 100644 index 4f038d7e6..000000000 --- a/notebooks/old_tutorials/05_orcabridge_dj_integration.ipynb +++ /dev/null @@ -1,916 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "8ba1a45b", - "metadata": {}, - "source": [ - "In previous notebooks, we have explored the core concepts behind `orcabridge` and how you can use that to define and execute computation pipeline, piecing together various operations (e.g., sources, mappers, and pods) via streams.\n", - "\n", - "In this notebook, we will explore how `orcabridge` can integrate with DataJoint, particularly by seeing how one could automatically generate a functional DataJoint table-based pipeline that can be used to query computation results from the original `orcabridge` pipeline and furthermore, how the auto-generated DJ pipeline can be used to trigger computations in the original pipeline. \n", - "\n", - "Key to all of this is `Tracker` that we explored in the [previous notebook](./04_orcabridge_tracker.ipynb) that allows us to track computational graph for a pipeline. Using a special version of tracker called `QueryTracker` that can convert the tracked computation into a DataJoint tables!" - ] - }, - { - "cell_type": "markdown", - "id": "5fdc7ea2", - "metadata": {}, - "source": [ - "## Defining the pipeline" - ] - }, - { - "cell_type": "markdown", - "id": "4247cdde", - "metadata": {}, - "source": [ - "As in previous notebooks, let's start by defining a concrete data pipeline in `orcabridge`." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "c1d0a0f4", - "metadata": {}, - "outputs": [], - "source": [ - "import json\n", - "import tempfile\n", - "from pathlib import Path\n", - "\n", - "import yaml\n", - "\n", - "from orcabridge.pod import function_pod\n", - "from orcabridge.source import GlobSource\n", - "from orcabridge.store import DirDataStore\n", - "\n", - "# define data source\n", - "data_source = GlobSource(\n", - " \"data_file\", \"../examples/dataset1\", \"*.txt\", label=\"LocalDataStore\"\n", - ")\n", - "\n", - "# use default data store location of `./pod_data`\n", - "data_store = DirDataStore()\n", - "\n", - "\n", - "# function to count lines in a file and save it as JSON\n", - "@function_pod([\"stats\"], data_store=data_store)\n", - "def count_lines(file: str):\n", - " with open(file, \"r\") as f:\n", - " n = len(f.readlines())\n", - " tmp_dir = tempfile.mkdtemp()\n", - " data_file = Path(tmp_dir) / \"data.json\"\n", - " data = dict(lines=n)\n", - " with open(data_file, \"w\") as f:\n", - " json.dump(data, f)\n", - " return data_file\n", - "\n", - "\n", - "@function_pod([\"yaml_file\"], data_store=data_store)\n", - "def json_to_yaml(json_file: str):\n", - " with open(json_file, \"r\") as f:\n", - " data = json.load(f)\n", - " tmp_dir = tempfile.mkdtemp()\n", - " yaml_path = Path(tmp_dir) / Path(json_file).with_suffix(\".yaml\").name\n", - " with open(yaml_path, \"w\") as f:\n", - " yaml.dump(data, f)\n", - " return yaml_path\n", - "\n", - "\n", - "# function to extract keys from a JSON file and save them as a list in another JSON file\n", - "@function_pod([\"key_info\"], data_store=data_store)\n", - "def extract_keys(json_file: str):\n", - " with open(json_file, \"r\") as f:\n", - " data = json.load(f)\n", - " keys = list(data.keys())\n", - " tmp_dir = tempfile.mkdtemp()\n", - " keys_file = Path(tmp_dir) / \"keys.json\"\n", - " with open(keys_file, \"w\") as f:\n", - " json.dump(keys, f)\n", - " return keys_file\n", - "\n", - "\n", - "import hashlib # noqa: E402\n", - "\n", - "\n", - "@function_pod([\"joint_hash\"], data_store=data_store)\n", - "def joint_hash(file_path1: str, file_path2: str):\n", - " \"\"\"\n", - " Hash the contents of two files, create a combined hash,\n", - " and save it to a JSON file in a new temporary directory.\n", - "\n", - " Args:\n", - " file_path1 (str): Path to the first file\n", - " file_path2 (str): Path to the second file\n", - "\n", - " Returns:\n", - " str: Path to the created JSON file\n", - " \"\"\"\n", - " # Hash the first file\n", - " with open(file_path1, \"rb\") as f:\n", - " file1_content = f.read()\n", - " file1_hash = hashlib.sha256(file1_content).hexdigest()\n", - "\n", - " # Hash the second file\n", - " with open(file_path2, \"rb\") as f:\n", - " file2_content = f.read()\n", - " file2_hash = hashlib.sha256(file2_content).hexdigest()\n", - "\n", - " # Combine the hashes and create a new hash (like in a Merkle tree)\n", - " combined_hash_input = file1_hash + file2_hash\n", - " combined_hash = hashlib.sha256(combined_hash_input.encode()).hexdigest()\n", - "\n", - " # Create a temporary directory\n", - " temp_dir = tempfile.mkdtemp()\n", - "\n", - " # Create the JSON file path\n", - " json_file_path = Path(temp_dir) / \"hash_data.json\"\n", - " # Create and save the JSON file\n", - " hash_data = {\n", - " \"joint_hash\": combined_hash, # corrected key from \"hash_dat\" to \"hash_data\"\n", - " \"file1_hash\": file1_hash,\n", - " \"file2_hash\": file2_hash,\n", - " }\n", - "\n", - " with open(json_file_path, \"w\") as f:\n", - " json.dump(hash_data, f, indent=4)\n", - "\n", - " return json_file_path" - ] - }, - { - "cell_type": "markdown", - "id": "af154cbe", - "metadata": {}, - "source": [ - "Before we chain them together into a pipeline, let's prepare the new tracker. Unlike regular `Tracker`, `QueryTracker` needs a few additional configuration in order for it to function." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "43c043cd", - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "[2025-05-05 03:18:41,126][INFO]: Connecting eywalker@at-database3.stanford.edu:3306\n", - "[2025-05-05 03:18:41,190][INFO]: Connected eywalker@at-database3.stanford.edu:3306\n" - ] - } - ], - "source": [ - "import datajoint as dj\n", - "\n", - "from orcabridge.dj.tracker import QueryTracker\n", - "\n", - "schema = dj.schema(\"enigma_orcabridge_test\")\n", - "\n", - "\n", - "tracker = QueryTracker()" - ] - }, - { - "cell_type": "markdown", - "id": "68c103c4", - "metadata": {}, - "source": [ - "Now let's build the pipeline while tracking under the `QueryTracker`" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "ec739d25", - "metadata": {}, - "outputs": [], - "source": [ - "with tracker:\n", - " line_info_json = count_lines(data_source >> {\"data_file\": \"file\"})\n", - " line_info_yaml = json_to_yaml(line_info_json >> {\"stats\": \"json_file\"})\n", - " line_info_keys = extract_keys(line_info_json >> {\"stats\": \"json_file\"})\n", - " joined_stream = line_info_yaml * line_info_keys\n", - " joined_hash_data = joint_hash(\n", - " joined_stream >> {\"yaml_file\": \"file_path1\", \"key_info\": \"file_path2\"}\n", - " )\n", - " final_files = count_lines(joined_hash_data >> {\"joint_hash\": \"file\"})" - ] - }, - { - "cell_type": "markdown", - "id": "ba094ac2", - "metadata": {}, - "source": [ - "Let's make sure that the tracked computation graph looks good:" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "807bb835", - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "/home/eywalker/workspace/orcabridge/src/orcabridge/tracker.py:87: UserWarning: This figure includes Axes that are not compatible with tight_layout, so results might be incorrect.\n", - " plt.tight_layout()\n" - ] - }, - { - "data": { - "image/png": "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K6WUmjhxogJUQECAPl9sbKwC1OjRo4vtT79+/RSgZs2apU+7ePGiXoNSSvn4+ChAfffdd/q0hJNJem0fbNyhlhxIUksOJKk3vl+vPv79L7XkQJJ6buFifZ55a+P0eZYcSFJzVm5Qi/Yc1/8//eOv9XlnfLJILTmQpOatjdOnPbdwsT7vgi17r7jt0h5unl7Kzt6hzIemaSqm963F6ir6KFrP8h9/Ukop1bx5cwWozz//XH9tkpKS1P79+5VSSk2fPl0BymAwqB07diillFq6dKm+no8//lgppdTo0aP1+cyv/aBBgxSgGjZsWJFDU33yySf6eou6/L0/evSoPt/69esrdRwppdSSJUsUoOrVq1ehuoQQliHXUAphBfr166e3+g0fPpyvvvqKvLw8Dh06RIcOHdi9ezdjxozh4MGDZGYW/w3opKQkQkJCiIuLA+COO+4gPDwcAIPBQKtWrUps75133gFM3Yw9evTQp5tbwn7++We9O9rs1KlTnD59mkaNGpW5H/3792flypVMmzaNDz74gIiICDp37sz48eP1eS5dugSg7y+Ap7c3zVq34+DuHTx8cxd8mwTROKwZ7br3omu/QVd49Uythe9Nf5LjB/eTk5WJKnKz8ORzf5e7rJtX1ba9YGt8uev99NUXWP7RPI4f3E9I85blzmuut3///uzdu5fRo0czY8YMIiIiiI2N1V+/P/74A4BmzZrRtm1bAAYOHIizszNZWVls376dsWPH6utt0aKF/v5HRUWxdOlS/v67/NejOlTmODIPSDIfF0KI2kkCpRBW7rfffmP06NEopfDx8SEqKoqMjAz2798PQGFhYaXX6erqSkZGBrNnz6Z37944OTkVe75Ro0YEBASUWK6goPybcN9///1ERESwYsUK9uzZw44dO/jpp5/49ttv2bt3L2AKEMnJyWRkZOjLGTSNGQu+YdPKpRzc+QcnDyew9acf+H3VclLO/83Aex4qc5tnTx7nlQnjKMjPw8nFleDolhgLCzi63xT4jBV4faqy7VFtQ8nJKv+nEzvf2p+gIl3tZdE00w2TXnzxRbp06cKaNWvYu3cvv/76Kz/88AMbNmzghx9+uOJ6Lufp6an/29a25r8OKnIcpaWlAdTKke5CiH/JNZRCWIEffvhBD1jffPMNAPb29oSHhxMXF6e3YO3Zs4dt27Zx9913l1hHTIxp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dna0adOmXPsqrJsElLepkSNHMnDgQL2P1LBhw5gyZQoAHTt25I033tD72IWHhzNjxowiadx1112sX7+erl274uLiwt69e3FxcdFr+K7VoUMHPv30UzRN4/PPP+e5556jXbt2/PLLLzzwwANomsbu3bsxGAz06tWL0aNH69uOHj2aDh064OTkxLZt2/TgsHPnzrRt25bs7GySkpJwcHCga9euLF++XA8M+/XrB8CPP/5YpAnd09OTvn376v8vWBvj7u7O/PnziYyMJD8/H3t7e7777ruKHO5bwpIlSxg3bhyhoaEcOnSIkydPEhERwb/+9S+9xqM8NE1j6NChNyyYtJgxYwZvv/02AWERpJ0+xdnUY3j51aProGE0an1XudJ69eO52NsbybuaR/3QcF6ZMQfPuj4APPN/79Io+m4MRiM52dk8/sprBIRFFEmj2+CnaHJXW+wdHDm8eycHd+4o9z6dPHqEk0ePkHPFXIuWm3NFX5aXa75GMy+a+5/VDw3HyVD22t+PP/6YBx54gNzcXHr37s369euZMWMG77zzDo0bNyY1NZWUlBQCAwMZNWpUkSfsPP300/rfjz76aIVqs6rKf//7X958800iIiI4evQoubm5dOjQgdWrV1f4yUC9e/cutYtHVejfvz/Lli0jJiaG7Oxs9u7di8lk4rHHHmPIkCHlSuvjjz+mUaNGZGZm4uvry3vvvaf/sB0zZgzx8fG4ublx8eJFHnnkkULnz6JLly48+eSTeHp6sn//fhISErh0qew17AWnlMvIyCAhIaHQq+D7lq5DDz74YKHab1Hzaaq6O3SJmyowMJCUlBTGjx9f5sf91QRt2rQhISGBpUuX6oNkLCzN+W3btuWXX36pphKK61l95GyFnue9etHXfDDmeQAWJpdvoEJ1Gt3zfo7s2cV7C77n2Z4P3LR8T548iY+PD5qmsX//fkJCQm5a3sKs4DyPa9asqfbHapZHixYt2LZtGz/++KPeKiJuD9KHUtwWJk6cSFxcHFOnTtUDykWLFjFv3jx++OEHAF588cXqLCLff/89kyZNKva9zp076xMt3648HA1cuFL08Yur5n/BqgXFj9bt0LsfNrbWd5vLyrhISvJuOvYdSNu7y1cLW1Fnz55l5MiReu1/jx49CgWTM2fOZObMmcVuO2TIkHLXvN3Otm7dWmxNIpgDspL6J97q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", - "text/plain": [ - "<Figure size 640x480 with 1 Axes>" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "tracker.draw_graph()" - ] - }, - { - "cell_type": "markdown", - "id": "5234eb0d", - "metadata": {}, - "source": [ - "Now comes the magical part -- generating the DataJoint tables from this graph." - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "390b4e30", - "metadata": {}, - "outputs": [], - "source": [ - "G, module = tracker.generate_tables(schema)" - ] - }, - { - "cell_type": "markdown", - "id": "429e3b96", - "metadata": {}, - "source": [ - "Believe it or not, that was all that was needed to generate a full-fledged DataJoint pipeline that corresponds to our tracked `orcabridge` pipeline. The returned `module` object actually contains all the tables in the pipeline." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "79aa67f4", - "metadata": {}, - "outputs": [ - { - "data": { - "image/svg+xml": [ - "<svg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" width=\"294pt\" height=\"291pt\" viewBox=\"0.00 0.00 293.50 291.00\">\n", - "<g id=\"graph0\" class=\"graph\" transform=\"scale(1 1) rotate(0) translate(4 287)\">\n", - "<title>%3\n", - "\n", - "\n", - "\n", - "module.CountLinesId1\n", - "\n", - "\n", - "module.CountLinesId1\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "module.CountLinesId0\n", - "\n", - "\n", - "module.CountLinesId0\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "module.ExtractKeys\n", - "\n", - "\n", - "module.ExtractKeys\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "module.CountLinesId0->module.ExtractKeys\n", - "\n", - "\n", - "\n", - "\n", - "module.JsonToYaml\n", - "\n", - "\n", - "module.JsonToYaml\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "module.CountLinesId0->module.JsonToYaml\n", - "\n", - "\n", - "\n", - "\n", - "module.JointHash\n", - "\n", - "\n", - "module.JointHash\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "module.ExtractKeys->module.JointHash\n", - "\n", - "\n", - "\n", - "\n", - "module.JointHash->module.CountLinesId1\n", - "\n", - "\n", - "\n", - "\n", - "module.JsonToYaml->module.JointHash\n", - "\n", - "\n", - "\n", - "\n", - "module.LocalDataStore\n", - "\n", - "\n", - "module.LocalDataStore\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "module.LocalDataStore->module.CountLinesId0\n", - "\n", - "\n", - "\n", - "" - ], - "text/plain": [ - "" - ] - }, - "execution_count": 6, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "dj.Diagram(module)" - ] - }, - { - "cell_type": "markdown", - "id": "f98413cc", - "metadata": {}, - "source": [ - "You can see that the struture of the tables naturally correspond to our `orcabridge` pipeline from the above, but with some minor differences. Namely, all nodes corresponding to `Mappers` such as `MapData` and `Join` are missing. This is because in DataJoint, these operations are handled as defining characteristic of the connections between tables and don't really explicitly show up in the graph." - ] - }, - { - "cell_type": "markdown", - "id": "12111161", - "metadata": {}, - "source": [ - "Let's now take a look at some of these tables!" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "cb86320e", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "\n", - " \n", - " \n", - " \n", - " glob_source_7805336534710128524 outputs\n", - "
\n", - " \n", - " \n", - " \n", - "
\n", - "

file_name

\n", - " \n", - "
\n", - "

data_file

\n", - " \n", - "
\n", - " \n", - "

Total: 0

\n", - " " - ], - "text/plain": [ - "*file_name data_file \n", - "+-----------+ +-----------+\n", - "\n", - " (Total: 0)" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "module.LocalDataStore()" - ] - }, - { - "cell_type": "markdown", - "id": "6d545e32", - "metadata": {}, - "source": [ - "You might be wondering where is the data? If you were to look at the `data_source` that corresponds to our `LocalDataStore` table, there are certainly a few files present." - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "8be3fba1", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Tag: {'file_name': 'day1'}, Data: {'data_file': PosixPath('../examples/dataset1/day1.txt')}\n", - "Tag: {'file_name': 'day2'}, Data: {'data_file': PosixPath('../examples/dataset1/day2.txt')}\n", - "Tag: {'file_name': 'day3'}, Data: {'data_file': PosixPath('../examples/dataset1/day3.txt')}\n", - "Tag: {'file_name': 'day4'}, Data: {'data_file': PosixPath('../examples/dataset1/day4.txt')}\n", - "Tag: {'file_name': 'day6'}, Data: {'data_file': PosixPath('../examples/dataset1/day6.txt')}\n" - ] - } - ], - "source": [ - "data_source.head(10)" - ] - }, - { - "cell_type": "markdown", - "id": "1bf44a4b", - "metadata": {}, - "source": [ - "Don't panic just yet! By default, DataJoint tables created to reflect `orcabridge` pipeline do *not* come prefilled with the results of the pipeline execution. Instead, you want to trigger the filling by calling `populate` on the table. Let's try filling the `LocalDataStore` table:" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "c61038f4", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "5" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "module.LocalDataStore().populate()" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "id": "c7d3916d", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "\n", - " \n", - " \n", - " \n", - " glob_source_7805336534710128524 outputs\n", - "
\n", - " \n", - " \n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "
\n", - "

file_name

\n", - " \n", - "
\n", - "

data_file

\n", - " \n", - "
day1../examples/dataset1/day1.txt
day2../examples/dataset1/day2.txt
day3../examples/dataset1/day3.txt
day4../examples/dataset1/day4.txt
day6../examples/dataset1/day6.txt
\n", - " \n", - "

Total: 5

\n", - " " - ], - "text/plain": [ - "*file_name data_file \n", - "+-----------+ +------------+\n", - "day1 ../examples/da\n", - "day2 ../examples/da\n", - "day3 ../examples/da\n", - "day4 ../examples/da\n", - "day6 ../examples/da\n", - " (Total: 5)" - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "module.LocalDataStore()" - ] - }, - { - "cell_type": "markdown", - "id": "4a7b2123", - "metadata": {}, - "source": [ - "Now you can see that the table was successfully filled with the files from the local glob-based data source (corresponding to `data_source`)." - ] - }, - { - "cell_type": "markdown", - "id": "ac383388", - "metadata": {}, - "source": [ - "You can in fact trigger the computation in the downstream tables by calling `populate` on them! Let's go ahead and call `populate` on all tables, following the topographical order to ensure parent tables are populated before moving onto child tables." - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "id": "db04f85a", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'success_count': 5, 'error_list': []}" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "module.LocalDataStore().populate()\n", - "module.CountLinesId0().populate()\n", - "module.ExtractKeys().populate()\n", - "module.JsonToYaml().populate()\n", - "module.JointHash().populate()\n", - "module.CountLinesId1().populate()" - ] - }, - { - "cell_type": "markdown", - "id": "c17001a8", - "metadata": {}, - "source": [ - "Now all tables are filled, having processed available contents. You might be happy to know that the underlying computation for each table is *memoized* and in fact shared with the `FunctionPod` based on which the table was created. Consequently, *populating* the tables actually have led to our original pipeline achieving memoization of all computations performed as part of the `populate` calls!" - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "id": "49f1a620", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "\n", - " \n", - " \n", - " \n", - " json_to_yaml_14249291253996769187 outputs\n", - "
\n", - " \n", - " \n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "
\n", - "

file_name

\n", - " \n", - "
\n", - "

yaml_file

\n", - " \n", - "
day1pod_data/json_to_yaml/0a2282eda2b641e6/6d0b282e-6970-a099-c1d7-632a66200b85/data.yaml
day2pod_data/json_to_yaml/0a2282eda2b641e6/4ff1d406-4431-1849-9c36-266e39f1bbfd/data.yaml
day3pod_data/json_to_yaml/0a2282eda2b641e6/d58c568b-7f44-f259-a195-94038e348017/data.yaml
day4pod_data/json_to_yaml/0a2282eda2b641e6/14e16c5b-c470-66bc-b92a-7f1c09d091df/data.yaml
day6pod_data/json_to_yaml/0a2282eda2b641e6/998c26f1-fc82-5d90-e25d-25f61f073189/data.yaml
\n", - " \n", - "

Total: 5

\n", - " " - ], - "text/plain": [ - "*file_name yaml_file \n", - "+-----------+ +------------+\n", - "day1 pod_data/json_\n", - "day2 pod_data/json_\n", - "day3 pod_data/json_\n", - "day4 pod_data/json_\n", - "day6 pod_data/json_\n", - " (Total: 5)" - ] - }, - "execution_count": 12, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "module.JsonToYaml()" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "id": "6783b463", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "\n", - " \n", - " \n", - " \n", - " count_lines_12479767188212706286 outputs\n", - "
\n", - " \n", - " \n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "
\n", - "

file_name

\n", - " \n", - "
\n", - "

stats

\n", - " \n", - "
day1pod_data/count_lines/48028707c9dc37d7/8cd40c14-2c09-8a84-14e5-6c0b45f92cf7/data.json
day2pod_data/count_lines/48028707c9dc37d7/1d1430e5-cc85-7005-b8ce-603963a825df/data.json
day3pod_data/count_lines/48028707c9dc37d7/eda0b080-5b97-d917-1d53-ab4704e9e279/data.json
day4pod_data/count_lines/48028707c9dc37d7/8df403a2-522c-208e-ecd8-53d146963c9f/data.json
day6pod_data/count_lines/48028707c9dc37d7/79b8c697-920f-08eb-cfc6-499e810ab9d1/data.json
\n", - " \n", - "

Total: 5

\n", - " " - ], - "text/plain": [ - "*file_name stats \n", - "+-----------+ +------------+\n", - "day1 pod_data/count\n", - "day2 pod_data/count\n", - "day3 pod_data/count\n", - "day4 pod_data/count\n", - "day6 pod_data/count\n", - " (Total: 5)" - ] - }, - "execution_count": 13, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "module.CountLinesId1()" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "venv", - "language": "python", - "name": "python3" - }, - "language_info": { - "name": "python", - "version": "3.10.12" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/notebooks/tutorials/README.md b/notebooks/tutorials/README.md deleted file mode 100644 index 3e5dd47a7..000000000 --- a/notebooks/tutorials/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Tutorials - -The Orcapod tutorial now lives in the documentation, where every sample is run by the test -suite: [`docs/tutorial/`](../../docs/tutorial/index.md). - -It is a self-paced course in eleven short parts on one small synthetic dataset. To generate -the dataset: - -```bash -uv run python docs/tutorial/workshop_data.py -``` - -The notebooks that used to be in this directory were written against an earlier API and no -longer ran; they are in the git history if you need them. `notebooks/old_tutorials/` is kept -for reference only and is not maintained. diff --git a/plan.md b/plan.md deleted file mode 100644 index d2a42082b..000000000 --- a/plan.md +++ /dev/null @@ -1,830 +0,0 @@ -# Plan: Unified `process_data` / `async_process_data` + Node `async_execute` - -## Goal - -Establish `process_data` and `async_process_data` as **the** universal per-data -interface across FunctionPod, FunctionPodStream, FunctionNode, and PersistentFunctionNode. -All iteration paths — sequential, concurrent, and async — route through these methods. -Add `async_execute` to all four Node classes. Add cache-aware `async_call` to -`CachedDataFunction`. Remove `_execute_concurrent` module-level helper. - ---- - -## What exists today - -### Class hierarchy - -``` -_FunctionPodBase (TraceableBase) - ├── process_data(tag, data) → calls data_function.call(data) - ├── FunctionPod - │ ├── process() → FunctionPodStream - │ └── async_execute() → calls data_function.async_call(data) DIRECTLY - │ - FunctionPodStream (StreamBase) - │ ├── _iter_data_sequential() → calls _function_pod.process_data(tag, data) ✓ - │ └── _iter_data_concurrent() → calls _execute_concurrent(data_function, ...) DIRECTLY - │ - FunctionNode (StreamBase) - │ ├── _iter_data_sequential() → calls _data_function.call(data) DIRECTLY - │ ├── _iter_data_concurrent() → calls _execute_concurrent(_data_function, ...) DIRECTLY - │ └── (no async_execute) - │ - PersistentFunctionNode (FunctionNode) - ├── process_data(tag, data) → calls _data_function.call(data, skip_cache_*=...) - │ then add_pipeline_record(...) - ├── iter_data() → Phase 1: replay from DB - │ Phase 2: calls self.process_data(tag, data) ✓ - └── (no async_execute) - -OperatorNode (StreamBase) - ├── run() → calls _operator.process(*streams) - └── (no async_execute) - -PersistentOperatorNode (OperatorNode) - ├── _compute_and_store() → calls _operator.process() + bulk DB write - ├── _replay_from_cache() → loads from DB - └── (no async_execute) -``` - -### Module-level helpers - -```python -def _executor_supports_concurrent(data_function) -> bool: - """True if the pf's executor supports concurrent execution.""" - -def _execute_concurrent(data_function, data) -> list[DataProtocol | None]: - """Submit all data concurrently via asyncio.gather(pf.async_call(...)). - Falls back to sequential pf.call() if already inside a running event loop.""" -``` - -### Problems - -1. **FunctionPod.async_execute** bypasses `process_data` — calls `data_function.async_call` - directly (line 317). -2. **FunctionPodStream._iter_data_concurrent** bypasses `process_data` — calls - `_execute_concurrent(data_function, ...)` directly (line 472). -3. **FunctionNode._iter_data_sequential** bypasses any process_data — calls - `_data_function.call(data)` directly (line 831). -4. **FunctionNode._iter_data_concurrent** same — calls `_execute_concurrent` directly - (line 852). -5. **CachedDataFunction.async_call** inherits from `DataFunctionWrapper` — completely - **bypasses the cache** (no lookup, no recording). -6. **No `async_process_data`** exists anywhere. -7. **No `async_execute`** on any Node class. -8. **`_execute_concurrent`** is a module-level function that takes a raw `data_function` - and list of bare `data` — no way to route through `process_data`. - ---- - -## Design principles - -### A. `process_data` / `async_process_data` is the single per-data entry point - -Every class in the function pod hierarchy defines these two methods. **All** iteration and -execution paths go through them — sequential, concurrent, and async. No direct -`data_function.call()` or `data_function.async_call()` calls outside of these methods. - -``` -_FunctionPodBase.process_data(tag, pkt) → data_function.call(pkt) -_FunctionPodBase.async_process_data(tag, pkt) → await data_function.async_call(pkt) - -FunctionNode.process_data(tag, pkt) → self._function_pod.process_data(tag, pkt) -FunctionNode.async_process_data(tag, pkt) → await self._function_pod.async_process_data(tag, pkt) - -PersistentFunctionNode.process_data(tag, pkt) → cache check → self._function_pod.process_data → pipeline record -PersistentFunctionNode.async_process_data(tag, pkt) → cache check → await self._function_pod.async_process_data → pipeline record -``` - -Wait — there's a subtlety with PersistentFunctionNode. Today its `process_data` calls -`self._data_function.call(data, skip_cache_lookup=..., skip_cache_insert=...)` directly, -where `self._data_function` is a `CachedDataFunction` (which wraps the original pf). -It does NOT delegate to the pod's `process_data`. That's because PersistentFunctionNode -needs to pass `skip_cache_*` kwargs that the base `process_data` doesn't accept. - -The cleanest structure: - -``` -PersistentFunctionNode.process_data(tag, pkt) - → self._data_function.call(pkt, skip_cache_*=...) # CachedDataFunction (sync) - → self.add_pipeline_record(...) # pipeline DB (sync) - -PersistentFunctionNode.async_process_data(tag, pkt) - → await self._data_function.async_call(pkt, skip_cache_*=...) # CachedDataFunction (async) - → self.add_pipeline_record(...) # pipeline DB (sync) -``` - -This is the same as today for the sync path. The `CachedDataFunction` handles the result -cache internally. The `PersistentFunctionNode` handles pipeline records. Neither delegates -to the pod's `process_data` — the pod is bypassed because the `CachedDataFunction` -replaced the raw data function in `__init__`. - -### B. Concurrent iteration routes through `async_process_data` - -The concurrent path is inherently async — it uses `asyncio.gather`. So it naturally routes -through `async_process_data`. The fallback path (when already inside an event loop) routes -through `process_data` (sync). - -For **FunctionPodStream**, the target is the pod: -```python -# concurrent -await self._function_pod.async_process_data(tag, pkt) -# fallback -self._function_pod.process_data(tag, pkt) -``` - -For **FunctionNode**, the target is `self` — so overrides (PersistentFunctionNode) kick in: -```python -# concurrent -await self.async_process_data(tag, pkt) -# fallback -self.process_data(tag, pkt) -``` - -This means PersistentFunctionNode's concurrent path **automatically** gets cache checks + -pipeline records via polymorphism. No special handling needed. - -### C. `_execute_concurrent` is removed - -The module-level `_execute_concurrent(data_function, data)` helper is removed. Its -logic (asyncio.gather with event-loop fallback) is inlined into `_iter_data_concurrent` -methods, but now routes through `process_data` / `async_process_data` instead of raw -`data_function.call` / `data_function.async_call`. - -The `_executor_supports_concurrent` helper stays — it's just a predicate check. - -### D. Sync and async are cleanly separated execution modes - -- Sync: `iter_data()` / `as_table()` / `run()` -- Async: `async_execute(inputs, output)` - -They don't populate each other's caches. DB persistence (for Persistent variants) provides -durability that works across both modes. - -### E. OperatorNode delegates to operator, PersistentOperatorNode intercepts for storage - -Operators are opaque stream transformers — no per-data hook. `OperatorNode` passes through -directly. `PersistentOperatorNode` uses an intermediate channel + `TaskGroup` to forward -results downstream immediately while collecting them for post-hoc DB storage. - -### F. DB operations stay synchronous - -The `ArrowDatabaseProtocol` is sync. All DB reads/writes within async methods are sync calls. -Acceptable because DB is typically in-process and fast. Async DB protocol is deferred. - ---- - -## Implementation steps - -### Step 1: Add `async_process_data` to `_FunctionPodBase` - -**File:** `src/orcapod/core/function_pod.py` - -Add alongside existing `process_data` (after line 180): - -```python -async def async_process_data( - self, tag: TagProtocol, data: DataProtocol -) -> tuple[TagProtocol, DataProtocol | None]: - """Async counterpart of ``process_data``.""" - return tag, await self.data_function.async_call(data) -``` - -### Step 2: Fix `FunctionPod.async_execute` to use `async_process_data` - -**File:** `src/orcapod/core/function_pod.py` - -Change the `process_one` inner function (lines 315-322): - -```python -async def process_one(tag: TagProtocol, data: DataProtocol) -> None: - try: - tag, result_data = await self.async_process_data(tag, data) - if result_data is not None: - await output.send((tag, result_data)) - finally: - if sem is not None: - sem.release() -``` - -### Step 3: Fix `FunctionPodStream._iter_data_concurrent` to use `async_process_data` - -**File:** `src/orcapod/core/function_pod.py` - -Replace the `_execute_concurrent` call (lines 454-482) with direct `async_process_data` -routing: - -```python -def _iter_data_concurrent( - self, -) -> Iterator[tuple[TagProtocol, DataProtocol]]: - """Collect remaining inputs, execute concurrently, and yield results in order.""" - input_iter = self._cached_input_iterator - - all_inputs: list[tuple[int, TagProtocol, DataProtocol]] = [] - to_compute: list[tuple[int, TagProtocol, DataProtocol]] = [] - for i, (tag, data) in enumerate(input_iter): - all_inputs.append((i, tag, data)) - if i not in self._cached_output_datas: - to_compute.append((i, tag, data)) - self._cached_input_iterator = None - - if to_compute: - try: - loop = asyncio.get_running_loop() - except RuntimeError: - loop = None - - if loop is not None: - # Already in event loop — fall back to sequential sync - results = [ - self._function_pod.process_data(tag, pkt) - for _, tag, pkt in to_compute - ] - else: - # No event loop — run concurrently via asyncio.run - async def _gather() -> list[tuple[TagProtocol, DataProtocol | None]]: - return list( - await asyncio.gather( - *[ - self._function_pod.async_process_data(tag, pkt) - for _, tag, pkt in to_compute - ] - ) - ) - - results = asyncio.run(_gather()) - - for (i, _, _), (tag, output_data) in zip(to_compute, results): - self._cached_output_datas[i] = (tag, output_data) - - for i, *_ in all_inputs: - tag, data = self._cached_output_datas[i] - if data is not None: - yield tag, data -``` - -**Note:** The method signature drops the `data_function` parameter — it no longer needs -it since it routes through `self._function_pod`. - -The `iter_data` method that calls this also needs updating — remove the `pf` argument: - -```python -def iter_data(self) -> Iterator[tuple[TagProtocol, DataProtocol]]: - if self.is_stale: - self.clear_cache() - if self._cached_input_iterator is not None: - if _executor_supports_concurrent(self._function_pod.data_function): - yield from self._iter_data_concurrent() - else: - yield from self._iter_data_sequential() - else: - for i in range(len(self._cached_output_datas)): - tag, data = self._cached_output_datas[i] - if data is not None: - yield tag, data -``` - -### Step 4: Fix `FunctionNode._iter_data_sequential` to use `process_data` - -**File:** `src/orcapod/core/function_pod.py` - -Change line 831 from: -```python -output_data = self._data_function.call(data) -self._cached_output_datas[i] = (tag, output_data) -``` -to: -```python -tag, output_data = self.process_data(tag, data) -self._cached_output_datas[i] = (tag, output_data) -``` - -### Step 5: Fix `FunctionNode._iter_data_concurrent` to use `async_process_data` - -**File:** `src/orcapod/core/function_pod.py` - -Same transformation as Step 3, but routing through `self` instead of `self._function_pod`: - -```python -def _iter_data_concurrent( - self, -) -> Iterator[tuple[TagProtocol, DataProtocol]]: - """Collect remaining inputs, execute concurrently, and yield results in order.""" - input_iter = self._cached_input_iterator - - all_inputs: list[tuple[int, TagProtocol, DataProtocol]] = [] - to_compute: list[tuple[int, TagProtocol, DataProtocol]] = [] - for i, (tag, data) in enumerate(input_iter): - all_inputs.append((i, tag, data)) - if i not in self._cached_output_datas: - to_compute.append((i, tag, data)) - self._cached_input_iterator = None - - if to_compute: - try: - loop = asyncio.get_running_loop() - except RuntimeError: - loop = None - - if loop is not None: - # Already in event loop — fall back to sequential sync - results = [ - self.process_data(tag, pkt) - for _, tag, pkt in to_compute - ] - else: - # No event loop — run concurrently via asyncio.run - async def _gather() -> list[tuple[TagProtocol, DataProtocol | None]]: - return list( - await asyncio.gather( - *[ - self.async_process_data(tag, pkt) - for _, tag, pkt in to_compute - ] - ) - ) - - results = asyncio.run(_gather()) - - for (i, _, _), (tag, output_data) in zip(to_compute, results): - self._cached_output_datas[i] = (tag, output_data) - - for i, *_ in all_inputs: - tag, data = self._cached_output_datas[i] - if data is not None: - yield tag, data -``` - -**Critical difference from Step 3:** Uses `self.process_data` / `self.async_process_data` -instead of `self._function_pod.*`. This means when `PersistentFunctionNode` inherits this -method, it automatically routes through its overridden `process_data` / -`async_process_data` which include cache checks + pipeline record storage. - -### Step 6: Remove `_execute_concurrent` - -**File:** `src/orcapod/core/function_pod.py` - -Delete the `_execute_concurrent` function (lines 52-82). Its logic is now inlined into the -`_iter_data_concurrent` methods. - -### Step 7: Add `process_data` and `async_process_data` to `FunctionNode` - -**File:** `src/orcapod/core/function_pod.py` - -FunctionNode currently has no `process_data`. Add delegation to the function pod: - -```python -def process_data( - self, tag: TagProtocol, data: DataProtocol -) -> tuple[TagProtocol, DataProtocol | None]: - """Process a single data by delegating to the function pod.""" - return self._function_pod.process_data(tag, data) - -async def async_process_data( - self, tag: TagProtocol, data: DataProtocol -) -> tuple[TagProtocol, DataProtocol | None]: - """Async counterpart of ``process_data``.""" - return await self._function_pod.async_process_data(tag, data) -``` - -### Step 8: Add `FunctionNode.async_execute` - -**File:** `src/orcapod/core/function_pod.py` - -Sequential streaming through `async_process_data`: - -```python -async def async_execute( - self, - inputs: Sequence[ReadableChannel[tuple[TagProtocol, DataProtocol]]], - output: WritableChannel[tuple[TagProtocol, DataProtocol]], -) -> None: - """Streaming async execution — process each data via async_process_data.""" - try: - async for tag, data in inputs[0]: - tag, result_data = await self.async_process_data(tag, data) - if result_data is not None: - await output.send((tag, result_data)) - finally: - await output.close() -``` - -### Step 9: Add async cache-aware `async_call` to `CachedDataFunction` - -**File:** `src/orcapod/core/data_function.py` - -Override `async_call` to mirror the sync `call()` logic (lines 508-533): - -```python -async def async_call( - self, - data: DataProtocol, - *, - skip_cache_lookup: bool = False, - skip_cache_insert: bool = False, -) -> DataProtocol | None: - """Async counterpart of ``call`` with cache check and recording.""" - output_data = None - if not skip_cache_lookup: - logger.info("Checking for cache...") - output_data = self.get_cached_output_for_data(data) - if output_data is not None: - logger.info(f"Cache hit for {data}!") - if output_data is None: - output_data = await self._data_function.async_call(data) - if output_data is not None: - if not skip_cache_insert: - self.record_data(data, output_data) - output_data = output_data.with_meta_columns( - **{self.RESULT_COMPUTED_FLAG: True} - ) - return output_data -``` - -### Step 10: Add `async_process_data` to `PersistentFunctionNode` - -**File:** `src/orcapod/core/function_pod.py` - -PersistentFunctionNode already has `process_data` (line 1027-1066) which calls -`self._data_function.call(data, skip_cache_*=...)` (where `_data_function` is a -`CachedDataFunction`) then `self.add_pipeline_record(...)`. Add the async counterpart: - -```python -async def async_process_data( - self, - tag: TagProtocol, - data: DataProtocol, - skip_cache_lookup: bool = False, - skip_cache_insert: bool = False, -) -> tuple[TagProtocol, DataProtocol | None]: - """Async counterpart of ``process_data``. - - Uses the CachedDataFunction's async_call for computation + result caching. - Pipeline record storage is synchronous (DB protocol is sync). - """ - output_data = await self._data_function.async_call( - data, - skip_cache_lookup=skip_cache_lookup, - skip_cache_insert=skip_cache_insert, - ) - - if output_data is not None: - result_computed = bool( - output_data.get_meta_value( - self._data_function.RESULT_COMPUTED_FLAG, False - ) - ) - self.add_pipeline_record( - tag, - data, - data_record_id=output_data.datagram_id, - computed=result_computed, - ) - - return tag, output_data -``` - -### Step 11: Add `PersistentFunctionNode.async_execute` (two-phase) - -**File:** `src/orcapod/core/function_pod.py` - -Overrides `FunctionNode.async_execute`: - -```python -async def async_execute( - self, - inputs: Sequence[ReadableChannel[tuple[TagProtocol, DataProtocol]]], - output: WritableChannel[tuple[TagProtocol, DataProtocol]], -) -> None: - """Two-phase async execution: replay cached, then compute missing.""" - try: - # Phase 1: emit existing results from DB - existing = self.get_all_records(columns={"meta": True}) - computed_hashes: set[str] = set() - if existing is not None and existing.num_rows > 0: - tag_keys = self._input_stream.keys()[0] - hash_col = constants.INPUT_DATA_HASH_COL - computed_hashes = set( - cast(list[str], existing.column(hash_col).to_pylist()) - ) - data_table = existing.drop([hash_col]) - existing_stream = ArrowTableStream(data_table, tag_columns=tag_keys) - for tag, data in existing_stream.iter_data(): - await output.send((tag, data)) - - # Phase 2: process data not already in the DB - async for tag, data in inputs[0]: - input_hash = data.content_hash().to_string() - if input_hash in computed_hashes: - continue - tag, output_data = await self.async_process_data(tag, data) - if output_data is not None: - await output.send((tag, output_data)) - finally: - await output.close() -``` - -### Step 12: Add `OperatorNode.async_execute` - -**File:** `src/orcapod/core/operator_node.py` - -Direct pass-through: - -```python -async def async_execute( - self, - inputs: Sequence[ReadableChannel[tuple[TagProtocol, DataProtocol]]], - output: WritableChannel[tuple[TagProtocol, DataProtocol]], -) -> None: - """Delegate to operator's async_execute.""" - await self._operator.async_execute(inputs, output) -``` - -### Step 13: Extract `_store_output_stream` from `PersistentOperatorNode._compute_and_store` - -**File:** `src/orcapod/core/operator_node.py` - -```python -def _store_output_stream(self, stream: StreamProtocol) -> None: - """Materialize stream and store in the pipeline database with per-row dedup.""" - output_table = stream.as_table( - columns={"source": True, "system_tags": True}, - ) - - arrow_hasher = self.data_context.arrow_hasher - record_hashes = [] - for batch in output_table.to_batches(): - for i in range(len(batch)): - record_hashes.append( - arrow_hasher.hash_table(batch.slice(i, 1)).to_hex() - ) - - output_table = output_table.add_column( - 0, - self.HASH_COLUMN_NAME, - pa.array(record_hashes, type=pa.large_string()), - ) - - self._pipeline_database.add_records( - self.pipeline_path, - output_table, - record_id_column=self.HASH_COLUMN_NAME, - skip_duplicates=True, - ) - - self._cached_output_table = output_table.drop(self.HASH_COLUMN_NAME) -``` - -Refactor `_compute_and_store`: - -```python -def _compute_and_store(self) -> None: - self._cached_output_stream = self._operator.process(*self._input_streams) - if self._cache_mode == CacheMode.OFF: - self._update_modified_time() - return - self._store_output_stream(self._cached_output_stream) - self._update_modified_time() -``` - -### Step 14: Add `PersistentOperatorNode.async_execute` - -**File:** `src/orcapod/core/operator_node.py` - -```python -async def async_execute( - self, - inputs: Sequence[ReadableChannel[tuple[TagProtocol, DataProtocol]]], - output: WritableChannel[tuple[TagProtocol, DataProtocol]], -) -> None: - """Async execution with cache mode handling. - - REPLAY: emit from DB, close output. - OFF: delegate to operator, forward results. - LOG: delegate to operator, forward + collect results, then store in DB. - """ - try: - if self._cache_mode == CacheMode.REPLAY: - self._replay_from_cache() - assert self._cached_output_stream is not None - for tag, data in self._cached_output_stream.iter_data(): - await output.send((tag, data)) - return # finally block closes output - - # OFF or LOG: delegate to operator, forward results downstream - intermediate = Channel[tuple[TagProtocol, DataProtocol]]() - collected: list[tuple[TagProtocol, DataProtocol]] = [] - - async def forward() -> None: - async for item in intermediate.reader: - collected.append(item) - await output.send(item) - - async with asyncio.TaskGroup() as tg: - tg.create_task( - self._operator.async_execute(inputs, intermediate.writer) - ) - tg.create_task(forward()) - - # TaskGroup has completed — all results are in `collected` - # Store if LOG mode (sync DB write, post-hoc) - if self._cache_mode == CacheMode.LOG and collected: - stream = StaticOutputPod._materialize_to_stream(collected) - self._cached_output_stream = stream - self._store_output_stream(stream) - - self._update_modified_time() - finally: - await output.close() -``` - -### Step 15: Add imports - -**`src/orcapod/core/operator_node.py`** — add: -```python -import asyncio -from collections.abc import Sequence - -from orcapod.channels import Channel, ReadableChannel, WritableChannel -from orcapod.core.static_output_pod import StaticOutputPod -``` - -**`src/orcapod/core/function_pod.py`** — already has all needed imports. - -### Step 16: Update regression test for `_execute_concurrent` removal - -**File:** `tests/test_core/test_regression_fixes.py` - -`TestExecuteConcurrentInRunningLoop` imports and tests `_execute_concurrent` directly. -Since we're removing that function, this test class needs to be rewritten to test the -behavior through the actual classes: - -- Test that `FunctionPodStream._iter_data_concurrent` falls back to sequential - `process_data` when called inside a running event loop. -- Test that `FunctionNode._iter_data_concurrent` does the same. - -The tested behavior (event-loop fallback) is preserved — it's just now method-internal -rather than in a standalone helper. - -### Step 17: Tests for new functionality - -**File:** `tests/test_channels/test_node_async_execute.py` (new) - -``` -TestProtocolConformance - - test_function_node_satisfies_async_executable_protocol - - test_persistent_function_node_satisfies_async_executable_protocol - - test_operator_node_satisfies_async_executable_protocol - - test_persistent_operator_node_satisfies_async_executable_protocol - -TestCachedDataFunctionAsync - - test_async_call_cache_miss_computes_and_records - - test_async_call_cache_hit_returns_cached - - test_async_call_skip_cache_lookup - - test_async_call_skip_cache_insert - -TestProcessDataRouting - - test_function_pod_stream_sequential_uses_process_data - - test_function_pod_stream_concurrent_uses_async_process_data - - test_function_node_sequential_uses_process_data - - test_function_node_concurrent_uses_async_process_data - - test_persistent_function_node_concurrent_uses_overridden_async_process_data - - test_concurrent_fallback_in_event_loop_uses_sync_process_data - -TestFunctionNodeAsyncExecute - - test_basic_streaming_matches_sync - - test_empty_input_closes_cleanly - - test_none_data_filtered_out - -TestPersistentFunctionNodeAsyncExecute - - test_no_cache_processes_all_inputs - - test_phase1_emits_cached_results - - test_phase2_skips_cached_computes_new - - test_pipeline_records_created_for_new_data - - test_result_cache_populated_for_new_data - -TestOperatorNodeAsyncExecute - - test_unary_op_delegation (SelectDataColumns) - - test_binary_op_delegation (SemiJoin) - - test_nary_op_delegation (Join) - - test_results_match_sync_run - -TestPersistentOperatorNodeAsyncExecute - - test_off_mode_computes_no_db_write - - test_log_mode_computes_and_stores - - test_log_mode_results_match_sync - - test_replay_mode_emits_from_db - - test_replay_empty_db_returns_empty - -TestEndToEnd - - test_source_to_persistent_function_node_pipeline - - test_source_to_persistent_operator_node_pipeline -``` - -### Step 18: Run full test suite - -```bash -uv run pytest tests/ -x -``` - ---- - -## Summary of all changes - -### Call chains after changes - -**Sync sequential path:** -``` -FunctionPodStream._iter_data_sequential - → self._function_pod.process_data(tag, pkt) # already correct - → data_function.call(pkt) - -FunctionNode._iter_data_sequential - → self.process_data(tag, pkt) # CHANGED: was _data_function.call(pkt) - → self._function_pod.process_data(tag, pkt) - → data_function.call(pkt) - -PersistentFunctionNode._iter_data_sequential (inherited from FunctionNode) - → self.process_data(tag, pkt) # polymorphism kicks in - → CachedDataFunction.call(pkt, skip_cache_*=...) # cache check + compute + record - → self.add_pipeline_record(...) # pipeline DB -``` - -**Sync concurrent path:** -``` -FunctionPodStream._iter_data_concurrent - → asyncio.run(gather( - self._function_pod.async_process_data(tag, pkt) ... # CHANGED: was _execute_concurrent - )) - OR (if event loop running): - self._function_pod.process_data(tag, pkt) ... # fallback - -FunctionNode._iter_data_concurrent - → asyncio.run(gather( - self.async_process_data(tag, pkt) ... # CHANGED: was _execute_concurrent - )) - OR (if event loop running): - self.process_data(tag, pkt) ... # fallback - -PersistentFunctionNode._iter_data_concurrent (inherited from FunctionNode) - → asyncio.run(gather( - self.async_process_data(tag, pkt) ... # polymorphism kicks in - → await CachedDataFunction.async_call(pkt) # cache + compute - → self.add_pipeline_record(...) # pipeline DB - )) -``` - -**Async execution path:** -``` -FunctionPod.async_execute - → await self.async_process_data(tag, pkt) # CHANGED: was data_function.async_call - → await data_function.async_call(pkt) - -FunctionNode.async_execute # NEW - → await self.async_process_data(tag, pkt) - → await self._function_pod.async_process_data(tag, pkt) - → await data_function.async_call(pkt) - -PersistentFunctionNode.async_execute # NEW (two-phase) - Phase 1: emit from DB - Phase 2: - → await self.async_process_data(tag, pkt) # polymorphic override - → await CachedDataFunction.async_call(pkt) # cache + compute - → self.add_pipeline_record(...) # pipeline DB (sync) - -OperatorNode.async_execute # NEW - → await operator.async_execute(inputs, output) - -PersistentOperatorNode.async_execute # NEW - REPLAY: emit from DB - OFF/LOG: - TaskGroup: - operator.async_execute(inputs, intermediate.writer) - forward(intermediate.reader → output + collect) - if LOG: _store_output_stream(materialize(collected)) # sync DB write -``` - -### Files modified - -| File | Changes | -|------|---------| -| `src/orcapod/core/data_function.py` | Add `CachedDataFunction.async_call` override with cache logic | -| `src/orcapod/core/function_pod.py` | (1) Add `_FunctionPodBase.async_process_data` | -| | (2) Fix `FunctionPod.async_execute` to use `async_process_data` | -| | (3) Rewrite `FunctionPodStream._iter_data_concurrent` — route through `_function_pod.async_process_data` / `process_data`, drop `data_function` param | -| | (4) Update `FunctionPodStream.iter_data` — remove `pf` arg to `_iter_data_concurrent` | -| | (5) Fix `FunctionNode._iter_data_sequential` to use `self.process_data` | -| | (6) Rewrite `FunctionNode._iter_data_concurrent` — route through `self.async_process_data` / `self.process_data` | -| | (7) Add `FunctionNode.process_data` + `async_process_data` (delegate to pod) | -| | (8) Add `FunctionNode.async_execute` | -| | (9) Add `PersistentFunctionNode.async_process_data` (cache + pipeline records) | -| | (10) Add `PersistentFunctionNode.async_execute` (two-phase) | -| | (11) Remove `_execute_concurrent` module-level helper | -| `src/orcapod/core/operator_node.py` | (1) Add imports | -| | (2) Add `OperatorNode.async_execute` (pass-through) | -| | (3) Extract `PersistentOperatorNode._store_output_stream` | -| | (4) Refactor `PersistentOperatorNode._compute_and_store` | -| | (5) Add `PersistentOperatorNode.async_execute` (TaskGroup + post-hoc storage) | -| `tests/test_core/test_regression_fixes.py` | Rewrite `TestExecuteConcurrentInRunningLoop` — test through classes instead of removed helper | -| `tests/test_channels/test_node_async_execute.py` | New test file | diff --git a/pyproject.toml b/pyproject.toml index d23e2fc83..ce7b93091 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -128,9 +128,6 @@ torch = [{ index = "pytorch-cpu", marker = "sys_platform == 'linux'" }] [tool.ruff] target-version = "py311" line-length = 88 -# Tutorial notebooks are not linted or formatted: reformatting rewrites their JSON, and -# the ones under old_tutorials/ target a package that no longer exists. -extend-exclude = ["notebooks"] [tool.basedpyright] # Strictness stays at the basedpyright default. Existing errors and warnings are @@ -149,7 +146,6 @@ exclude = [ "build", "dist", "site", - "notebooks", ] [tool.coverage.run] diff --git a/scripts/design_issues.py b/scripts/design_issues.py index 5e387cbba..3910081ab 100644 --- a/scripts/design_issues.py +++ b/scripts/design_issues.py @@ -1,7 +1,10 @@ -"""Read and check the design issues log in ``design_issues/``. +"""Read and check the design issues log in ``docs/dev/design_issues/``. -The log is one file per entry, ``design_issues/-.md`` (see -``design_issues/README.md``). This script reads the log as a whole. +The log is one file per entry, ``docs/dev/design_issues/-.md`` +(see ``docs/dev/design_issues/README.md``). This script reads the log as a whole. The log +was at the top-level ``design_issues/`` until ITL-1169 and in a single +``DESIGN_ISSUES.md`` before ITL-968; a file at either old location is an error in every +mode. Usage: @@ -26,6 +29,9 @@ from pathlib import Path REPO_ROOT = Path(__file__).resolve().parents[1] +LOG_DIR = REPO_ROOT / "docs" / "dev" / "design_issues" +OLD_LOG_DIR = REPO_ROOT / "design_issues" +OLD_LOG_FILE = REPO_ROOT / "DESIGN_ISSUES.md" STATUSES = ("open", "in progress", "resolved") SEVERITIES = ("critical", "high", "medium", "low", "trivial") @@ -296,6 +302,33 @@ def load_entries(entries_dir: Path) -> tuple[list[tuple[Path, Entry]], list[str] return entries, problems +def files_at_old_location() -> list[str]: + """List the files left at the log's old locations. + + The old locations are the single-file log ``DESIGN_ISSUES.md`` (split in ITL-968) and + the top-level ``design_issues/`` (moved in ITL-1169), both at the repository root. + Dotfiles (such as ``.DS_Store``) are not counted. + + Returns: + One message per file found, naming the new location; empty if there is none. + """ + new = LOG_DIR.relative_to(REPO_ROOT).as_posix() + problems: list[str] = [] + if OLD_LOG_FILE.is_file(): + problems.append( + f"{OLD_LOG_FILE}: the design issues log is one file per entry in {new}/ " + "(ITL-968, ITL-1169); move its entries there and delete this file" + ) + if OLD_LOG_DIR.is_dir(): + problems.extend( + f"{path}: the design issues log moved to {new}/ (ITL-1169); " + f"move this file there (git mv design_issues/{path.name} {new}/)" + for path in sorted(OLD_LOG_DIR.iterdir()) + if not path.name.startswith(".") + ) + return problems + + def _entry_order(entry: Entry) -> tuple[str, str, str, int, str]: """Sort key: area text without Markdown marks, the area heading, then the id. @@ -394,12 +427,13 @@ def main(argv: Sequence[str] | None = None) -> int: parser.add_argument( "--dir", type=Path, - default=REPO_ROOT / "design_issues", + default=LOG_DIR, help="directory holding the entry files", ) args = parser.parse_args(argv) loaded, problems = load_entries(args.dir) + problems = files_at_old_location() + problems if problems: print("\n".join(problems), file=sys.stderr) return 1 diff --git a/scripts/migrate_design_issues.py b/scripts/migrate_design_issues.py deleted file mode 100644 index 5d30c4a6e..000000000 --- a/scripts/migrate_design_issues.py +++ /dev/null @@ -1,324 +0,0 @@ -"""Split a single-file design issues log into one file per entry (ITL-968). - -``DESIGN_ISSUES.md`` used to hold every entry. This script moves each entry, text -unchanged, into ``design_issues/-.md`` (see ``design_issues/README.md``): - -- The file holds the entry's ``## `` area heading, a blank line, and the entry exactly as - it stood in the log, from its ``### `` heading to its last line. -- ```` is the first Linear issue id on the entry's ``**Issue:**`` line, or - ``NOISSUE`` for an entry with no such line. -- When two entries would get the same name, the later one in the log gets ``-2`` (then - ``-3``, ...) after its entry id. - -Usage: - - uv run python scripts/migrate_design_issues.py --source DESIGN_ISSUES.md - uv run python scripts/migrate_design_issues.py --source DESIGN_ISSUES.md --verify - -The first command writes the entry files (it never deletes the source or any other -file). ``--verify`` writes nothing: it rebuilds the source from its own preamble and -separators plus the entry files on disk, and fails unless the result equals the source -byte for byte. - -A branch that still edits an entry in ``DESIGN_ISSUES.md`` can use the script while -merging ``main``; ``design_issues/README.md`` gives the steps. The branch's copy is older -than ``main`` for every entry ``main`` changed since, so keep only the rewritten files of -the entries the branch itself changed. The script uses the standard library only. -""" - -from __future__ import annotations - -import argparse -import re -import sys -from collections.abc import Sequence -from dataclasses import dataclass -from pathlib import Path - -REPO_ROOT = Path(__file__).resolve().parents[1] - -# This one-off script stands alone: it shares no code with scripts/design_issues.py, which -# checks the files it writes. -NO_ISSUE = "NOISSUE" -_ENTRY_HEADING = re.compile(r"^### ([A-Z][A-Z0-9]*) — \S") -_ISSUE_LINE = re.compile(r"^\*\*Issue:\*\*\s*(.*)$") -_ISSUE_ID = re.compile(r"\b[A-Z][A-Z0-9]*-[0-9]+\b") -_FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})(.*)$") - - -class LogError(ValueError): - """The single-file log cannot be split without losing or guessing text.""" - - -@dataclass(frozen=True) -class Piece: - """A run of consecutive lines of the log. - - Attributes: - text: The lines, with their line endings. - area: For an entry, the ``## `` heading line it stands under (no line ending); - ``None`` for text between entries (the preamble, blank lines, ``---`` - separators and area headings). - """ - - text: str - area: str | None = None - - -def outside_fences(lines: Sequence[str]) -> list[bool]: - """Mark the lines that are not inside (or delimiting) a fenced code block. - - A block is closed only by a fence of the same character that is at least as long - as the one that opened it. - """ - mask: list[bool] = [] - opener: str | None = None - for line in lines: - fence = _FENCE.match(line) - if opener is None: - # A backtick fence cannot have a backtick in its info string. - if fence and not (fence.group(1)[0] == "`" and "`" in fence.group(2)): - opener = fence.group(1) - mask.append(False) - else: - mask.append(True) - continue - mask.append(False) - if ( - fence - and fence.group(1)[0] == opener[0] - and len(fence.group(1)) >= len(opener) - and not fence.group(2).strip() - ): - opener = None - return mask - - -def split_log(text: str) -> list[Piece]: - """Split the log into entries and the text between them. - - Joining ``piece.text`` over the result gives ``text`` back exactly. An entry runs - from its ``### `` heading to the last non-blank line before the next ``### `` - heading, ``## `` heading or ``---`` separator. Lines inside code fences never count - as headings or separators. - - Args: - text: The full text of the log. - - Returns: - The pieces in order. - - Raises: - LogError: If an entry comes before the first area heading, or text other than - the preamble stands outside every entry. - """ - lines = text.splitlines(keepends=True) - bare = [line.rstrip("\r\n") for line in lines] - mask = outside_fences(bare) - - pieces: list[Piece] = [] - between: list[str] = [] - entry: list[str] | None = None - area: str | None = None - - def close_entry() -> None: - """Add the open entry to ``pieces``; its trailing blank lines go to ``between``.""" - nonlocal entry - if entry is None: - return - end = len(entry) - while not entry[end - 1].strip(): - end -= 1 - assert area is not None # an entry is opened only under an area heading - pieces.append(Piece("".join(entry[:end]), area)) - between.extend(entry[end:]) - entry = None - - for number, (line, text_line, is_markdown) in enumerate( - zip(lines, bare, mask, strict=True), start=1 - ): - if is_markdown and text_line.startswith("### "): - close_entry() - if area is None: - raise LogError(f"line {number}: an entry before the first area heading") - if between: - pieces.append(Piece("".join(between))) - between = [] - entry = [line] - elif is_markdown and (text_line.startswith("## ") or text_line == "---"): - close_entry() - between.append(line) - if text_line.startswith("## "): - area = text_line - elif entry is not None: - entry.append(line) - elif area is not None and text_line.strip(): - raise LogError(f"line {number}: text outside every entry: {text_line!r}") - else: - between.append(line) - close_entry() - if between: - pieces.append(Piece("".join(between))) - return pieces - - -def entry_file_text(piece: Piece) -> str: - """The text of the file that holds an entry: area heading, blank line, entry.""" - return f"{piece.area}\n\n{piece.text}" - - -def name_entries(pieces: Sequence[Piece]) -> list[str | None]: - """Choose the file name of each entry. - - Args: - pieces: The pieces of the log, in order. - - Returns: - For each piece, its file name, or ``None`` for text between entries. - - Raises: - LogError: If an entry's heading is not ``### — ``, or its - ``**Issue:**`` line names no Linear issue. - """ - names: list[str | None] = [] - used: dict[str, int] = {} - for piece in pieces: - if piece.area is None: - names.append(None) - continue - lines = piece.text.splitlines() - heading = _ENTRY_HEADING.match(lines[0]) - if heading is None: - raise LogError(f"{lines[0]!r}: not a '### <ENTRY-ID> — <title>' heading") - # The field lines stand directly under the heading, before the first blank line. - fields = lines[1 : lines.index("") if "" in lines else len(lines)] - issue = next((m.group(1) for f in fields if (m := _ISSUE_LINE.match(f))), None) - if issue is None: - prefix = NO_ISSUE - elif found := _ISSUE_ID.search(issue): - prefix = found.group(0) - else: - raise LogError(f"{lines[0]!r}: no Linear issue id in {issue!r}") - stem = f"{prefix}-{heading.group(1)}" - used[stem] = used.get(stem, 0) + 1 - names.append(f"{stem}.md" if used[stem] == 1 else f"{stem}-{used[stem]}.md") - return names - - -def main(argv: Sequence[str] | None = None) -> int: - """Write the entry files, or with ``--verify`` check them against the source. - - Args: - argv: Command-line arguments; ``sys.argv[1:]`` when omitted. - - Returns: - The process exit code: 0 on success, 1 if the log cannot be split or the - entry files do not reproduce it. - """ - parser = argparse.ArgumentParser(description=(__doc__ or "").split("\n\n")[0]) - parser.add_argument( - "--source", type=Path, required=True, help="the single-file log to split" - ) - parser.add_argument( - "--out", - type=Path, - default=REPO_ROOT / "design_issues", - help="directory that receives the entry files", - ) - parser.add_argument( - "--verify", - action="store_true", - help="write nothing; check that the entry files reproduce the source", - ) - args = parser.parse_args(argv) - - source = args.source.read_bytes().decode("utf-8") - try: - pieces = split_log(source) - names = name_entries(pieces) - except LogError as error: - print(f"{args.source}: {error}", file=sys.stderr) - return 1 - entries = [(name, piece) for name, piece in zip(names, pieces) if name is not None] - if not entries: - print(f"{args.source}: no '### ' entry found", file=sys.stderr) - return 1 - - if args.verify: - return _verify(source, pieces, names, args.out) - - args.out.mkdir(parents=True, exist_ok=True) - counts = {"created": 0, "updated": 0, "unchanged": 0} - for name, piece in entries: - path = args.out / name - if path.is_symlink(): - print(f"{path}: is a symbolic link; not written", file=sys.stderr) - return 1 - new = entry_file_text(piece).encode("utf-8") - if not path.exists(): - outcome = "created" - elif path.read_bytes() == new: - outcome = "unchanged" - else: - outcome = "updated" - counts[outcome] += 1 - if outcome != "unchanged": - path.write_bytes(new) - print(f"{outcome}: {path}") - summary = ", ".join(f"{count} {outcome}" for outcome, count in counts.items()) - print(f"{len(entries)} entries from {args.source}: {summary}") - return 0 - - -def _verify( - source: str, pieces: Sequence[Piece], names: Sequence[str | None], out: Path -) -> int: - """Rebuild the source from the entry files on disk and compare.""" - rebuilt: list[str] = [] - problems: list[str] = [] - for name, piece in zip(names, pieces, strict=True): - if name is None: - rebuilt.append(piece.text) - continue - path = out / name - if not path.is_file(): - problems.append(f"{path}: missing") - continue - text = path.read_bytes().decode("utf-8") - area, blank, entry = text.partition("\n\n") - if area != piece.area or not blank: - problems.append( - f"{path}: does not start with the area heading {piece.area!r}" - ) - if entry != piece.text: - problems.append(f"{path}: the entry text differs from the source") - rebuilt.append(entry) - if not problems and "".join(rebuilt) != source: - problems.append("the rebuilt text differs from the source") - if problems: - print("\n".join(problems), file=sys.stderr) - return 1 - - between = "".join(p.text for p in pieces if p.area is None).splitlines() - first_area = next( - (i for i, line in enumerate(between) if line.startswith("## ")), len(between) - ) - rest = between[first_area:] - total = len(source.encode("utf-8")) - in_entries = sum(len(p.text.encode("utf-8")) for p in pieces if p.area is not None) - print( - f"{sum(name is not None for name in names)} entry files reproduce the source " - f"byte for byte: {total} bytes = {in_entries} in entries + " - f"{total - in_entries} outside them" - ) - print( - f"outside the entries: {first_area} preamble lines, " - f"{sum(line.startswith('## ') for line in rest)} '## ' area heading lines, " - f"{sum(line == '---' for line in rest)} '---' lines, " - f"{sum(not line.strip() for line in rest)} blank lines" - ) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/src/orcapod/core/nodes/operator_node.py b/src/orcapod/core/nodes/operator_node.py index 5139d84a4..ad1a38453 100644 --- a/src/orcapod/core/nodes/operator_node.py +++ b/src/orcapod/core/nodes/operator_node.py @@ -1151,7 +1151,7 @@ def _filter_by_content_hash(self, table: pa.Table) -> pa.Table: f"column {col_name!r} has type {col_type!r}, expected large_binary. " "This table was written by an older version of the code that stored " "this column as large_string. Drop and recreate the affected pipeline " - "DB tables (see design_issues/ ON1)." + "DB tables (see docs/dev/design_issues/ ON1)." ) own_hash = self.content_hash().to_prefixed_digest() mask = pc.equal(table.column(col_name), own_hash) diff --git a/src/orcapod/core/result_cache.py b/src/orcapod/core/result_cache.py index f89caaa83..9203515bf 100644 --- a/src/orcapod/core/result_cache.py +++ b/src/orcapod/core/result_cache.py @@ -56,7 +56,7 @@ class ResultCache: The match strategy is extensible: the default lookup matches on ``INPUT_DATA_HASH_COL`` only, but callers can supply additional constraints (e.g. function variation columns) to narrow the match. - This is the hook for future match-tier support (see design_issues/ P6). + This is the hook for future match-tier support (see docs/dev/design_issues/ P6). Args: result_database: The database to store/retrieve cached results. diff --git a/src/orcapod/databases/file_utils.py b/src/orcapod/databases/file_utils.py deleted file mode 100644 index ed484d54d..000000000 --- a/src/orcapod/databases/file_utils.py +++ /dev/null @@ -1,434 +0,0 @@ -# # file_ops.py - Atomic file operations module - -# import builtins -# import contextlib -# import inspect -# import logging -# import os -# from pathlib import Path - -# from orcapod.types import PathLike, PathSet, DataLike -# from collections.abc import Collection, Callable - - -# logger = logging.getLogger(__name__) - - -# def atomic_write(file_path: PathLike, content: str) -> Path: -# """ -# Atomically write content to a file. - -# This function writes content to a temporary file and then atomically -# renames it to the target file path, ensuring that other processes never -# see a partially-written file. - -# Args: -# file_path: Target file path -# content: Content to write - -# Returns: -# Path object to the written file - -# Raises: -# OSError: If the file cannot be written -# """ -# file_path = Path(file_path) -# temp_path = file_path.with_name(f"{file_path.name}.tmp{os.getpid()}") - -# # Ensure parent directory exists -# file_path.parent.mkdir(parents=True, exist_ok=True) - -# try: -# # Write content to a temporary file -# with open(temp_path, "w") as f: -# f.write(content) -# f.flush() -# os.fsync(f.fileno()) # Force flush to disk - -# # Atomic rename -# os.rename(temp_path, file_path) -# return file_path -# except Exception as e: -# logger.error(f"Error writing file {file_path}: {str(e)}") -# raise -# finally: -# # Clean up the temporary file if it exists -# if temp_path.exists(): -# temp_path.unlink(missing_ok=True) - - -# def atomic_write_bytes(file_path: PathLike, content: bytes) -> Path: -# """ -# Atomically write binary content to a file. - -# This function writes binary content to a temporary file and then atomically -# renames it to the target file path. - -# Args: -# file_path: Target file path -# content: Binary content to write - -# Returns: -# Path object to the written file - -# Raises: -# OSError: If the file cannot be written -# """ -# file_path = Path(file_path) -# temp_path = file_path.with_name(f"{file_path.name}.tmp{os.getpid()}") - -# # Ensure parent directory exists -# file_path.parent.mkdir(parents=True, exist_ok=True) - -# try: -# # Write content to a temporary file -# with open(temp_path, "wb") as f: -# f.write(content) -# f.flush() -# os.fsync(f.fileno()) # Force flush to disk - -# # Atomic rename -# os.rename(temp_path, file_path) -# return file_path -# except Exception as e: -# logger.error(f"Error writing file {file_path}: {str(e)}") -# raise -# finally: -# # Clean up the temporary file if it exists -# if temp_path.exists(): -# temp_path.unlink(missing_ok=True) - - -# def atomic_copy(source_path: PathLike, dest_path: PathLike) -> Path: -# """ -# Atomically copy a file. - -# This function copies a file to a temporary location and then atomically -# renames it to the target path, ensuring that other processes never -# see a partially-copied file. - -# Args: -# source_path: Source file path -# dest_path: Destination file path - -# Returns: -# Path object to the copied file - -# Raises: -# OSError: If the file cannot be copied -# FileNotFoundError: If the source file does not exist -# """ -# import shutil - -# source_path = Path(source_path) -# dest_path = Path(dest_path) -# temp_path = dest_path.with_name(f"{dest_path.name}.tmp{os.getpid()}") - -# # Check if source exists -# if not source_path.exists(): -# raise FileNotFoundError(f"Source file does not exist: {source_path}") - -# # Ensure parent directory exists -# dest_path.parent.mkdir(parents=True, exist_ok=True) - -# try: -# # Copy to temporary file -# shutil.copy2(source_path, temp_path) - -# # Ensure the data is written to disk -# with open(temp_path, "a") as f: -# os.fsync(f.fileno()) - -# # Atomic rename -# os.rename(temp_path, dest_path) -# return dest_path -# except Exception as e: -# logger.error(f"Error copying file from {source_path} to {dest_path}: {str(e)}") -# raise -# finally: -# # Clean up the temporary file if it exists -# if temp_path.exists(): -# temp_path.unlink(missing_ok=True) - - -# def atomic_append(file_path: PathLike, content: str) -> Path: -# """ -# Atomically append content to a file. - -# This function reads the existing content, appends the new content, -# and then atomically writes the result back to the file. - -# Args: -# file_path: Target file path -# content: Content to append - -# Returns: -# Path object to the appended file - -# Raises: -# OSError: If the file cannot be written -# """ -# file_path = Path(file_path) - -# # Read existing content if file exists -# existing_content = "" -# if file_path.exists(): -# try: -# with open(file_path, "r") as f: -# existing_content = f.read() -# except Exception as e: -# logger.error(f"Error reading file {file_path} for append: {str(e)}") -# raise - -# # Write the combined content atomically -# return atomic_write(file_path, existing_content + content) - - -# def atomic_replace( -# file_path: PathLike, pattern: str, replacement: str, count: int = -1 -# ) -> tuple[Path, int]: -# """ -# Atomically replace text in a file. - -# This function reads the existing content, performs the replacement, -# and then atomically writes the result back to the file. - -# Args: -# file_path: Target file path -# pattern: Pattern to replace -# replacement: Replacement text -# count: Maximum number of replacements (default: unlimited) - -# Returns: -# Tuple of (Path object to the file, number of replacements made) - -# Raises: -# OSError: If the file cannot be read or written -# FileNotFoundError: If the file does not exist -# """ -# file_path = Path(file_path) - -# # Check if file exists -# if not file_path.exists(): -# raise FileNotFoundError(f"File does not exist: {file_path}") - -# # Read existing content -# try: -# with open(file_path, "r") as f: -# existing_content = f.read() -# except Exception as e: -# logger.error(f"Error reading file {file_path} for replacement: {str(e)}") -# raise - -# # Perform replacement -# new_content, num_replacements = existing_content, 0 -# if count == -1: -# # Replace all occurrences -# new_content = existing_content.replace(pattern, replacement) -# num_replacements = existing_content.count(pattern) -# else: -# # Replace only up to count occurrences -# new_content = "" -# remaining = existing_content -# for _ in range(count): -# if pattern not in remaining: -# break -# pos = remaining.find(pattern) -# new_content += remaining[:pos] + replacement -# remaining = remaining[pos + len(pattern) :] -# num_replacements += 1 -# new_content += remaining - -# # Write the new content atomically -# return atomic_write(file_path, new_content), num_replacements - - -# def is_file_locked(file_path: PathLike) -> bool: -# """ -# Check if a file is locked. - -# This function attempts to open the file for writing in non-blocking mode -# and checks if it fails with a "resource temporarily unavailable" error. - -# Args: -# file_path: File path to check - -# Returns: -# True if the file is locked, False otherwise -# """ -# import errno -# import fcntl - -# file_path = Path(file_path) - -# # If file doesn't exist, it's not locked -# if not file_path.exists(): -# return False - -# try: -# # Try to open the file and get an exclusive lock in non-blocking mode -# with open(file_path, "r+") as f: -# fcntl.flock(f, fcntl.LOCK_EX | fcntl.LOCK_NB) -# # If we get here, the file is not locked -# fcntl.flock(f, fcntl.LOCK_UN) -# return False -# except IOError as e: -# if e.errno == errno.EAGAIN: -# # Resource temporarily unavailable = the file is locked -# return True -# # Some other error - assume not locked -# return False -# except Exception: -# # Any other exception - assume not locked -# return False - - -# @contextlib.contextmanager -# def redirect_open( -# mapping: dict[str, str] | Callable[[str], str | None], -# ): -# """ -# Context manager to intercept file opening operations. - -# Args: -# mapping: Either a dictionary mapping original paths to their replacements, -# or a function that takes a path string and returns a replacement path -# (or None to indicate the file should not be opened). - -# Raises: -# FileNotFoundError: If using a dictionary and the path is not found in it. -# """ -# # Track all places that might store an open() function -# places_to_patch = [] - -# # 1. Standard builtins.open -# original_builtin_open = builtins.open -# places_to_patch.append((builtins, "open", original_builtin_open)) - -# # 2. __builtins__ (could be different in some contexts, especially IPython) -# if isinstance(__builtins__, dict) and "open" in __builtins__: -# places_to_patch.append((__builtins__, "open", __builtins__["open"])) - -# # 3. Current module's globals (for the calling namespace) -# current_frame = inspect.currentframe() -# if current_frame is not None: -# caller_globals = current_frame.f_back.f_globals if current_frame.f_back else {} -# if "open" in caller_globals: -# places_to_patch.append((caller_globals, "open", caller_globals["open"])) - -# # 4. Check for IPython user namespace -# try: -# import IPython - -# ip = IPython.get_ipython() # type: ignore -# if ip and "open" in ip.user_ns: -# places_to_patch.append((ip.user_ns, "open", ip.user_ns["open"])) -# except (ImportError, AttributeError): -# pass - -# def patched_open(file, *args, **kwargs): -# # Convert PathLike objects to string if needed -# if hasattr(file, "__fspath__"): -# file_path = os.fspath(file) -# else: -# file_path = str(file) - -# if isinstance(mapping, dict): -# if file_path in mapping: -# redirected_path = mapping[file_path] -# print(f"Redirecting '{file_path}' to '{redirected_path}'") -# return original_builtin_open(redirected_path, *args, **kwargs) -# else: -# raise FileNotFoundError( -# f"Path '{file_path}' not found in redirection mapping" -# ) -# else: # mapping is a function -# redirected_path = mapping(file_path) -# if redirected_path is not None: -# print(f"Redirecting '{file_path}' to '{redirected_path}'") -# return original_builtin_open(redirected_path, *args, **kwargs) -# else: -# raise FileNotFoundError(f"Path '{file_path}' could not be redirected") - -# # Apply the patch to all places -# for obj, attr, _ in places_to_patch: -# if isinstance(obj, dict): -# obj[attr] = patched_open -# else: -# setattr(obj, attr, patched_open) - -# try: -# yield -# finally: -# # Restore all original functions -# for obj, attr, original in places_to_patch: -# if isinstance(obj, dict): -# obj[attr] = original -# else: -# setattr(obj, attr, original) - - -# def virtual_mount( -# data: DataLike, -# ) -> tuple[DataLike, dict[str, str], dict[str, str]]: -# """ -# Visit all pathset within the data, and convert them to alternative path -# representation. By default, full path is mapped to the file name. If two or -# more paths have the same file name, the second one is suffixed with "_1", the -# third one with "_2", etc. This is useful for creating a virtual mount point -# for a set of files, where the original paths are not important, but the file -# names can be used to identify the files. -# """ -# forward_lut = {} # mapping from original path to new path -# reverse_lut = {} # mapping from new path to original path -# new_data = {} - -# for key, value in data.items(): -# new_data[key] = convert_pathset(value, forward_lut, reverse_lut) # type: ignore - -# return new_data, forward_lut, reverse_lut - - -# # TODO: re-assess the structure of PathSet and consider making it recursive -# def convert_pathset(pathset: PathSet, forward_lut, reverse_lut) -> PathSet: -# """ -# Convert a pathset to a new pathset. forward_lut and reverse_lut are updated -# with the new paths. The new paths are created by replacing the original paths -# with the new paths in the forward_lut. The reverse_lut is updated with the -# original paths. If name already exists, a suffix is added to the new name to avoid -# collisions. -# """ -# if isinstance(pathset, (str, bytes)): -# new_name = Path(pathset).name -# if new_name in reverse_lut: -# # if the name already exists, add a suffix -# i = 1 -# while f"{new_name}_{i}" in reverse_lut: -# i += 1 -# new_name = f"{new_name}_{i}" -# forward_lut[pathset] = new_name -# reverse_lut[new_name] = pathset -# return new_name -# elif isinstance(pathset, Collection): -# return [convert_pathset(p, forward_lut, reverse_lut) for p in pathset] # type: ignore -# else: -# raise ValueError( -# f"Unsupported pathset type: {type(pathset)}. Expected str, bytes, or Collection." -# ) - - -# class WrappedPath: -# def __init__(self, path, name=None): -# self.path = Path(path) -# if name is None: -# name = self.path.name -# self.name = name - -# def __fspath__(self) -> str | bytes: -# return self.path.__fspath__() - -# def __str__(self) -> str: -# return self.name - -# def __repr__(self) -> str: -# return f"WrappedPath({self.path}): {self.name}" diff --git a/src/orcapod/logical_types/registry.py b/src/orcapod/logical_types/registry.py index 2b1a692ae..e1cf19ae9 100644 --- a/src/orcapod/logical_types/registry.py +++ b/src/orcapod/logical_types/registry.py @@ -188,7 +188,7 @@ def make_polars_extension_type( passing it here. Types produced by ``register_python_class`` and ``register_storage_type`` satisfy this invariant, but arbitrary ``pa.DataType`` values do not. This is tracked as design issue ET1 in - ``design_issues/``. + ``docs/dev/design_issues/``. Args: extension_name: The extension type name used for Polars registration. diff --git a/src/orcapod/logical_types/user_class_logical_type.py b/src/orcapod/logical_types/user_class_logical_type.py index fe505eb4c..6301157c0 100644 --- a/src/orcapod/logical_types/user_class_logical_type.py +++ b/src/orcapod/logical_types/user_class_logical_type.py @@ -125,7 +125,7 @@ def __init__( if identity_record is not None: metadata["identity"] = identity_record metadata_json = uci.canonical_json(metadata) - # ``storage_type`` never contains nested extension types (ET1 in design_issues/): + # ``storage_type`` never contains nested extension types (ET1 in docs/dev/design_issues/): # the factory strips each field's top-level extension type before building it. self._arrow_ext_class, self._polars_ext_class = _extension_classes( logical_name, storage_type, metadata_json @@ -344,7 +344,7 @@ def _storage( f"{python_type.__qualname__}.{field_name} -> {exc}" ) from exc raise - # Struct fields cannot hold extension types (ET1; see design_issues/). + # Struct fields cannot hold extension types (ET1; see docs/dev/design_issues/). if isinstance(arrow_type, pa.ExtensionType): arrow_type = arrow_type.storage_type arrow_fields.append(pa.field(field_name, arrow_type)) diff --git a/src/orcapod/semantic_types/universal_converter.py b/src/orcapod/semantic_types/universal_converter.py index eb1c03139..45ecc6e2e 100644 --- a/src/orcapod/semantic_types/universal_converter.py +++ b/src/orcapod/semantic_types/universal_converter.py @@ -390,7 +390,7 @@ def _register_python_class_impl( # list[T] → large_list(T storage) when T is a plain type, or a top-level # ListLogicalType extension when T has a registered LogicalType. - # Arrow forbids extension types inside list value fields (ET1 in design_issues/). + # Arrow forbids extension types inside list value fields (ET1 in docs/dev/design_issues/). # Wrapping the whole list as an extension type (ET2 fix, ITL-173) preserves # element type information at the field-metadata level. if origin is list: diff --git a/src/orcapod/utils/arrow_utils.py b/src/orcapod/utils/arrow_utils.py index c439ba47e..e76f38ea7 100644 --- a/src/orcapod/utils/arrow_utils.py +++ b/src/orcapod/utils/arrow_utils.py @@ -126,7 +126,7 @@ def normalize_to_large_types( if pa.types.is_string(arrow_type) or pa.types.is_string_view(arrow_type): # string_view has no comparison/sort kernels in PyArrow (>=23, <=24), so # normalizing it to large_string is required for filtering, not just for - # consistency. See design_issues/ D8 / ENG-601. + # consistency. See docs/dev/design_issues/ D8 / ENG-601. return pa.large_string() elif pa.types.is_binary(arrow_type) or pa.types.is_binary_view(arrow_type): return pa.large_binary() @@ -385,7 +385,7 @@ def normalize_extension_columns(table: "pa.Table") -> "pa.Table": Note: only **top-level** extension columns are handled. Extension types nested inside struct fields or list element types are not supported by the - orcapod type system (see ET1 in design_issues/) and are left unchanged. + orcapod type system (see ET1 in docs/dev/design_issues/) and are left unchanged. Args: table: Input Arrow table, may contain extension-typed columns. @@ -1516,7 +1516,7 @@ def build_aggregated_table( Logical element types are preserved. Arrow cannot embed an extension type inside a list value field, so ``pa.list_(extension_type)`` raises - ``ArrowNotImplementedError`` (see ``design_issues/`` ET1/ET2). For such a + ``ArrowNotImplementedError`` (see ``docs/dev/design_issues/`` ET1/ET2). For such a column the list is built over the element's *storage* type and then wrapped in the outer ``list[<element>]`` extension type supplied by ``ListLogicalType``. A pod annotated ``-> Path`` therefore groups into diff --git a/src/sample.py b/src/sample.py deleted file mode 100644 index 3c10555b1..000000000 --- a/src/sample.py +++ /dev/null @@ -1,7 +0,0 @@ -from collections.abc import Mapping - - -def test() -> Mapping[str, type] | int: ... - - -x = test() diff --git a/tests/test_core/operators/test_group_by.py b/tests/test_core/operators/test_group_by.py index f9dbf524b..b43c29b53 100644 --- a/tests/test_core/operators/test_group_by.py +++ b/tests/test_core/operators/test_group_by.py @@ -568,7 +568,7 @@ class TestAggregationLogicalTypes: A pod annotated ``-> Path`` emits an ``extension<orcapod.path>`` column. Naively wrapping that in ``pa.list_()`` raises ``ArrowNotImplementedError``: Arrow cannot embed an extension type inside a list value field - (design_issues/ ET1/ET2). The list must be built over the element's + (docs/dev/design_issues/ ET1/ET2). The list must be built over the element's *storage* type and wrapped in the ``list[orcapod.path]`` extension type at the outermost level, which is what ``ListLogicalType`` provides. diff --git a/tests/test_databases/test_spiraldb_connector_integration.py b/tests/test_databases/test_spiraldb_connector_integration.py index c04b1b82d..ccb6d5293 100644 --- a/tests/test_databases/test_spiraldb_connector_integration.py +++ b/tests/test_databases/test_spiraldb_connector_integration.py @@ -1,6 +1,7 @@ """Integration tests for SpiralDBConnector against the live dev project. -These tests are skipped unless the ``SPIRAL_INTEGRATION_TESTS=1`` env var is set. +These tests are skipped unless the ``SPIRAL_INTEGRATION_TESTS=1`` env var is set and +``SPIRAL_PROJECT_ID`` names the project to test against. They require a valid auth mechanism, either: - Local dev: a saved ``spiral login`` (pyspiral keeps it in @@ -15,7 +16,7 @@ Project and server URL are configurable via env vars: -- ``SPIRAL_PROJECT_ID`` (default: ``test-orcapod-362211``) +- ``SPIRAL_PROJECT_ID`` (required; no default) - ``SPIRAL_SERVER_URL`` (default: ``https://api.spiraldb.dev``) Version compatibility note (PLT-1773) @@ -46,14 +47,17 @@ from orcapod.types import ColumnInfo INTEGRATION = os.environ.get("SPIRAL_INTEGRATION_TESTS") == "1" -DEV_PROJECT = os.environ.get("SPIRAL_PROJECT_ID", "test-orcapod-362211") +DEV_PROJECT = os.environ.get("SPIRAL_PROJECT_ID", "") DEV_OVERRIDES = { "server.url": os.environ.get("SPIRAL_SERVER_URL", "https://api.spiraldb.dev") } pytestmark = pytest.mark.skipif( - not INTEGRATION, - reason="Set SPIRAL_INTEGRATION_TESTS=1 to run SpiralDB integration tests", + not (INTEGRATION and DEV_PROJECT), + reason=( + "Set SPIRAL_INTEGRATION_TESTS=1 and SPIRAL_PROJECT_ID to run SpiralDB " + "integration tests" + ), ) diff --git a/tests/test_design_issues.py b/tests/test_design_issues.py index ce43af073..d1176032a 100644 --- a/tests/test_design_issues.py +++ b/tests/test_design_issues.py @@ -1,11 +1,12 @@ -"""The design issues log (``design_issues/``), one file per entry (ITL-968). +"""The design issues log (``docs/dev/design_issues/``), one file per entry (ITL-968). -Every test drives ``scripts/design_issues.py`` or ``scripts/migrate_design_issues.py`` as -a command, the way a developer and CI use them. +Every test drives ``scripts/design_issues.py`` as a command, the way a developer and CI +use it. """ from __future__ import annotations +import shutil import subprocess import sys from pathlib import Path @@ -14,7 +15,6 @@ REPO_ROOT = Path(__file__).resolve().parents[1] SCRIPT = REPO_ROOT / "scripts" / "design_issues.py" -MIGRATE = REPO_ROOT / "scripts" / "migrate_design_issues.py" ENTRY = """\ ## `src/x.py` — things @@ -61,20 +61,59 @@ def _write(directory: Path, name: str, text: str) -> None: def test_repository_entries_are_well_formed() -> None: - """Every file in ``design_issues/`` except ``README.md`` is a valid entry.""" + """Every file in ``docs/dev/design_issues/`` except ``README.md`` is a valid entry.""" result = _run(SCRIPT, "--check") assert result.returncode == 0, result.stderr def test_repository_log_has_a_readme() -> None: - assert (REPO_ROOT / "design_issues" / "README.md").is_file() + assert (REPO_ROOT / "docs" / "dev" / "design_issues" / "README.md").is_file() def test_the_single_file_log_is_not_brought_back() -> None: - """Entries live in ``design_issues/``; ``DESIGN_ISSUES.md`` no longer exists.""" + """Entries live in ``docs/dev/design_issues/``; ``DESIGN_ISSUES.md`` no longer exists.""" assert not (REPO_ROOT / "DESIGN_ISSUES.md").exists() +@pytest.fixture +def repo_copy(tmp_path: Path) -> Path: + """A repository holding the script and an empty log at ``docs/dev/design_issues``.""" + (tmp_path / "scripts").mkdir() + shutil.copy(SCRIPT, tmp_path / "scripts" / SCRIPT.name) + log = tmp_path / "docs" / "dev" / "design_issues" + log.mkdir(parents=True) + (log / "README.md").write_text("# Design issues\n", encoding="utf-8") + return tmp_path + + +def test_check_refuses_entries_at_the_old_location(repo_copy: Path) -> None: + """An entry added at the top-level ``design_issues/`` (moved in ITL-1169) fails.""" + old = repo_copy / "design_issues" + old.mkdir() + _write(old, "ITL-7-AB1.md", ENTRY) + result = _run(repo_copy / "scripts" / SCRIPT.name, "--check") + assert result.returncode == 1 + assert "ITL-7-AB1.md" in result.stderr + assert "docs/dev/design_issues" in result.stderr + + +def test_check_refuses_a_restored_single_file_log(repo_copy: Path) -> None: + """A ``DESIGN_ISSUES.md`` at the repository root fails beside a valid log.""" + (repo_copy / "DESIGN_ISSUES.md").write_text("# Design issues\n", encoding="utf-8") + result = _run(repo_copy / "scripts" / SCRIPT.name, "--check") + assert result.returncode == 1 + assert "DESIGN_ISSUES.md" in result.stderr + assert "docs/dev/design_issues" in result.stderr + + +def test_check_ignores_an_old_location_holding_only_dotfiles(repo_copy: Path) -> None: + old = repo_copy / "design_issues" + old.mkdir() + (old / ".DS_Store").write_text("", encoding="utf-8") + result = _run(repo_copy / "scripts" / SCRIPT.name, "--check") + assert result.returncode == 0, result.stderr + + # --- --check ------------------------------------------------------------------------ @@ -322,162 +361,3 @@ def test_index_refuses_a_malformed_log(log: Path) -> None: result = _run(SCRIPT, "--dir", log) assert result.returncode == 1 assert "wrong.md" in result.stderr - - -# --- the migration from the single-file log ----------------------------------------- - -LOG = """\ -# Design & Implementation Issues - -A running log. - ---- - -## Area one - -### A1 — First -**Status:** open -**Severity:** low - -Body one. - -```python -# TODO: not a heading ---- -### Z9 — not an entry -``` - ---- - -### A2 — Second -**Status:** resolved -**Severity:** high -**Issue:** ITL-5 (related: ITL-6) - -Body two. - ---- - -## `area/two.py` - -### A1 — Same id, other area -**Status:** in progress -**Severity:** medium - -Body three. - - -""" - - -@pytest.fixture -def source(tmp_path: Path) -> Path: - """A single-file log holding ``LOG``.""" - path = tmp_path / "DESIGN_ISSUES.md" - path.write_text(LOG, encoding="utf-8") - return path - - -def _migrate(source: Path, *args: str) -> subprocess.CompletedProcess[str]: - """Run the migration from ``source`` into an ``out`` directory beside it.""" - return _run(MIGRATE, "--source", source, "--out", source.parent / "out", *args) - - -def test_migration_writes_one_file_per_entry(source: Path) -> None: - result = _migrate(source) - - assert result.returncode == 0, result.stderr - out = source.parent / "out" - assert sorted(p.name for p in out.iterdir()) == [ - "ITL-5-A2.md", - "NOISSUE-A1-2.md", - "NOISSUE-A1.md", - ] - assert (out / "ITL-5-A2.md").read_text(encoding="utf-8") == ( - "## Area one\n\n### A2 — Second\n**Status:** resolved\n**Severity:** high\n" - "**Issue:** ITL-5 (related: ITL-6)\n\nBody two.\n" - ) - assert ( - (out / "NOISSUE-A1.md") - .read_text(encoding="utf-8") - .endswith("```python\n# TODO: not a heading\n---\n### Z9 — not an entry\n```\n") - ) - assert ( - (out / "NOISSUE-A1-2.md") - .read_text(encoding="utf-8") - .startswith("## `area/two.py`\n\n### A1 — Same id, other area\n") - ) - assert source.read_text(encoding="utf-8") == LOG - # The files it writes are valid entries. - assert _check(out).returncode == 0 - - -def test_migration_verify_passes_on_its_own_output(source: Path) -> None: - assert _migrate(source).returncode == 0 - result = _migrate(source, "--verify") - assert result.returncode == 0, result.stderr - assert "3 entry files reproduce the source byte for byte" in result.stdout - - -def test_migration_verify_fails_when_an_entry_file_differs(source: Path) -> None: - assert _migrate(source).returncode == 0 - path = source.parent / "out" / "ITL-5-A2.md" - path.write_text( - path.read_text(encoding="utf-8").replace("Body two.", "Body 2."), - encoding="utf-8", - ) - result = _migrate(source, "--verify") - assert result.returncode == 1 - assert "ITL-5-A2.md" in result.stderr - - -def test_migration_verify_fails_when_an_entry_file_is_missing(source: Path) -> None: - assert _migrate(source).returncode == 0 - (source.parent / "out" / "NOISSUE-A1-2.md").unlink() - result = _migrate(source, "--verify") - assert result.returncode == 1 - assert "NOISSUE-A1-2.md" in result.stderr - - -def test_migration_rerun_rewrites_only_the_entries_that_changed(source: Path) -> None: - assert _migrate(source).returncode == 0 - source.write_text( - LOG.replace("**Status:** open", "**Status:** resolved"), encoding="utf-8" - ) - result = _migrate(source) - assert result.returncode == 0, result.stderr - assert "0 created, 1 updated, 2 unchanged" in result.stdout - assert "**Status:** resolved" in ( - source.parent / "out" / "NOISSUE-A1.md" - ).read_text(encoding="utf-8") - - -def test_migration_refuses_text_outside_every_entry(source: Path) -> None: - source.write_text( - LOG.replace("## `area/two.py`\n", "## `area/two.py`\n\nStray prose.\n"), - encoding="utf-8", - ) - result = _migrate(source) - assert result.returncode == 1 - assert "Stray prose." in result.stderr - assert not (source.parent / "out").exists() - - -def test_migration_refuses_a_source_with_no_entry(source: Path) -> None: - source.write_text("# Design issues\n\nNothing yet.\n", encoding="utf-8") - for extra in ([], ["--verify"]): - result = _migrate(source, *extra) - assert result.returncode == 1 - assert "no '### ' entry" in result.stderr - - -def test_migration_refuses_to_write_through_a_symbolic_link(source: Path) -> None: - out = source.parent / "out" - out.mkdir() - target = source.parent / "elsewhere.md" - target.write_text("keep\n", encoding="utf-8") - (out / "ITL-5-A2.md").symlink_to(target) - result = _migrate(source) - assert result.returncode == 1 - assert "ITL-5-A2.md" in result.stderr - assert target.read_text(encoding="utf-8") == "keep\n" diff --git a/tests/test_hashing/test_string_cacher/test_redis_cacher.py b/tests/test_hashing/test_string_cacher/test_redis_cacher.py deleted file mode 100644 index 5da229298..000000000 --- a/tests/test_hashing/test_string_cacher/test_redis_cacher.py +++ /dev/null @@ -1,428 +0,0 @@ -# """Tests for RedisCacher using mocked Redis.""" - -# from typing import cast, TYPE_CHECKING -# from unittest.mock import patch, MagicMock - -# import pytest - -# from orcapod.hashing.string_cachers import RedisCacher - -# if TYPE_CHECKING: -# import redis - - -# # Mock Redis exceptions -# class MockRedisError(Exception): -# """Mock for redis.RedisError""" - -# pass - - -# class MockConnectionError(Exception): -# """Mock for redis.ConnectionError""" - -# pass - - -# class MockRedis: -# """Mock Redis client for testing.""" - -# def __init__(self, fail_connection=False, fail_operations=False): -# self.data = {} -# self.fail_connection = fail_connection -# self.fail_operations = fail_operations -# self.ping_called = False - -# def ping(self): -# self.ping_called = True -# if self.fail_connection: -# raise MockConnectionError("Connection failed") -# return True - -# def set(self, key, value, ex=None): -# if self.fail_operations: -# raise MockRedisError("Operation failed") -# self.data[key] = value -# return True - -# def get(self, key): -# if self.fail_operations: -# raise MockRedisError("Operation failed") -# return self.data.get(key) - -# def delete(self, *keys): -# if self.fail_operations: -# raise MockRedisError("Operation failed") -# deleted = 0 -# for key in keys: -# if key in self.data: -# del self.data[key] -# deleted += 1 -# return deleted - -# def keys(self, pattern): -# if self.fail_operations: -# raise MockRedisError("Operation failed") -# if pattern.endswith("*"): -# prefix = pattern[:-1] -# return [key for key in self.data.keys() if key.startswith(prefix)] -# return [key for key in self.data.keys() if key == pattern] - - -# class MockRedisModule: -# ConnectionError = MockConnectionError -# RedisError = MockRedisError -# Redis = MagicMock(return_value=MockRedis()) # Simple one-liner! - - -# def mock_get_redis(): -# return MockRedisModule - - -# def mock_no_redis(): -# return None - - -# class TestRedisCacher: -# """Test cases for RedisCacher with mocked Redis.""" - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_basic_operations(self): -# """Test basic get/set/clear operations.""" -# mock_redis = MockRedis() -# cacher = RedisCacher(connection=mock_redis, key_prefix="test:") - -# # Test empty cache -# assert cacher.get_cached("nonexistent") is None - -# # Test set and get -# cacher.set_cached("key1", "value1") -# assert cacher.get_cached("key1") == "value1" - -# # Test overwrite -# cacher.set_cached("key1", "new_value1") -# assert cacher.get_cached("key1") == "new_value1" - -# # Test multiple keys -# cacher.set_cached("key2", "value2") -# assert cacher.get_cached("key1") == "new_value1" -# assert cacher.get_cached("key2") == "value2" - -# # Test clear -# cacher.clear_cache() -# assert cacher.get_cached("key1") is None -# assert cacher.get_cached("key2") is None - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_key_prefixing(self): -# """Test that keys are properly prefixed.""" -# mock_redis = MockRedis() -# cacher = RedisCacher(connection=mock_redis, key_prefix="myapp:") - -# cacher.set_cached("key1", "value1") - -# # Check that the key is stored with prefix -# assert "myapp:key1" in mock_redis.data -# assert mock_redis.data["myapp:key1"] == "value1" - -# # But retrieval should work without prefix -# assert cacher.get_cached("key1") == "value1" - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_connection_initialization_success(self): -# """Test successful connection initialization.""" -# mock_redis = MockRedis() - -# with patch("logging.info") as mock_log: -# cacher = RedisCacher(connection=mock_redis, key_prefix="test:") -# mock_log.assert_called_once() -# assert "Redis connection established successfully" in str( -# mock_log.call_args -# ) - -# assert mock_redis.ping_called -# assert cacher.is_connected() - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_connection_initialization_failure(self): -# """Test connection initialization failure.""" -# mock_redis = MockRedis(fail_connection=True) - -# with pytest.raises(RuntimeError, match="Redis connection test failed"): -# RedisCacher(connection=mock_redis, key_prefix="test:") - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_new_connection_creation(self): -# """Test creation of new Redis connection when none provided.""" -# cacher = RedisCacher(host="localhost", port=6379, db=0, key_prefix="test:") - -# # Verify Redis was called with correct parameters -# # Get the mock module to verify calls -# mock_module = mock_get_redis() -# mock_module.Redis.assert_called_with( -# host="localhost", -# port=6379, -# db=0, -# password=None, -# socket_timeout=5.0, -# socket_connect_timeout=5.0, -# decode_responses=True, -# ) - -# assert cacher.is_connected() - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_graceful_failure_on_operations(self): -# """Test graceful failure when Redis operations fail during use.""" -# mock_redis = MockRedis() -# cacher = RedisCacher(connection=mock_redis, key_prefix="test:") - -# # Initially should work -# cacher.set_cached("key1", "value1") -# assert cacher.get_cached("key1") == "value1" -# assert cacher.is_connected() - -# # Simulate Redis failure -# mock_redis.fail_operations = True - -# with patch("logging.error") as mock_log: -# # Operations should fail gracefully -# result = cacher.get_cached("key1") -# assert result is None -# assert not cacher.is_connected() -# mock_log.assert_called_once() -# assert "Redis get failed" in str(mock_log.call_args) - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_set_failure_handling(self): -# """Test handling of set operation failures.""" -# mock_redis = MockRedis() -# cacher = RedisCacher(connection=mock_redis, key_prefix="test:") - -# # Simulate set failure -# mock_redis.fail_operations = True - -# with patch("logging.error") as mock_log: -# cacher.set_cached("key1", "value1") # Should not raise -# mock_log.assert_called_once() -# assert "Redis set failed" in str(mock_log.call_args) -# assert not cacher.is_connected() - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_clear_cache_failure_handling(self): -# """Test handling of clear cache operation failures.""" -# mock_redis = MockRedis() -# cacher = RedisCacher(connection=mock_redis, key_prefix="test:") - -# # Add some data first -# cacher.set_cached("key1", "value1") - -# # Simulate clear failure -# mock_redis.fail_operations = True - -# with patch("logging.error") as mock_log: -# cacher.clear_cache() # Should not raise -# mock_log.assert_called_once() -# assert "Redis clear failed" in str(mock_log.call_args) -# assert not cacher.is_connected() - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_clear_cache_with_pattern_matching(self): -# """Test that clear_cache only removes keys with the correct prefix.""" -# mock_redis = MockRedis() - -# # Manually add keys with different prefixes -# mock_redis.data["test:key1"] = "value1" -# mock_redis.data["test:key2"] = "value2" -# mock_redis.data["other:key1"] = "other_value1" - -# cacher = RedisCacher(connection=mock_redis, key_prefix="test:") -# cacher.clear_cache() - -# # Only keys with "test:" prefix should be removed -# assert "test:key1" not in mock_redis.data -# assert "test:key2" not in mock_redis.data -# assert "other:key1" in mock_redis.data # Should remain - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_connection_reset(self): -# """Test connection reset functionality.""" -# mock_redis = MockRedis() -# cacher = RedisCacher(connection=mock_redis, key_prefix="test:") - -# # Simulate connection failure -# mock_redis.fail_operations = True -# cacher.get_cached("key1") # This should mark connection as failed -# assert not cacher.is_connected() - -# # Reset connection -# mock_redis.fail_operations = False # Fix the "connection" - -# with patch("logging.info") as mock_log: -# success = cacher.reset_connection() -# assert success -# assert cacher.is_connected() -# # Check that the reset message was logged (it should be the last call) -# mock_log.assert_called_with("Redis connection successfully reset") - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_connection_reset_failure(self): -# """Test connection reset failure handling.""" -# mock_redis = MockRedis() -# cacher = RedisCacher(connection=mock_redis, key_prefix="test:") - -# # Simulate connection failure -# mock_redis.fail_operations = True -# cacher.get_cached("key1") # Mark connection as failed - -# # Keep connection broken for reset attempt -# mock_redis.fail_connection = True - -# with patch("logging.error") as mock_log: -# success = cacher.reset_connection() -# assert not success -# assert not cacher.is_connected() -# # Check that the reset failure message was logged (should be the last call) -# mock_log.assert_called_with( -# "Failed to reset Redis connection: Redis connection test failed: Connection failed" -# ) - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_error_logging_only_once(self): -# """Test that errors are only logged once per failure.""" -# mock_redis = MockRedis() -# cacher = RedisCacher(connection=mock_redis, key_prefix="test:") - -# # Simulate failure -# mock_redis.fail_operations = True - -# with patch("logging.error") as mock_log: -# # Multiple operations should only log error once -# cacher.get_cached("key1") -# cacher.get_cached("key2") -# cacher.set_cached("key3", "value3") - -# # Should only log the first error -# assert mock_log.call_count == 1 - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_default_key_prefix(self): -# """Test default key prefix behavior.""" -# mock_redis = MockRedis() -# # Don't specify key_prefix, should use default -# cacher = RedisCacher(connection=mock_redis) - -# cacher.set_cached("key1", "value1") - -# # Should use default prefix "cache:" -# assert "cache:key1" in mock_redis.data -# assert cacher.get_cached("key1") == "value1" - -# def test_redis_not_available(self): -# """Test behavior when redis package is not available.""" -# with patch("orcapod.hashing.string_cachers._get_redis", mock_no_redis): -# with pytest.raises(ImportError, match="redis package is required"): -# RedisCacher() - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_connection_test_key_access_failure(self): -# """Test failure when connection test can't create/access test key.""" - -# # Create a MockRedis that allows ping but fails key verification -# class FailingKeyMockRedis(MockRedis): -# def get(self, key): -# if key.endswith("__connection_test__"): -# return "wrong_value" # Return wrong value for test key -# return super().get(key) - -# mock_redis = FailingKeyMockRedis() - -# with pytest.raises(RuntimeError, match="Redis connection test failed"): -# RedisCacher(connection=mock_redis, key_prefix="test:") - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_thread_safety(self): -# """Test thread safety of Redis operations.""" -# import threading - -# mock_redis = MockRedis() -# cacher = RedisCacher(connection=mock_redis, key_prefix="thread_test:") - -# results = {} -# errors = [] - -# def worker(thread_id: int): -# try: -# for i in range(50): -# key = f"thread{thread_id}_key{i}" -# value = f"thread{thread_id}_value{i}" -# cacher.set_cached(key, value) - -# # Verify immediately -# result = cacher.get_cached(key) -# if result != value: -# errors.append( -# f"Thread {thread_id}: Expected {value}, got {result}" -# ) - -# # Final verification -# thread_results = [] -# for i in range(50): -# key = f"thread{thread_id}_key{i}" -# result = cacher.get_cached(key) -# thread_results.append(result) - -# results[thread_id] = thread_results - -# except Exception as e: -# errors.append(e) - -# # Start multiple threads -# threads = [] -# for i in range(3): -# t = threading.Thread(target=worker, args=(i,)) -# threads.append(t) -# t.start() - -# # Wait for completion -# for t in threads: -# t.join() - -# # Check for errors -# assert not errors, f"Thread safety errors: {errors}" - -# # Verify each thread's results -# for thread_id in range(3): -# thread_results = results[thread_id] -# for i, result in enumerate(thread_results): -# expected = f"thread{thread_id}_value{i}" -# assert result == expected - -# @patch("orcapod.hashing.string_cachers._get_redis", mock_get_redis) -# def test_operations_after_connection_failure(self): -# """Test that operations return None/do nothing after connection failure.""" -# mock_redis = MockRedis() -# cacher = RedisCacher(connection=mock_redis, key_prefix="test:") - -# # Add some data initially -# cacher.set_cached("key1", "value1") -# assert cacher.get_cached("key1") == "value1" - -# # Simulate connection failure -# mock_redis.fail_operations = True - -# # This should mark connection as failed -# result = cacher.get_cached("key1") -# assert result is None -# assert not cacher.is_connected() - -# # All subsequent operations should return None/do nothing without trying Redis -# assert cacher.get_cached("key2") is None -# cacher.set_cached("key3", "value3") # Should do nothing -# cacher.clear_cache() # Should do nothing - -# # Redis should not receive any more calls after initial failure -# call_count_before = len([k for k in mock_redis.data.keys()]) -# cacher.set_cached("key4", "value4") -# call_count_after = len([k for k in mock_redis.data.keys()]) -# assert call_count_before == call_count_after # No new calls to Redis diff --git a/tests/test_pipeline/test_stored_data_context.py b/tests/test_pipeline/test_stored_data_context.py index d18745265..668139490 100644 --- a/tests/test_pipeline/test_stored_data_context.py +++ b/tests/test_pipeline/test_stored_data_context.py @@ -1263,7 +1263,7 @@ class TestInputOfAnotherDataContext: These tests construct the nodes and caches directly. They do not cover a ``PipelineJob``: a job wraps every input stream in a source node of the default data context, so an input of another data context is not seen as such there (a - known gap, ``design_issues/ITL-944-DC1.md``, ITL-951). + known gap, ``docs/dev/design_issues/ITL-944-DC1.md``, ITL-951). """ def test_function_node_raises_and_writes_nothing(self, store: Store):