Skip to content

About

No description, website, or topics provided.

Resources

Code of conduct

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

pyclesperanto runtime API transition-notes generator

This version deliberately uses runtime introspection.

It imports:

import pyclesperanto_prototype
import pyclesperanto

and then compares the public callable API using:

dir(module)
getattr(module, name)
callable(...)
inspect.signature(...)

There is no source-folder parsing.

What it reports

The generated transition notes contain:

  1. Functions in pyclesperanto_prototype but not in pyclesperanto.
  2. Functions present in both libraries whose signatures differ.
  3. Parameter rename candidates for common functions.
  4. Added/removed parameters.
  5. Parameter kind changes.
  6. Default-value changes.
  7. Functions in pyclesperanto but not in pyclesperanto_prototype.

Important assumption

Both libraries must be importable in the Python environment in which this tool runs.

For example:

pip install pyclesperanto pyclesperanto-prototype

or install your local development checkouts into the same environment.

Installation

python -m venv .venv
source .venv/bin/activate

pip install -e .

For tests:

pip install -e ".[dev]"
pytest

Generate transition notes

clesperanto-api-diff --ignore config/api-diff-ignore.toml --output transition_notes.md --json-output transition_notes.json

Equivalent:

python -m api_diff \
  --ignore config/api-diff-ignore.toml \
  --output transition_notes.md

By default it imports:

pyclesperanto_prototype
pyclesperanto

You can override them:

clesperanto-api-diff \
  --prototype-module some_old_module \
  --current-module some_new_module

Ignore functions

config/api-diff-ignore.toml:

[ignore_functions]
both = [
    "some_internal_helper",
]

prototype = [
    "old_function_we_do_not_want_to_document",
]

pyclesperanto = [
    "new_function_we_do_not_want_to_document",
]

Function matching is currently by exact public name.

Ignore parameters

[ignore_parameters.gaussian_blur]
both = ["device"]
prototype = ["destination"]
pyclesperanto = ["output_image"]

Parameter ignores are applied before signature comparison.

This is useful for known differences which should not show up in the generated transition notes.

How rename detection works

For a function present in both libraries:

# pyclesperanto_prototype
def gaussian_blur(source, destination, sigma_x, sigma_y):
    ...

# pyclesperanto
def gaussian_blur(input_image, output_image, sigma_x, sigma_y):
    ...

the comparator sees compatible parameter kinds at the same positions and emits:

source      -> input_image
destination -> output_image

This is intentionally only a rename candidate. Matching position does not prove that the two parameters have identical semantics.

What is considered a function

The runtime scanner:

  • skips names beginning with _;
  • skips classes;
  • requires the object to be callable;
  • requires inspect.signature(object) to succeed.

This means Python functions, wrapped functions, many extension functions, and other inspectable callables can be compared.

Objects for which Python cannot provide a signature are skipped.

JSON output

Use:

--json-output transition_notes.json

The JSON contains the complete extracted runtime API snapshots as well as the computed differences.

Why this implementation is simpler

The package itself defines its public runtime namespace.

By comparing what users actually see after:

import pyclesperanto as cle

we avoid trying to reconstruct exports, aliases, decorators, or generated functions from package source code.

About

No description, website, or topics provided.

Resources

Code of conduct

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages