# brBug
`brBug` is a tool/library to debug android BeeWare apps on Android with ease.
## Installation
Install using pip: `pip install brbug`.
```bash
pip install brbug
```
If you want the `rich` version of the `brbug` CLI, you can also install it using: `pip install brbug[rich]`
If you manage your briefcase dependencies using `pyproject.toml`, add `brdebug` to the app `requires`.
## Usage
brBug contains two part: the toga part and the build part.
At the build instead of running your android app with:
```bash
briefcase run android -u -d device_id
```
you can run it with:
```bash
brbug -d device_id
```
(or if you want you can also disable the `briefcase run` command using `-X`, and just stay with the build step like this `brbug -X -d device_id && briefcase run ...`).
After you can see that in you `resources` folder there is a file called `_brbug.tar.gz`.
Then in your toga app use it like this:
```python
import brbug
@brbug.catch_beeapp
class YourTogaApp(toga.App):
```
That's it.
Now `brbug` will use the `.tar.gz` file to create better traceback (using [friendly-traceback](https://friendly-traceback.github.io/docs/index.html)).
Here is an example of better traceback with brBug :
```python
W/python.stderr: Traceback (most recent call last):
W/python.stderr: File "/data/data/com.matan_h.ipython.bee_ipython/files/chaquopy/AssetFinder/requirements/brbug/brbug.py", line 146, in wrapper
W/python.stderr:
W/python.stderr: File "/data/data/com.matan_h.ipython.bee_ipython/files/chaquopy/AssetFinder/app/bee_ipython/app.py", line 38, in startup
W/python.stderr: nameerror
W/python.stderr: NameError: name 'nameerror' is not defined. Did you mean: 'NameError'?
W/python.stderr:
W/python.stderr: A `NameError` exception indicates that a variable or
W/python.stderr: function name is not known to Python.
W/python.stderr: Most often, this is because there is a spelling mistake.
W/python.stderr: However, sometimes it is because the name is used
W/python.stderr: before being defined or given a value.
W/python.stderr: Did you mean `NameError`?
W/python.stderr: In your program, no object with the name `nameerror` exists.
W/python.stderr: The Python builtin `NameError` has a similar name.
W/python.stderr:
```
compare this to the default android python crash/traceback:
```python
E/AndroidRuntime: Caused by: com.chaquo.python.PyException: NameError: name 'nameerror' is not defined
E/AndroidRuntime: at <python>.bee_ipython.app.startup(app.py:38)
E/AndroidRuntime: at <python>.toga.app._startup(app.py:624)
E/AndroidRuntime: at <python>.toga_android.app.create(app.py:179)
E/AndroidRuntime: at <python>.toga_android.app.main_loop(app.py:199)
E/AndroidRuntime: at <python>.toga.app.main_loop(app.py:663)
E/AndroidRuntime: at <python>.__main__.<module>(__main__.py:3)
E/AndroidRuntime: at <python>.runpy._run_code(<frozen runpy>:88)
```
## Supported tools
brBug modifies the `executing` engine to work on android using the `tar.gz` source.
That mean, by extension it supports most debugging tools:
* [snoop](https://github.com/alexmojaki/snoop) - if you don't know this yet, highly recommended - it's awesome.
* [python-devtools](https://github.com/samuelcolvin/python-devtools).
* friendly-traceback - this package already provide it by default.
* [icecream](https://github.com/gruns/icecream) (although it doesn't look good in the android logcat view - somehow each word is in different line)
## How its works
Chaquopy/beeware python apps are in a `pyc` state, which mean that no line information is stored.
That cause the normal python traceback/error to look like this:
The `build` side generate `.tar.gz` file of all `.py` files in your application directory, then the `toga` side open it, find the python source and modify `executing` to use it as source.
#### Why I need this `@brbug.catch_beeapp` ? It cannot just catch the errors automatically?
The "normal" way to catch errors is to use `sys.excepthook`. Unfortunately [chaquopy doesn't support it](https://github.com/chaquo/chaquopy/issues/1053). The other way is use `try/except`. But then `executing` came across `app.mainloop` it crashes, as It's pretty much a java method (`executing.executing.NotOneValueFound`). Maybe in the future I will create a `mrbug.automatic` module which detect and catch the toga app automatically.
### what `@brbug.catch_beeapp` does?
It wraps every method you defined (And not the ones that are inherited) with `try/ except : print traceback` to make it able to print traceback when a function fails
## FAQ
### What not supported
* `rich.traceback` - it uses the traceback object instead of `executing` or `stack_data`, so I cannot support it.
### How to report errors/problems/suggestions
please open a [GitHub issue](https://github.com/matan-h/brbug/issues)
### Why it's named 'brBug'
It's like `briefcaseBug` but no one can spell it right, so `brBug`.
it also sounds like `mr. Bug` which is nice.
### How can I donate you
If you found this tool/library useful, it would be great if you could buy me a coffee:
<a href="https://www.buymeacoffee.com/matanh" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-blue.png" alt="Buy Me A Coffee" height="47" width="200"></a>
Raw data
{
"_id": null,
"home_page": "https://github.com/matan-h/brbug",
"name": "brbug",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6,<4.0",
"maintainer_email": "",
"keywords": "beeware,android,debug,debuging,simple,easy,briefcase",
"author": "matan-h",
"author_email": "matan.honig2@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a5/7a/524f9d2a172d84e6b06884403727be33f401d9b14f408eb45aa2d562a429/brbug-0.1.1.1.tar.gz",
"platform": null,
"description": "# brBug\n\n`brBug` is a tool/library to debug android BeeWare apps on Android with ease.\n\n## Installation\nInstall using pip: `pip install brbug`.\n```bash\npip install brbug\n```\nIf you want the `rich` version of the `brbug` CLI, you can also install it using: `pip install brbug[rich]`\n\nIf you manage your briefcase dependencies using `pyproject.toml`, add `brdebug` to the app `requires`.\n\n## Usage\n\nbrBug contains two part: the toga part and the build part.\n\nAt the build instead of running your android app with:\n\n```bash\nbriefcase run android -u -d device_id\n```\n\nyou can run it with:\n\n```bash\nbrbug -d device_id\n```\n\n(or if you want you can also disable the `briefcase run` command using `-X`, and just stay with the build step like this `brbug -X -d device_id && briefcase run ...`).\n\nAfter you can see that in you `resources` folder there is a file called `_brbug.tar.gz`. \n\nThen in your toga app use it like this:\n\n```python\nimport brbug\n@brbug.catch_beeapp\nclass YourTogaApp(toga.App):\n```\n\nThat's it.\nNow `brbug` will use the `.tar.gz` file to create better traceback (using [friendly-traceback](https://friendly-traceback.github.io/docs/index.html)).\n\nHere is an example of better traceback with brBug :\n\n```python\nW/python.stderr: Traceback (most recent call last):\nW/python.stderr: File \"/data/data/com.matan_h.ipython.bee_ipython/files/chaquopy/AssetFinder/requirements/brbug/brbug.py\", line 146, in wrapper\nW/python.stderr: \nW/python.stderr: File \"/data/data/com.matan_h.ipython.bee_ipython/files/chaquopy/AssetFinder/app/bee_ipython/app.py\", line 38, in startup\nW/python.stderr: nameerror\nW/python.stderr: NameError: name 'nameerror' is not defined. Did you mean: 'NameError'?\nW/python.stderr: \nW/python.stderr: A `NameError` exception indicates that a variable or\nW/python.stderr: function name is not known to Python.\nW/python.stderr: Most often, this is because there is a spelling mistake.\nW/python.stderr: However, sometimes it is because the name is used\nW/python.stderr: before being defined or given a value.\nW/python.stderr: Did you mean `NameError`?\nW/python.stderr: In your program, no object with the name `nameerror` exists.\nW/python.stderr: The Python builtin `NameError` has a similar name.\nW/python.stderr: \n```\n\ncompare this to the default android python crash/traceback:\n\n```python\nE/AndroidRuntime: Caused by: com.chaquo.python.PyException: NameError: name 'nameerror' is not defined\nE/AndroidRuntime: at <python>.bee_ipython.app.startup(app.py:38)\nE/AndroidRuntime: at <python>.toga.app._startup(app.py:624)\nE/AndroidRuntime: at <python>.toga_android.app.create(app.py:179)\nE/AndroidRuntime: at <python>.toga_android.app.main_loop(app.py:199)\nE/AndroidRuntime: at <python>.toga.app.main_loop(app.py:663)\nE/AndroidRuntime: at <python>.__main__.<module>(__main__.py:3)\nE/AndroidRuntime: at <python>.runpy._run_code(<frozen runpy>:88)\n```\n\n## Supported tools\n\nbrBug modifies the `executing` engine to work on android using the `tar.gz` source. \n\nThat mean, by extension it supports most debugging tools:\n\n* [snoop](https://github.com/alexmojaki/snoop) - if you don't know this yet, highly recommended - it's awesome.\n* [python-devtools](https://github.com/samuelcolvin/python-devtools). \n* friendly-traceback - this package already provide it by default.\n* [icecream](https://github.com/gruns/icecream) (although it doesn't look good in the android logcat view - somehow each word is in different line)\n\n## How its works\n\nChaquopy/beeware python apps are in a `pyc` state, which mean that no line information is stored.\n That cause the normal python traceback/error to look like this:\n\nThe `build` side generate `.tar.gz` file of all `.py` files in your application directory, then the `toga` side open it, find the python source and modify `executing` to use it as source. \n\n#### Why I need this `@brbug.catch_beeapp` ? It cannot just catch the errors automatically?\n\nThe \"normal\" way to catch errors is to use `sys.excepthook`. Unfortunately [chaquopy doesn't support it](https://github.com/chaquo/chaquopy/issues/1053). The other way is use `try/except`. But then `executing` came across `app.mainloop` it crashes, as It's pretty much a java method (`executing.executing.NotOneValueFound`). Maybe in the future I will create a `mrbug.automatic` module which detect and catch the toga app automatically. \n### what `@brbug.catch_beeapp` does?\nIt wraps every method you defined (And not the ones that are inherited) with `try/ except : print traceback` to make it able to print traceback when a function fails\n\n## FAQ\n### What not supported\n\n* `rich.traceback` - it uses the traceback object instead of `executing` or `stack_data`, so I cannot support it. \n\n### How to report errors/problems/suggestions\n\nplease open a [GitHub issue](https://github.com/matan-h/brbug/issues)\n\n### Why it's named 'brBug'\n\nIt's like `briefcaseBug` but no one can spell it right, so `brBug`. \nit also sounds like `mr. Bug` which is nice.\n\n### How can I donate you\n\nIf you found this tool/library useful, it would be great if you could buy me a coffee:\n\n<a href=\"https://www.buymeacoffee.com/matanh\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/default-blue.png\" alt=\"Buy Me A Coffee\" height=\"47\" width=\"200\"></a>",
"bugtrack_url": null,
"license": "MIT",
"summary": "a tool/library to debug android BeeWare apps on Android with ease.",
"version": "0.1.1.1",
"project_urls": {
"Homepage": "https://github.com/matan-h/brbug",
"issues": "https://github.com/matan-h/brbug/issues"
},
"split_keywords": [
"beeware",
"android",
"debug",
"debuging",
"simple",
"easy",
"briefcase"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c79ade98dd533e8bea9952498c6ca73f60563af5dd1d148964723266b46e1239",
"md5": "e2b1a6d42b1aa2e12a21c50ae2cd6b0e",
"sha256": "3a3f401d48a4699391073644f8c18074321a7579af45e7dbf16791ce08797c35"
},
"downloads": -1,
"filename": "brbug-0.1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2b1a6d42b1aa2e12a21c50ae2cd6b0e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6,<4.0",
"size": 7547,
"upload_time": "2023-12-15T09:29:47",
"upload_time_iso_8601": "2023-12-15T09:29:47.171473Z",
"url": "https://files.pythonhosted.org/packages/c7/9a/de98dd533e8bea9952498c6ca73f60563af5dd1d148964723266b46e1239/brbug-0.1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a57a524f9d2a172d84e6b06884403727be33f401d9b14f408eb45aa2d562a429",
"md5": "e3f2338070da14e6ab4a7c770ef1b3ab",
"sha256": "46c60bf299b8d6de6a10f3fd17a5bdadb0a04a6330866414d3c8272f7fc78c0f"
},
"downloads": -1,
"filename": "brbug-0.1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "e3f2338070da14e6ab4a7c770ef1b3ab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4.0",
"size": 6687,
"upload_time": "2023-12-15T09:29:48",
"upload_time_iso_8601": "2023-12-15T09:29:48.928111Z",
"url": "https://files.pythonhosted.org/packages/a5/7a/524f9d2a172d84e6b06884403727be33f401d9b14f408eb45aa2d562a429/brbug-0.1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-15 09:29:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matan-h",
"github_project": "brbug",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "brbug"
}
JSON
