tebelorg#50 - follow-up to frame()

sync upstream code-fix logic for frame step

tebelorg#36 tebelorg#50 tebelorg#52 - added frame() & popup(), fixed …

…snap() & read()

tebelorg#36 - add link to license in tagui.py to facilitate air-gap deployments (without internet access to pip)

# 50 - add frame() function to access web page frames (supports main frame and sub frame). add popup() function to access webpage popup tabs launched from webpage.

tebelorg#52 - bugfix for snap() and read(), when 'page' is used to mean entire webpage a 'cannot find page' error message appears.

tebelorg#35 tebelorg#34 - cleaner execution and error handling

tebelorg#35 - Cleaner usage and execution without TagUI intermediary files

During usage, the following temporary files will be generated in order to use TagUI -

tagui_python - simple flow to initiate TagUI live mode
tagui_python.raw - raw file for TagUI module expansion
tagui_python.js - generated JavaScript code for TagUI
tagui_local.js - TagUI for Python custom functions file
tagui_python.log - log file for automation execution
tagui_python.txt - to retrieve data output from TagUI

When debug mode is on using debug(True), only tagui_python.log and tagui_python.txt will be retained while the rest are deleted. That essentially means that the first 4 files above do not really add value to the typical TagUI for Python user. Having them in the script folder during execution may add clutter, clunkiness and confusion.

Furthermore, TagUI for Python has been downloaded over 5000 times since initial release, without users reporting issue that requires above 4 temporary files for debugging and troubleshooting.

Raising issue to update code to immediately delete the first 4 files upon connecting to TagUI to remove clutter. For the last 2 files, they will be retained until close() is used, where they will be deleted if debug(False) (default).

tebelorg#34 - graceful error handling on Windows folder path with space

On Windows, if script is used in folder path name with space, error message can appear without any meaningful information.

Some components of upstream project TagUI cannot work with spaces in the path and folder name containing the TagUI automation script. Solution is store the script in a folder path without space, or run it from a folder path without space in it.

tebelorg#31 tebelorg#32 tebelorg#24 - bump readme to v1.8

tebelorg#31 - ask() shows the question in terminal window. This is not intuitive if automation is running on the Chrome browser and a prompt appears in terminal window to ask for user input. Raising an issue to update behaviour to show prompt in Chrome browser, if it's available. PS - similar issue exists if chrome_browser = False and visual_automation = True. The terminal may not be in the foreground during the automation flow to be visible for user inputs. However, there isn't a consistent way to show SikuliX popup with focus across platforms. Thus KIV for now.

tebelorg#32 - At present, if visual automation mode is not on and `snap('page.png', 'screenshot.png')` is used, there is no error message saying that `init(visual_automation = True)` is needed to use this. Raising an issue to show error message instead of hanging waiting for SikuliX response.

tebelorg#24 - readme linking to RedMart online groceries example to automate re-adding all items to cart (to reschedule delivery, need to cancel and create new order manually)

tebelorg#30 - fix timeout() hangs if no visual automation

There is a bug in the timeout step in upstream TagUI project (aisingapore/TagUI#497). When timeout() is used with visual_automation = False, it hangs indefinitely. Raising a PR for a new release that implements the bug-fix upstream.

tebelorg#18 - autoflush processes for dirty exit

It is possible that TagUI processes (main TagUI, integration background processes - SikuliX, Chrome, Chrome browser) are not exited cleanly under certain conditions. For eg, if user Ctrl+C to kill a TagUI for Python script, or if user forgets to use close() to gracefully close off the running processes.

These dead processes have insignificant impact to TagUI for Python functionality. However they can cause unnecessary drain on battery and CPU cycles. Raising this issue to make a commit that runs a TagUI script that flush all TagUI-related processes.

This will be run within init() so that an accidental Ctrl+C or forgetting to close() allows immediate resumption of use by relaunching Jupyter notebook or Python interactive shell or Python script, and using init(). Placing within close() is meaningless for the scenarios where dead processes happen.

v1.5 - tebelorg#16 cleaner debug log when ' is used

Upstream TagUI project has a limitation in live mode. It was a tradeoff to enable dynamic variables working for selectors and parameters in live mode. As a result, TagUI for Python sends the following string to TagUI when a single quote ' is used as parameter (non-identifier parameter).

```
'+"\'"+'
```

With the issue aisingapore/TagUI#465 raised by user, an improvement is made upstream, using a solution for a similar problem while working on this personal side project. Thus a commit can now be made here that replaces single quote ' for non-identifier parameter with

```
\'
```

This may seem like a small improvement, but it helps clarify in debug log tagui_python.log when t.debug(True) is set. Otherwise, whenever there is a ' it would result in some roundabout escape sequence above due to a limitation in upstream live mode. This commit fixes that by escaping ' to \' following standard convention.

tebelorg#14 - explicit unicode utf-8 encoding

This change explicitly specifies unicode utf-8 as the encoding for both Python 2 and 3, and for read and write operations to files. More details at issue tebelorg#14.

This helps potential issues when TagUI outputs utf-8 encoded characters from extended ASCII set (eg webpage has special characters) but user Python locale preferred encoding is not utf-8, resulting in error in I/O between TagUI for Python and TagUI.

v1.3 - tebelorg#13 tebelorg#12 OCR and ROI capability, streamline API

Details at respective issues below.

tebelorg#13 - Support OCR capability and regions of interests for read() and snap()

tebelorg#12 - Streamlining API - remove show() and save(), remove visible()

tebelorg#6 tebelorg#7 - mac download(), autosync delta, snap() element

tebelorg#6 - on macOS with Python 3, there is no SSL certs support by default. adding an additional check to auto-install SSL certs. before this change, download() simply fails.

tebelorg#7 - adding capability to autosync tagui delta files when new tagui for python releases are installed. this lets users immediately access current features when they do a pip install tagui --upgrade. before this change, t.setup() is needed for existing installations.

tebelorg#7 - upstream fix implemented for snapshots of web elements on Chrome. fix improves performance and quality base on newer DevTools Protocol capabilities. the fix is accessible when users do a pip install tagui --upgrade. before this change, snap() captures screenshot of the whole webpage instead of only the element.