refactor: rename preview terminology to free tier cloud

Replace preview-client wording with free tier cloud across the SDK,
docs, and tests. Rename JUDGE0_SUPPRESS_PREVIEW_WARNING to
JUDGE0_SUPPRESS_FREE_TIER_CLOUD_WARNING and PreviewClientLimitError
to FreeTierCloudClientLimitError.

Closes #45

Author: ijelacicbot

AGENTS.md

@@ -19,11 +19,11 @@
   - `clients.py` implements the base HTTP client and the provider- and flavor-specific clients for Judge0 Cloud, RapidAPI, and AllThingsDev.
   - `common.py` contains shared base64 encoding and decoding helpers and iterable batching.
   - `data.py` maps language aliases to Judge0 language IDs by server version and flavor.
-  - `errors.py` defines SDK-specific exception types for client resolution and preview-client usage limits.
+  - `errors.py` defines SDK-specific exception types for client resolution and free-tier-cloud-client usage limits.
   - `filesystem.py` models individual files and ZIP-backed collections used for additional and post-execution files.
   - `retry.py` defines the polling strategy interface and retry-count, wait-time, and periodic retry implementations.
   - `submission.py` models submission request and response data, including serialization, response updates, completion checks, and execution filesystem handling.
-  - `utils.py` detects HTTP rate-limit responses and translates preview-client rate limits into SDK-specific errors.
+  - `utils.py` detects HTTP rate-limit responses and translates free-tier-cloud-client rate limits into SDK-specific errors.
   - `version.py` exposes the package version constant.
 - `tests/` contains the pytest suite. Shared fixtures belong in `conftest.py`, and focused tests should use `test_<area>.py` modules that correspond to SDK behavior.
 - `examples/` contains runnable SDK usage examples, including the standalone HTTP callback example in `examples/1000_http_callback_aka_webhook/`.

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## v0.1.0-dev
 
+- Rename "preview" terminology to "free tier cloud" and rename the
+  `JUDGE0_SUPPRESS_PREVIEW_WARNING` environment variable to
+  `JUDGE0_SUPPRESS_FREE_TIER_CLOUD_WARNING`.
 - Fix Sphinx autodoc imports for Pydantic-backed submission types.
 - Add complete static typing across the SDK and tests, with typed single and batch
   submission return values.

docs/source/in_depth/client_resolution.rst

@@ -34,11 +34,11 @@ If a custom client is not configured, the SDK will try to find API keys for one
 
 The first API key found determines the client that will be used.
 
-3. **Preview Client**
+3. **Free Tier Cloud Client**
 
-If none of the above environment variables are set, the SDK falls back to using a **preview client**. This is an unauthenticated client that connects to the official Judge0 Cloud service. It initializes ``Judge0CloudCE()`` and ``Judge0CloudExtraCE()`` for the CE and Extra CE flavors, respectively.
+If none of the above environment variables are set, the SDK falls back to using a **free tier cloud client**. This is an unauthenticated client that connects to the official Judge0 Cloud service. It initializes ``Judge0CloudCE()`` and ``Judge0CloudExtraCE()`` for the CE and Extra CE flavors, respectively.
 
-When the preview client is used, a warning message is logged to the console, as this option is not recommended for production use. To suppress this warning, you can set the ``JUDGE0_SUPPRESS_PREVIEW_WARNING`` environment variable.
+When the free tier cloud client is used, a warning message is logged to the console, as this option is not recommended for production use. To suppress this warning, you can set the ``JUDGE0_SUPPRESS_FREE_TIER_CLOUD_WARNING`` environment variable.
 
 Example Resolution Flow
 -----------------------
@@ -50,6 +50,6 @@ When you call a function like ``judge0.run(..., flavor=judge0.CE)``, the SDK wil
 3.  Check for ``JUDGE0_CLOUD_CE_AUTH_HEADERS`` to configure a ``Judge0CloudCE`` client.
 4.  Check for ``JUDGE0_RAPID_API_KEY`` to configure a ``RapidJudge0CE`` client.
 5.  Check for ``JUDGE0_ATD_API_KEY`` to configure an ``ATDJudge0CE`` client.
-6.  If none of the above are found, initialize a preview ``Judge0CloudCE`` client and log a warning.
+6.  If none of the above are found, initialize a free tier cloud ``Judge0CloudCE`` client and log a warning.
 
 This implicit client resolution makes it easy to get started with the Judge0 Python SDK while providing the flexibility to configure it for different environments and services.

src/judge0/__init__.py

@@ -76,7 +76,9 @@
 if os.getenv("JUDGE0_ENABLE_LOGGING"):
     setup_logging()
 
-suppress_preview_warning = os.getenv("JUDGE0_SUPPRESS_PREVIEW_WARNING") is not None
+suppress_free_tier_cloud_warning = (
+    os.getenv("JUDGE0_SUPPRESS_FREE_TIER_CLOUD_WARNING") is not None
+)
 
 
 # TODO: I belive that the whole logic for importing implicit client can be moved
@@ -105,9 +107,9 @@ def _get_implicit_client(flavor: Flavor) -> Client:
         client = _get_hub_client(flavor)
 
     # If we didn't find any of the possible keys, initialize
-    # the preview client based on the flavor.
+    # the free tier cloud client based on the flavor.
     if client is None:
-        client = _get_preview_client(flavor)
+        client = _get_free_tier_cloud_client(flavor)
 
     if flavor == Flavor.CE:
         JUDGE0_IMPLICIT_CE_CLIENT = client
@@ -117,10 +119,10 @@ def _get_implicit_client(flavor: Flavor) -> Client:
     return client
 
 
-def _get_preview_client(flavor: Flavor) -> Judge0CloudCE | Judge0CloudExtraCE:
-    if not suppress_preview_warning:
+def _get_free_tier_cloud_client(flavor: Flavor) -> Judge0CloudCE | Judge0CloudExtraCE:
+    if not suppress_free_tier_cloud_warning:
         logger.warning(
-            "You are using a preview version of the client which is not recommended"
+            "You are using the free tier cloud client which is not recommended"
             " for production.\n"
             "For production, please specify your API key in the environment variable."
         )

src/judge0/api.py

@@ -19,7 +19,7 @@
 
 
 def get_client(flavor: Flavor = Flavor.CE) -> Client:
-    """Resolve client from API keys from environment or default to preview client.
+    """Resolve client from API keys or default to the free tier cloud client.
 
     Parameters
     ----------

src/judge0/clients.py

@@ -13,7 +13,7 @@
 from .data import LANGUAGE_TO_LANGUAGE_ID
 from .retry import RetryStrategy
 from .submission import Submission, Submissions
-from .utils import handle_too_many_requests_error_for_preview_client
+from .utils import handle_too_many_requests_error_for_free_tier_cloud_client
 from .version import __version__
 
 
@@ -70,7 +70,7 @@ def __init__(
     def __del__(self) -> None:
         self.client.close()
 
-    @handle_too_many_requests_error_for_preview_client
+    @handle_too_many_requests_error_for_free_tier_cloud_client
     def get_about(self) -> JsonObject:
         """Get general information about judge0.
 
@@ -86,7 +86,7 @@ def get_about(self) -> JsonObject:
         response.raise_for_status()
         return cast(JsonObject, response.json())
 
-    @handle_too_many_requests_error_for_preview_client
+    @handle_too_many_requests_error_for_free_tier_cloud_client
     def get_config_info(self) -> Config:
         """Get information about client's configuration.
 
@@ -102,7 +102,7 @@ def get_config_info(self) -> Config:
         response.raise_for_status()
         return Config.model_validate(response.json())
 
-    @handle_too_many_requests_error_for_preview_client
+    @handle_too_many_requests_error_for_free_tier_cloud_client
     def get_language(self, language_id: int) -> Language:
         """Get language corresponding to the id.
 
@@ -121,7 +121,7 @@ def get_language(self, language_id: int) -> Language:
         response.raise_for_status()
         return Language.model_validate(response.json())
 
-    @handle_too_many_requests_error_for_preview_client
+    @handle_too_many_requests_error_for_free_tier_cloud_client
     def get_languages(self) -> list[Language]:
         """Get a list of supported languages.
 
@@ -135,7 +135,7 @@ def get_languages(self) -> list[Language]:
         languages = cast(list[JsonObject], response.json())
         return [Language.model_validate(language) for language in languages]
 
-    @handle_too_many_requests_error_for_preview_client
+    @handle_too_many_requests_error_for_free_tier_cloud_client
     def get_statuses(self) -> list[JsonObject]:
         """Get a list of possible submission statuses.
 
@@ -192,7 +192,7 @@ def is_language_supported(self, language: LanguageAlias | int) -> bool:
         language_id = self.get_language_id(language)
         return any(language_id == lang.id for lang in self.languages)
 
-    @handle_too_many_requests_error_for_preview_client
+    @handle_too_many_requests_error_for_free_tier_cloud_client
     def create_submission(self, submission: Submission) -> Submission:
         """Send submission for execution to a client.
 
@@ -234,7 +234,7 @@ def create_submission(self, submission: Submission) -> Submission:
 
         return submission
 
-    @handle_too_many_requests_error_for_preview_client
+    @handle_too_many_requests_error_for_free_tier_cloud_client
     def get_submission(
         self,
         submission: Submission,
@@ -279,7 +279,7 @@ def get_submission(
 
         return submission
 
-    @handle_too_many_requests_error_for_preview_client
+    @handle_too_many_requests_error_for_free_tier_cloud_client
     def create_submissions(self, submissions: Submissions) -> Submissions:
         """Send submissions for execution to a client.
 
@@ -319,7 +319,7 @@ def create_submissions(self, submissions: Submissions) -> Submissions:
 
         return submissions
 
-    @handle_too_many_requests_error_for_preview_client
+    @handle_too_many_requests_error_for_free_tier_cloud_client
     def get_submissions(
         self,
         submissions: Submissions,

src/judge0/errors.py

@@ -1,8 +1,8 @@
 """Library specific errors."""
 
 
-class PreviewClientLimitError(RuntimeError):
-    """Limited usage of a preview client exceeded."""
+class FreeTierCloudClientLimitError(RuntimeError):
+    """Limited usage of the free tier cloud client exceeded."""
 
 
 class ClientResolutionError(RuntimeError):

src/judge0/utils.py

@@ -7,7 +7,7 @@
 
 from httpx import HTTPError, HTTPStatusError
 
-from .errors import PreviewClientLimitError
+from .errors import FreeTierCloudClientLimitError
 
 P = ParamSpec("P")
 R = TypeVar("R")
@@ -20,7 +20,7 @@ def is_http_too_many_requests_error(exception: Exception) -> bool:
     )
 
 
-def handle_too_many_requests_error_for_preview_client(
+def handle_too_many_requests_error_for_free_tier_cloud_client(
     func: Callable[P, R],
 ) -> Callable[P, R]:
     @wraps(func)
@@ -33,13 +33,13 @@ def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
                 # let's check if we are dealing with the implicit client.
                 instance = args[0]
                 class_name = instance.__class__.__name__
-                # Check if we are using a preview version of the client.
+                # Check if we are using the free tier cloud client.
                 if (
                     class_name in ("Judge0CloudCE", "Judge0CloudExtraCE")
                     and getattr(instance, "api_key", None) is None
                 ):
-                    raise PreviewClientLimitError(
-                        "You are using a preview version of a client and "
+                    raise FreeTierCloudClientLimitError(
+                        "You are using the free tier cloud client and "
                         "you've hit a rate limit on it. Visit "
                         f"{getattr(instance, 'HOME_URL', None)} "
                         "to get your authentication credentials."

tests/conftest.py

@@ -116,12 +116,12 @@ def judge0_cloud_extra_ce_client() -> clients.Judge0CloudExtraCE | None:
 
 
 @pytest.fixture(scope="session")
-def preview_ce_client() -> clients.Judge0CloudCE:
+def free_tier_cloud_ce_client() -> clients.Judge0CloudCE:
     return clients.Judge0CloudCE(retry_strategy=RegularPeriodRetry(0.5))
 
 
 @pytest.fixture(scope="session")
-def preview_extra_ce_client() -> clients.Judge0CloudExtraCE:
+def free_tier_cloud_extra_ce_client() -> clients.Judge0CloudExtraCE:
     return clients.Judge0CloudExtraCE(retry_strategy=RegularPeriodRetry(0.5))
 
 
@@ -131,7 +131,7 @@ def ce_client(
     judge0_cloud_ce_client: clients.Judge0CloudCE | None,
     rapid_ce_client: clients.RapidJudge0CE | None,
     # atd_ce_client,
-    preview_ce_client: clients.Judge0CloudCE,
+    free_tier_cloud_ce_client: clients.Judge0CloudCE,
 ) -> clients.Client:
     if custom_ce_client is not None:
         return custom_ce_client
@@ -141,8 +141,8 @@ def ce_client(
         return rapid_ce_client
     # if atd_ce_client is not None:
     #     return atd_ce_client
-    if preview_ce_client is not None:
-        return preview_ce_client
+    if free_tier_cloud_ce_client is not None:
+        return free_tier_cloud_ce_client
 
     pytest.fail("No CE client available for testing. This error should not happen!")
 
@@ -153,7 +153,7 @@ def extra_ce_client(
     judge0_cloud_extra_ce_client: clients.Judge0CloudExtraCE | None,
     rapid_extra_ce_client: clients.RapidJudge0ExtraCE | None,
     # atd_extra_ce_client,
-    preview_extra_ce_client: clients.Judge0CloudExtraCE,
+    free_tier_cloud_extra_ce_client: clients.Judge0CloudExtraCE,
 ) -> clients.Client:
     if custom_extra_ce_client is not None:
         return custom_extra_ce_client
@@ -163,8 +163,8 @@ def extra_ce_client(
         return rapid_extra_ce_client
     # if atd_extra_ce_client is not None:
     #     return atd_extra_ce_client
-    if preview_extra_ce_client is not None:
-        return preview_extra_ce_client
+    if free_tier_cloud_extra_ce_client is not None:
+        return free_tier_cloud_extra_ce_client
 
     pytest.fail(
         "No Extra CE client available for testing. This error should not happen!"

tests/test_free_tier_cloud.py

@@ -0,0 +1,36 @@
+from http import HTTPStatus
+
+import httpx
+import pytest
+
+from judge0 import errors, utils
+from judge0.errors import FreeTierCloudClientLimitError
+from judge0.utils import handle_too_many_requests_error_for_free_tier_cloud_client
+
+
+class Judge0CloudCE:
+    HOME_URL = "https://ce.judge0.com"
+    api_key = None
+
+    @handle_too_many_requests_error_for_free_tier_cloud_client
+    def ping(self) -> None:
+        request = httpx.Request("GET", "https://ce.judge0.com")
+        response = httpx.Response(HTTPStatus.TOO_MANY_REQUESTS, request=request)
+        raise httpx.HTTPStatusError(
+            "rate limited",
+            request=request,
+            response=response,
+        )
+
+
+def test_preview_error_and_handler_names_are_removed() -> None:
+    assert not hasattr(errors, "PreviewClientLimitError")
+    assert not hasattr(utils, "handle_too_many_requests_error_for_preview_client")
+
+
+def test_rate_limit_raises_free_tier_cloud_client_limit_error() -> None:
+    with pytest.raises(
+        FreeTierCloudClientLimitError,
+        match="free tier cloud client",
+    ):
+        Judge0CloudCE().ping()