[jwrosewell]

What was wrong

Two changes on rc, #97 and #100, gave every environment variable one _51DEGREES_ name and stopped reading the names used before. Neither has been released. A patch release must not take a public name away, and every environment variable name this repository reads is a public name, so each old name has to be read still.

The names main at 0b4081a reads and rc at 435274d does not:

Old name	New name	Read on main by
FOD_CLOUD_API_URL	_51DEGREES_CLOUD_ENDPOINT	The Cloud Request Engine (cloudrequestengine.py line 117), the 51Did client (did_client.py line 472) and the 51Did creator context example (server.py line 126)
resource_key	_51DEGREES_RESOURCE_KEY	The Device Detection cloud tests (test_cloud.py line 53, test_properties.py line 54), the three example helpers (Device Detection line 165, IP Intelligence line 40, Cloud Request Engine line 66), the two Location examples (gettingstarted.py line 43, web.py line 44) and their tests (test_examples.py line 31, test_properties51D.py line 32), the Cloud Request Engine tests (test_cloudengine.py line 36) and the 51Did live tests (test_did_client_live.py line 52)
license_key	_51DEGREES_LICENSE_KEY	The Cloud Request Engine example helper (line 72) and live test (test_licensekey_live.py line 36), the 51Did live tests (line 54) and the two data file update examples (Device Detection lines 172 and 195, IP Intelligence lines 77 and 108)
RESOURCE_KEY, LICENSE_KEY	_51DEGREES_RESOURCE_KEY, _51DEGREES_LICENSE_KEY	The 51Did creator context example (server.py lines 115 and 116)
cloud_endpoint	_51DEGREES_CLOUD_ENDPOINT	The three example helpers (Device Detection line 49, IP Intelligence line 42, Cloud Request Engine line 53)
RESOURCE_KEY, CLOUD_ENDPOINT	_51DEGREES_RESOURCE_KEY, _51DEGREES_CLOUD_ENDPOINT	The IP Intelligence example helper, which read each of its two names a second time in upper case (lines 234 to 238)
cloud_request_origin	_51DEGREES_CLOUD_REQUEST_ORIGIN	The Cloud Request Engine example helper (line 58)
51DEGREES_DD_PATH	_51DEGREES_DD_PATH	The Device Detection example helper (line 54)
IPINTELLIGENCEDATAFILE	_51DEGREES_IPI_PATH	The IP Intelligence example helper (line 46) and on-premise tests (constants.py line 38)
run_performance_tests	_51DEGREES_RUN_PERFORMANCE_TESTS	The Device Detection example tests (test_onpremiseexamples.py lines 67 and 91)
The upper case form of a name given to KeyUtils.get_named_key	The name as given	fiftyone_devicedetection_shared (key_utils.py line 31) and fiftyone_ipintelligence_shared (key_utils.py line 31)

Four published packages are in that table. The 4.5.43 wheels of fiftyone_pipeline_cloudrequestengine and fiftyone_pipeline_did read FOD_CLOUD_API_URL, and the 4.5.101 wheel of fiftyone_devicedetection_shared and the 4.5.2 wheel of fiftyone_ipintelligence_shared read the upper case form at line 31 of key_utils.py. All four were uploaded on 4 November 2026 and hold the same lines as main. The other readers are tests and examples in this repository.

Three public constants in the published packages changed as well. Constants.FOD_CLOUD_API_URL in the Cloud Request Engine (constants.py line 25) was renamed to Constants.CLOUD_ENDPOINT, and ENDPOINT_VARIABLE in fiftyone_pipeline_did.did_client (did_client.py line 77) kept its name with its value changed to "_51DEGREES_CLOUD_ENDPOINT". The example helpers lost LEGACY_RESOURCE_KEY_ENV_VAR and LEGACY_LICENSE_KEY_ENV_VAR, and had the values of ENDPOINT_ENV_VAR, DATA_FILE_ENV_VAR, ORIGIN_ENV_VAR, the IP Intelligence RESOURCE_KEY_ENV_VAR and the two UPDATE_EXAMPLE_LICENSE_KEY_NAME changed to the new names.

After a patch upgrade, a deployment that points the engine or the 51Did client at a privately hosted cloud with FOD_CLOUD_API_URL would have called cloud.51degrees.com with nothing said, code that reads Constants.FOD_CLOUD_API_URL would have raised AttributeError, and a person who runs the tests or the examples with the names they have always set would have been told no key or no data file was set.

The rules

James Rosewell, 12 November 2026, at about 11:40 UTC: "A patch release never removes or renames a public name. The old name stays for at least one release, deprecated and pointing at the new one."

Asked at about 12:05 UTC whether that covers an environment variable name a package reads as well as names in code, he answered "Yes, env names too".

Asked later the same day whether it covers environment variable names read by tests and examples as well as packages, he answered "How could they not be if they're needed for tests?", "And examples? Some people will want to run the tests themselves. That's a good thing." and "They were always public!!"

So this draft covers every environment variable name a package, a test, an example or a CI script here reads, and not only the cloud endpoint it began with. The new _51DEGREES_ names stay the names everything documents.

The Cloud Request Engine specification names no environment variable for the endpoint. Its configuration table gives EndPoint the default https://cloud.51degrees.com/api/v4/, which this change leaves alone. The 51Did package surface specification names no environment variable either.

What changed

All links are to the head, 21bcbe0. Everywhere, the _51DEGREES_ name is read first, the old name is read only when the new one is unset or empty, the new name wins when both are set, and nothing else about any setting changes.

The published packages

1. The Cloud Request Engine reads FOD_CLOUD_API_URL second. _endpoint_from_environment reads _51DEGREES_CLOUD_ENDPOINT, then the old name. The cloud_endpoint setting still comes before both, at lines 162 to 167.
2. The 51Did client does the same, in _endpoint_from_environment, called at line 530 after the endpoint argument, which still comes first.
3. Each of the two reports the old name once, the first time it takes its endpoint from it. The two packages do not depend on each other, so each keeps its own record, and a process that uses both with the old name is told twice. The message is "The FOD_CLOUD_API_URL environment variable is deprecated and _51DEGREES_CLOUD_ENDPOINT replaces it. The cloud endpoint was read from FOD_CLOUD_API_URL because _51DEGREES_CLOUD_ENDPOINT is not set, so set _51DEGREES_CLOUD_ENDPOINT to the same value." It goes through warnings.warn, which is how the engine already reports (line 575, line 663 and line 695). The 51Did package reported nothing before and carries no logger, so it reports the same way. The category is FutureWarning, which the Python documentation describes as the "Base class for warnings about deprecated features when those warnings are intended for end users of applications that are written in Python", and which Python shows by default. The person who sets an environment variable runs the application, and DeprecationWarning is ignored by default outside __main__, so that person would never see one.
4. Constants.FOD_CLOUD_API_URL is back in the Cloud Request Engine, holding "FOD_CLOUD_API_URL", at constants.py lines 27 to 32. It is a plain class attribute, and its comment carries @deprecated and points at Constants.CLOUD_ENDPOINT. Python has no keyword that marks a constant as deprecated, and it gives no warning when read. The engine reads the old variable through the constant, at line 79, as 4.5.43 did, so code that points the constant at another variable still decides what is read. Earlier versions of this change made the constant a descriptor that gave a DeprecationWarning on each read, and had the engine read the old name from a private copy. That put an object in the class's dictionary where 4.5.43 had the name, and made the engine ignore the constant, both of which the review found.
5. did_client.ENDPOINT_VARIABLE holds "FOD_CLOUD_API_URL" again, in the same way, as a plain module attribute at did_client.py lines 78 to 86, beside the new did_client.CLOUD_ENDPOINT_VARIABLE, which holds "_51DEGREES_CLOUD_ENDPOINT". Its comment says it is deprecated and points at the new constant. It gives no warning when read. Making a module attribute warn when read means serving it from the module's __getattr__, which takes it out of the module's dictionary, so dir() and from fiftyone_pipeline_did.did_client import * stop giving it. The first version of this change did that, the review found it, and the name being found every way it was in 4.5.43 matters more than the warning. The client reads the old variable through the constant, at line 108, as 4.5.43 did.
6. KeyUtils.get_named_key reads the upper case form of a name again, in fiftyone_devicedetection_shared and fiftyone_ipintelligence_shared, when the name as given is unset or empty. That read is deprecated and reported once for each name with a FutureWarning. It returns what the 4.5.101 and 4.5.2 code returned for every combination of the two variables.

The examples

7. The three example helpers read each setting under both names, through one __get_env_variable(name, old_name) in each, which prints once to the error stream that the old name is deprecated and which name replaces it. They are the Device Detection helper (lines 186 to 254), the IP Intelligence helper (lines 147 to 195, with the reader at lines 430 to 456) and the Cloud Request Engine examples' helper (lines 72 to 121). The IP Intelligence helper reads its resource key and its endpoint under the old name in upper case as well (lines 148 to 181), as 4.5.43 did. Its licence key was never read in upper case and is not now.
8. The helpers' constants that held an old name hold it again, each with a comment that says it is deprecated and names the constant to use, and each new name has a constant of its own. In the Device Detection helper (lines 44 to 74) LEGACY_RESOURCE_KEY_ENV_VAR is back, ENDPOINT_ENV_VAR holds "cloud_endpoint" beside the new CLOUD_ENDPOINT_ENV_VAR, and DATA_FILE_ENV_VAR holds "51DEGREES_DD_PATH" beside the new DD_PATH_ENV_VAR. In the IP Intelligence helper (lines 42 to 70) RESOURCE_KEY_ENV_VAR holds "resource_key" beside the new CLOUD_RESOURCE_KEY_ENV_VAR, ENDPOINT_ENV_VAR holds "cloud_endpoint" beside CLOUD_ENDPOINT_ENV_VAR, and DATA_FILE_ENV_VAR holds "IPINTELLIGENCEDATAFILE" beside IPI_PATH_ENV_VAR. In the Cloud Request Engine examples' helper (lines 37 to 67) the two LEGACY_ constants are back, and ENDPOINT_ENV_VAR and ORIGIN_ENV_VAR hold the old names beside CLOUD_ENDPOINT_ENV_VAR and CLOUD_REQUEST_ORIGIN_ENV_VAR. Every use of a constant that meant the new name now uses the new constant, which is most of the other example files in this diff.
9. The two data file update examples read the licence key through their helper, at Device Detection lines 174 to 179, read at line 231 and IP Intelligence lines 77 to 83, read at line 145. UPDATE_EXAMPLE_LICENSE_KEY_NAME holds "license_key" again in both, deprecated, beside the new UPDATE_EXAMPLE_LICENSE_KEY_VARIABLE. The Device Detection one reached LICENSE_KEY in upper case through KeyUtils, so its helper reads that as well (lines 192 to 206).
10. The two Location cloud examples read resource_key second, through a read_environment function in each (gettingstarted.py lines 41 to 68, web.py lines 41 to 68). They are scripts with no helper to share.
11. The 51Did creator context example reads all three of its variables under both names, through env. Its endpoint is read at lines 139 and 140 and its keys, whose old names were RESOURCE_KEY and LICENSE_KEY, at lines 128 and 129. It warns with a FutureWarning, as the 51Did client does.

The tests

12. live_cloud.py gains read_environment(name, old_name), at lines 57 to 81, and find_resource_key reads resource_key when neither of its two new names is set (lines 97 to 106). It also gains is_set(name, old_name) (lines 84 to 94), which says whether a variable is set under either name, whatever it holds, for a variable that works as a switch. A search for a key under other names, which the 51Did tier tests make, does not fall back. The file is in eight test folders, three of them new (the Cloud Request Engine tests, the Location tests and the IP Intelligence on-premise tests), and the eight copies are the same bytes, which a test checks.
13. Every test that reads a renamed variable reads it through that helper. They are the Cloud Request Engine tests (test_cloudengine.py line 38, test_licensekey_live.py line 36), the 51Did live tests (test_did_client_live.py line 60), the Location tests (test_examples.py line 33, test_properties51D.py line 33), the IP Intelligence on-premise tests (constants.py line 41) and the Device Detection example tests (test_onpremiseexamples.py lines 36, 71 and 95). The switch that turns the performance examples on is read with is_set, so it is on when its variable is set under either name, even to an empty value, as it was. The tests that already called find_resource_key need no change.
14. The two tests that run the examples with no settings take the old names out as well (Device Detection, IP Intelligence), so a licence key set under an old name does not reach them.
15. Fifteen tox.ini files pass each old name to the tests wherever they pass its new name. tox strips every variable it is not told to keep, so without this the old names would never reach a test run under tox. pipeline/fiftyone_pipeline_did/tox.ini is one of them.

The name check

16. ci/check-environment-variable-names.ps1 still fails on an old name, except in the two places a deprecated read needs one. The first is a line where the old name is the argument straight after its _51DEGREES_ name, which is how every deprecated read here is written (lines 87 to 91 and line 194). The second is a list of 21 files, each given by its exact path with the old names it may hold (lines 93 to 187). They hold the deprecated constants, the documentation that says an old name is still read, the tests that set an old name to check the read, and the tox.ini lists. In such a file only the names it is listed with are left alone (lines 189 to 206). Any other old name still fails there, and so does any name that starts with a digit other than 51DEGREES_DD_PATH in the two files listed with it. A new tox.ini or example_utils.py is on no list, so it may hold no old name. FOD_CLOUD_API_URL is in the list of old names again (line 66), so it fails in every file not listed with it. The rule that matched any LEGACY_ constant is gone, because those constants are back. The first version of this part left a listed file out of the check whole, which the review found.

The two readmes changed in the first version still say FOD_CLOUD_API_URL is deprecated and read (Cloud Request Engine, 51Did). No other readme changes, so the new names stay the ones documented.

Tests

The tests went in first each time, and alone.

Commit	What it is
09a99511	Tests for the cloud endpoint
1dc955f1	The cloud endpoint read under both names, and the two constants
680d216f	Tests that the 51Did constant is a plain module attribute
468814a3	The 51Did constant as a plain module attribute
1ec177ab	Tests for every other renamed variable, nine files
b3ccf061	Every other renamed variable read under both names, 50 files
797f1834	Tests for the three findings of the second review, three files
1b8c448d	The IP Intelligence helper's upper case reads, the switch read by presence, and the name check file by file, 11 files
252d8871	Tests that the engine's old constant is a plain attribute the engine reads, six files
21bcbe0d	The engine's old constant as a plain attribute that the engine reads, two files (head)

The tests in 1ec177ab are test_live_cloud.py (the helper under both names, reported once, and the eight copies being one file), the Device Detection and IP Intelligence and Cloud Request Engine example tests (each example helper's readers and constants, with the Device Detection key helper's upper case read), test_shared.py (the IP Intelligence key helper's upper case read), the IP Intelligence on-premise test of the data file path, the Location test (each Location example's reading function, taken out of the example's source and run on its own because importing an example calls the cloud), test_creator_context_server.py (the 51Did example's keys) and check-environment-variable-names.Tests.ps1 (the name check). 797f1834 adds to three of them, being the upper case reads in the IP Intelligence helper's tests, is_set in test_live_cloud.py, and each file's own names in the name check's tests. 252d8871 changes the engine's test of its old constant and adds one that the engine reads through it (test_cloudrequestengine.py lines 213 to 240), and stops six tests creating the record they reset when it is missing.

Red

Tests alone	Run	Result
09a9951	Full build, run 43245291522, job Ubuntu_Python_3.14	6 failed and 237 passed in the 51Did package, with Setting 'PullRequestSha' reading 09a9951. Four failed with 'https://old.example/api/v4/' != 'https://cloud.51degrees.com/api/v4/', one with "DeprecationWarning not triggered" and one with "module 'fiftyone_pipeline_did.did_client' has no attribute 'CLOUD_ENDPOINT_VARIABLE'". The job stopped when its unit tests failed, before the integration tests, which is where the Cloud Request Engine tests run, and the other nine jobs were cancelled
09a9951	Cloud Request Engine endpoint tests, run 43249531675	4 failed, 7 passed. Three failed with 'http://testOldEnvVarEndPoint/' != 'https://cloud.51degrees.com/api/v4/' and one with "type object 'Constants' has no attribute 'FOD_CLOUD_API_URL'"
09a9951	Environment variable names, run 43245253322	5 failed, 48 passed
680d216	51Did client construction tests, run 43260379666	2 failed, 12 passed. One failed with "'ENDPOINT_VARIABLE' not found in" the list dir() gave, and one with 'https://other.example/api/v4/' != 'https://cloud.51degrees.com/api/v4/'
1ec177a	The new tests for every other variable, run 43268668697	Every step failed. The helper and the 51Did example failed with 'old-key' != None, 'old-resource-key' != None and "module 'tests.live_cloud' has no attribute 'read_environment'" (9 failed, 10 passed). The Cloud Request Engine example helper failed with assert '' == 'old-value' for each of its four settings (5 failed, 15 passed). The Device Detection helper failed with ('old-value', 'old-value') != ('', '') and its key helper with 'value' != None (16 failed, 6 passed, counting each case of a looped test). The IP Intelligence helper failed with ('old-value', 'old-value') != (None, None) (15 failed, 4 passed), its on-premise test with 'old.ipi' != the Lite file's path (1 failed, 2 passed), and its key helper with None != 'value' (1 failed, 4 passed). The Location examples failed because neither has a read_environment function (6 failed, 3 passed)
1ec177a	Environment variable names, run 43268632526	Failed in its own tests, which is what that commit changes (26 failed, 47 passed)
797f183	The same temporary workflow, run 43279463298	The helper failed with "module 'tests.live_cloud' has no attribute 'is_set'" (3 failed, 16 passed), and the IP Intelligence example helper failed with 'old-value' != None for RESOURCE_KEY and for CLOUD_ENDPOINT (2 failed, 8 passed). The other five steps passed, as nothing they test changed
797f183	Environment variable names, run 43279435118	Failed in its own tests (28 failed, 63 passed)
252d887	Cloud Request Engine endpoint tests, run 43288007021	2 failed, 10 passed. testOldEndPointConstant failed because the class's dictionary held a descriptor object where the test wants 'FOD_CLOUD_API_URL', and testConfigEndPoint_VariableTheOldConstantNames failed with 'http://testOldEnvVarEndPoint/' != 'https://cloud.51degrees.com/api/v4/'. The other temporary workflow passed on this commit (run 43288006475), because a test that no longer creates a missing record gives the same result while the record exists

Runs 43249531675, 43260379666, 43268668697, 43279463298 and 43288007021 ran from throwaway branches, each holding the tests-only commit and one temporary workflow that installs the branch's own source and runs the named test files.

One test from 09a9951, test_old_constant_keeps_its_old_value_and_is_deprecated, asked for a warning on read. 680d216 replaced it with test_old_constant_keeps_its_old_value and the two tests in its row above, and 252d887 did the same for the engine's testOldEndPointConstant. The tests that passed before each fix are the ones that guard what must not change, such as the new name winning when both are set.

Green, on the head (21bcbe0)

Run	Result
Full build, run 43288063365	Success. All ten build and test jobs passed, being Ubuntu and Windows on Python 3.10, 3.11, 3.12, 3.13 and 3.14. Every Setting 'PullRequestSha' line, one in each of the eleven jobs, reads 21bcbe0, and Configure printed "Left out 5 macOS entries". The new test files run inside the build as well. In the Ubuntu_Python_3.12 job the 51Did package's unit tests ran 260 passed with 8 deselected, the IP Intelligence on-premise tests 53 passed and its key helper tests 5 passed, and in the integration step the Cloud Request Engine tests ran 81 passed with 2 skipped, its examples 52 passed with 13 skipped, the Device Detection examples 41 passed, the Location tests 6 passed and the IP Intelligence examples 28 passed with 3 skipped
Cloud Request Engine endpoint tests, run 43288048205	12 passed, from a throwaway branch holding 21bcbe0 and the two temporary workflows
The other temporary workflow, run 43288048164	Every step passed, from the same throwaway branch. 19 passed for the helper and the 51Did example, 20 for the Cloud Request Engine example helper, 9 for the Device Detection helper and key helper, 8 for the IP Intelligence helper, 3 for its on-premise test, 5 for its key helper and 3 for the Location examples
Environment variable names, run 43288041451	Success, 91 tests of the check and the check itself over every tracked file

The earlier green runs were on earlier heads. The Cloud Request Engine endpoint tests passed 11 in run 43249636622 on 1dc955f, the 51Did client construction tests passed 14 in run 43260468270 on 468814a, and the temporary workflow passed every step in run 43269176036 on b3ccf06 and in run 43279579296 on 1b8c448. The full builds of 1dc955f (run 43249652603), 468814a (run 43260481768), b3ccf06 (run 43269213683) and 1b8c448 (run 43279596850) all passed. The runs on the head replace them.

rc moved twice while that full build ran. #98 merged at 19:19 UTC as 58111e7 and #94 at 19:34 UTC as 5b9fd55. Every build job merges rc into the head before it builds, and each did so between 19:22 and 19:24 UTC, so the build ran on the head merged with 58111e7, which is why the engines package ran 65 tests where the earlier builds ran 54. #94 is not in the build. It changes javascriptbuilder.py and two of its tests in fiftyone_pipeline_core, and #98 changes datafile_update_service.py and two of its tests in fiftyone_pipeline_engines. This draft touches none of those six files, and GitHub reports that the head merges cleanly with rc at 5b9fd55.

macOS was left out of this draft's full build under the 9 November decision. The rc head is built with macOS before it merges into main.

What remains

1. The release draft #67 says under "Before you upgrade" that "The old name is no longer read" for FOD_CLOUD_API_URL, and that the examples, tests and CI scripts read only names that start _51DEGREES_. Once this merges both need to say the old names are deprecated and still read.
2. ipintelligencetestkey is not read again. One test in fiftyone_ipintelligence_shared set that variable itself and read it straight back to check the upper case read, so no one outside the test could set it. The test of the upper case read is back under a name that starts _51DEGREES_.
3. Constants that were defined inside a test module, such as LEGACY_RESOURCE_KEY_ENV_VAR in the Device Detection cloud tests on main, are not back. Those tests read the old name through live_cloud.py now.
4. The CI scripts set only the new names, as they do on rc. On main they set cloud_endpoint and 51DEGREES_DD_PATH, and read neither.
5. The old names and the deprecated constants stay for at least one release. Taking them out is a later change.