robotframework-debug 4.4.0__tar.gz → 4.6.0__tar.gz

robotframework_debug-4.6.0/.github/workflows/pythonpublish.yml

@@ -0,0 +1,31 @@
+# This workflows will upload a Python Package using Twine when a release is created
+# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v1
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install setuptools wheel twine
+    - name: Build and publish
+      env:
+        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+      run: |
+        python setup.py sdist bdist_wheel
+        twine upload dist/*

robotframework_debug-4.6.0/.github/workflows/test.yml

@@ -0,0 +1,57 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: test
+
+on:
+  push:
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build:
+    name: py-${{ matrix.python-version }} rf-${{ matrix.robotframework-version }} ${{ matrix.platform }}
+    runs-on: ${{ matrix.platform }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [3.6, 3.7, 3.8, 3.9, "3.10"]
+        robotframework-version: [3.2, 4.1, 5.0]
+        platform: [ubuntu-latest, macOS-latest]
+        exclude:
+          - python-version: 3.6
+            platform: macOS-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8
+        pip install coverage
+        pip install robotframework==${{ matrix.robotframework-version }}
+    - name: Lint with flake8
+      run: |
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=80 --statistics
+    - name: Test
+      run: |
+        python setup.py develop
+        python setup.py test
+    - name: Generate coverage report
+      run: |
+        coverage xml
+    - name: Send coverage report to codecov
+      uses: codecov/codecov-action@v1
+      with:
+        file: ./coverage.xml
+    - name: Send coverage report to codeclimate
+      uses: paambaati/codeclimate-action@v2.6.0
+      with:
+        coverageCommand: echo "Ignore rerun"
+        coverageLocations: ${{github.workspace}}/coverage.xml:coverage.py
+      env:
+        CC_TEST_REPORTER_ID: ${{secrets.CC_TEST_REPORTER_ID}}

robotframework_debug-4.6.0/.gitignore

@@ -0,0 +1,22 @@
+*.egg-info
+build
+dist
+*.pyc
+*.txt
+*.robot
+log.html
+output.xml
+report.html
+.venv
+TODO
+.eggs/
+.vscode
+.DS_Store
+*.log
+.coverage
+.coverage.*
+htmlcov
+coverage.xml
+coverage.json
+results
+.matrix

robotframework_debug-4.6.0/CONTRIBUTION.md

@@ -0,0 +1,112 @@
+# Contributing to RobotDebug
+
+Thanks for helping improve `robotframework-debug`! This guide covers local
+setup, running and debugging the tool, testing, and cutting a release.
+
+For the design of the test suite and the cross-version compatibility work, see
+[`docs/development.md`](docs/development.md).
+
+## Setup
+
+RobotDebug uses a PEP 621 `pyproject.toml` with the [Flit](https://flit.pypa.io)
+build backend. Install it in editable mode with the development extras:
+
+```bash
+# with uv (recommended)
+uv venv
+uv pip install -e ".[dev]"
+
+# or with pip
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+The `dev` extra pulls in `invoke`, `ruff`, `black`, `pexpect` and `flit`.
+The compatibility matrix additionally requires [`uv`](https://docs.astral.sh/uv/)
+on your `PATH`.
+
+## Running RobotDebug locally
+
+Run the standalone shell against a sample suite:
+
+```bash
+python RobotDebug/shell.py tests/step.robot
+```
+
+`shell.py` launches `robot` in a **child process**, which interrupts Python
+debugging. To set breakpoints in tools like VS Code or `pdb`, run the suite
+directly instead:
+
+```bash
+python -m robot tests/step.robot
+```
+
+Robot Framework takes over `stdout`, so emit debugging output explicitly:
+
+```python
+import sys
+print("some information", file=sys.stdout)
+```
+
+## Testing
+
+The acceptance suite drives `irobot`/`RobotDebug` end to end (REPL, the `Debug`
+keyword, listener-on-error and step debugging). Run it with the task runner:
+
+```bash
+invoke test               # dotted console; writes results/ (log/report/output.xml)
+invoke test --verbose     # per-test console output
+```
+
+To check compatibility across Robot Framework releases (RF 5.0 → 7.4, each in an
+isolated `uv` venv), regenerate the matrix in
+[`docs/compatibility_matrix.md`](docs/compatibility_matrix.md):
+
+```bash
+invoke matrix                     # full sweep
+invoke matrix --only 7.3.2,7.4.2  # a subset
+```
+
+## Linting and formatting
+
+```bash
+invoke lint               # ruff check
+invoke lint --fix         # ruff check --fix
+invoke format             # ruff format + black
+invoke format --check     # verify formatting without changing files
+```
+
+`invoke check` runs `lint` then the acceptance suite — the recommended check
+before opening a pull request.
+
+## Releasing
+
+The version is single-sourced from `RobotDebug.__version__` in
+[`RobotDebug/__init__.py`](RobotDebug/__init__.py); `RobotDebug/version.py`
+re-exports it as `VERSION` for backwards compatibility.
+
+1. Bump `__version__` in `RobotDebug/__init__.py`.
+2. Update the `ChangeLog`.
+3. Make sure the working tree is clean and tests pass: `invoke check`.
+4. Build the artifacts:
+
+   ```bash
+   invoke build            # flit build → dist/*.whl + dist/*.tar.gz
+   # or directly:  flit build      (uses git to pick sdist files; needs a clean tree)
+   ```
+
+5. Publish to PyPI with Flit (needs PyPI credentials):
+
+   ```bash
+   flit publish
+   ```
+
+6. Tag the release: `git tag v<version> && git push --tags`.
+
+## Submitting issues
+
+Bugs and enhancements are tracked in the
+[issue tracker](https://github.com/imbus/robotframework-debug/issues). Before
+opening a new issue, please check whether the same bug or enhancement has
+already been reported and, if so, add your comments to the existing issue
+instead of creating a new one.

robotframework_debug-4.6.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: robotframework-debug
+Version: 4.6.0
+Summary: A debug library and REPL for Robot Framework.
+Keywords: robotframework,debug,shell,repl
+Author-email: René Rohner <snooz@posteo.de>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Classifier: Framework :: Robot Framework
+License-File: LICENSE
+Requires-Dist: prompt-toolkit >= 3.0.38
+Requires-Dist: robotframework >= 5.0, < 8.0
+Requires-Dist: pygments >= 2.14.0
+Requires-Dist: pyperclip >= 1.8.2
+Requires-Dist: invoke >= 2.0 ; extra == "dev"
+Requires-Dist: ruff >= 0.4 ; extra == "dev"
+Requires-Dist: black >= 24.0 ; extra == "dev"
+Requires-Dist: pexpect >= 4.8 ; extra == "dev"
+Requires-Dist: flit >= 3.4 ; extra == "dev"
+Project-URL: Homepage, https://github.com/imbus/robotframework-debug/
+Project-URL: Issues, https://github.com/imbus/robotframework-debug/issues
+Project-URL: Repository, https://github.com/imbus/robotframework-debug/
+Provides-Extra: dev
+
+# Debug Library for Robot Framework
+
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Usage](#usage)
+    - [REPL mode](#repl-mode)
+    - [Library mode](#library-mode)
+    - [Listener mode](#listener-mode)
+    - [Step debugging](#step-debugging)
+- [Overview of commands](#overview-of-commands)
+- [Submitting issues](#submitting-issues)
+- [Development](#development)
+- [License](#license)
+
+## Introduction
+
+This library is a fork by René Rohner from the original robotframework-debuglibrary by Xie Yanbo.
+
+Robotframework-RobotDebug is a debug library for [RobotFramework](https://robotframework.org),
+which can be used as an interactive shell(REPL) and listener also.
+
+## Installation
+
+To install using `pip`:
+
+    pip install robotframework-debug
+
+## Usage
+
+You can use RobotDebug library in 3 different modes:
+- REPL mode,
+- Library mode,
+- Listener mode.
+
+### REPL mode
+
+Just call `irobot` in the terminal with all available robot arguments. An interactive shell will open. To exit use the command `exit` or shortcut `Ctrl+D`.
+It is possible to evaluate both single-line and multi-line expressions.
+
+![irobot](res/irobot.png)
+
+- you can execute keywords and define variables
+
+![keywords and variables](res/keywords_and_variables_irobot.png)
+
+- You can set a variable and use this variable in another keyword in one step. Use the keyboard shortcut `Shift + Down Arrow` to go to the next line without evaluating the first line. Then press the `Enter` key twice to evaluate expressions.
+
+![two lines evaluation](res/Shift_down.gif)
+
+- `irobot` can evaluate multi line expressions as `FOR` and `WHILE` loops, `IF / ELSE` statements and `TRY / EXCEPT` expressions.
+
+![multi line evaluation](res/multiline_example.png)
+
+- you can import libraries, resources and variable files
+
+![import library, resource and variable file](res/import.png)
+
+- you can use the resource file syntax like `*** Settings *** `, `*** Variables ***` and `*** Keywords ***` and write the resource file directly into the irobot shell. Press the `Enter` key twice to import your resource.
+
+![resource file](res/resource.png)
+
+### Library mode
+
+Import `RobotDebug` as library and use the `Debug` keyword to set a breakpoint in your test cases:
+
+
+    *** Settings ***
+    Library         RobotDebug
+
+    *** Test Cases ***
+    Some Test
+        # some keywords...
+        Debug
+        # some else...
+
+The `Debug` keyword pauses test execution and opens an interactive shell. Then you can evaluate expressions, try out keywords, inspect the variables and trace and view the code step by step. See also the section [step debugging](#step-debugging).
+
+### Listener mode
+
+You can attach it as a listener and run your test until it fails. Just add `--listener RobotDebug.Listener` to you `robot` call.
+
+    robot --listener RobotDebug.Listener some.robot
+
+If your test case fails, RobotDebug will stop there and the interactive shell will be opened at that point. Then you can try out keywords and analyze the issue.
+
+https://github.com/user-attachments/assets/18c48b1c-e870-45fd-ad67-f0424e88f172
+
+### Step debugging
+
+RobotDebug supports step debugging in Library and Listner mode.
+
+Use keys *F7 (INTO)*, *F8 (OVER)* and *F9 (OUT)* to trace and view the code step by step.
+
+*F7: INTO*
+The `F7` key allows you to go into the keyword if it contains further keywords inside. The first line within the user keyword is executed and the execution is paused again.
+
+*F8: OVER*
+The `F8` key allows you to execute the current line completely in one step, even if it contains other keywords inside.
+
+*F9: OUT*
+You can use the `F9` key to exit the keyword if you have entered it previously.
+
+*F10: CONTINUE*
+You can use the `F10` key or the `continue` or `c` command to continue execution until the next `Debug` keyword if you use this in library mode or the next failure of the test if you use this in listner mode.
+
+*SHIFT TAB: DETACH*
+`Shift Tab` allows you to run the rest of the test case to the end without opening the interactive shell.
+
+*List*
+The commands `list` or `l` and `ll` display the test case snippet including the line being executed:
+![list command](res/list_command.png)
+
+### Overview of commands
+
+Use `exit` or keys `Ctrl+D` to exit the interactive shell.
+
+Use `clear` or `cls` to clear the screen.
+
+The interactive shell supports auto-completion for robotframework keywords and commands. Try input BuiltIn. then hit `Control + Space` key to feel it.
+
+You can use the `F5` key to enable or disable live completion.
+Live completion ON:
+![live completion](res/live_completion.gif)
+
+You can use the `F12` key to enable or disable mouse support within the shell.
+Mouse support ON:
+![toglle mouse on](res/toggle_mouse_on.gif)
+To be able to scroll, disable mouse support.
+
+You can use the command `history` or key `F4` to view the history in your irobot shell. You can see used keywords and commands on the left and imported resources on the right side.
+Use `TAB` to switch focus from one part to another. To close history, press key `F4`.
+
+https://github.com/user-attachments/assets/cfa2b7c7-a2eb-4063-b1c4-30bff48da850
+
+The history will save at `~/.rfdebug_history` located in user home directory default or any path defined in the environment variable RFDEBUG_HISTORY.
+
+Use `help` to view possible commands:
+
+![help](res/help_image.png)
+
+To import a library, use  `Library    <lib_name>`.
+To show all imported Libraries, use `libs` and to show sources for each library, use `libs -s`.
+
+![help library](res/libs_image.png)
+
+The command `res` lists the imported resource files.
+`res -s` lists the imported resources files with source:
+
+![help resource](res/help_res.png)
+
+The command `keywords` or `k` lists all keywords of imported libraries.
+The command `keywords <lib_name>` lists keywords of a specified library.
+
+To get keyword documentation for individual keywords, use `docs <keyword_name>` or `d <keyword_name>`:
+
+![help docs](res/docs.png)
+
+## Submitting issues
+
+Bugs and enhancements are tracked in the [issue tracker](https://github.com/imbus/robotframework-debug/issues).
+
+Before submitting a new issue, it is always a good idea to check if the same bug or enhancement already been reported. If it is, please add your comments to the existing issue instead of creating a new one.
+
+## Development
+
+See [`CONTRIBUTION.md`](CONTRIBUTION.md) for local setup, running and debugging
+RobotDebug, testing, and the release process.
+
+## License
+
+This software is licensed under the `New BSD License`. See the `LICENSE` file in the top distribution directory for the full license text.
+

{robotframework-debug-4.4.0 → robotframework_debug-4.6.0}/RobotDebug/RobotDebug.py

@@ -3,10 +3,12 @@ from __future__ import annotations
 import sys
 from pathlib import Path
 
-from robot.libraries.BuiltIn import BuiltIn
+from robot.api import logger
+from robot.libraries.BuiltIn import BuiltIn, run_keyword_variant
 
 from .debugcmd import DebugCmd, ReplCmd, is_step_mode
 from .globals import StepMode
+from .robotkeyword import run_debug_if
 from .styles import ERROR_STYLE, LOW_VISIBILITY_STYLE, print_output
 from .version import VERSION
 
@@ -44,7 +46,10 @@ class Listener:
 
         path = attrs["source"]
         if path and Path(path).exists() and path not in self.source_files:
-            self.source_files[path] = Path(path).open().readlines()
+            if Path(path).is_dir() and (Path(path) / "__init__.robot").exists():
+                path = Path(path) / "__init__.robot"
+            with Path(path).open() as f:
+                self.source_files[path] = f.readlines()
         lineno = attrs["lineno"]
         self.library.current_source_path = path
         self.library.current_source_line = lineno
@@ -58,7 +63,9 @@ class Listener:
         self.last_keyword_layer = self.keyword_layer
 
         print_output(
-            "", f"{Path(path).relative_to(Path.cwd())}:{lineno}", style=LOW_VISIBILITY_STYLE
+            "",
+            f"{Path(path).relative_to(Path.cwd())}:{lineno}",
+            style=LOW_VISIBILITY_STYLE,
         )
         line = self.source_files[path][lineno - 1]
         print_output(f"{lineno} ->", line.rstrip())
@@ -123,12 +130,57 @@ class RobotDebug:
         self.current_source_path = ""
 
     def Library(self, name, *args):  # noqa: N802
+        """Imports a library with the given name and optional arguments.
+
+        This keyword supports importing libraries both using library
+        names and physical paths. When paths are used, they must be
+        given in absolute format or found from
+        [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#module-search-path|
+        search path]. Forward slashes can be used as path separators in all
+        operating systems.
+
+        It is possible to pass arguments to the imported library and also
+        named argument syntax works if the library supports it. ``AS``
+        syntax can be used to give a custom name to the imported library.
+
+        Examples:
+        | Import Library | MyLibrary   |
+        | Import Library | path/Lib.py | arg1 | named=arg2 | AS | Custom |
+        """
         BuiltIn().import_library(name, *args)
 
     def Resource(self, path):  # noqa: N802
+        """Imports a resource file with the given path.
+
+        The given path must be absolute or found from
+        [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#module-search-path|search path].
+        Forward slashes can be used as path separator regardless
+        the operating system.
+
+        Examples:
+        | Import Resource | path/resource.txt |
+        | Import Resource | path/../resources/resource.html |
+        | Import Resource | found_from_pythonpath.robot |
+        """
+
         BuiltIn().import_resource(path)
 
     def Variables(self, path, *args):  # noqa: N802
+        """Imports a variable file with the given path and optional arguments.
+
+        These variables override possible existing variables with
+        the same names.
+
+        The given path must be absolute or found from
+        [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html##module-search-path|search path].
+        Forward slashes can be used as path separator regardless
+        the operating system.
+
+        Examples:
+        | Import Variables | path/variables.py        |      |      |
+        | Import Variables | path/../vars/env.py      | arg1 | arg2 |
+        | Import Variables | file_from_pythonpath.py  |      |      |
+        """
         BuiltIn().import_variables(path, *args)
 
     def debug(self):
@@ -140,6 +192,25 @@ class RobotDebug:
         # support
         return self._debug()
 
+    @run_keyword_variant(resolve=1)
+    def debug_if(self, condition, *args):
+        """Run the `Debug` keyword if the given ``condition`` is true.
+
+        *Deprecated.* ``Debug If`` only exists for backwards compatibility with
+        ``robotframework-debuglibrary`` and will be removed in a future
+        release. Use a native Robot Framework ``IF`` block around the `Debug`
+        keyword instead:
+
+        | IF    ${count} < 1
+        |     Debug
+        | END
+        """
+        logger.warn(
+            "'Debug If' is deprecated and will be removed in a future release. "
+            "Use a Robot Framework 'IF' block around the 'Debug' keyword instead."
+        )
+        return run_debug_if(condition, *args)
+
     def _debug(self, muted: bool = False):
         if self.listener.step_mode == StepMode.STOP:
             return

{robotframework-debug-4.4.0 → robotframework_debug-4.6.0}/RobotDebug/__init__.py

@@ -1,4 +1,6 @@
+"""A debug library and REPL for Robot Framework."""
+
+__version__ = "4.6.0"
+
 from .RobotDebug import Listener, RobotDebug  # noqa: F401
 from .version import VERSION  # noqa: F401
-
-"""A debug library and REPL for RobotFramework."""