lucius-mcp 0.1.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

src/client/refactor-hotspots.md

@@ -1,53 +0,0 @@
-# Refactor Hotspots in `src/client/client.py`
-
-Below are the main repetition hotspots identified in `src/client/client.py` with ordered numbering and detailed explanations.
-
-1. **Repeated “entered” guard across public methods**
-   - **Where:** Multiple methods begin with the same check:
-     `if not self._is_entered: raise AllureAPIError("Client not initialized. Use 'async with AllureClient(...)'")`
-     (e.g., `create_test_case` at `src/client/client.py:397`, `list_test_cases` at `:462`, `upload_attachment` at `:510`, `create_scenario_step` at `:551`, `get_test_case` at `:634`, `delete_test_case` at `:846`, and many others).
-   - **Why it’s repetitive:** The guard is identical and repeated across nearly every API-facing method.
-   - **Refactor idea:** Add a private helper (e.g., `_require_entered()`) that encapsulates this check, and call it at the top of each method.
-
-2. **Token refresh + API existence checks repeated**
-   - **Where:** Pattern appears in most methods:
-     `await self._ensure_valid_token()` then `if self._X_api is None: raise AllureAPIError("Internal error: X_api not initialized")`
-     (e.g., `create_test_case` at `:400-404`, `list_test_cases` at `:465-468`, `upload_attachment` at `:513-515`, `create_scenario_step` at `:554-556`, `get_test_case` at `:637-639`).
-   - **Why it’s repetitive:** Each method repeats the same two steps, only the controller attribute changes.
-   - **Refactor idea:** Provide a helper like `_require_api(attr_name: str)` that ensures valid token and returns the controller or raises consistently.
-
-3. **Boilerplate `ApiException` mapping block**
-   - **Where:** Many methods wrap API calls in `try/except` that only invokes `_handle_api_exception` and re-raises
-     (e.g., `create_test_case` at `:408-416`, `list_test_cases` at `:479-489`, `upload_attachment` at `:517-525`, `delete_scenario_step` at `:611-618`, `update_test_case` at `:705-714`).
-   - **Why it’s repetitive:** The `try/except` structure is identical across methods with only the API call inside changing.
-   - **Refactor idea:** Add a helper like `_call_api(coro)` that awaits the coroutine and handles `ApiException` centrally.
-
-4. **Scenario step creation logic duplicated**
-   - **Where:** `create_scenario_step` and `create_shared_step_scenario_step`
-     (`src/client/client.py:527-593` and `:933-976`).
-   - **Why it’s repetitive:** Both methods call `*_without_preload_content`, validate the HTTP status, parse JSON, and construct `ScenarioStepCreatedResponseDto` in the same way.
-   - **Refactor idea:** Extract a shared helper (e.g., `_create_scenario_step_via_api(api, step, after_id=None, with_expected_result=False)`) that performs the common workflow.
-
-5. **Attachment upload methods are structurally identical**
-   - **Where:** `upload_attachment` and `upload_shared_step_attachment`
-     (`src/client/client.py:491-525` and `:978-1007`).
-   - **Why it’s repetitive:** Both methods follow the same structure: ensure entered, refresh token, check controller, call `createXX`, handle `ApiException`.
-   - **Refactor idea:** Use a shared private method that takes the controller and ID parameter name/value (test case vs shared step) and file data.
-
-6. **Two attributes for the same controller type**
-   - **Where:** `_scenario_api` and `_test_case_scenario_api` both use `TestCaseScenarioControllerApi` in `__init__` and `_ensure_valid_token`
-     (`src/client/client.py:173-175` and `:309-310`).
-   - **Why it’s repetitive:** Maintaining separate attributes for the same class adds duplicated initialization and checks without a functional difference.
-   - **Refactor idea:** Keep a single attribute (e.g., `_scenario_api`) and reuse it for both operations, or wrap access in a helper to avoid duplicated state.
-
-7. **Repeated “internal error” strings for uninitialized controllers**
-   - **Where:** Many methods raise nearly identical errors with only the controller name changed
-     (e.g., `:402`, `:467`, `:515`, `:556`, `:609`, `:639`, `:703`, `:734`, `:918`, `:950`, `:997`, `:1020`, `:1047`, `:1076`).
-   - **Why it’s repetitive:** These strings are copy-pasted and differ only in the controller identifier.
-   - **Refactor idea:** Centralize the error generation in a helper (e.g., `_raise_missing_api("test_case")`).
-
-8. **Duplicate entries in `__all__`**
-   - **Where:** `ScenarioStepCreateDto` and `ScenarioStepCreatedResponseDto` appear twice
-     (`src/client/client.py:97-100`).
-   - **Why it’s repetitive:** The export list contains duplicates, which is unnecessary and can be cleaned up for clarity.
-   - **Refactor idea:** Remove duplicates from `__all__`.

src/client/refactor-plan.md

@@ -1,78 +0,0 @@
-# Refactor Plan for `src/client/client.py`
-
-This plan targets the repetition hotspots documented in `src/client/refactor-hotspots.md` and keeps behavior unchanged.
-
-## Goals
-- Reduce repeated guards, token refresh checks, and exception handling boilerplate.
-- Centralize controller access and error messaging.
-- Deduplicate scenario step creation and attachment upload flows.
-- Keep API behavior and error semantics identical.
-
-## Non-goals
-- No functional changes to API behavior or response handling.
-- No changes to external interfaces beyond internal helper use.
-- No changes to configuration, logging, or test behavior.
-
-## Step-by-step plan
-
-1. **Introduce a shared “entered” guard helper**
-   - **Why:** Replaces repeated `if not self._is_entered ...` checks across methods (e.g., `src/client/client.py:397`, `:462`, `:510`, `:551`, `:634`, `:846`).
-   - **Action:** Add a private method (e.g., `_require_entered(self) -> None`) and use it at the top of public API methods.
-   - **Behavioral constraint:** Same exception type/message as today.
-
-2. **Add a controller access helper that includes token refresh**
-   - **Why:** Many methods do `await self._ensure_valid_token()` and then check a controller attribute (e.g., `:400-404`, `:465-468`, `:513-515`, `:554-556`, `:637-639`).
-   - **Action:** Add a helper such as:
-     - `_get_api(self, attr_name: str) -> ControllerType`
-     - It should call `_require_entered()`, await `_ensure_valid_token()`, and return the controller or raise the same “Internal error: X_api not initialized” message.
-   - **Behavioral constraint:** Preserve error text formatting exactly.
-
-3. **Centralize `ApiException` mapping**
-   - **Why:** Many methods have identical `try/except ApiException` blocks calling `_handle_api_exception` (e.g., `:408-416`, `:479-489`, `:517-525`, `:611-618`, `:705-714`).
-   - **Action:** Create a helper wrapper such as `_call_api(self, coro: Awaitable[T]) -> T` that awaits the call, catches `ApiException`, routes to `_handle_api_exception`, then re-raises.
-   - **Behavioral constraint:** Preserve the same exception mapping and logging.
-
-4. **Extract common scenario step creation logic**
-   - **Why:** `create_scenario_step` and `create_shared_step_scenario_step` are nearly identical (see `src/client/client.py:527-593` and `:933-976`).
-   - **Action:** Add a private helper like `_create_scenario_step_via_api(...)` that:
-     - Calls the `*_without_preload_content` endpoint
-     - Validates HTTP status
-     - Parses JSON
-     - Returns `ScenarioStepCreatedResponseDto.model_construct(...)`
-   - **Behavioral constraint:** Keep the same status validation and response parsing.
-
-5. **Extract common attachment upload logic**
-   - **Why:** `upload_attachment` and `upload_shared_step_attachment` repeat the same flow (`src/client/client.py:491-525`, `:978-1007`).
-   - **Action:** Create a helper to accept controller + target ID + file data, and invoke the corresponding `createXX` method.
-   - **Behavioral constraint:** Same exception handling and timeout usage.
-
-6. **Consolidate scenario controller attributes**
-   - **Why:** Both `_scenario_api` and `_test_case_scenario_api` are `TestCaseScenarioControllerApi` (see `:173-175`, initialization in `:309-310`).
-   - **Action:** Keep a single attribute (prefer `_scenario_api`) and update usages to that single field.
-   - **Behavioral constraint:** No change in which endpoints are called.
-
-7. **Centralize “internal error” message formatting**
-   - **Why:** Repeated strings with only controller name changed (e.g., `:402`, `:467`, `:515`, `:556`, `:609`, `:639`, `:703`, `:734`, `:918`, `:950`, `:997`, `:1020`, `:1047`, `:1076`).
-   - **Action:** Add a helper that formats and raises the same `AllureAPIError` message.
-   - **Behavioral constraint:** Preserve exact wording.
-
-8. **Clean up duplicate entries in `__all__`**
-   - **Why:** `ScenarioStepCreateDto` and `ScenarioStepCreatedResponseDto` appear twice (`src/client/client.py:97-100`).
-   - **Action:** Remove duplicates to keep `__all__` concise and accurate.
-
-9. **Validation & regression checks**
-   - **Action:** After refactor, review call sites to ensure all exceptions, timeouts, and API calls are unchanged.
-   - **Optional:** Run unit/integration tests if desired (per project test instructions).
-
-## Helper signatures (non-binding)
-- `_require_entered(self) -> None`
-- `_get_api(self, attr_name: str) -> ControllerType`
-- `_call_api(self, coro: Awaitable[T]) -> T`
-- `_raise_missing_api(self, api_name: str) -> None`
-- `_create_scenario_step_via_api(...) -> ScenarioStepCreatedResponseDto`
-- `_upload_attachment_via_api(...) -> list[AttachmentRowType]`
-
-## Notes
-- Keep new helpers type-annotated without introducing `Any`.
-- Maintain all existing exception classes and messages.
-- Avoid changing public method signatures.