Document .validate_templates() by dekatzenel · Pull Request #308 · CitrineInformatics/citrine-python

dekatzenel · 2020-04-22T20:11:25Z

Citrine Python PR

Description

Document .validate_templates()

PR Type:

Breaking change (fix or feature that would cause existing functionality to change)
Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)

Adherence to team decisions

I have added tests for 100% coverage
I have written Numpy-style docstrings for every method and class.
I have communicated the downstream consequences of the PR to others.
I have bumped the version in setup.py

…ate-templates

bfolie · 2020-04-22T20:43:54Z

Could you please make it one sentence per line (for ease of future PR review)?

bfolie · 2020-04-22T20:44:14Z

+Template and Simple Validations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Sometimes, it is convenient to be able to bulk validate a group of runs and/or specs against their attribute and object
+templates before any of the data objects is stored. The ``.validate_templates()`` methods, available for all runs and


Suggested change

templates before any of the data objects is stored. The ``.validate_templates()`` methods, available for all runs and

templates before any of the data objects are stored. The ``.validate_templates()`` methods, available for all runs and

bfolie · 2020-04-22T20:59:14Z

+    process_template = ProcessTemplate("pt")
+    process_spec = ProcessSpec("ps", template=process_template)
+    material_spec = MaterialSpec("ms", process=process_spec)
+    ingredient_spec = IngredientSpec("is", process=process_spec, material=material_spec)


Isn't this creating a loop (the process makes the material which is used as an ingredient in the process)?

bfolie · 2020-04-22T20:59:37Z

+    process_spec = ProcessSpec("ps", template=process_template)
+    material_spec = MaterialSpec("ms", process=process_spec)
+    ingredient_spec = IngredientSpec("is", process=process_spec, material=material_spec)
+    dataset.ingredient_specs.validate_templates(run, ingredient_process_template=process_template)


What's run?

bfolie · 2020-04-22T21:05:31Z

+Notably, these methods do not validate linked objects in any way, making it possible to run validations on an object
+with links to yet-unstored objects. Be aware that this means that ``.validate_templates()`` does not validate links and
+will not surface any link-based errors. For ingredients, the associated object template is a process template that is
+provided as a separate parameter. This method returns a list of validation errors, which is empty on validation success.


The sentence about ingredients seems like a secondary set of information: once the reader understands validation in the general case, here's an extra wrinkle for the ingredients case. I suggest it be separated. After explaining and showing examples for typical validation, then explain and show an example for ingredient validation.

bfolie · 2020-04-22T21:06:30Z

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Sometimes, it is convenient to be able to bulk validate a group of runs and/or specs against their attribute and object
+templates before any of the data objects is stored. The ``.validate_templates()`` methods, available for all runs and
+specs, validate the provided object against already-stored attribute templates as well as a provided object template.


Where do these attribute templates come from? Are links to them expected to be in the object template?

Not necessarily. Links are expected to be on the object

bfolie · 2020-04-22T21:12:11Z

Could you expand on the examples? They show the structure of the methods, but their usage would make more sense if some example outputs were shown. Since the successful case results in an empty list, there should be examples of failed validation.

bfolie · 2020-04-22T22:10:44Z

+    material_spec = MaterialSpec("ms", process=mat_process_spec)
+
+    ingredient_spec = IngredientSpec("is", process=process_spec, material=material_spec, labels=["ingredient"])
+    dataset.ingredient_specs.validate_templates(ingredient_spec, ingredient_process_template=process_template)


If the collection is ingredient specs/runs, is the object_template field ignored?

Sort of? It's passed through to the core validation code, which then validates the object template against all attributes that have attribute templates that are also on the object template. But ingredients don't have attributes, so there's nothing to validate the object template against

bfolie · 2020-04-23T00:45:53Z

+
+Template and Simple Validations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Sometimes, it is convenient to be able to bulk validate a group of runs and/or specs against their attribute and object


Suggested change

Sometimes, it is convenient to be able to bulk validate a group of runs and/or specs against their attribute and object

Sometimes, it is convenient to validate a group of runs and/or specs against their attribute and object

bfolie · 2020-04-23T00:46:55Z

+Sometimes, it is convenient to be able to bulk validate a group of runs and/or specs against their attribute and object
+templates before any of the data objects are stored.
+The ``.validate_templates()`` methods, available for all runs and specs, validate the provided object against all of the
+(already-stored) attribute templates linked to attributes on the object as well as an optional provided object template.


Suggested change

(already-stored) attribute templates linked to attributes on the object as well as an optional provided object template.

(already-stored) attribute templates linked to attributes on the object as well as against an optional object template.

bfolie · 2020-04-23T00:48:32Z

+Be aware that this means that ``.validate_templates()`` does not validate links and will not surface any link-based
+errors.


Suggested change

Be aware that this means that ``.validate_templates()`` does not validate links and will not surface any link-based

errors.

Be aware that this means that ``.validate_templates()`` will not surface any link-based errors.

bfolie · 2020-04-23T00:49:57Z

+The below example usages are trivial examples intended to illustrate the method arguments, rather than interesting
+validation cases.


Suggested change

The below example usages are trivial examples intended to illustrate the method arguments, rather than interesting

validation cases.

The examples below illustrate the usage of ``.validate_templates()``.

bfolie · 2020-04-23T00:50:55Z

I made stylistic suggestions. You can incorporate them as you see fit and then I'll approve

Document .validate_templates()

94fac19

dekatzenel requested review from bfolie and maxhutch April 22, 2020 20:11

dekatzenel added 2 commits April 22, 2020 13:40

Merge remote-tracking branch 'origin/master' into documentation/valid…

da7ce90

…ate-templates

Bump version

cbdcbd3

bfolie reviewed Apr 22, 2020

View reviewed changes

Improve clarity of docs & quality of examples for validate_templates()

0b7c7a4

bfolie reviewed Apr 22, 2020

View reviewed changes

bfolie reviewed Apr 23, 2020

View reviewed changes

Text stylistic improvements

3247d57

bfolie approved these changes Apr 23, 2020

View reviewed changes

dekatzenel merged commit 6372559 into master Apr 23, 2020

dekatzenel deleted the documentation/validate-templates branch April 23, 2020 15:28

	templates before any of the data objects is stored. The ``.validate_templates()`` methods, available for all runs and
	templates before any of the data objects are stored. The ``.validate_templates()`` methods, available for all runs and

	Sometimes, it is convenient to be able to bulk validate a group of runs and/or specs against their attribute and object
	Sometimes, it is convenient to validate a group of runs and/or specs against their attribute and object

	(already-stored) attribute templates linked to attributes on the object as well as an optional provided object template.
	(already-stored) attribute templates linked to attributes on the object as well as against an optional object template.

		Be aware that this means that ``.validate_templates()`` does not validate links and will not surface any link-based
		errors.

		The below example usages are trivial examples intended to illustrate the method arguments, rather than interesting
		validation cases.

	The below example usages are trivial examples intended to illustrate the method arguments, rather than interesting
	validation cases.
	The examples below illustrate the usage of ``.validate_templates()``.

Conversation

dekatzenel commented Apr 22, 2020

Citrine Python PR

Description

PR Type:

Adherence to team decisions

Uh oh!

bfolie commented Apr 22, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bfolie commented Apr 22, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bfolie commented Apr 23, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants