robotframework-parallelrunner 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

ParallelRunner/parallel_library.py

@@ -1,5 +1,6 @@
 import os
 import concurrent.futures
+import importlib
 from typing import Iterable, Any, List, Dict, Optional, Tuple, Union
 from robot.api import logger
 from robot.libraries.BuiltIn import BuiltIn
@@ -94,11 +95,31 @@ class ParallelRunner:
     or use ``return_values_only=True`` / `Get Result Values`, which fail
     if any call failed.
 
+    = Custom logger mappers =
+
+    A logger mapper replaces the default buffering logger: the target keyword
+    receives it as ``_logger`` and every message goes straight to your own
+    logging system. Use it when a project already has its own log format
+    (severity codes, JSON...).
+
+    - Give it as a callable or as a ``module.function`` path, either with the
+      ``logger_mapper`` argument or, for a project-wide default, with the
+      ``ROBOT_LOGGER_MAPPER`` environment variable. The argument wins.
+    - Bare names (without a module path) are not supported. A value that
+      can't be resolved is ignored with a warning in the log.
+    - Mapper messages are *not* buffered and replayed into ``log.html``, so
+      ``thread_log_level`` and ``remove_passing_logs`` don't apply to them.
+      The mapper is called from several threads at once, so it must be
+      thread-safe.
+    - ``ROBOT_LOGGER_MAPPER`` must be a real environment variable (e.g. set
+      with ``Set Environment Variable`` or in the shell); a Robot variable
+      given with ``--variable`` is not read.
+
     = Environment variables =
 
     | =Variable=             | =Description= |
     | ROBOT_THREAD_WORKERS   | Number of worker threads. Read when the library is imported. Default ``4``. |
-    | ROBOT_LOGGER_MAPPER    | Default ``logger_mapper`` as a ``module.function`` path, used when the argument is not given. |
+    | ROBOT_LOGGER_MAPPER    | Default ``logger_mapper`` as a ``module.function`` path, used when the argument is not given. See `Custom logger mappers`. |
 
     = When not to use it =
 
@@ -147,10 +168,12 @@ class ParallelRunner:
         - ``thread_log_level``: Minimum level replayed from the threads:
           ``INFO`` (default), ``WARN`` or ``ERROR``.
         - ``logger_mapper``: Optional callable ``mapper(msg, level)`` - or a
-          ``module.function`` path to one - injected as ``_logger`` instead of
-          the default buffering logger, to route logs to a custom logging
+          ``module.function`` path to one, such as
+          ``my_package.my_module.my_mapper`` - injected as ``_logger`` instead
+          of the default buffering logger, to route logs to a custom logging
           system. Falls back to the ``ROBOT_LOGGER_MAPPER`` environment
-          variable.
+          variable. A value that can't be resolved (e.g. a bare name without a
+          module) is ignored with a warning. See `Custom logger mappers`.
         - ``return_values_only``: If true, return a plain tuple of each call's
           return value (in call order) instead of the result dictionaries.
           Fails with ``ParallelTaskError`` if any call failed. Same as calling
@@ -229,52 +252,59 @@ class ParallelRunner:
             raise ParallelTaskError(failures, len(results))
         return tuple(entry["result"] for entry in results)
 
-    def _resolve_mapper(self, mapper: Optional[Any]) -> Optional[Any]:
+    def _resolve_mapper(self, mapper: Optional[Any], source: str = "logger_mapper") -> Optional[Any]:
         """
-        Resolve a mapper which might be a callable or a string path to a module function.
-        
+        Resolve a mapper given as a callable or as a ``module.function`` path
+        (e.g. "examples.custom_logger.custom_logging_mapper.custom_logger_adapter").
+
+        Returns the callable, or None when no mapper was given. A mapper that
+        was given but can't be resolved (a bare name without a module, a module
+        that can't be imported, a missing or non-callable attribute) is ignored
+        with a warning in the log - it used to be ignored silently, which hid
+        typos and unsupported values such as bare registered names.
+
         Args:
-            mapper: Callable or string path (e.g., "examples.custom_logger.custom_logging_mapper.custom_logger_adapter")
-        
-        Returns:
-            Callable: The mapper function if successfully resolved, None otherwise.
+            mapper: Callable, ``module.function`` string, or "not given": None,
+                an empty string, or the string "None" (any case - Robot
+                Framework's usual spelling of None, e.g. ``logger_mapper=None``).
+            source: Where the value came from, used in the warning message.
         """
-        if mapper is None:
+        if mapper is None or (isinstance(mapper, str) and mapper.strip().upper() in ("", "NONE")):
             return None
-        
-        # If already callable, return it
+
         if callable(mapper):
             return mapper
-        
-        # If it's a string, try to import it
+
         if isinstance(mapper, str):
-            try:
-                parts = mapper.rsplit(".", 1)
-                if len(parts) == 2:
-                    module_name, func_name = parts
-                    module = __import__(module_name, fromlist=[func_name])
+            module_name, _, func_name = mapper.strip().rpartition(".")
+            if not module_name or not func_name:
+                reason = "expected a 'module.function' path such as 'my_package.my_module.my_mapper'"
+            else:
+                try:
+                    module = importlib.import_module(module_name)
+                except ImportError as error:
+                    reason = f"cannot import module '{module_name}' ({error})"
+                else:
                     resolved = getattr(module, func_name, None)
                     if callable(resolved):
                         return resolved
-            except (ImportError, AttributeError):
-                pass
-        
+                    reason = f"module '{module_name}' has no callable '{func_name}'"
+        else:
+            reason = f"expected a callable or a 'module.function' string, got {type(mapper).__name__}"
+
+        logger.warn(f"Ignoring {source} {mapper!r}: {reason}.")
         return None
 
     def _load_mapper_from_environment(self) -> Optional[Any]:
         """
-        Load custom logger mapper from ROBOT_LOGGER_MAPPER environment variable.
-        Supports both registered mapper names and module.function paths.
-        
+        Load the logger mapper named by the ROBOT_LOGGER_MAPPER environment
+        variable, which must be a ``module.function`` path (bare names are not
+        supported and are ignored with a warning).
+
         Returns:
             Callable: The mapper function if found, None otherwise.
         """
-        mapper_name = os.getenv("ROBOT_LOGGER_MAPPER")
-        if not mapper_name:
-            return None
-        
-        # Use _resolve_mapper to handle the string path
-        return self._resolve_mapper(mapper_name)
+        return self._resolve_mapper(os.getenv("ROBOT_LOGGER_MAPPER"), source="ROBOT_LOGGER_MAPPER")
 
     def _get_library_instance_owning_keyword(self, keyword_name: str, library: str) -> Any:
         method_name = keyword_name.replace(" ", "_").lower()

{robotframework_parallelrunner-0.2.0.dist-info → robotframework_parallelrunner-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robotframework-parallelrunner
-Version: 0.2.0
+Version: 0.2.1
 Summary: Run a keyword in parallel inside a single Robot Framework test case, with one clean, ordered log.html.
 License-Expression: MIT
 License-File: LICENSE
@@ -112,8 +112,10 @@ threading, buffering, and replay logic stay out of your `.robot` files.
 
 ## Summary of Benefits
 
-- **Speed.** Validating 100 APIs that take 1s each takes roughly 10s (with 10
-  workers) instead of 100s.
+- **Speed.** Waiting time is overlapped instead of added up. In this repo's
+  examples, 9 HTTP checks with a 1 s delay each drop from 13 s to 2 s with
+  9 workers, and 4 suites × 8 items × 1 s drop from 32.7 s to 4.6 s with
+  8 workers (see [Using It Together With pabot](#using-it-together-with-pabot)).
 - **Integrity.** Your `log.html` remains the single source of truth — no
   broken XML tags from concurrent writes.
 - **Flexibility.** Pass `repeat=10` to stress-test a single endpoint, or
@@ -164,6 +166,57 @@ for pabot. If you need to speed up "this one test case loops over 100 items
 and I want a single readable log instead of 100 sequential HTTP round trips
 (or 100 merged `output.xml` files)," that's what ParallelRunner is for.
 
+## Using It Together With pabot
+
+The two combine without any extra configuration: pabot splits suites (or
+tests) across processes, and inside each process ParallelRunner splits a
+loop across threads. Every pabot process gets its own ParallelRunner
+instance, its own thread pool and its own `output.xml`, so nothing is shared
+between processes, and pabot merges the results as usual.
+
+```bash
+pabot --processes 4 --pythonpath . atest/
+pabot --processes 4 --testlevelsplit --pythonpath . atest/
+```
+
+Both commands pass the full acceptance suite of this repository (41 tests;
+checked with pabot 5.2.2).
+
+How much time each one saves, from the offline
+[pabot timing demo](https://github.com/cristiangarciavd/robotframework-parallelrunner/tree/main/examples/pabot_demo/)
+(4 suites × 8 items × 1 s of simulated I/O wait; `poetry run invoke demo-pabot`):
+
+| Run | Wall-clock time | Speedup |
+|---|---|---|
+| robot, sequential loop | 32.7 s | ×1.0 |
+| robot + ParallelRunner (8 workers) | 4.6 s | ×7.1 |
+| pabot (4 processes), sequential loop | 10.6 s | ×3.1 |
+| pabot (4 processes) + ParallelRunner (8 workers) | 3.5 s | ×9.2 |
+
+ParallelRunner removes the waiting *inside* each test, and pabot removes it
+*between* suites. With suites this short, pabot's process start-up (about
+2.5 s here) is most of what's left, so the combination pays off more as
+suites get longer.
+
+Things to keep in mind:
+
+- **Run pabot from the virtual environment where the library is installed**
+  (or via `poetry run pabot ...`). pabot starts whichever `robot` command is
+  first on the `PATH`. If that belongs to another Python installation, every
+  test that uses the library fails with
+  `No keyword with name 'Run Parallel Scenarios' found`.
+- **Concurrency multiplies.** The number of simultaneous calls is roughly
+  pabot processes × `ROBOT_THREAD_WORKERS`: 4 processes × 4 workers means up
+  to 16 concurrent requests against the same API or database. Lower one of
+  the two if you hit rate limits, connection-pool limits or lock timeouts.
+- **Shared test resources can collide across processes.** Data, files, user
+  accounts, or a table that a `Suite Setup` resets are visible to every
+  process. With `--testlevelsplit`, each test of a suite runs its own
+  `Suite Setup` in its own process. For example, the `examples/db_seed`
+  suite drops and recreates its table in `Suite Setup`, so two of its tests
+  could interfere with each other. Keep shared state per process, or split
+  by suite.
+
 ## When Not To Use This
 
 - **CPU-bound work.** Threads share Python's GIL — number crunching won't
@@ -183,11 +236,13 @@ and I want a single readable log instead of 100 sequential HTTP round trips
 ## Project Structure
 
 ```
-ParallelRunner/
-├── src/ParallelRunner/     # The installable library (core, do not depend on internals prefixed with `_`)
-├── examples/               # Example "business logic" libraries used by the test suites
-├── atest/            # Robot Framework acceptance suites
-├── docs/                   # INSTALLATION, QUICKSTART, API_REFERENCE
+robotframework-parallelrunner/
+├── src/ParallelRunner/     # The installable library (do not depend on internals prefixed with `_`)
+├── examples/               # Example libraries used by the tests, plus the pabot timing demo
+├── atest/                  # Robot Framework acceptance suites
+├── utest/                  # pytest unit tests
+├── docs/                   # INSTALLATION, QUICKSTART, API_REFERENCE, generated keyword docs
+├── tasks.py                # invoke tasks: tests, libdoc, demo-pabot, build, ...
 └── ARCHITECTURE.md         # Technical deep dive
 ```
 

{robotframework_parallelrunner-0.2.0.dist-info → robotframework_parallelrunner-0.2.1.dist-info}/RECORD

@@ -1,9 +1,9 @@
 ParallelRunner/__init__.py,sha256=ifsoO1rXf4kL3i75NokrD_KHxnlvE3IuH69Fb-ByfNg,641
-ParallelRunner/parallel_library.py,sha256=FL7UkGwDJ8deN0F87bZr-PwuWqx3HEX8hF1kDKR8JUc,15173
+ParallelRunner/parallel_library.py,sha256=wOBvPLPLC0GSc9el7O_bcVHfl5NuGKaiWGXdZKTH6do,17380
 ParallelRunner/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ParallelRunner/version.py,sha256=W8E8ymdTLqfKl_1qBIOrjGpO8kSbqPw30aYZpqYUNMk,632
 parallelrunner.py,sha256=2oyKOVeKlOaZUZ3f2i_l5xCAYFKVm11bSQZOtzSSJO8,1132
-robotframework_parallelrunner-0.2.0.dist-info/METADATA,sha256=rpxLRJ4t-d8VKyrLfKSVxVNUL4Gd7tPsUoa7FI9xS4w,11187
-robotframework_parallelrunner-0.2.0.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
-robotframework_parallelrunner-0.2.0.dist-info/licenses/LICENSE,sha256=xxQh3uvlk5jC1i0eoH5Nyo9cDz2Fzu0DqOzAZw8XxFs,1072
-robotframework_parallelrunner-0.2.0.dist-info/RECORD,,
+robotframework_parallelrunner-0.2.1.dist-info/METADATA,sha256=9VmBqhZ3dMGu9_onf6S8afWTGbr-130YVHWuDHWZJ0M,14053
+robotframework_parallelrunner-0.2.1.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
+robotframework_parallelrunner-0.2.1.dist-info/licenses/LICENSE,sha256=xxQh3uvlk5jC1i0eoH5Nyo9cDz2Fzu0DqOzAZw8XxFs,1072
+robotframework_parallelrunner-0.2.1.dist-info/RECORD,,