Feature/refactor api

[reiase]

Overview:

Details:

Where should the reviewer start?

Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)

• closes GitHub issue: #xxx

In general, to fix “variable defined multiple times” when the first value is never used, you either remove the first assignment entirely or, if its right-hand side has important side effects, keep the call but drop the unused variable binding. The second assignment then becomes the only definition of the variable prior to its use.

For this specific code in comparison_examples/pulsing_research.py, we want to preserve any potential side effects of ResearcherAgent.spawn, AnalystAgent.spawn, and ReporterAgent.spawn while removing the redundant initial bindings. The best minimal-change fix is:

• On lines 39–41, remove the variable targets (researcher =, analyst =, reporter =) and just call the asynchronous spawn methods with await, discarding the return values.
• Leave the resolve(...) assignments on lines 44–46 unchanged so that researcher, analyst, and reporter are defined once, right before use.

No new imports or additional methods/definitions are needed; we only adjust these three lines within run_workflow.

In general, to fix “variable defined multiple times” where the first value is never used, you either remove the first assignment entirely (if it has no side effects) or keep the expression for its side effects and drop the unused variable binding.

Here, researcher, analyst, and reporter are each assigned twice: first via *.spawn(...) and then via resolve(...). The second assignments (from resolve) are the ones actually used later in the workflow. The spawn calls, however, may be necessary to create/register the agents, so they should likely remain, but their return values do not need to be stored since they are never used. The minimal, behavior-preserving fix is:

• Keep the three spawn calls but do not assign their results to variables.
• Leave the resolve assignments as they are, since those variables are used in the subsequent workflow.

Concretely, in comparison_examples/pulsing_research.py inside run_workflow, lines 39–41:

• Replace:
  • researcher = await ResearcherAgent.spawn(name="researcher")
  • analyst = await AnalystAgent.spawn(name="analyst")
  • reporter = await ReporterAgent.spawn(name="reporter")
• With:
  • await ResearcherAgent.spawn(name="researcher")
  • await AnalystAgent.spawn(name="analyst")
  • await ReporterAgent.spawn(name="reporter")

No new methods or imports are needed.

In general, to fix “variable defined multiple times” when the first definition is never used, you either remove the earlier assignment entirely or keep the expression as a standalone call if you still need its side effects, without assigning its result to the same variable.

In this file, the safest fix that preserves all possible side effects of spawn is:

• Keep the three await <Agent>.spawn(name=...) calls.
• Stop assigning their return values to researcher, analyst, and reporter, since those names are immediately rebound via resolve(...).
• Optionally, one could remove the spawn calls entirely if the framework guarantees that resolve will implicitly spawn missing agents, but we cannot assume that from the snippet.

Concretely, in comparison_examples/pulsing_research.py:

• On lines 39–41, remove the left-hand-side variables and the = so that they become simple awaited calls:
  • Change researcher = await ResearcherAgent.spawn(name="researcher") to await ResearcherAgent.spawn(name="researcher"), and similarly for analyst and reporter.
• Leave the resolve(...) assignments on lines 44–46 unchanged.

No new imports or helper methods are required.

To fix an unused import, the general approach is to remove the unused name from the import statement (or delete the entire import if nothing in it is used). This preserves all existing functionality while cleaning up unnecessary dependencies.

In this case, in benchmarks/large_scale_stress_test.py, the line from pulsing.actor import Actor, StreamMessage, SystemConfig should be modified so that it only imports the names that are actually used: Actor and StreamMessage. Specifically, on line 21, remove SystemConfig from the imported names, resulting in from pulsing.actor import Actor, StreamMessage. No other code changes are required, and no additional methods, imports, or definitions are needed, since SystemConfig is not referenced elsewhere in the provided snippet.

To fix an unused import in Python, you remove the unused name from the import statement (or delete the entire import if none of its names are used). This decreases unnecessary dependencies and slightly improves readability.

In this case, we should edit benchmarks/large_scale_stress_test_pulsing_single.py at the import line currently reading from pulsing.actor import Actor, StreamMessage, SystemConfig. The detailed, minimal change is to remove SystemConfig from the imported names, leaving Actor and StreamMessage intact, as both are used by the worker classes shown. No additional methods, imports, or definitions are needed; we are only simplifying the existing import list. The rest of the file’s functionality remains unchanged.

In general, unused imports should be removed to keep the code clean and avoid unnecessary dependencies. Here, the time module is not referenced anywhere in the visible tests, so the best fix is simply to delete the import time line.

Concretely, in tests/python/apis/ray_compat/test_ray_compat_api.py, remove line 16 containing import time, leaving the pytest and ray imports unchanged. No other code changes, new methods, or additional imports are required, since the tests do not rely on time.

In general, to fix "module is imported more than once" issues, you remove redundant imports and rely on the existing import, unless you need a different alias or import style. Here, the file already imports pulsing as pul at the top (line 26), and the inner setup coroutine in test_sync_queue_standalone re-imports it with the same alias, which is unnecessary.

The best fix without changing functionality is to delete the inner import pulsing as pul inside the setup coroutine (around line 1013) and keep using pul as defined by the top-level import. The rest of the code in setup already uses pul and write_queue, read_queue exactly as imported at the top of the file, so no further changes are required. We must leave the from pulsing.queue import write_queue, read_queue inside setup intact, because write_queue and read_queue are not directly imported at the top level of the snippet’s function scope; however, even that is arguably redundant given the module-level import, but the static analysis complaint is specifically about pulsing, so we only remove that line.

To fix the problem, remove the redundant imports inside the setup() coroutine and use the already imported names from the module scope. In general, a single import of a module or symbol per file is sufficient; additional imports of the same module/symbol in inner scopes should be removed unless they serve a specific purpose (e.g., conditional or optional dependency loading).

Concretely, in tests/python/test_queue.py, within test_sync_writer_reader_standalone, there is an inner coroutine:

async def setup():
    import pulsing as pul
    from pulsing.queue import write_queue, read_queue
    ...

You should delete the two import lines inside setup(), leaving the body to use pul, write_queue, and read_queue from the module-level imports defined on lines 26–34. No other code changes are necessary: the names are already available in the function scope as they are defined at module level. This preserves all existing functionality while eliminating redundant imports.

In general, to fix a “module imported more than once” issue in Python, remove the redundant import and rely on the existing import that already brings the module or symbols into scope. If the inner code genuinely needs an import and there is no existing one, move that import to the top of the file; otherwise, just delete the duplicate.

For this specific file, we should remove the inner imports inside the setup coroutine within test_sync_reader_offset_standalone. At the top of tests/python/test_queue.py, the module already imports import pulsing as pul (line 26) and from pulsing.queue import (..., read_queue, write_queue) (lines 27–34). Therefore, inside setup, we can safely delete:

                import pulsing as pul
                from pulsing.queue import write_queue, read_queue

and rely on the already-imported pul, write_queue, and read_queue. No other functional changes are required; the rest of the code will continue to work as before, since names defined by top-level imports are accessible inside nested functions in the same module.

In general, to fix a “statement has no effect” issue where an awaited coroutine result is intentionally unused, either capture the result in a variable (optionally asserting/inspecting it) or explicitly assign it to _ to signal that it is intentionally ignored. This makes the side effect of “waiting for completion” explicit and resolves the static analysis warning.

For this specific test in tests/python/test_remote_decorator.py, the best minimal change without altering behavior is to bind the awaited value of slow_task to a variable. Optionally, we can assert on it, but that’s not required to preserve existing behavior. The key is to show that the awaited expression is being used.

Concretely:

• In test_async_method_does_not_block_actor, at line 228, change await slow_task to something like result = await slow_task. This preserves all functionality (we still wait for completion), makes the use of the expression explicit, and eliminates the “no effect” warning. No new imports or helper methods are required.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 60.31746% with 75 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
python/pulsing/actors/router.py	0.00%	31 Missing ⚠️
python/pulsing/actor/remote.py	77.04%	14 Missing ⚠️
python/pulsing/actor/helpers.py	12.50%	7 Missing ⚠️
python/pulsing/autogen/runtime.py	0.00%	7 Missing ⚠️
python/pulsing/langgraph/executor.py	0.00%	7 Missing ⚠️
python/pulsing/langgraph/wrapper.py	0.00%	6 Missing ⚠️
python/pulsing/__init__.py	94.87%	2 Missing ⚠️
python/pulsing/actors/__init__.py	0.00%	1 Missing ⚠️

Files with missing lines	Coverage Δ
python/pulsing/actor/__init__.py	85.71% <100.00%> (-0.57%)	⬇️
python/pulsing/cli/__main__.py	76.59% <ø> (ø)
python/pulsing/cli/inspect.py	52.94% <100.00%> (ø)
python/pulsing/compat/ray.py	89.02% <100.00%> (+2.86%)	⬆️
python/pulsing/queue/__init__.py	100.00% <100.00%> (ø)
python/pulsing/queue/manager.py	67.08% <100.00%> (-0.42%)	⬇️
python/pulsing/queue/queue.py	90.58% <100.00%> (ø)
python/pulsing/topic/topic.py	90.47% <ø> (ø)
python/pulsing/actors/__init__.py	0.00% <0.00%> (ø)
python/pulsing/__init__.py	95.00% <94.87%> (-5.00%)	⬇️
... and 6 more

... and 51 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.