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.
- edgecase_provocateur-0.1.0/LICENSE +21 -0
- edgecase_provocateur-0.1.0/PKG-INFO +180 -0
- edgecase_provocateur-0.1.0/README.md +155 -0
- edgecase_provocateur-0.1.0/pyproject.toml +49 -0
- edgecase_provocateur-0.1.0/setup.cfg +4 -0
- edgecase_provocateur-0.1.0/src/edgecase_provocateur/__init__.py +17 -0
- edgecase_provocateur-0.1.0/src/edgecase_provocateur/coach.py +80 -0
- edgecase_provocateur-0.1.0/src/edgecase_provocateur/core.py +171 -0
- edgecase_provocateur-0.1.0/src/edgecase_provocateur/engines.py +154 -0
- edgecase_provocateur-0.1.0/src/edgecase_provocateur/models.py +59 -0
- edgecase_provocateur-0.1.0/src/edgecase_provocateur/report.py +54 -0
- edgecase_provocateur-0.1.0/src/edgecase_provocateur.egg-info/PKG-INFO +180 -0
- edgecase_provocateur-0.1.0/src/edgecase_provocateur.egg-info/SOURCES.txt +20 -0
- edgecase_provocateur-0.1.0/src/edgecase_provocateur.egg-info/dependency_links.txt +1 -0
- edgecase_provocateur-0.1.0/src/edgecase_provocateur.egg-info/requires.txt +5 -0
- edgecase_provocateur-0.1.0/src/edgecase_provocateur.egg-info/top_level.txt +1 -0
- edgecase_provocateur-0.1.0/tests/test_coach.py +40 -0
- edgecase_provocateur-0.1.0/tests/test_core.py +139 -0
- edgecase_provocateur-0.1.0/tests/test_decorator_output.py +49 -0
- edgecase_provocateur-0.1.0/tests/test_engines.py +111 -0
- edgecase_provocateur-0.1.0/tests/test_integration.py +24 -0
- edgecase_provocateur-0.1.0/tests/test_report.py +48 -0
|
@@ -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
|
+
[](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
|
+
[](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,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
|