edgecase-provocateur 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ahmed Raza, Hamza Hafeez, and Usman Ahmed
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,180 @@
1
+ Metadata-Version: 2.4
2
+ Name: edgecase-provocateur
3
+ Version: 0.1.0
4
+ Summary: An educational tool that probes Python functions with edge cases and explains failures with Socratic feedback.
5
+ Author: Ahmed Raza, Hamza Hafeez, Usman Ahmed
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/ahmed123-ar/edgecase-provocateur
8
+ Project-URL: Repository, https://github.com/ahmed123-ar/edgecase-provocateur
9
+ Project-URL: Issues, https://github.com/ahmed123-ar/edgecase-provocateur/issues
10
+ Keywords: testing,edge cases,education,debugging,decorator
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Education
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Topic :: Education
16
+ Classifier: Topic :: Software Development :: Testing
17
+ Requires-Python: >=3.9
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Provides-Extra: dev
21
+ Requires-Dist: pytest>=8.0; extra == "dev"
22
+ Requires-Dist: build>=1.0; extra == "dev"
23
+ Requires-Dist: twine>=5.0; extra == "dev"
24
+ Dynamic: license-file
25
+
26
+ # edgecase-provocateur
27
+
28
+ [![tests](https://github.com/ahmed123-ar/edgecase-provocateur/actions/workflows/test.yml/badge.svg)](https://github.com/ahmed123-ar/edgecase-provocateur/actions/workflows/test.yml)
29
+
30
+ **Probe your Python function with the inputs you forgot, and learn why it broke.**
31
+
32
+ Edgecase-Provocateur takes a function and an example call, generates a small set of
33
+ boundary-oriented inputs (empty lists, `None`, zero, negative numbers, huge values,
34
+ odd strings), runs the function on each one, and reports every crash with the failing
35
+ input, the exact source line, a plain-English explanation, and a **Socratic question**
36
+ that makes you decide how the function *should* behave. It never rewrites your code.
37
+
38
+ ## Motivation
39
+
40
+ Students tend to test only the "happy path": a few normal lists, positive numbers, short
41
+ strings. Code that looks correct then fails on the empty list or the `None` that hidden
42
+ tests use. Beginners often don't know *which* cases to try, and a raw traceback explains
43
+ *what* happened, not *which assumption was wrong*.
44
+
45
+ ## What's new here
46
+
47
+ | Existing tool | What it does | Gap for learners |
48
+ |---|---|---|
49
+ | `pytest` | runs tests you write | you must already know the edge cases |
50
+ | Hypothesis | powerful property-based fuzzing | steep learning curve; terse failure output |
51
+ | Edgecase-Provocateur | auto-generates beginner-friendly edge cases **and** coaches you through each failure | heuristic, exceptions only (see [limitations](#limitations)) |
52
+
53
+ The combination is the point: type-aware boundary generation + exception capture +
54
+ a readable report + reflection prompts instead of ready-made fixes.
55
+
56
+ ## Install
57
+
58
+ ```bash
59
+ pip install edgecase-provocateur
60
+ ```
61
+
62
+ Requires Python 3.9+. No dependencies.
63
+
64
+ ## Quick start
65
+
66
+ ```python
67
+ from edgecase_provocateur import provoke
68
+
69
+ @provoke
70
+ def find_max_difference(numbers):
71
+ largest = numbers[0]
72
+ smallest = numbers[0]
73
+ for num in numbers:
74
+ if num > largest:
75
+ largest = num
76
+ if num < smallest:
77
+ smallest = num
78
+ return largest - smallest
79
+
80
+ print(find_max_difference([1, 2, 3]))
81
+ ```
82
+
83
+ On the first call the package probes the function and prints:
84
+
85
+ ```
86
+ ============================================================
87
+ EDGECASE-PROVOCATEUR REPORT: find_max_difference()
88
+ ============================================================
89
+ 6 edge cases tried, 4 raised an exception.
90
+ ------------------------------------------------------------
91
+ Edge case : numbers = []
92
+ Full call : find_max_difference([])
93
+ Exception : IndexError: list index out of range
94
+ Where : line 8 -> largest = numbers[0]
95
+ Why : The function tried to use a position in a sequence that does not exist. ...
96
+ Reflect : What should the function do when the collection has no items (or too few)?
97
+ ...
98
+ ```
99
+
100
+ then runs your real call normally and prints `2`.
101
+
102
+ ### Explicit API (recommended for anything with side effects)
103
+
104
+ ```python
105
+ from edgecase_provocateur import analyze, print_report
106
+
107
+ report = analyze(find_max_difference, [1, 2, 3]) # example call; nothing printed
108
+ print_report(report)
109
+ print(len(report.failures), "failures")
110
+ for failure in report.failures:
111
+ print(failure.changed, failure.error_type, failure.line_no)
112
+ ```
113
+
114
+ Keyword arguments work too: `analyze(f, 4, b=2)`.
115
+
116
+ ### Decorator options
117
+
118
+ ```python
119
+ @provoke(once=False) # re-analyze on every call (default: first call only)
120
+ @provoke(show=False) # stay quiet; read f.last_report yourself
121
+ @provoke(max_cases=50, max_str_len=64)
122
+ ```
123
+
124
+ `max_cases` must be a non-negative integer; `max_str_len` must be a positive integer.
125
+
126
+ ## API
127
+
128
+ | Name | Description |
129
+ |---|---|
130
+ | `provoke` | decorator; probes on call, then runs the real call unchanged |
131
+ | `analyze(func, *args, **kwargs)` | returns an `AnalysisReport` |
132
+ | `AnalysisReport` | `.function_name`, `.results`, `.failures`, `.passes`, `.total` |
133
+ | `CaseResult` | `.test_input`, `.kwargs`, `.passed`, `.error_type`, `.message`, `.line_no`, `.line_text`, `.changed` |
134
+ | `format_report(report, limit=None)` / `print_report(report)` | render a report |
135
+
136
+ ## What gets generated
137
+
138
+ One argument is changed at a time, so each failure points at one input.
139
+
140
+ | Input | Edge cases |
141
+ |---|---|
142
+ | `int` | 0, 1, -1, `sys.maxsize`, `-sys.maxsize-1` |
143
+ | `float` | 0.0, -1.0, tiny, huge, ±inf, NaN |
144
+ | `str` | empty, one char, whitespace, long (capped), symbols, Unicode |
145
+ | `list` / `tuple` | empty, `[None]`, singleton, duplicates, wrong type, mixed types |
146
+ | `dict` | empty, `None` value, missing key |
147
+ | `set` | empty, `{None}`, wrong type |
148
+ | `bool` | the opposite value |
149
+ | `None` | 0, `""`, `[]`, `{}` |
150
+
151
+ Generation is deterministic and bounded (`max_cases`, default 200).
152
+
153
+ ## Limitations
154
+
155
+ - **Heuristic, finite.** A clean report is **not** proof of correctness.
156
+ - **Exceptions only.** It cannot tell that a function returns a *wrong answer* without a specification.
157
+ - **Some probes may be invalid** for your function's contract (e.g. it legitimately only accepts non-empty lists). Treat reports as prompts for reflection.
158
+ - **Your function runs many times.** Avoid probing functions that write files, hit the network, or change global state. Output printed by the probed function is suppressed during probing.
159
+ - **Not a sandbox.** Catching exceptions is not security isolation; there is no timeout, so an input that makes a function loop forever will hang the run. Never probe untrusted code.
160
+ - Probes receive deep copies of your arguments, so your own data is not mutated (best effort for uncopyable objects).
161
+
162
+ ## Development
163
+
164
+ ```bash
165
+ git clone https://github.com/ahmed123-ar/edgecase-provocateur
166
+ cd edgecase-provocateur
167
+ python -m venv .venv && source .venv/bin/activate
168
+ pip install -e ".[dev]"
169
+ pytest
170
+ ```
171
+
172
+ More: [architecture](docs/architecture.md) · [examples](docs/examples.md) · [publishing](docs/publishing.md) · [spec](docs/spec.md)
173
+
174
+ ## Team
175
+
176
+ Ahmed Raza, Hamza Hafeez, Usman Ahmed. CS1302, City University of Hong Kong.
177
+
178
+ ## License
179
+
180
+ MIT
@@ -0,0 +1,155 @@
1
+ # edgecase-provocateur
2
+
3
+ [![tests](https://github.com/ahmed123-ar/edgecase-provocateur/actions/workflows/test.yml/badge.svg)](https://github.com/ahmed123-ar/edgecase-provocateur/actions/workflows/test.yml)
4
+
5
+ **Probe your Python function with the inputs you forgot, and learn why it broke.**
6
+
7
+ Edgecase-Provocateur takes a function and an example call, generates a small set of
8
+ boundary-oriented inputs (empty lists, `None`, zero, negative numbers, huge values,
9
+ odd strings), runs the function on each one, and reports every crash with the failing
10
+ input, the exact source line, a plain-English explanation, and a **Socratic question**
11
+ that makes you decide how the function *should* behave. It never rewrites your code.
12
+
13
+ ## Motivation
14
+
15
+ Students tend to test only the "happy path": a few normal lists, positive numbers, short
16
+ strings. Code that looks correct then fails on the empty list or the `None` that hidden
17
+ tests use. Beginners often don't know *which* cases to try, and a raw traceback explains
18
+ *what* happened, not *which assumption was wrong*.
19
+
20
+ ## What's new here
21
+
22
+ | Existing tool | What it does | Gap for learners |
23
+ |---|---|---|
24
+ | `pytest` | runs tests you write | you must already know the edge cases |
25
+ | Hypothesis | powerful property-based fuzzing | steep learning curve; terse failure output |
26
+ | Edgecase-Provocateur | auto-generates beginner-friendly edge cases **and** coaches you through each failure | heuristic, exceptions only (see [limitations](#limitations)) |
27
+
28
+ The combination is the point: type-aware boundary generation + exception capture +
29
+ a readable report + reflection prompts instead of ready-made fixes.
30
+
31
+ ## Install
32
+
33
+ ```bash
34
+ pip install edgecase-provocateur
35
+ ```
36
+
37
+ Requires Python 3.9+. No dependencies.
38
+
39
+ ## Quick start
40
+
41
+ ```python
42
+ from edgecase_provocateur import provoke
43
+
44
+ @provoke
45
+ def find_max_difference(numbers):
46
+ largest = numbers[0]
47
+ smallest = numbers[0]
48
+ for num in numbers:
49
+ if num > largest:
50
+ largest = num
51
+ if num < smallest:
52
+ smallest = num
53
+ return largest - smallest
54
+
55
+ print(find_max_difference([1, 2, 3]))
56
+ ```
57
+
58
+ On the first call the package probes the function and prints:
59
+
60
+ ```
61
+ ============================================================
62
+ EDGECASE-PROVOCATEUR REPORT: find_max_difference()
63
+ ============================================================
64
+ 6 edge cases tried, 4 raised an exception.
65
+ ------------------------------------------------------------
66
+ Edge case : numbers = []
67
+ Full call : find_max_difference([])
68
+ Exception : IndexError: list index out of range
69
+ Where : line 8 -> largest = numbers[0]
70
+ Why : The function tried to use a position in a sequence that does not exist. ...
71
+ Reflect : What should the function do when the collection has no items (or too few)?
72
+ ...
73
+ ```
74
+
75
+ then runs your real call normally and prints `2`.
76
+
77
+ ### Explicit API (recommended for anything with side effects)
78
+
79
+ ```python
80
+ from edgecase_provocateur import analyze, print_report
81
+
82
+ report = analyze(find_max_difference, [1, 2, 3]) # example call; nothing printed
83
+ print_report(report)
84
+ print(len(report.failures), "failures")
85
+ for failure in report.failures:
86
+ print(failure.changed, failure.error_type, failure.line_no)
87
+ ```
88
+
89
+ Keyword arguments work too: `analyze(f, 4, b=2)`.
90
+
91
+ ### Decorator options
92
+
93
+ ```python
94
+ @provoke(once=False) # re-analyze on every call (default: first call only)
95
+ @provoke(show=False) # stay quiet; read f.last_report yourself
96
+ @provoke(max_cases=50, max_str_len=64)
97
+ ```
98
+
99
+ `max_cases` must be a non-negative integer; `max_str_len` must be a positive integer.
100
+
101
+ ## API
102
+
103
+ | Name | Description |
104
+ |---|---|
105
+ | `provoke` | decorator; probes on call, then runs the real call unchanged |
106
+ | `analyze(func, *args, **kwargs)` | returns an `AnalysisReport` |
107
+ | `AnalysisReport` | `.function_name`, `.results`, `.failures`, `.passes`, `.total` |
108
+ | `CaseResult` | `.test_input`, `.kwargs`, `.passed`, `.error_type`, `.message`, `.line_no`, `.line_text`, `.changed` |
109
+ | `format_report(report, limit=None)` / `print_report(report)` | render a report |
110
+
111
+ ## What gets generated
112
+
113
+ One argument is changed at a time, so each failure points at one input.
114
+
115
+ | Input | Edge cases |
116
+ |---|---|
117
+ | `int` | 0, 1, -1, `sys.maxsize`, `-sys.maxsize-1` |
118
+ | `float` | 0.0, -1.0, tiny, huge, ±inf, NaN |
119
+ | `str` | empty, one char, whitespace, long (capped), symbols, Unicode |
120
+ | `list` / `tuple` | empty, `[None]`, singleton, duplicates, wrong type, mixed types |
121
+ | `dict` | empty, `None` value, missing key |
122
+ | `set` | empty, `{None}`, wrong type |
123
+ | `bool` | the opposite value |
124
+ | `None` | 0, `""`, `[]`, `{}` |
125
+
126
+ Generation is deterministic and bounded (`max_cases`, default 200).
127
+
128
+ ## Limitations
129
+
130
+ - **Heuristic, finite.** A clean report is **not** proof of correctness.
131
+ - **Exceptions only.** It cannot tell that a function returns a *wrong answer* without a specification.
132
+ - **Some probes may be invalid** for your function's contract (e.g. it legitimately only accepts non-empty lists). Treat reports as prompts for reflection.
133
+ - **Your function runs many times.** Avoid probing functions that write files, hit the network, or change global state. Output printed by the probed function is suppressed during probing.
134
+ - **Not a sandbox.** Catching exceptions is not security isolation; there is no timeout, so an input that makes a function loop forever will hang the run. Never probe untrusted code.
135
+ - Probes receive deep copies of your arguments, so your own data is not mutated (best effort for uncopyable objects).
136
+
137
+ ## Development
138
+
139
+ ```bash
140
+ git clone https://github.com/ahmed123-ar/edgecase-provocateur
141
+ cd edgecase-provocateur
142
+ python -m venv .venv && source .venv/bin/activate
143
+ pip install -e ".[dev]"
144
+ pytest
145
+ ```
146
+
147
+ More: [architecture](docs/architecture.md) · [examples](docs/examples.md) · [publishing](docs/publishing.md) · [spec](docs/spec.md)
148
+
149
+ ## Team
150
+
151
+ Ahmed Raza, Hamza Hafeez, Usman Ahmed. CS1302, City University of Hong Kong.
152
+
153
+ ## License
154
+
155
+ MIT
@@ -0,0 +1,49 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "edgecase-provocateur"
7
+ version = "0.1.0"
8
+ description = "An educational tool that probes Python functions with edge cases and explains failures with Socratic feedback."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [
14
+ { name = "Ahmed Raza" },
15
+ { name = "Hamza Hafeez" },
16
+ { name = "Usman Ahmed" },
17
+ ]
18
+ keywords = ["testing", "edge cases", "education", "debugging", "decorator"]
19
+ classifiers = [
20
+ "Development Status :: 3 - Alpha",
21
+ "Intended Audience :: Education",
22
+ "Programming Language :: Python :: 3",
23
+ "Operating System :: OS Independent",
24
+ "Topic :: Education",
25
+ "Topic :: Software Development :: Testing",
26
+ ]
27
+ dependencies = []
28
+
29
+ [project.optional-dependencies]
30
+ dev = [
31
+ "pytest>=8.0",
32
+ "build>=1.0",
33
+ "twine>=5.0",
34
+ ]
35
+
36
+ [project.urls]
37
+ Homepage = "https://github.com/ahmed123-ar/edgecase-provocateur"
38
+ Repository = "https://github.com/ahmed123-ar/edgecase-provocateur"
39
+ Issues = "https://github.com/ahmed123-ar/edgecase-provocateur/issues"
40
+
41
+ [tool.setuptools]
42
+ package-dir = {"" = "src"}
43
+
44
+ [tool.setuptools.packages.find]
45
+ where = ["src"]
46
+
47
+ [tool.pytest.ini_options]
48
+ testpaths = ["tests"]
49
+ pythonpath = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,17 @@
1
+ """Edgecase-Provocateur: educational adversarial testing with Socratic feedback."""
2
+
3
+ from .core import analyze, provoke
4
+ from .models import AnalysisReport, CaseResult
5
+ from .report import format_report, print_report
6
+
7
+ __version__ = "0.1.0"
8
+
9
+ __all__ = [
10
+ "provoke",
11
+ "analyze",
12
+ "AnalysisReport",
13
+ "CaseResult",
14
+ "format_report",
15
+ "print_report",
16
+ "__version__",
17
+ ]
@@ -0,0 +1,80 @@
1
+ """Socratic feedback: turn an exception into an explanation and a question.
2
+
3
+ The coach never writes the fix. It names the violated assumption and asks the
4
+ learner to decide how the function *should* behave.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import Any, Dict, Optional
10
+
11
+
12
+ def explain(
13
+ error_type: Optional[str],
14
+ failed_input: Any,
15
+ line_no: Optional[int],
16
+ raw_error: Optional[str],
17
+ ) -> Dict[str, str]:
18
+ """Return ``{"why": ..., "reflection": ...}`` for one failure."""
19
+ location = f" at line {line_no}" if line_no is not None else ""
20
+ raw = raw_error or ""
21
+
22
+ if error_type == "IndexError":
23
+ why = (
24
+ "The function tried to use a position in a sequence that does not exist. "
25
+ "Check whether the collection can be empty or shorter than you assumed."
26
+ )
27
+ prompt = "What should the function do when the collection has no items (or too few)?"
28
+ elif error_type == "KeyError":
29
+ why = (
30
+ f"The function looked up the key {raw} in a dictionary that does not "
31
+ "contain it. Check whether every key you read is guaranteed to exist."
32
+ )
33
+ prompt = "Is a missing key an error, or should the function fall back to a default?"
34
+ elif error_type == "TypeError" and "NoneType" in raw:
35
+ why = (
36
+ "A value was None where the function expected a real value. "
37
+ "None often means 'nothing here' and cannot be used in arithmetic, "
38
+ "comparisons, or indexing."
39
+ )
40
+ prompt = "Can this parameter ever be None? Who is responsible for checking?"
41
+ elif error_type == "TypeError":
42
+ why = (
43
+ "An operation received a value of an incompatible type. "
44
+ "Check the input contract and whether values need validating first."
45
+ )
46
+ prompt = "Which input types does this function promise to accept?"
47
+ elif error_type == "ZeroDivisionError":
48
+ why = (
49
+ "A denominator became zero. Consider whether zero is a legal input "
50
+ "and how the function should define its behaviour then."
51
+ )
52
+ prompt = "How can you check the denominator before dividing, and what should be returned?"
53
+ elif error_type == "ValueError":
54
+ why = (
55
+ "The value had the right type but an unsuitable content "
56
+ f"(e.g. converting text to a number, or an empty sequence): {raw}"
57
+ )
58
+ prompt = "Which values are valid for this parameter, and how will you reject the others?"
59
+ elif error_type == "AttributeError":
60
+ why = (
61
+ "The code used an attribute or method that the value does not have. "
62
+ "This often happens when a value is None or a different type than expected."
63
+ )
64
+ prompt = "What type did you assume this value had when you wrote the method call?"
65
+ elif error_type in ("RecursionError", "MemoryError", "OverflowError"):
66
+ why = (
67
+ f"The function hit a resource limit ({error_type}). "
68
+ "Extreme sizes can expose loops or recursion that never settle."
69
+ )
70
+ prompt = "What is the largest input you want to support, and what stops the recursion or growth?"
71
+ elif error_type == "StopIteration":
72
+ why = "The function asked for the next item of an iterator that had none left."
73
+ prompt = "What should happen when there is nothing left to take?"
74
+ elif error_type == "AssertionError":
75
+ why = "An assertion in the code did not hold for this input."
76
+ prompt = "Is this input legal? If so, is the assertion too strict?"
77
+ else:
78
+ why = f"The function raised {error_type}{location}: {raw}"
79
+ prompt = "Which assumption about the input or program state was violated?"
80
+ return {"why": why, "reflection": prompt}
@@ -0,0 +1,171 @@
1
+ """Execution engine: run generated probes and capture exceptions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import contextlib
6
+ import contextvars
7
+ import copy
8
+ import functools
9
+ import inspect
10
+ import io
11
+ import linecache
12
+ import traceback
13
+ from typing import Any, Callable, Dict, Optional
14
+
15
+ from .engines import DEFAULT_MAX_CASES, DEFAULT_MAX_STR_LEN, generate_cases
16
+ from .models import AnalysisReport, CaseResult, Probe
17
+
18
+ # True while a diagnostic pass or a decorated call is running. It stops a
19
+ # recursive @provoke function from triggering an analysis inside an analysis.
20
+ _busy: contextvars.ContextVar = contextvars.ContextVar("edgecase_busy", default=False)
21
+
22
+
23
+ def _safe_copy(value: Any) -> Any:
24
+ """Deep-copy so probes cannot mutate the caller's data (best effort)."""
25
+ try:
26
+ return copy.deepcopy(value)
27
+ except Exception:
28
+ return value
29
+
30
+
31
+ def _label(func: Callable, probe: Probe) -> Optional[str]:
32
+ """Describe which argument was changed, e.g. ``numbers = []``."""
33
+ target = probe.target
34
+ if target is None:
35
+ return None
36
+ if isinstance(target, str):
37
+ return f"{target} = {probe.kwargs[target]!r}"
38
+ value = probe.args[target]
39
+ try:
40
+ names = list(inspect.signature(func).parameters)
41
+ name = names[target] if target < len(names) else f"argument {target}"
42
+ except (TypeError, ValueError):
43
+ name = f"argument {target}"
44
+ return f"{name} = {value!r}"
45
+
46
+
47
+ def _locate(func: Callable, exc: BaseException):
48
+ """Find the failing line, preferring a frame inside the learner's function.
49
+
50
+ The deepest traceback frame may be inside a library call (e.g. ``sum``);
51
+ the frame in the learner's own file is usually more useful.
52
+ """
53
+ frames = traceback.extract_tb(exc.__traceback__)
54
+ if not frames:
55
+ return None, None
56
+ code = getattr(func, "__code__", None)
57
+ own_file = code.co_filename if code else None
58
+ chosen = frames[-1]
59
+ for frame in reversed(frames):
60
+ if own_file and frame.filename == own_file:
61
+ chosen = frame
62
+ break
63
+ text = (chosen.line or linecache.getline(chosen.filename, chosen.lineno)).strip()
64
+ return chosen.lineno, text or None
65
+
66
+
67
+ def _run_probe(func: Callable, probe: Probe) -> CaseResult:
68
+ args = tuple(_safe_copy(a) for a in probe.args)
69
+ kwargs = {k: _safe_copy(v) for k, v in probe.kwargs.items()}
70
+ label = _label(func, probe)
71
+ sink = io.StringIO() # swallow prints from the probed function
72
+ try:
73
+ with contextlib.redirect_stdout(sink), contextlib.redirect_stderr(sink):
74
+ func(*args, **kwargs)
75
+ except Exception as exc: # a diagnostic result, not a crash
76
+ line_no, line_text = _locate(func, exc)
77
+ return CaseResult(
78
+ test_input=probe.args,
79
+ kwargs=probe.kwargs,
80
+ passed=False,
81
+ error_type=type(exc).__name__,
82
+ message=str(exc),
83
+ line_no=line_no,
84
+ line_text=line_text,
85
+ changed=label,
86
+ )
87
+ return CaseResult(test_input=probe.args, kwargs=probe.kwargs, passed=True, changed=label)
88
+
89
+
90
+ def _analyze(
91
+ func: Callable,
92
+ args: tuple,
93
+ kwargs: Dict[str, Any],
94
+ max_cases: int,
95
+ max_str_len: int,
96
+ ) -> AnalysisReport:
97
+ token = _busy.set(True)
98
+ try:
99
+ probes = generate_cases(args, kwargs, max_cases, max_str_len)
100
+ results = [_run_probe(func, p) for p in probes]
101
+ finally:
102
+ _busy.reset(token)
103
+ name = getattr(func, "__name__", repr(func))
104
+ return AnalysisReport(name, results)
105
+
106
+
107
+ def analyze(func: Callable, *args: Any, **kwargs: Any) -> AnalysisReport:
108
+ """Probe ``func`` with edge cases derived from the example call ``func(*args, **kwargs)``.
109
+
110
+ This is the explicit, recommended API. It returns an :class:`AnalysisReport`
111
+ and prints nothing. The function is called many times, so avoid functions
112
+ with irreversible side effects.
113
+ """
114
+ return _analyze(func, args, kwargs, DEFAULT_MAX_CASES, DEFAULT_MAX_STR_LEN)
115
+
116
+
117
+ def provoke(
118
+ func: Optional[Callable] = None,
119
+ *,
120
+ once: bool = True,
121
+ show: bool = True,
122
+ max_cases: int = DEFAULT_MAX_CASES,
123
+ max_str_len: int = DEFAULT_MAX_STR_LEN,
124
+ ):
125
+ """Decorator that probes a function with edge cases when it is called.
126
+
127
+ Works as ``@provoke`` or ``@provoke(once=False)``. On a call, the real
128
+ arguments are used as the example, the probe report is printed, and then
129
+ the function runs normally with the original arguments. Probe failures
130
+ never stop or change the real call.
131
+
132
+ Args:
133
+ once: analyze only on the first call (default) instead of every call.
134
+ show: print the report. If False the report is kept on
135
+ ``wrapper.last_report`` only.
136
+ max_cases: upper bound on generated cases.
137
+ max_str_len: length of the "long string" probe.
138
+ """
139
+
140
+ def decorate(f: Callable) -> Callable:
141
+ analyzed = False
142
+
143
+ @functools.wraps(f)
144
+ def wrapper(*args: Any, **kwargs: Any):
145
+ nonlocal analyzed
146
+ if _busy.get() or (once and analyzed):
147
+ return f(*args, **kwargs)
148
+ analyzed = True
149
+ token = _busy.set(True)
150
+ try:
151
+ # Analyze copies so the real call below sees untouched arguments.
152
+ report = _analyze(
153
+ f,
154
+ tuple(_safe_copy(a) for a in args),
155
+ {k: _safe_copy(v) for k, v in kwargs.items()},
156
+ max_cases,
157
+ max_str_len,
158
+ )
159
+ wrapper.last_report = report
160
+ if show:
161
+ from .report import print_report
162
+
163
+ print_report(report)
164
+ return f(*args, **kwargs)
165
+ finally:
166
+ _busy.reset(token)
167
+
168
+ wrapper.last_report = None
169
+ return wrapper
170
+
171
+ return decorate(func) if func is not None else decorate