nonetrace 0.1.0__tar.gz

nonetrace-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khalid Sulaiman Al-Mulaify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nonetrace-0.1.0/PKG-INFO

@@ -0,0 +1,644 @@
+Metadata-Version: 2.4
+Name: nonetrace
+Version: 0.1.0
+Summary: Explains where a None value came from when your Python program crashes because of it.
+Author-email: Khalid Sulaiman Al-Mulaify <khalidpythonist@gmail.com>
+License-Expression: MIT
+Keywords: none,debugging,traceback,beginners,errors
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Education
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nonetrace
+
+nonetrace tells you where a None came from. When your program crashes with an error like "'NoneType' object has no attribute 'upper'", Python shows you the line where the None was used. nonetrace adds a few plain-English lines underneath that show where the None was born, why, and what to change.
+
+You ran your program, and instead of the result you hoped for, Python printed something like this:
+
+```
+AttributeError: 'NoneType' object has no attribute 'upper'
+```
+
+If you are new to Python, that message can feel like a door slammed in your face. You never typed the word `NoneType`. You never asked for `None`. So where did it come from?
+
+`None` is Python's way of saying "nothing here". It is a real value, like `0` or `""`, but it means "no value at all". The tricky part is that Python hands it to you quietly, without any warning, in these situations:
+
+- a function finishes without a `return` line
+- a dictionary lookup with `.get()` finds nothing
+- a search like `re.search()` finds no match
+- you store the result of a method like `.sort()` that changes a list in place
+
+The `None` then travels through your program until a later line tries to use it, and only then does Python complain.
+
+## Why the traceback is not enough
+
+Take this little program. One function builds a greeting, another one shouts it:
+
+```python
+def make_greeting(name):
+    greeting = "Hello, " + name + "!"
+    print(greeting)
+
+def shout(text):
+    return text.upper()
+
+message = make_greeting("Ada")
+print(shout(message))
+```
+
+Run it with plain Python and you get:
+
+```
+Hello, Ada!
+Traceback (most recent call last):
+  File "C:\code\greet.py", line 9, in <module>
+    print(shout(message))
+          ^^^^^^^^^^^^^^
+  File "C:\code\greet.py", line 6, in shout
+    return text.upper()
+           ^^^^^^^^^^
+AttributeError: 'NoneType' object has no attribute 'upper'
+```
+
+Python points at line 6, inside `shout()`. But `shout()` is perfectly fine. The real mistake is up in `make_greeting()`: it prints the greeting instead of returning it, so it hands back `None`, and that `None` is passed along to `shout()`. The traceback shows you where the `None` was used, not where it was born. In a bigger program those two places can be far apart, in different functions or even different files, and that is where beginners lose hours.
+
+## What nonetrace does
+
+Here is the same program with two extra lines at the top that switch nonetrace on:
+
+```python
+import nonetrace
+nonetrace.enable()
+
+def make_greeting(name):
+    greeting = "Hello, " + name + "!"
+    print(greeting)
+
+def shout(text):
+    return text.upper()
+
+message = make_greeting("Ada")
+print(shout(message))
+```
+
+And here is what you see now:
+
+```
+Hello, Ada!
+Traceback (most recent call last):
+  File "C:\code\greet_enabled.py", line 12, in <module>
+    print(shout(message))
+          ^^^^^^^^^^^^^^
+  File "C:\code\greet_enabled.py", line 9, in shout
+    return text.upper()
+           ^^^^^^^^^^
+AttributeError: 'NoneType' object has no attribute 'upper'
+
+nonetrace: 'text' is None on greet_enabled.py line 9, and None has no attribute 'upper'.
+  'text' is None because it is a parameter of shout(), and the call on greet_enabled.py line 12 passed in 'message', which is None.
+  'message' is None because make_greeting() returned None at greet_enabled.py line 6.
+  'message' got that value on greet_enabled.py line 11: message = make_greeting("Ada")
+  Why: the function ended without a return statement, so Python gave back None automatically.
+  Hint: make_greeting() uses print(). Printing shows a value on the screen, but it does not hand the value back to the code that called make_greeting().
+  Suggested fix: replace 'print(greeting)' with 'return greeting' at the end of make_greeting() (greet_enabled.py line 6).
+```
+
+The normal traceback is still there, exactly as before. Underneath it, nonetrace follows the `None` backwards: `text` was `None` because the call passed in `message`, `message` was `None` because `make_greeting()` returned `None`, and `make_greeting()` returned `None` because it never had a `return` line. Then it tells you what to change.
+
+## Install and turn it on
+
+Install it with pip:
+
+```
+pip install nonetrace
+```
+
+There are two ways to use it. The first is to add these two lines at the very top of your program:
+
+```python
+import nonetrace
+nonetrace.enable()
+```
+
+The second way needs no change to your code at all. Instead of running `python myscript.py`, run:
+
+```
+python -m nonetrace myscript.py
+```
+
+Anything you type after the script name is passed to your script as usual, so `python -m nonetrace myscript.py input.txt` works the same way `python myscript.py input.txt` does.
+
+## Every picture nonetrace recognizes
+
+Each example below is a complete program you can run yourself. The output shown is exactly what nonetrace printed. (Only the folder in the traceback lines was shortened to `C:\code\`.) Every example was run with `python -m nonetrace`.
+
+### You forgot the return line
+
+```python
+def average(numbers):
+    result = sum(numbers) / len(numbers)
+
+score = average([80, 90, 100])
+print("With the bonus you have", score + 5)
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\forgot_return.py", line 5, in <module>
+    print("With the bonus you have", score + 5)
+                                     ~~~~~~^~~
+TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'
+
+nonetrace: 'score' is None on forgot_return.py line 5, and None cannot be used with '+'.
+  'score' is None because average() returned None at forgot_return.py line 2.
+  'score' got that value on forgot_return.py line 4: score = average([80, 90, 100])
+  Why: the function ended without a return statement, so Python gave back None automatically.
+  Suggested fix: add 'return result' as the last line of average(), right after forgot_return.py line 2.
+```
+
+`average()` does the calculation and stores it in `result`, but then simply stops. A function that reaches its end without a `return` gives back `None`. The fix is to add `return result` as its last line.
+
+### A return with no value
+
+```python
+def total_price(prices):
+    total = 0
+    for price in prices:
+        total = total + price
+    return
+
+cost = total_price([3, 4, 5])
+print("For two people:", cost * 2)
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\bare_return.py", line 8, in <module>
+    print("For two people:", cost * 2)
+                             ~~~~~^~~
+TypeError: unsupported operand type(s) for *: 'NoneType' and 'int'
+
+nonetrace: 'cost' is None on bare_return.py line 8, and None cannot be used with '*'.
+  'cost' is None because total_price() returned None at bare_return.py line 5.
+  'cost' got that value on bare_return.py line 7: cost = total_price([3, 4, 5])
+  Why: the function has a return with no value. The bare 'return' on bare_return.py line 5 hands back None.
+  Suggested fix: write the value you want after 'return' on bare_return.py line 5, for example 'return total'.
+```
+
+A `return` on its own means "stop here and give back nothing", which is `None`. Write the value after it: `return total`.
+
+### One branch of an if/else has no return
+
+```python
+def grade(score):
+    if score >= 90:
+        return "A"
+    elif score >= 80:
+        return "B"
+
+letter = grade(72)
+print("You got " + letter.upper())
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\one_branch.py", line 8, in <module>
+    print("You got " + letter.upper())
+                       ^^^^^^^^^^^^
+AttributeError: 'NoneType' object has no attribute 'upper'
+
+nonetrace: 'letter' is None on one_branch.py line 8, and None has no attribute 'upper'.
+  'letter' is None because grade() returned None at one_branch.py line 4.
+  'letter' got that value on one_branch.py line 7: letter = grade(72)
+  Why: one code path in the function has no return statement (check your if/else branches).
+  This time grade() reached its end on one_branch.py line 4 without meeting a return.
+  Suggested fix: make sure every path through grade() ends with 'return <value>', for example by adding an else branch or a final return at the end.
+```
+
+`grade()` returns something for 90 and above and for 80 and above, but a score of 72 falls through both checks and reaches the end of the function. Add an `else:` branch or a final `return` so that every score gets an answer.
+
+### The function returns None on purpose
+
+```python
+def find_user(users, name):
+    if name not in users:
+        return None
+    return users[name]
+
+users = {"ada": "Ada Lovelace", "grace": "Grace Hopper"}
+user = find_user(users, "linus")
+print("Welcome back, " + user.title())
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\explicit_none.py", line 8, in <module>
+    print("Welcome back, " + user.title())
+                             ^^^^^^^^^^
+AttributeError: 'NoneType' object has no attribute 'title'
+
+nonetrace: 'user' is None on explicit_none.py line 8, and None has no attribute 'title'.
+  'user' is None because find_user() returned None at explicit_none.py line 3.
+  'user' got that value on explicit_none.py line 7: user = find_user(users, "linus")
+  Why: the function explicitly returned None, with 'return None' on explicit_none.py line 3.
+  That return runs when this condition is true: name not in users
+  Suggested fix: check the result before you use it, for example 'if user is not None:', or change find_user() so it returns a real value in that case.
+```
+
+Sometimes `None` is the function's honest way of saying "I did not find it". That is fine, but the code that calls it has to be ready for that answer. Check with `if user is not None:` before using the result.
+
+### dict.get() with a missing key
+
+```python
+ages = {"Ada": 36, "Grace": 45}
+age = ages.get("Linus")
+print("Next year you will be", age + 1)
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\dict_get.py", line 3, in <module>
+    print("Next year you will be", age + 1)
+                                   ~~~~^~~
+TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'
+
+nonetrace: 'age' is None on dict_get.py line 3, and None cannot be used with '+'.
+  'age' is None because ages.get("Linus") returns None when the key "Linus" is not in the dictionary.
+  'age' got that value on dict_get.py line 2: age = ages.get("Linus")
+  dict .get() does not raise an error when a key is missing. It quietly gives back None instead.
+  'ages' has no key 'Linus'. The keys it does have are: 'Ada', 'Grace'.
+  Suggested fix: check that the key is there first with 'if "Linus" in ages:', or give .get() a default value, like ages.get("Linus", 0).
+```
+
+`.get()` is polite: when the key is missing it does not crash, it just gives you `None`. Give it a default as the second argument, like `ages.get("Linus", 0)`, or check `if "Linus" in ages:` first.
+
+### re.search() found no match
+
+```python
+import re
+
+text = "Order number: ABC"
+match = re.search(r"\d+", text)
+print("Found order", match.group())
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\regex_search.py", line 5, in <module>
+    print("Found order", match.group())
+                         ^^^^^^^^^^^
+AttributeError: 'NoneType' object has no attribute 'group'
+
+nonetrace: 'match' is None on regex_search.py line 5, and None has no attribute 'group'.
+  'match' is None because re.search(r"\d+", text) found no match, and re.search() returns None when the pattern does not match.
+  'match' got that value on regex_search.py line 4: match = re.search(r"\d+", text)
+  re.search() gives back a match object only when it finds the pattern. Otherwise it gives back None.
+  Suggested fix: check the result before you use it, for example 'if match:', and make sure the pattern really fits your text.
+```
+
+`re.search()`, `re.match()` and `re.fullmatch()` give you a match object only when the pattern is found. When nothing matches, they give you `None`. Always check `if match:` before calling `.group()`.
+
+### Storing the result of list.sort()
+
+```python
+scores = [70, 95, 82]
+ranked = scores.sort(reverse=True)
+print("Top score:", ranked[0])
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\list_sort.py", line 3, in <module>
+    print("Top score:", ranked[0])
+                        ~~~~~~^^^
+TypeError: 'NoneType' object is not subscriptable
+
+nonetrace: 'ranked' is None on list_sort.py line 3, and you cannot look inside None with [ ].
+  'ranked' is None because scores.sort(reverse=True) sorts 'scores' in place and returns None.
+  'ranked' got that value on list_sort.py line 2: ranked = scores.sort(reverse=True)
+  Methods like .sort() change the list itself. They do not give back a new list, so the result is None.
+  Suggested fix: use 'ranked = sorted(scores, reverse=True)' to get a new sorted list, or call 'scores.sort(reverse=True)' on its own line and keep using 'scores'.
+```
+
+`.sort()` rearranges the list you already have and returns `None`. If you want a new sorted list you can store, use `sorted(scores, reverse=True)` instead.
+
+### Storing the result of append(), extend() or reverse()
+
+```python
+shopping = ["milk", "bread"]
+shopping = shopping.append("eggs")
+print("Items to buy:", len(shopping))
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\list_append.py", line 3, in <module>
+    print("Items to buy:", len(shopping))
+                           ^^^^^^^^^^^^^
+TypeError: object of type 'NoneType' has no len()
+
+nonetrace: 'shopping' is None on list_append.py line 3, and None has no length.
+  'shopping' is None because shopping.append("eggs") changes 'shopping' in place and returns None.
+  'shopping' got that value on list_append.py line 2: shopping = shopping.append("eggs")
+  Methods like .append() change the list itself. They do not give back a new list, so the result is None.
+  Suggested fix: call 'shopping.append("eggs")' on its own line, then keep using 'shopping'.
+```
+
+This is one of the most common beginner mistakes of all. `.append()` changes the list and returns `None`, so writing `shopping = shopping.append("eggs")` throws your list away and puts `None` in its place. Just write `shopping.append("eggs")` on its own line. The same is true for `.extend()`, `.insert()`, `.remove()`, `.clear()` and `.reverse()` on lists, and `.update()` on dictionaries. Here is `.reverse()`:
+
+```python
+countdown = [1, 2, 3]
+backwards = countdown.reverse()
+for number in backwards:
+    print(number)
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\list_reverse.py", line 3, in <module>
+    for number in backwards:
+TypeError: 'NoneType' object is not iterable
+
+nonetrace: 'backwards' is None on list_reverse.py line 3, and you cannot loop over None or unpack it.
+  'backwards' is None because countdown.reverse() reverses 'countdown' in place and returns None.
+  'backwards' got that value on list_reverse.py line 2: backwards = countdown.reverse()
+  Methods like .reverse() change the list itself. They do not give back a new list, so the result is None.
+  Suggested fix: call 'countdown.reverse()' on its own line, then keep using 'countdown'. If you want a reversed copy instead, use 'countdown[::-1]'.
+```
+
+### random.shuffle()
+
+```python
+import random
+
+cards = ["Ace", "King", "Queen", "Jack"]
+deck = random.shuffle(cards)
+print("You drew the", deck[0])
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\shuffle.py", line 5, in <module>
+    print("You drew the", deck[0])
+                          ~~~~^^^
+TypeError: 'NoneType' object is not subscriptable
+
+nonetrace: 'deck' is None on shuffle.py line 5, and you cannot look inside None with [ ].
+  'deck' is None because random.shuffle(cards) shuffles the list in place and returns None.
+  'deck' got that value on shuffle.py line 4: deck = random.shuffle(cards)
+  random.shuffle() mixes up the list you give it. It does not give back a new list.
+  Suggested fix: call 'random.shuffle(cards)' on its own line, then keep using 'cards', which is now shuffled.
+```
+
+`random.shuffle()` mixes up the list you give it and returns `None`. Call it on its own line and keep using `cards`.
+
+### Storing the result of print()
+
+```python
+total = print(19 + 23)
+print("Double it:", total * 2)
+```
+
+```
+42
+Traceback (most recent call last):
+  File "C:\code\print_assign.py", line 2, in <module>
+    print("Double it:", total * 2)
+                        ~~~~~~^~~
+TypeError: unsupported operand type(s) for *: 'NoneType' and 'int'
+
+nonetrace: 'total' is None on print_assign.py line 2, and None cannot be used with '*'.
+  'total' is None because print() only shows text on the screen, and it always returns None.
+  'total' got that value on print_assign.py line 1: total = print(19 + 23)
+  print() is for showing things to the person running the program. It does not give anything back to your code.
+  Suggested fix: store the value first and print it separately: 'total = 19 + 23', then 'print(total)'.
+```
+
+`print()` shows something on the screen, and that is all it does. It gives nothing back to your program. Store the value first, then print it.
+
+### A variable that was set to None and never changed
+
+```python
+names = ["Ada", "Grace", "Linus"]
+winner = None
+for name in names:
+    if name.startswith("Z"):
+        winner = name
+print("The winner is " + winner.upper())
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\direct_none.py", line 6, in <module>
+    print("The winner is " + winner.upper())
+                             ^^^^^^^^^^^^
+AttributeError: 'NoneType' object has no attribute 'upper'
+
+nonetrace: 'winner' is None on direct_none.py line 6, and None has no attribute 'upper'.
+  'winner' is None because it was set to None directly on direct_none.py line 2.
+  That line is: winner = None
+  The later assignment on direct_none.py line 5 (winner = name) is inside an if block that most likely did not run, so it did not change 'winner'.
+  Suggested fix: give 'winner' a real value before you use it, or check 'if winner is not None:' first.
+```
+
+Starting a variable at `None` and filling it in later is a normal pattern. Here, though, nobody's name starts with "Z", so the line that would have changed `winner` never ran. nonetrace points out both the line that set it to `None` and the assignment that most likely did not happen. Check `if winner is not None:` before using it, or give it a sensible starting value.
+
+### A None that nonetrace cannot trace
+
+```python
+def log(message):
+    print("LOG:", message)
+
+def load_user():
+    return {"name": "Ada", "nickname": None}
+
+log("starting")
+user = load_user()
+nickname = user["nickname"]
+log("user loaded")
+print("Hi, " + nickname.title())
+```
+
+```
+LOG: starting
+LOG: user loaded
+Traceback (most recent call last):
+  File "C:\code\untraceable.py", line 11, in <module>
+    print("Hi, " + nickname.title())
+                   ^^^^^^^^^^^^^^
+AttributeError: 'NoneType' object has no attribute 'title'
+
+nonetrace: 'nickname' is None on untraceable.py line 11, and None has no attribute 'title'.
+  nonetrace could not find where this None came from.
+  'nickname' got its value on untraceable.py line 9: nickname = user["nickname"]
+  These are the last functions of yours that returned None. They are only candidates, not a sure answer:
+    1. log() returned None at untraceable.py line 2 (called from untraceable.py line 10)
+    2. log() returned None at untraceable.py line 2 (called from untraceable.py line 7)
+  Suggested fix: add 'print(repr(nickname))' on the lines before untraceable.py line 11 to see where it becomes None, and check 'if nickname is not None:' before you use it.
+```
+
+Here the `None` was sitting inside a dictionary, and nonetrace cannot see how it got there. Instead of guessing, it says so plainly. It shows the line where the variable got its value, and it lists the last few of your functions that returned `None`, clearly marked as candidates. In this case they are not the culprit: the `None` is simply stored in the dictionary. That honesty matters. A tool that sounds sure when it is not would send you in the wrong direction.
+
+## TypeError cases too
+
+`AttributeError` is not the only way `None` shows up. The same detective work runs for these errors as well.
+
+`'NoneType' object is not subscriptable` happens when you use `[ ]` on `None`:
+
+```python
+def load_scores():
+    scores = [90, 85, 70]
+
+scores = load_scores()
+print("First score:", scores[0])
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\te_subscript.py", line 5, in <module>
+    print("First score:", scores[0])
+                          ~~~~~~^^^
+TypeError: 'NoneType' object is not subscriptable
+
+nonetrace: 'scores' is None on te_subscript.py line 5, and you cannot look inside None with [ ].
+  'scores' is None because load_scores() returned None at te_subscript.py line 2.
+  'scores' got that value on te_subscript.py line 4: scores = load_scores()
+  Why: the function ended without a return statement, so Python gave back None automatically.
+  Suggested fix: add 'return scores' as the last line of load_scores(), right after te_subscript.py line 2.
+```
+
+`'NoneType' object is not iterable` happens when you loop over `None`:
+
+```python
+def get_names():
+    names = ["Ada", "Grace"]
+
+for name in get_names():
+    print(name)
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\te_iterable.py", line 4, in <module>
+    for name in get_names():
+TypeError: 'NoneType' object is not iterable
+
+nonetrace: 'get_names()' is None on te_iterable.py line 4, and you cannot loop over None or unpack it.
+  'get_names()' is None because get_names() returned None at te_iterable.py line 2.
+  Why: the function ended without a return statement, so Python gave back None automatically.
+  Suggested fix: add 'return names' as the last line of get_names(), right after te_iterable.py line 2.
+```
+
+`'NoneType' object is not callable` happens when you try to call `None` like a function:
+
+```python
+def pick_greeting(language):
+    if language == "en":
+        return lambda name: "Hello, " + name
+
+greet = pick_greeting("fr")
+print(greet("Ada"))
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\te_callable.py", line 6, in <module>
+    print(greet("Ada"))
+          ^^^^^^^^^^^^
+TypeError: 'NoneType' object is not callable
+
+nonetrace: 'greet' is None on te_callable.py line 6, and you cannot call None like a function.
+  'greet' is None because pick_greeting() returned None at te_callable.py line 2.
+  'greet' got that value on te_callable.py line 5: greet = pick_greeting("fr")
+  Why: one code path in the function has no return statement (check your if/else branches).
+  This time pick_greeting() reached its end on te_callable.py line 2 without meeting a return.
+  Suggested fix: make sure every path through pick_greeting() ends with 'return <value>', for example by adding an else branch or a final return at the end.
+```
+
+`unsupported operand type(s)` happens when you do math with `None`:
+
+```python
+def get_price(item):
+    prices = {"apple": 3, "pear": 4}
+    if item in prices:
+        return prices[item]
+
+total = 10 + get_price("mango")
+print("Total:", total)
+```
+
+```
+Traceback (most recent call last):
+  File "C:\code\te_operand.py", line 6, in <module>
+    total = 10 + get_price("mango")
+            ~~~^~~~~~~~~~~~~~~~~~~~
+TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'
+
+nonetrace: 'get_price("mango")' is None on te_operand.py line 6, and None cannot be used with '+'.
+  'get_price("mango")' is None because get_price() returned None at te_operand.py line 3.
+  Why: one code path in the function has no return statement (check your if/else branches).
+  This time get_price() reached its end on te_operand.py line 3 without meeting a return.
+  Suggested fix: make sure every path through get_price() ends with 'return <value>', for example by adding an else branch or a final return at the end.
+```
+
+## What it cannot do
+
+It only sees functions written in Python. Built-in functions like `dict.get()`, `re.search()` and `list.sort()` are written in C, and nonetrace cannot watch them from the inside. That is why it recognizes them by their shape instead: when it sees `x = something.sort()`, it knows what `.sort()` does.
+
+It slows your program down while it is switched on, because it keeps an eye on every function of yours that returns. That is perfectly fine while you are hunting a bug, but it is meant for debugging, not for programs running in production.
+
+Some IDE consoles and notebook tools replace Python's error hook with their own, and then the explanation will not be printed automatically. In that case you can still ask for it yourself inside an `except` block:
+
+```python
+import nonetrace
+nonetrace.enable()
+
+def make_title(words):
+    title = " ".join(words).title()
+
+try:
+    heading = make_title(["hello", "world"])
+    print(heading.center(30))
+except AttributeError as error:
+    print(nonetrace.explain(error))
+```
+
+```
+nonetrace: 'heading' is None on in_except.py line 9, and None has no attribute 'center'.
+  'heading' is None because make_title() returned None at in_except.py line 5.
+  'heading' got that value on in_except.py line 8: heading = make_title(["hello", "world"])
+  Why: the function ended without a return statement, so Python gave back None automatically.
+  Suggested fix: add 'return title' as the last line of make_title(), right after in_except.py line 5.
+```
+
+## How it works
+
+When you switch nonetrace on, it keeps a small diary. Every time one of your own functions returns `None`, it writes down the function's name, the line where it returned and the line that called it. It keeps only the last 200 entries, and it ignores Python's own library and installed packages so that the diary is about your code. When your program crashes because of `None`, nonetrace reads your source code, finds the variable that was `None` on the crashing line, looks backwards for the line that gave that variable its value, and checks that line against the diary and against a list of well-known built-in functions that return `None`. If the value came from one of your functions, it reads that function to explain why it returned `None`. If it cannot work out the answer, it says so.
+
+## API
+
+`nonetrace.enable()` switches nonetrace on: it starts a fresh diary and adds the explanation to Python's error messages.
+
+`nonetrace.disable()` switches it off again and puts Python's normal error handling back.
+
+`nonetrace.explain(error)` returns the explanation for an exception as a string, or `None` if the error has nothing to do with `None`.
+
+## License
+
+MIT. See the LICENSE file.