This release includes most if not all of the **breaking changes that will go into version 1.0.0 of citrine-python**. Updating your libraries and scripts to work with this release will **facilitate a smooth migration** to version 1.0.0.
The two most notable changes are **the removal of deprecated code** and **stricter enforcement of keyword arguments**. If you run into errors after updating, it can likely be fixed by adapting to one of these changes.
Removal of Deprecated Code
If you are using a deprecated class, method, or argument, and are unsure of what to use instead, please see the comprehensive list in the "Deprecated and Removed Items" section below. For each removed item it describes the updated way to achieve the same functionality. In most cases a simple name change suffices. In a few cases there is some migration work, and how to do that is explained below.
Of particular note are the classes that have been removed after being superseded by a comparable yet slightly different class: `GeneralizedMeanPropertyPredictor`, `DeprecatedExpressionPredictor`, `PerformanceWorkflow`, and `CrossValidationAnalysisConfiguration`. Resources of these types will no longer render in citrine-python.
Enforced Keyword Arguments
Keyword arguments are enforced in python by placing an asterisk in a method signature. All arguments after the asterisk must be specified with keywords. For example, the `TableConfigCollection` signature `get(self, uid, *, version=None)` means that the call `tables.get(my_uid, my_version)` is not valid. Instead, you must use a keyword for `version`: `tables.get(my_uid, version=my_version)`. A keyword for `uid` is optional. Citrine-python currently enforces keyword arguments in many places; this release makes their usage broad and consistent. Migrating to consistent enforcement of keyword arguments makes code written on top of citrine-python more legible and easier to maintain.
Other Changes
The other changes in this release are backwards compatible or non-user-facing and hence do not require immediate migration, though implementing these change will result in a better experience. We've made terminology more consistent, made it easier to share resources between projects, improved the performance of the gemd-python library, and more. Details are below.
What's New
* Keyword arguments are enforced more broadly and consistently (628). [Keyword-only arguments](https://www.python.org/dev/peps/pep-3102/) make code developed on top of citrine-python easier to read and easier to maintain. All **externally-facing methods now require keywords** be used for all arguments, with the **exception of the first argument if and only if that argument is stable, ubiquitous, and its meaning is obvious**. See "New Keyword-Only Arguments", below, for a complete list.
* Gem Variables `TerminalMaterialInfo` and `TerminalMaterialIdentifier` should now be used in place of `RootInfo` and `RootIdentifier` (618). This is part of a standardization on the term "terminal material" to describe the ultimate material in a GEMD material history.
* The input descriptor of a `MolecularStructureFeaturizer` is now called `input_descriptor`, not `descriptor` (622). This aligns its behavior with that of the other featurizers.
What's Gone
* **A large number of long-deprecated classes, methods, and arguments have been removed** (616). See "Deprecated and Removed Items" section, below, for a complete list.
* **Non-user-facing arguments have been removed from constructor methods**, making docstrings more concise and easier to read (620, 630). These attributes are automatically assigned when the object is built, and it is unlikely that their removal will affect your code. If you find that your code *is* setting one of these arguments, you can safely remove it.
Improvements
* Several improvements to gemd-python, described in their [release notes](https://github.com/CitrineInformatics/gemd-python/releases/tag/v0.18.1).
* The method to share a resource between projects, `ProjectCollection.share()`, now has a simpler interface (617).
* The `list()` method for GEMD object collections now returns an `Iterator`, not a `List` (621). This aligns its behavior with the rest of the client and leads to better performance.
* A new `Citrine` instance now by default reads the api key and host from the environment variables `CITRINE_API_KEY` and `CITRINE_API_HOST` (625).
* Doc improvements (619, 623, 627)
Coming Soon
* The ability to list archived design workflows
* Official release of Citrine-python version 1.0.0!
Deprecated and Removed Items
The following have been changed or removed after being deprecated for at least one month:
* All `RealDescriptor` objects must have units specified. If the quantity is dimensionless, set `units=''`, or `units='dimensionless'`
* The `training_data` field in a `Predictor`, if specified, must be a list. If a `Predictor` has a single training data source, wrap it in brackets: `training_data=[my_data_source]`.
* A `collection`, such as `workflow.design_executions`, must be specified when using the utility method `wait_while_executing()`
* Removed items:
* All references to `Ara`, which was the development codename for Gem Tables
* Class `Table`, which is now `GemTable`
* Method `GemTable.read()`, instead use `GemTableCollection.read()`
* Attribute `TableConfig.definition_uid`, instead use `TableConfig.config_uid`
* Method `TableConfigCollection.get_job_status()`, instead use `initiate_build()` to kick off table building and `get_by_build_job()` to synchronously get the table
* Class `CrossValidationAnalysisConfiguration`, instead use `CrossValidationEvaluator`
* Class `CategoricalConstraint`, instead use `AcceptableCategoriesConstraint`
* Arguments `min`, `max`, `min_inclusive`, and `max_inclusive` in `ScalarRangeConstraint`, instead use `lower`, `upper`, `lower_inclusive`, and `upper_inclusive`
* Class `GeneralizedMeanPropertyPredictor`, instead use `MeanPropertyPredictor` ([migration guide](https://github.com/CitrineInformatics/citrine-python/blob/c3c7c4db406bdb72c851918b47392f280046e45c/src/citrine/informatics/predictors/generalized_mean_property_predictor.py#L19))
* Class `DeprecatedExpressionPredictor`, instead use `ExpressionPredictor` ([migration guide](https://github.com/CitrineInformatics/citrine-python/blob/c3c7c4db406bdb72c851918b47392f280046e45c/src/citrine/informatics/predictors/expression_predictor.py#L73))
* Argument `max_size` in `EnumeratedProcessor`, instead use `max_candidates`
* Class `WorkflowExecution`, instead use specific classes `DesignExecution` or `PredictorEvaluationExecution`
* Class `WorkflowExecutionCollection`, accessed with `project.workflows`, instead use specific collections `project.design_workflows` or `project.predictor_evaluation_workflows`
* Class `PerformanceWorkflow`, instead use `PredictorEvaluationWorkflow`
* Methods `filter_by_....()`, instead use corresponding `list_by_...()` (e.g., use `list_by_tag()` instead of `filter_by_tag()`). The `filter_by_...()` methods have better performance.
New Keyword-Only Arguments
The following methods and constructors now require keywords be used for all arguments, unless otherwise noted:
* Constructors
* All `Constraint` constructors
* All `DataSource` constructors
* All `Descriptor` constructors, although no keyword is required for the first argument, `key`
* All `Predictor`, `DesignSpace`, `Processor`, `Workflow`, and `PredictorEvaluator` constructors, although no keyword is required for the first argument, `name`
* All `Variable` constructors already require keyword-arguments, but the first argument, `name`, is now exempt
* All `Dimension` constructors, although no keyword is required for the first argument, `descriptor`
* All `PredictorEvaluationMetric` constructors
* `ProjectMember()`
* `TableConfig()`
* `Project()`
* `Dataset()`
* `User()`
* Methods
* Most register/get/update/list/delete methods have one primary argument that does not require a keyword. If there are additional arguments then they do require keywords and are generally optional. Examples and special cases:
* A call to `update()` does not require a keyword, since the only argument is the `model` to be updated.
* A call to `delete()` does not require a keyword for the first argument, `uid`, but requires a keyword for any subsequent optional parameters, such as `dry_run`.
* The GEMD method `list_by_tag()` does not require a keyword for the first argument, `tag`, but requires keywords for subsequent optional arguments.
* `list()` methods have no required arguments. The optional parameters, such as `page` or `per_page`, require keywords.
* `UserCollection.register()` requires keywords for all arguments, since it uses distinctive parameters.
* `DescriptorMethods.from_predictor_responses()` and `DescriptorMethods.descriptors_from_data_source()`
* `DesignExecution.candidates()`
* `DesignSpaceCollection.create_default()`
* `FileCollection.upload()`, `FileCollection.download()`, and `FileCollection.process()`
* `PredictorEvaluationWorkflowCollection.create_default()`
* `PlatformVocabulary()` and `PlatformVocabulary.from_templates()`
* Utility methods for asynchronous tasks: `wait_while_validating()`, `wait_while_executing()`, and `wait_for_asynchronous_object()`
* Utility seeding methods, such as `find_collection()` and `find_or_create_project()`
* `ProjectCollection.transfer_resource()`, `ProjectCollection.search()`, and `ProjectCollection.update_user_role`)