# Crab Debugger
This repo contains the Python equivalent of Rust's `dbg!()` macro debugging tool, which helps developers inspect variables and expressions during development. The `dbg` method is a perfect replacement for Python built-in function `print` so if that is your way of debugging, then you can switch to `crab_dbg` with just a `Ctrl + R` to replace `print(` with `dbg(`.
## Features
- Easily print values of variables and expressions using the `dbg()` function, eliminating the need for multiple `print()` statements
- Supports primitive types (int, char, str, bool, etc.) along with basic and complex data structures (lists, arrays, NumPy arrays, PyTorch tensors, etc.)
- When `dbg()` is called, the output also includes the file name, line number, and other key info for context
- Able to process multi-line arguments and recursively inspects user-defined classes and nested objects.
## Example Usage
```python
from sys import stderr
from crab_dbg import dbg
pai = 3.14
ultimate_answer = 42
flag = True
fruits = ["apple", "peach", "watermelon"]
country_to_capital_cities = {
"China": "Beijing",
"United Kingdom": "London",
"Liyue": "Liyue Harbor",
}
# You can use dbg to inspect a lot of variables.
dbg(
pai,
ultimate_answer,
flag, # You can leave a comment here as well, dbg() won't show this comment.
fruits,
country_to_capital_cities,
)
# Or, you can ust dbg to inspect one. Note that you can pass any keyword arguments originally supported by print()
dbg(country_to_capital_cities, file=stderr)
# You can also use dbg to inspect expressions.
dbg(1 + 1)
# When used with objects, it will show all fields contained by that object.
linked_list = LinkedList.create(2)
dbg(linked_list)
# dbg() works with lists, tuples, and dictionaries.
dbg(
[linked_list, linked_list],
(linked_list, linked_list),
{"a": 1, "b": linked_list},
[
1,
2,
3,
4,
],
)
# For even more complex structures, it works as well.
stack = Stack()
stack.push(linked_list)
stack.push(linked_list)
dbg(stack)
dbg("What if my input is a string?")
# If your type has its own __repr__ or __str__ implementation, no worries, crab_dbg will jut use it.
phone = Phone("Apple", "white", 1099)
dbg(phone)
# It works with your favorite machine learning data structures as well.
import numpy as np
import torch
numpy_array = np.zeros(shape=(2, 3))
dbg(numpy_array)
torch_tensor = torch.from_numpy(numpy_array)
dbg(torch_tensor)
# If invoked without arguments, then it will just print the filename and line number.
dbg()
```
The above example will generate the following output in your terminal:
```text
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:76:5] pai = 3.14
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:76:5] ultimate_answer = 42
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:76:5] flag = True
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:76:5] fruits = [
'apple',
'peach',
'watermelon'
]
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:76:5] country_to_capital_cities = {
China: Beijing
United Kingdom: London
Liyue: Liyue Harbor
}
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:85:5] country_to_capital_cities = {
China: Beijing
United Kingdom: London
Liyue: Liyue Harbor
}
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:88:5] 1 + 1 = 2
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:92:5] linked_list = LinkedList {
start: Node {
val: 0
next: Node {
val: 1
next: None
}
}
}
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:95:5] [linked_list, linked_list] = [
LinkedList {
start: Node {
val: 0
next: Node {
val: 1
next: None
}
}
},
LinkedList {
start: Node {
val: 0
next: Node {
val: 1
next: None
}
}
}
]
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:95:5] (linked_list, linked_list) = (
LinkedList {
start: Node {
val: 0
next: Node {
val: 1
next: None
}
}
},
LinkedList {
start: Node {
val: 0
next: Node {
val: 1
next: None
}
}
}
)
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:95:5] {"a": 1, "b": linked_list} = {
a: 1
b: LinkedList {
start: Node {
val: 0
next: Node {
val: 1
next: None
}
}
}
}
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:95:5] [1,2,3,4,] = [
1,
2,
3,
4
]
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:111:5] stack = Stack {
data: [
LinkedList {
start: Node {
val: 0
next: Node {
val: 1
next: None
}
}
},
LinkedList {
start: Node {
val: 0
next: Node {
val: 1
next: None
}
}
}
]
}
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:113:5] "What if my input is a string?" = 'What if my input is a string?'
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:117:5] phone = A white phone made by Apple, official price: 1099.
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:120:5] numpy_array =
array([[0., 0., 0.],
[0., 0., 0.]])
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:123:5] torch_tensor =
tensor([[0., 0., 0.],
[0., 0., 0.]], dtype=torch.float64)
[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:126:5]
```
For full executable code please refer to [./examples/example.py](./examples/example.py).
## License
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](./LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "crab_dbg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "dbg, debug, rust",
"author": null,
"author_email": "Wenqing Zong <wenqing.zong98@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/78/b7/4d623a1c2cbe0b8594bfb63aa05af94bb6fa4dc6b5f4b182431da350130f/crab_dbg-0.1.0.tar.gz",
"platform": null,
"description": "# Crab Debugger\nThis repo contains the Python equivalent of Rust's `dbg!()` macro debugging tool, which helps developers inspect variables and expressions during development. The `dbg` method is a perfect replacement for Python built-in function `print` so if that is your way of debugging, then you can switch to `crab_dbg` with just a `Ctrl + R` to replace `print(` with `dbg(`.\n\n## Features\n- Easily print values of variables and expressions using the `dbg()` function, eliminating the need for multiple `print()` statements\n- Supports primitive types (int, char, str, bool, etc.) along with basic and complex data structures (lists, arrays, NumPy arrays, PyTorch tensors, etc.)\n- When `dbg()` is called, the output also includes the file name, line number, and other key info for context\n- Able to process multi-line arguments and recursively inspects user-defined classes and nested objects. \n\n## Example Usage\n```python\nfrom sys import stderr\nfrom crab_dbg import dbg\n\npai = 3.14\nultimate_answer = 42\nflag = True\nfruits = [\"apple\", \"peach\", \"watermelon\"]\ncountry_to_capital_cities = {\n \"China\": \"Beijing\",\n \"United Kingdom\": \"London\",\n \"Liyue\": \"Liyue Harbor\",\n}\n\n# You can use dbg to inspect a lot of variables.\ndbg(\n pai,\n ultimate_answer,\n flag, # You can leave a comment here as well, dbg() won't show this comment.\n fruits,\n country_to_capital_cities,\n)\n\n# Or, you can ust dbg to inspect one. Note that you can pass any keyword arguments originally supported by print()\ndbg(country_to_capital_cities, file=stderr)\n\n# You can also use dbg to inspect expressions.\ndbg(1 + 1)\n\n# When used with objects, it will show all fields contained by that object.\nlinked_list = LinkedList.create(2)\ndbg(linked_list)\n\n# dbg() works with lists, tuples, and dictionaries.\ndbg(\n [linked_list, linked_list],\n (linked_list, linked_list),\n {\"a\": 1, \"b\": linked_list},\n [\n 1,\n 2,\n 3,\n 4,\n ],\n)\n\n# For even more complex structures, it works as well.\nstack = Stack()\nstack.push(linked_list)\nstack.push(linked_list)\ndbg(stack)\n\ndbg(\"What if my input is a string?\")\n\n# If your type has its own __repr__ or __str__ implementation, no worries, crab_dbg will jut use it.\nphone = Phone(\"Apple\", \"white\", 1099)\ndbg(phone)\n\n# It works with your favorite machine learning data structures as well.\nimport numpy as np\nimport torch\nnumpy_array = np.zeros(shape=(2, 3))\ndbg(numpy_array)\n\ntorch_tensor = torch.from_numpy(numpy_array)\ndbg(torch_tensor)\n\n# If invoked without arguments, then it will just print the filename and line number.\ndbg()\n```\n\nThe above example will generate the following output in your terminal:\n```text\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:76:5] pai = 3.14\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:76:5] ultimate_answer = 42\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:76:5] flag = True\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:76:5] fruits = [\n 'apple',\n 'peach',\n 'watermelon'\n]\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:76:5] country_to_capital_cities = {\n China: Beijing\n United Kingdom: London\n Liyue: Liyue Harbor\n}\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:85:5] country_to_capital_cities = {\n China: Beijing\n United Kingdom: London\n Liyue: Liyue Harbor\n}\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:88:5] 1 + 1 = 2\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:92:5] linked_list = LinkedList {\n start: Node {\n val: 0\n next: Node {\n val: 1\n next: None\n }\n }\n}\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:95:5] [linked_list, linked_list] = [\n LinkedList {\n start: Node {\n val: 0\n next: Node {\n val: 1\n next: None\n }\n }\n },\n LinkedList {\n start: Node {\n val: 0\n next: Node {\n val: 1\n next: None\n }\n }\n }\n]\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:95:5] (linked_list, linked_list) = (\n LinkedList {\n start: Node {\n val: 0\n next: Node {\n val: 1\n next: None\n }\n }\n },\n LinkedList {\n start: Node {\n val: 0\n next: Node {\n val: 1\n next: None\n }\n }\n }\n)\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:95:5] {\"a\": 1, \"b\": linked_list} = {\n a: 1\n b: LinkedList {\n start: Node {\n val: 0\n next: Node {\n val: 1\n next: None\n }\n }\n }\n}\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:95:5] [1,2,3,4,] = [\n 1,\n 2,\n 3,\n 4\n]\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:111:5] stack = Stack {\n data: [\n LinkedList {\n start: Node {\n val: 0\n next: Node {\n val: 1\n next: None\n }\n }\n },\n LinkedList {\n start: Node {\n val: 0\n next: Node {\n val: 1\n next: None\n }\n }\n }\n ]\n}\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:113:5] \"What if my input is a string?\" = 'What if my input is a string?'\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:117:5] phone = A white phone made by Apple, official price: 1099.\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:120:5] numpy_array = \narray([[0., 0., 0.],\n [0., 0., 0.]])\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:123:5] torch_tensor = \ntensor([[0., 0., 0.],\n [0., 0., 0.]], dtype=torch.float64)\n[/Users/wenqingzong/Projects/crab_dbg/examples/example.py:126:5]\n\n```\n\nFor full executable code please refer to [./examples/example.py](./examples/example.py).\n\n## License\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](./LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "Python equivalent to Rust's `dbg!()` macro",
"version": "0.1.0",
"project_urls": {
"repository": "https://github.com/WenqingZong/crab_dbg"
},
"split_keywords": [
"dbg",
" debug",
" rust"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1ba40307e650b4f67bb74955bb114dfd51f88b3a25075f452ff188b46aee4162",
"md5": "a77c28beaab070566f1880a4c296f8c0",
"sha256": "9981f49edb98917d356d170b4051d578f1a1f0cb99ac36a6cabb5881aaa31e50"
},
"downloads": -1,
"filename": "crab_dbg-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a77c28beaab070566f1880a4c296f8c0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 18101,
"upload_time": "2024-10-08T02:01:09",
"upload_time_iso_8601": "2024-10-08T02:01:09.798254Z",
"url": "https://files.pythonhosted.org/packages/1b/a4/0307e650b4f67bb74955bb114dfd51f88b3a25075f452ff188b46aee4162/crab_dbg-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "78b74d623a1c2cbe0b8594bfb63aa05af94bb6fa4dc6b5f4b182431da350130f",
"md5": "dd5fcf6e2b22ef8c11d6f46941f0264e",
"sha256": "0d6431ef8cb681cf3a43816394b912b98e6805359b1aebbf869e7672700e9066"
},
"downloads": -1,
"filename": "crab_dbg-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "dd5fcf6e2b22ef8c11d6f46941f0264e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 18647,
"upload_time": "2024-10-08T02:01:11",
"upload_time_iso_8601": "2024-10-08T02:01:11.659878Z",
"url": "https://files.pythonhosted.org/packages/78/b7/4d623a1c2cbe0b8594bfb63aa05af94bb6fa4dc6b5f4b182431da350130f/crab_dbg-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-08 02:01:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "WenqingZong",
"github_project": "crab_dbg",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "crab_dbg"
}
JSON
