[v4.0] Update use of type annotations by anoto-moniz · Pull Request #1017 · CitrineInformatics/citrine-python

anoto-moniz · 2026-02-17T20:25:19Z

A handful of updates and improvements came into type annotations in Python 3.9 and 3.10. The ones most relevant to us are the introduction of | for union types, the ability to use builtin classes as annotations (i.e. list), and the deprecation of a handful of types in typing in favor of referencing them in collections.abc.

We could also replace our usages of Optional[T] with T | None, but the latter syntax doesn't seem as clear to me.

We're also clear to start using match statements and the dictionary update operator, it's just harder to identify opportunities for them without knowing where to look.

Note: a couple classes (namely DataConceptsCollection and PredictorEvaluationCollection) still have methods that return List. It seems the list method defined in Collection is conflicting with the built-in in those cases. I'm not sure why, but will be investigating in a follow-up.

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)
Maintenance (non-breaking change to assist developers)

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 __version__.py

As of python 3.9, the builtin classes can be used as type annotations, so there's no need to use the separate "typing" versions (which are also deprecated). Note that data_objects and predictor_evaluation retain List for now, as it conflicts with their definition of a method called "list".

As of python 3.10, unions can be expressed with the pipe (|) operator.

Clean up all the unused imports created by the previous two changes. It was easier to handle them all at once rather than as I went.

Many types introduced as type annotations in typing are now available for use from collections.abc. The typing versions are deprecated, so we switch to these newer versions. For us, this impacts Sequence, Iterator, Iterable, Callable, and (in one place) Collection.

kroenlein

I transformed a lot of Optional[x] to x | None, and there are a lot more left. Seems like it's the better pattern.

kroenlein · 2026-02-17T22:59:06Z

src/citrine/_serialization/properties.py


    def __init__(self,
-                 klass: typing.Type[typing.Any],
+                 klass: type[typing.Any],


Shouldn't this just be a naked type?

kroenlein · 2026-02-17T23:02:01Z

src/citrine/_utils/batcher.py

    """Batching by clusters where nothing references anything outside the cluster."""

-    def batch(self, objects: Iterable[DataConcepts], batch_size) -> List[List[DataConcepts]]:
+    def batch(self, objects: Iterable[DataConcepts], batch_size) -> list[list[DataConcepts]]:


Suggested change

def batch(self, objects: Iterable[DataConcepts], batch_size) -> list[list[DataConcepts]]:

def batch(self, objects: Iterable[DataConcepts], batch_size: int) -> list[list[DataConcepts]]:

kroenlein · 2026-02-17T23:02:15Z

src/citrine/_utils/batcher.py

    """Batching by object type."""

-    def batch(self, objects: Iterable[DataConcepts], batch_size) -> List[List[DataConcepts]]:
+    def batch(self, objects: Iterable[DataConcepts], batch_size) -> list[list[DataConcepts]]:


Suggested change

def batch(self, objects: Iterable[DataConcepts], batch_size) -> list[list[DataConcepts]]:

def batch(self, objects: Iterable[DataConcepts], batch_size: int) -> list[list[DataConcepts]]:

kroenlein · 2026-02-17T23:06:46Z

src/citrine/informatics/predictors/chemical_formula_featurizer.py

        The list of features to exclude, either by name or by group alias. Default is none.
        The final set of features generated by the predictor is set(features) - set(excludes).
-    powers: Optional[List[float]]
+    powers: Optional[list[int]]


I think maybe an accidental regression?

Suggested change

powers: Optional[list[int]]

powers: Optional[list[float]]

kroenlein · 2026-02-17T23:11:05Z

src/citrine/resources/experiment_datasource.py

+             branch_version_id: Optional[UUID | str] = None,
+             version: Optional[int | str] = None) -> Iterator[ExperimentDataSource]:


kroenlein · 2026-02-17T23:39:40Z

src/citrine/informatics/predictors/graph_predictor.py

-                 predictors: List[PredictorNode],
-                 training_data: Optional[List[DataSource]] = None):
+                 predictors: list[PredictorNode],
+                 training_data: Optional[list[DataSource]] = None):


Suggested change

training_data: Optional[list[DataSource]] = None):

training_data: list[DataSource] | None = None):

kroenlein · 2026-02-17T23:42:49Z

src/citrine/jobs/waiting.py

    -------
-    Union[PredictorEvaluationExecution, DesignExecution, GenerativeDesignExecution,
-          SampleDesignSpaceExecution]
+    ExectutionType


Suggested change

ExectutionType

ExecutionType

kroenlein · 2026-02-17T23:43:38Z

src/citrine/resources/experiment_datasource.py

@@ -1,8 +1,9 @@
 import csv
 import json
+from typing import Iterator


Suggested change

from typing import Iterator

from collections.abc import Iterator

kroenlein · 2026-02-17T23:45:26Z

src/citrine/informatics/constraints/ingredient_ratio_constraint.py

    label: Optional[tuple[str, float]]
        multiplier for a label in the numerator of the ratio
-    basis_ingredients: Optional[Union[list[str], dict[str, float]]]
+    basis_ingredients: Optional[list[str] | dict[str | float]]


Suggested change

basis_ingredients: Optional[list[str] | dict[str | float]]

basis_ingredients: Optional[list[str] | dict[str, float]]

kroenlein · 2026-02-17T23:45:38Z

src/citrine/informatics/constraints/ingredient_ratio_constraint.py

+    basis_ingredients: Optional[list[str] | dict[str | float]]
        the ingredients which should appear in the denominator of the ratio
-    basis_labels: Optional[Union[list[str], dict[str, float]]]
+    basis_labels: Optional[list[str] | dict[str | float]]


Suggested change

basis_labels: Optional[list[str] | dict[str | float]]

basis_labels: Optional[list[str] | dict[str, float]]

kroenlein

I transformed a lot of Optional[x] to x | None, and there are a lot more left. Seems like it's the better pattern.

anoto-moniz added 5 commits February 17, 2026 15:08

Use new union syntax.

0929f11

As of python 3.10, unions can be expressed with the pipe (|) operator.

Drop obsolete typing imports.

78ae264

Clean up all the unused imports created by the previous two changes. It was easier to handle them all at once rather than as I went.

dict update operator

001596f

anoto-moniz marked this pull request as ready for review February 17, 2026 20:35

anoto-moniz requested a review from a team as a code owner February 17, 2026 20:35

kroenlein reviewed Feb 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[v4.0] Update use of type annotations#1017

[v4.0] Update use of type annotations#1017
anoto-moniz wants to merge 5 commits intorelease/v4.0from
use-new-python-features

anoto-moniz commented Feb 17, 2026

Uh oh!

kroenlein left a comment

Uh oh!

kroenlein Feb 17, 2026

Uh oh!

kroenlein Feb 17, 2026

Uh oh!

kroenlein Feb 17, 2026

Uh oh!

kroenlein Feb 17, 2026

Uh oh!

kroenlein Feb 17, 2026

Uh oh!

kroenlein Feb 17, 2026

Uh oh!

kroenlein Feb 17, 2026

Uh oh!

kroenlein Feb 17, 2026

Uh oh!

kroenlein Feb 17, 2026

Uh oh!

kroenlein Feb 17, 2026

Uh oh!

kroenlein left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	def batch(self, objects: Iterable[DataConcepts], batch_size) -> list[list[DataConcepts]]:
	def batch(self, objects: Iterable[DataConcepts], batch_size: int) -> list[list[DataConcepts]]:

		branch_version_id: Optional[UUID \| str] = None,
		version: Optional[int \| str] = None) -> Iterator[ExperimentDataSource]:

	training_data: Optional[list[DataSource]] = None):
	training_data: list[DataSource] \| None = None):

	from typing import Iterator
	from collections.abc import Iterator

	basis_ingredients: Optional[list[str] \| dict[str \| float]]
	basis_ingredients: Optional[list[str] \| dict[str, float]]

	basis_labels: Optional[list[str] \| dict[str \| float]]
	basis_labels: Optional[list[str] \| dict[str, float]]

Conversation

anoto-moniz commented Feb 17, 2026

PR Type:

Adherence to team decisions

Uh oh!

kroenlein left a comment

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!

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!

kroenlein left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants