Deprecating classes used by global singletons is challenging

[verult]

Description of the issue

Example: SerializableGateSets

When we have a global singleton such as:

SYC_GATESET = cg.SerializableGateSet(...)

deprecating SerializableGateSet will cause tests to fail because all calls which raise deprecations must be declared in tests (using cirq.testing.assert_deprecated()), and because SYC_GATESET is loaded in init files, it's not possible to declare them within any particular unit test.

Possible solutions:

• Prior to 1.0, we could've first deprecated global singletons and then remove global singletons and deprecate the class in two separate minor releases. This is no longer possible after 1.0 and before 2.0.
• [Doesn't apply to the PR above] If SYC_GATESET doesn't need to be deprecated, SYC_GATESET could have been annotated with a more general type than SerializableGateSet, if possible, and the instance could have been swapped with a replacement class.
• [Used by the PR above] deprecate an empty SerializableGateSet shell class that subclasses from _SerializableGateSet, which contains the class implementation. Change SYC_GATESET to cg._SerializableGateSet(...). A bit hacky.
• Lazy load SYC_GATESET using PEP 562. If SYC_GATESET also needs to be deprecated, it's unclear how PEP 562 interacts with _compat.deprecate_attributes.
• Relax the constraint that every deprecation must be declared in tests. Is it possible to enforce deprecation declarations in the companion test file only, i.e. serializable_gate_set_test.py?

Relaxing the constraint, if possible, will also reduce the workload for large deprecations. Adding deprecation declarations in tests is a tedious manual process. Large regex-based search & replace helps but only to an extent - the declarations need to be inserted slightly differently depending on how the test code is structured. If there's a looser guarantee that protects against most deprecation errors and has significantly less manual work, that'd be ideal.

Cirq version
Cirq 1.0

[verult]

Pytest fixtures could potentially help us eliminate the hard requirement of declaring deprecations in tests. @pavoljuhas

[pavoljuhas]

Cirq deprecation decorators use the CIRQ_TESTING environment variable to determine if a deprecated code is used in test session or otherwise, and, correspondingly if they should raise error or show deprecation warning. The CIRQ_TESTING environment variable is set in the conftest.py pytest_configure hook functions, for example, here

Cirq/cirq-aqt/cirq_aqt/conftest.py

Lines 18 to 19 in 97781c7

	def pytest_configure(config) -> None:
	os.environ['CIRQ_TESTING'] = "true"

We can thus import (and thus create) any deprecated instances in the top-level conftest.py, so they are initialized before decorators find out they are in test session. If necessary we can also use the unittest.mock.patch.dict(os.environ, clear="CIRQ_TESTING") context to temporarily suppress test detection.

I am not aware of running into this problem for a while so I am closing this issue as wontfix.