Update documentation for exception type breaking change

- README.md: Update error handling examples to use strings
- docs/migration.md: Add security-related breaking changes section
- c_src/py_nif.h: Update make_py_error documentation
- c_src/py_logging.c: Use cached ATOM_OK/ATOM_ERROR for trace status
- test/py_logging_SUITE.erl: Revert trace status to atoms

Trace span status remains as atoms (ok/error) since these are known,
bounded values that use cached atoms for efficiency.

Author: benoitc

README.md

@@ -558,8 +558,10 @@ py:execution_mode().  %% => free_threaded | subinterp | multi_executor
 ## Error Handling
 
 ```erlang
-{error, {'NameError', "name 'x' is not defined"}} = py:eval(<<"x">>).
-{error, {'ZeroDivisionError', "division by zero"}} = py:eval(<<"1/0">>).
+%% Python exceptions return {error, {TypeString, Message}}
+%% Note: Exception types are strings (not atoms) since v2.0 to prevent atom table exhaustion
+{error, {"NameError", "name 'x' is not defined"}} = py:eval(<<"x">>).
+{error, {"ZeroDivisionError", "division by zero"}} = py:eval(<<"1/0">>).
 {error, timeout} = py:eval(<<"sum(range(10**9))">>, #{}, 100).
 ```
 

c_src/py_logging.c

@@ -277,9 +277,16 @@ static PyObject *erlang_trace_end_impl(PyObject *self, PyObject *args) {
     }
 
     ERL_NIF_TERM span_id_term = enif_make_uint64(msg_env, span_id);
-    /* Use string instead of atom to prevent atom table exhaustion from
-     * arbitrary Python trace status strings */
-    ERL_NIF_TERM status_term = enif_make_string(msg_env, status, ERL_NIF_LATIN1);
+    /* Use cached atom values for status - safe since only "ok"/"error" are expected */
+    ERL_NIF_TERM status_term;
+    if (strcmp(status, "ok") == 0) {
+        status_term = enif_make_copy(msg_env, ATOM_OK);
+    } else if (strcmp(status, "error") == 0) {
+        status_term = enif_make_copy(msg_env, ATOM_ERROR);
+    } else {
+        /* Unknown status - use string to be safe */
+        status_term = enif_make_string(msg_env, status, ERL_NIF_LATIN1);
+    }
     ERL_NIF_TERM attrs_term = py_to_term(msg_env, attrs);
 
     uint64_t ts = get_monotonic_ns() / 1000;

c_src/py_nif.h

@@ -1006,9 +1006,12 @@ static ERL_NIF_TERM make_error(ErlNifEnv *env, const char *reason);
  * error tuple, and clears the Python error state.
  *
  * @param env NIF environment for term allocation
- * @return `{error, {ExceptionType, Message}}` tuple
+ * @return `{error, {ExceptionTypeString, MessageString}}` tuple
+ *         where ExceptionTypeString is the Python exception class name
+ *         (e.g., "NameError", "TypeError") as a string (not atom)
  *
  * @note Always clears the Python exception state
+ * @note Exception type is returned as string to prevent atom table exhaustion
  */
 static ERL_NIF_TERM make_py_error(ErlNifEnv *env);
 

docs/migration.md

@@ -12,6 +12,35 @@ This guide covers breaking changes and migration steps when upgrading from erlan
 - [ ] Replace subprocess calls with Erlang ports
 - [ ] Move signal handlers to Erlang level
 - [ ] Review any `os.fork`/`os.exec` usage
+- [ ] Update error pattern matching: exception types are now strings
+
+## Security-Related Breaking Changes
+
+### Exception Types Changed from Atoms to Strings
+
+**Reason:** Atoms are never garbage collected in Erlang. Using atoms for Python exception type names (which are unbounded due to custom exceptions and third-party libraries) could exhaust the atom table.
+
+**Before (v1.8.x):**
+```erlang
+case py:eval(Code) of
+    {ok, Result} -> Result;
+    {error, {'NameError', Msg}} -> handle_name_error(Msg);
+    {error, {'TypeError', Msg}} -> handle_type_error(Msg);
+    {error, {ExcType, Msg}} -> handle_other(ExcType, Msg)
+end.
+```
+
+**After (v2.0):**
+```erlang
+case py:eval(Code) of
+    {ok, Result} -> Result;
+    {error, {"NameError", Msg}} -> handle_name_error(Msg);
+    {error, {"TypeError", Msg}} -> handle_type_error(Msg);
+    {error, {ExcType, Msg}} -> handle_other(ExcType, Msg)  %% ExcType is now a string
+end.
+```
+
+**Note:** Trace span status remains as atoms (`ok` | `error`) since these are known, bounded values.
 
 ## API Changes
 

test/py_logging_SUITE.erl

@@ -134,7 +134,7 @@ with erlang.Span('test-span', key='value'):
     1 = length(Spans),
     [Span] = Spans,
     <<"test-span">> = maps:get(name, Span),
-    "ok" = maps:get(status, Span),  %% Status is now string since v2.0
+    ok = maps:get(status, Span),
     true = maps:get(duration_us, Span) >= 0,
     #{<<"key">> := <<"value">>} = maps:get(attributes, Span),
     ok.
@@ -222,7 +222,7 @@ except ValueError:
 ">>),
 
     {ok, [Span]} = py:get_traces(),
-    "error" = maps:get(status, Span),  %% Status is now string since v2.0
+    error = maps:get(status, Span),
     EndAttrs = maps:get(end_attrs, Span),
     true = maps:is_key(<<"exception">>, EndAttrs),
     ok.