Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify language about different types of QREF objects. #118

Open
mstechly opened this issue Sep 4, 2024 · 1 comment
Open

Clarify language about different types of QREF objects. #118

mstechly opened this issue Sep 4, 2024 · 1 comment
Labels
documentation Improvements or additions to documentation

Comments

@mstechly
Copy link
Contributor

mstechly commented Sep 4, 2024

Currently QREF objects can come in different forms:

  1. Saved to a file
  2. Represented as a dictionary
  3. Instances of pydantic models (SchemaV1)

This introduces some ambiguity, as when we say "QREF object", we could mean any of these.

It would be good to clarify the language here, below is a proposal for this:

  1. "QREF file" would refer to a JSON or YAML file adhering to QREF schema
  2. "QREF dictionary" would refer to a Python dictionary adhering to QREF schema
  3. "QREF object" would refer to an instance of QREF pydantic model

Keep in mind that in future QREF pydantic models might become generic (i.e. they would support not only strings as expressions, but also other types, e.g.: sympy expressions). In such case we could imagine having dictionaries containing non-native expression types. Such dictionary would be a valid input for creating a QREF object. However, we should not call it "QREF dictionary", as it is not JSON/YAML-serializable.

Once we agree on what the good naming is, we should update documentation (including docstrings!) accordingly.

CC: @dexter2206 @sammorley-short

@mstechly mstechly added the documentation Improvements or additions to documentation label Sep 4, 2024
@sammorley-short
Copy link

Yep, am happy with that!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Development

No branches or pull requests

2 participants