Migration documentation needs more context

[clif-cisco]

The current migration documentation states the following.

webexpythonsdk is designed to be a drop-in replacement for the webexteamssdk package. The SDK interface and data objects are largely unchanged with only a few minor name changes.

Unfortunately, this is extremely misleading.

The upgrade from Adaptive Card 1.1 to 1.3 605bc7d ... 9d25de7 moved a number of classes, removed multiple modules, and changed some functionality. The API documentation also has multiple references to the previous implementation.

webexpythonsdk.models.cards.components and webexpythonsdk.models.cards.container no longer exist and the contents were broken up into .card_elements, .containers, and .inputs.

Various attributes now force specific enums to be passed, breaking backwards compatibility. As an example, TextBlock.color could previously be set with a string such as "Light". With the new validate_input enforcement, a Colors enum must be passed.

It would be helpful if wrapper classes were added as well as a module flag to sidestep validate_input to maintain drop-in compatibility.

Or, at the very least, please update the migration documentation with a clear table of changes.

(Note that my findings are not exhaustive. There may be other differences as well.)

[clif-cisco]

A drop-in wrapper for components.py

from .actions import OpenUrl, Submit
from .adaptive_card_component import AdaptiveCardComponent
from .card_elements import Image, Media, MediaSource, TextBlock
from .containers import Column, Fact
from .inputs import Choice
from .options import (
    BlockElementHeight,
    ImageSize,
    ImageStyle,
    Spacing,
    HorizontalAlignment,
)
from .utils import check_type

A drop-in wrapper for container.py

from .adaptive_card_component import AdaptiveCardComponent
from .containers import Container, ColumnSet, FactSet, ImageSet

(Github won't let me attach .py files.)

[Sakthivel-Ramasamy]

Wrapper is already available. Can you please try it the following way?

from webexpythonsdk.models.cards import TextBlock, FontWeight, FontSize, Column, AdaptiveCard

Note: This wrapper was available even before the migration from Adaptive Card 1.1 to 1.3 was done.

[Sakthivel-Ramasamy]

validate_input() is backward compatible to accept the values directly, but it should be case sensitive.

From your message above, I can see you are passing Light to TextBlock.color. The actual value that should have been passed is light. Reference: https://adaptivecards.io/explorer/TextBlock.html

It is recommended to use Enum class to avoid these case sensitivity issues.

Can you please retry with this mentioned correction and let me know how it goes through?

[clif-cisco]

@Sakthivel-Ramasamy I understand there is a new recommended way to do things. The documentation is completely devoid of this information still references calls to the previously existing modules.

It would be extremely useful if either the documentation reflected all of these changes instead of stating it is a "drop-in replacement", or the package was updated to maintain backwards compatibility with webexteamssdk as the documentation claims it currently does.

[Joezanini]

Hello team, just submitted PR

[ashjorda]

@clif-cisco I just merged @Joezanini PR. Would like your confirmation that you find the PR sufficient to resolve your issue.