Feature: Python XLR/DSL Support and DSL Class Generator

[KetanReddy]

Whats in this PR?

Python XLR Support

The first and most foundational part of the PR is the player_tools_xlr_types library. This library aims to be a complement to the @player-tools/xlr to bring XLR functionality to Python. At its core there are three parts. The class definitions for the XLR nodes themselves to make it possible to represent the AST natively, functions to act similarly to type guards in TypeScript to make it easy to work with the XLR nodes natively, and de-serialization logic to bring the XLRs into Python.

Python DSL Support

As a complement to the player_tools_xlr_types library, the player_tools_dsl aims to provide Python classes to represent the various parts of a Player Flow, similar to what the @player-ui/types package does. Similarly, this package doesn't contain a lot of logic apart from the serialization logic in the Serializable class to allow for custom recursive serialization. A few things that are handled specially is:

• The remapping of properties that might have had to be renamed (stored in the _propMap dict) as they couldn't be accurately represented in Python
• The ignoring of private properties/internal methods

While there could be an argument that these classes belong in the player repository there are a couple reasons there are a couple reasons why they are not yet. Primarily there just isn't the need for them to be part of "runtime" Player until we have a Python Player so they will primarily be used for content authoring and better align to be here. Eventually when full Python generation (something that will be touched on in the next section) is complete a majority of the classes may be removed from here, however certain classes will always have to exist as (similar to the React DSL) the way that they are interacted with during content authoring is different from how they are represented at runtime.

Python DSL Class Generator

The star of this PR is the player_tools_dsl_generator library. Combining both of the other foundational libraries this module ties everything together by reading in the XLRs generated from an XLR enabled plugin and create Python class representations of the Assets/Views.

At this point it should be noted that this is an opinionated generator. Unlike the TSWriter class from the @player-tools/xlr-converters package (which is a very literal 1:1 converter to make an interface) this converter makes Assets/Views and therefore makes assumptions on things like naming conventions, structure, and contextual interpretations.

The basic logic of the assets it generates are:

• Each XLR generates one top level asset and potentially multiple sub-classes to represent nested objects
• Each object has an initialization method where every non id/type/constant parameter can be optionally provided
• Each property has a "with" function that represents a way to set the property after initialization.
  • Properties that take a single value will have a single with function
  • Properties that take multiple will have two
    • One to supply a single value that is appended to an array
    • One to supply all values in one invocation (note: this will override any existing values)
  • These function return the class instance allowing these functions to be chained

This module can be invoked directly to mimic a CLI tool to make it easy to integrate in a build process. The arguments that can be supplied is:

• -i to specify the input directory which should contain a module.json
• -o to specify where the generated files should live (default is the current working directory)

Change Type (required)

Indicate the type of change your pull request is:

• patch
• minor
• major

Release Notes

Welcome Python to Player Tools 🎉. There are three new packages published from this repository all in support for generating Player content via Python classes.

• player_tools_xlr_types - Classes to represent XLR ASTs in Python and a de-serialization utility to read in XLRs from a manifest file.
• player_tools_dsl - Basic DSL constructs represented as Python classes and content serialization logic.
• player_tools_dsl_generator - DSL class generation using XLRs.

Currently Python support should be considered in Alpha as it is not at feature parity with the React based DSL. Notable things still under development are:

• Native Schema Support
• Native Binding/Expression Support
• Expression Helper Generation
• Data Type Generation

Stay tuned for updates on those!

📦 Published PR as canary version: 0.13.0--canary.231.5717

Try this version out locally by upgrading relevant packages to 0.13.0--canary.231.5717

[codecov]

Codecov Report

❌ Patch coverage is 84.48374% with 272 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.28%. Comparing base (c307cff) to head (b3e6f42).
⚠️ Report is 34 commits behind head on main.

Files with missing lines	Patch %	Lines
xlr/types/python/src/nodes.py	81.74%	96 Missing ⚠️
language/generators/python/src/generator.py	73.90%	88 Missing and 1 partial ⚠️
xlr/types/python/src/deserializer.py	69.03%	48 Missing ⚠️
language/generators/python/src/__main__.py	0.00%	33 Missing ⚠️
cli/src/commands/dsl/compile.ts	0.00%	2 Missing ⚠️
language/dsl/python/src/view.py	98.27%	1 Missing and 1 partial ⚠️
language/dsl/python/src/navigation.py	99.42%	1 Missing ⚠️
language/dsl/python/src/utils.py	97.56%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #231      +/-   ##
==========================================
- Coverage   68.12%   64.28%   -3.84%     
==========================================
  Files          91      128      +37     
  Lines        9518    13006    +3488     
  Branches     1338     1867     +529     
==========================================
+ Hits         6484     8361    +1877     
- Misses       3009     4617    +1608     
- Partials       25       28       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[sugarmanz]

The brunt of the logic I am unable to really review cause I don't have a ton of context into how it all works together — a walkthrough would help a ton to understand the happenings.

Additional comment:

Should I be expecting the Python XLR implementation organization to match the TS one? Definitely want to respect idiomatic language paradigms, but it does make it a bit tougher to map the logic between the two.

[KetanReddy]

Should I be expecting the Python XLR implementation organization to match the TS one? Definitely want to respect idiomatic language paradigms, but it does make it a bit tougher to map the logic between the two.

I think that a central decision I think we'll need to make as part of this. I am leaning slightly towards the side of "concepts should be consistent within the ecosystem rather than the larger language" since it allows for the easier association of ideas as you move around in the Player ecosystem.

[KetanReddy]

/canary

[KetanReddy]

/canary

[KetanReddy]

/canary

[KetanReddy]

/canary

[KetanReddy]

/canary

[KetanReddy]

/canary

[KetanReddy]

/canary

[KetanReddy]

/canary

[KetanReddy]

/canary

[KetanReddy]

/canary