Manual review of builtin functions: ascii-eval

Author: heikkitoivonen

docs/builtins/ascii.md

@@ -125,84 +125,6 @@ print(ascii(path))
 # "'/home/\\u7528\\u6237/\\u6587\\u4ef6.txt'"
 ```
 
-## Comparison with Alternatives
-
-### ascii() vs repr()
-
-```python
-# Both O(n), but different escaping
-
-text = "Café"
-
-# repr() - shows non-ASCII directly (Python 3)
-repr(text)   # "'Café'"
-
-# ascii() - escapes all non-ASCII
-ascii(text)  # "'Caf\\xe9'"
-
-# Use case:
-# repr() - for Python evaluation
-# ascii() - for ASCII-only output (logs, APIs)
-```
-
-### ascii() vs str()
-
-```python
-text = "Hello\nWorld"
-
-# str() - shows representation
-str(text)    # Shows actual newline
-
-# ascii() - escapes everything
-ascii(text)  # "'Hello\\nWorld'"
-
-# Use case:
-# str() - for human display
-# ascii() - for ASCII-safe output
-```
-
-## Escape Sequence Details
-
-```python
-# O(1) - understand escaping rules
-
-# Control characters
-ascii("\n")      # "'\\n'"
-ascii("\t")      # "'\\t'"
-ascii("\r")      # "'\\r'"
-ascii("\0")      # "'\\x00'"
-
-# Extended ASCII
-ascii("\x7f")    # "'\\x7f'"
-ascii("\xff")    # "'\\xff'"
-
-# Unicode BMP (Basic Multilingual Plane)
-ascii("α")       # "'\\u03b1'"
-ascii("中")      # "'\\u4e2d'"
-
-# Supplementary planes
-ascii("𝔸")      # "'\\U0001d538'"
-```
-
-## Containers with Unicode
-
-```python
-# O(n) - escapes all non-ASCII in container
-data = {
-    "name": "Josée",
-    "city": "Montréal",
-    "country": "Québec"
-}
-
-ascii(data)
-# {'name': 'Jos\\xe9e', 'city': 'Montr\\xe9al', 'country': 'Qu\\xe9bec'}
-
-# Each value is escaped separately
-lst = ["café", "naïve", "résumé"]
-ascii(lst)
-# ['caf\\xe9', 'na\\xefve', 'r\\xe9sum\\xe9']
-```
-
 ## Performance Patterns
 
 ### Batch Processing
@@ -224,50 +146,6 @@ safe_version = ascii(large_text)  # O(len(large_text))
 # Memory: output may be larger (each non-ASCII becomes \xXX, \uXXXX, etc)
 ```
 
-## Practical Examples
-
-### API Response Logging
-
-```python
-# O(n) - log safely without encoding issues
-import json
-
-response = {"name": "José", "country": "México"}
-response_json = json.dumps(response)
-
-# Log safely in ASCII-only environment
-print(ascii(response_json))
-# '{"name": "Jos\\u00e9", "country": "M\\u00e9xico"}'
-
-# vs print(response_json) which might have encoding issues
-```
-
-### Email Headers
-
-```python
-# O(n) - headers must be ASCII
-subject = "Meeting: Café ☕ Discussion"
-
-# Make safe for email
-safe_subject = ascii(subject)
-# "'Meeting: Caf\\xe9 \\u2615 Discussion'"
-
-# Email system can safely handle this
-```
-
-### Source Code Comments
-
-```python
-# O(n) - include comments with non-ASCII
-
-text = "Author: François"
-
-# Generate comment safely
-comment = f"# {ascii(text)}"
-# print(comment)
-# # 'Author: Fran\\xe7ois'
-```
-
 ## Special Cases
 
 ### Empty String

docs/builtins/eval.md

@@ -92,33 +92,6 @@ scope = {f"var{i}": i for i in range(1000)}
 eval("var0 + var1 + var2", scope)  # O(n + 1000)
 ```
 
-## Security Considerations
-
-### Why eval() is Dangerous
-
-```python
-# eval() executes arbitrary code
-user_input = "import os; os.system('rm -rf /')"
-# eval(user_input)  # DANGEROUS - would execute!
-
-# Only use eval() with trusted input
-# For untrusted input, use ast.literal_eval()
-import ast
-safe = ast.literal_eval("[1, 2, 3]")  # Safe - only literals
-```
-
-### Restricted Execution
-
-```python
-# eval() with custom globals/locals
-restricted_scope = {"__builtins__": {}}
-# eval("import os", restricted_scope)  # Still unsafe - can access builtins
-
-# Use ast.literal_eval() for truly safe evaluation
-import ast
-result = ast.literal_eval("{'key': 'value'}")  # Safe
-```
-
 ## Performance Patterns
 
 ### Repeated Evaluation
@@ -207,46 +180,6 @@ for x in range(10):
     result = eval(code)  # Efficient
 ```
 
-## Common Patterns
-
-### Dynamic Math Evaluation
-
-```python
-# O(n) - parse and evaluate user expression
-def calculate(expr, **kwargs):
-    # WARNING: Only use with trusted input!
-    return eval(expr, {"__builtins__": {}}, kwargs)
-
-# Safe because no builtins available
-result = calculate("x + y", x=10, y=20)  # 30
-```
-
-### Configuration Values
-
-```python
-import ast
-
-# O(n) - parse config safely
-config_str = '{"timeout": 30, "retries": 3, "items": [1, 2, 3]}'
-config = ast.literal_eval(config_str)
-# Safe - only allows data structures
-```
-
-### Lambda/Function Creation (Avoid!)
-
-```python
-# O(n) - can create functions at runtime
-# Generally a bad idea - use proper functions instead
-func = eval("lambda x: x ** 2")
-result = func(5)  # 25
-
-# Better - define function normally
-def square(x):
-    return x ** 2
-
-result = square(5)
-```
-
 ## Edge Cases
 
 ### Empty Expression