refactor: deprecate Actor.get_env()

docs/02_concepts/10_configuration.mdx

@@ -7,7 +7,7 @@ description: Customize Actor behavior through the Configuration class or environ
 import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
 
 import ConfigExample from '!!raw-loader!roa-loader!./code/10_config.py';
-import GetEnvExample from '!!raw-loader!roa-loader!./code/10_get_env.py';
+import RuntimeEnvironmentExample from '!!raw-loader!roa-loader!./code/10_runtime_environment.py';
 import PlatformDetectionExample from '!!raw-loader!roa-loader!./code/10_platform_detection.py';
 import ApiLink from '@theme/ApiLink';
 
@@ -52,10 +52,12 @@ The following table lists a few options you are most likely to set yourself. Whe
 
 ## Reading the runtime environment
 
-The <ApiLink to="class/Actor#get_env">`Actor.get_env`</ApiLink> method returns a dictionary with all `APIFY_*` environment variables parsed into their typed values. This is useful for inspecting the Actor's runtime context, such as the Actor ID, run ID, or default storage IDs. Variables that are not set or are invalid will have a value of `None`.
+The <ApiLink to="class/Actor#configuration">`Actor.configuration`</ApiLink> property exposes the `APIFY_*` and `ACTOR_*` environment variables parsed into their typed values. This is useful for inspecting the Actor's runtime context, such as the Actor ID, run ID, or default storage IDs. Variables that are not set are `None`.
+
+Variables that `Configuration` does not expose are read from `os.environ`, using the `ActorEnvVars` and `ApifyEnvVars` enums exported from `apify` for their names.
 
 <RunnableCodeBlock className="language-python" language="python">
-    {GetEnvExample}
+    {RuntimeEnvironmentExample}
 </RunnableCodeBlock>
 
 ## Platform detection

docs/02_concepts/code/10_runtime_environment.py

@@ -0,0 +1,22 @@
+import asyncio
+import os
+
+from apify import Actor, ApifyEnvVars
+
+
+async def main() -> None:
+    async with Actor:
+        config = Actor.configuration
+
+        Actor.log.info(f'Actor ID: {config.actor_id}')
+        Actor.log.info(f'Run ID: {config.actor_run_id}')
+        Actor.log.info(f'Default dataset ID: {config.default_dataset_id}')
+        Actor.log.info(f'Default KVS ID: {config.default_key_value_store_id}')
+
+        # Variables the configuration does not expose are read from the environment.
+        latest_sdk_version = os.environ.get(ApifyEnvVars.SDK_LATEST_VERSION)
+        Actor.log.info(f'Latest SDK version: {latest_sdk_version}')
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

src/apify/_actor.py

@@ -981,10 +981,20 @@ def is_at_home(self) -> bool:
     def get_env(self) -> dict:
         """Return a dictionary with information parsed from all the `APIFY_XXX` environment variables.
 
+        Deprecated. Read `Actor.configuration` instead, or `os.environ` for variables it does not expose.
+        Will be removed in version 5.0.0.
+
         For a list of all the environment variables, see the
         [Actor documentation](https://docs.apify.com/actors/development/environment-variables). If some variables
         are not defined or are invalid, the corresponding value in the resulting dictionary will be None.
         """
+        warnings.warn(
+            '`Actor.get_env()` is deprecated and will be removed in version 5.0.0. Read `Actor.configuration` '
+            'instead, or `os.environ` for variables it does not expose.',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         config = dict[str, Any]()
         for field_name, field in Configuration.model_fields.items():
             if field.deprecated:

tests/e2e/test_actor_api_helpers.py

@@ -36,19 +36,19 @@ async def test_actor_retrieves_env_vars(
 ) -> None:
     async def main() -> None:
         async with Actor:
-            env_dict = Actor.get_env()
+            config = Actor.configuration
 
-            assert env_dict.get('is_at_home') is True
-            assert env_dict.get('token') is not None
-            assert env_dict.get('events_websocket_url') is not None
-            assert env_dict.get('input_key') is not None
+            assert config.is_at_home is True
+            assert config.token is not None
+            assert config.actor_events_ws_url is not None
+            assert config.input_key is not None
 
-            assert len(env_dict.get('id', '')) == 17
-            assert len(env_dict.get('build_id', '')) == 17
-            assert len(env_dict.get('run_id', '')) == 17
-            assert len(env_dict.get('user_id', '')) == 17
+            assert len(config.actor_id or '') == 17
+            assert len(config.actor_build_id or '') == 17
+            assert len(config.actor_run_id or '') == 17
+            assert len(config.user_id or '') == 17
 
-    actor = await make_actor(label='get-env', main_func=main)
+    actor = await make_actor(label='configuration', main_func=main)
     run_result = await run_actor(actor)
 
     assert run_result.status == 'SUCCEEDED'

tests/unit/actor/test_actor_env_helpers.py

@@ -6,6 +6,7 @@
 from decimal import Decimal
 from typing import TYPE_CHECKING, Any
 
+import pytest
 from pydantic_core import TzInfo
 
 from apify import Actor
@@ -82,8 +83,6 @@
 if TYPE_CHECKING:
     from pathlib import Path
 
-    import pytest
-
 
 async def test_actor_is_not_at_home_when_local() -> None:
     async with Actor as actor:
@@ -199,6 +198,15 @@ async def test_get_env_with_randomized_env_vars(monkeypatch: pytest.MonkeyPatch,
     expected_get_env[ApifyEnvVars.CHARGED_ACTOR_EVENT_COUNTS.name.lower()] = None
 
     await Actor.init()
-    assert Actor.get_env() == expected_get_env
+    with pytest.warns(DeprecationWarning, match=r'`Actor.get_env\(\)` is deprecated'):
+        env = Actor.get_env()
+    assert env == expected_get_env
 
     await Actor.exit()
+
+
+async def test_get_env_warns_about_deprecation() -> None:
+    """`Actor.get_env()` emits a `DeprecationWarning` pointing at `Actor.configuration`."""
+    async with Actor:
+        with pytest.warns(DeprecationWarning, match=r'`Actor.get_env\(\)` is deprecated.*`Actor.configuration`'):
+            Actor.get_env()