Metadata-Version: 2.1
Name: brbug
Version: 0.1.0
Summary: 
Author: matan-h
Author-email: matan.honig2@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Provides-Extra: rich
Requires-Dist: click (>=8.1.7,<9.0.0)
Requires-Dist: executing (>=2.0.1,<3.0.0)
Requires-Dist: friendly-traceback (>=0.7.61,<0.8.0)
Requires-Dist: rich-click (>=1.7.2,<2.0.0) ; extra == "rich"
Requires-Dist: toml (>=0.10.2,<0.11.0)
Description-Content-Type: text/markdown

# brBug

`brBug` is a tool/library to debug native beeware apps on android with ease.

## Installation

Install using pip: `pip install brbug`

<!-- Install using pip and git: `pip install git+https://github.com/matan-h/brbug.git` -->

## 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 ...`)

then in your toga app use it like this:

```python
import brbug
@brbug.catch_beeapp
class YourTogaApp(toga.App):
```

that's it. now you got a better traceback by default. 

here is an example 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: 
```

## 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:

```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)#### on the build side (`brbug` cli):
```

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.

## supported tools

brBug modifies the `executing` engine to work on android using the tar.gz source generated by the `brbug` cli.

that mean, it supports:

* snoop - if you don't know this yet, highly recommended.
* python-devtools
* frendly-traceback
* icecream (although it doesn't look good in the android logcat view - somehow each word is in different line)

## FAQ

### what not supported

* `rich.traceback` - it uses the traceback object instead of executing or stack_data, so I cannot support it. 

### why its named 'brBug'

its like `briefcaseBug` but no one can spell it right, so `brBug`. 
it also sound like `mr. Bug` which is nice.
