Metadata-Version: 2.5
Name: oleander-kedro
Version: 0.0.1
Summary: Declare Oleander metadata on ordinary Kedro pipelines
Requires-Python: >=3.10
Requires-Dist: croniter<7,>=6
Requires-Dist: email-validator<3,>=2.3
Requires-Dist: kedro<1.8,>=1.7
Requires-Dist: tzdata>=2025.2
Description-Content-Type: text/markdown

# oleander-kedro

Public Python package for declaring Oleander metadata on standard Kedro pipelines.
Requires **Python >=3.10** and **Kedro >=1.7,<1.8**. Intended for distribution on
PyPI; it has no Oleander SDK or cloud dependencies.

## Author pipelines

Add this package to your Kedro project's dependencies, then decorate pipeline
factories:

```python
from kedro.pipeline import node, pipeline
from oleander_kedro import run_as, schedule


@run_as("sales-pipeline@iam.application.oleander.dev")
@schedule(cron="0 * * * *", timezone="UTC")
def create_pipeline(**kwargs):
    return pipeline([node(print, "params:message", None, name="print_message")])
```

Register pipelines using the usual `register_pipelines()` function, optionally
calling `find_pipelines(raise_errors=True)`. Authors use conventional Kedro:

```sh
uv run kedro run --pipelines orders
```

This package installs **no command or Kedro hooks**. Normal `kedro run` executes
ordinary Kedro pipelines without applying schedules, selecting identities, or
injecting intervals. Kedro's catalog and parameter behavior remains unchanged.
Decorators still validate their arguments and factory return types; invalid
declarations fail early.

## Declarations

- `@schedule(cron=..., timezone=...)` requires basic five-field cron syntax:
  numeric fields with `*`, `,`, `-`, and `/`, plus an explicit IANA timezone.
  For example, `0 9 * * 1-5` runs on weekdays at 09:00. Named months/weekdays
  and extensions such as `L5`, `L`, `W`, `#`, `H`, `R`, and `?` are rejected
  at declaration time, as are macros, seconds, and year expressions. Whitespace
  is normalized. Croniter validates field values and expression structure;
  its day-of-month/day-of-week convention is OR. Oleander's scheduler must
  use the same interpretation.
  Ranges must be ascending: use `22-23,0-2` instead of `22-2` for hours that
  cross midnight. List entries must not repeat or overlap values, including
  overlaps introduced by steps. Sunday may be `0` or `7`, but `0,7` is a
  duplicate. A single full-week range such as `0-7` remains valid.
- `@run_as(email)` requires one email address. UUIDs, principal names, display
  names, and address lists are rejected. Surrounding whitespace is stripped and
  the address is lowercased and normalized to match Oleander's email convention.
  Validation checks syntax locally, without DNS queries or delivery checks.
  It declares the desired principal for **scheduled** execution only. It grants
  no permissions and never changes the identity of a manual run. The example
  application-principal email is a placeholder; it need not exist for local tests.
- Either decorator order works. Duplicate declarations are errors. Factories
  preserve their signatures, names, and docstrings and return ordinary Kedro
  `Pipeline` objects.
- Metadata belongs to the exact returned object. Copying, composing, filtering,
  or namespacing a pipeline does not carry declarations forward. Decorate the
  factory returning the final scheduled pipeline.

Oleander's private discovery/runtime validates the complete registry: pipelines
must declare both decorators or neither, and the same scheduled object cannot
appear under multiple registry names. Undecorated pipelines are discoverable
and can be run manually. Conventional Kedro does not enforce these Oleander
registry rules.

The deployment service must resolve the declared email to an existing principal
within the organization linked to the GitHub installation, authorize the
repository-to-principal binding, and store the resolved UUID with the deployment.
Missing, ambiguous, or unauthorized principals must fail deployment. Scheduled
runs use that stored UUID so email changes cannot silently change the execution
identity. This resolution and authorization belongs to Oleander's service; neither
Python package performs it. Principal membership and access must be rechecked at
execution time.

## Metadata API

Private platform tools read metadata through the public, side-effect-free API:

```python
from oleander_kedro import get_pipeline_metadata

metadata = get_pipeline_metadata(create_pipeline())
print(metadata.schedule.cron)
print(metadata.run_as)
```

The returned `Declaration` and nested `Schedule` are frozen dataclasses.
`Declaration.run_as` contains the normalized email string.
Undecorated pipelines return a `Declaration` with both fields set to `None`.
`ConfigurationError` subclasses `ValueError`.

## Development

From this directory:

```sh
uv sync --locked
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv build
```

`.python-version` selects Python 3.10. Tests cover declaration validation and
real `kedro run` invocations with plain Python nodes and no SDK credentials.

From the repository root, also run the cross-language cron compatibility tests:

```sh
uv sync --locked --project kedro/oleander-kedro-cli
yarn exec vitest run workflows/kedro/manifest-compatibility.test.ts
```

These tests require the repository's Node dependencies and `uv`. They use the
same cron fixtures as the Python tests, generate manifests with the actual
Python decorators and CLI, and validate them with the TypeScript worker's
`parseManifest()`. No cloud services are involved.

The separate [private CLI project](../oleander-kedro-cli/README.md) depends on this
package and owns discovery, runtime interval injection, and the `oleander-kedro`
command.
It is not part of this distribution.

## Publishing

The [publishing workflow](../../.github/workflows/publish-oleander-kedro.yml)
builds and publishes this extension when changes under `kedro/oleander-kedro-ext/`
reach `main`. It uses the existing GitHub Actions `PYPI_TOKEN` secret and skips
already-published artifacts, following the Python SDK's release pattern.

To release a new version, update `version` in `pyproject.toml` and refresh this
project's `uv.lock`. Update the private CLI's exact extension dependency and its
lockfile to the same version, then merge to `main`. The builder release workflow
also rebuilds its bundled packages when these directories change. The private
CLI is not published to PyPI.
