chore: refactor operations and update pre-commit policies

- Moved several operation modules to a new `_internal` directory to better separate implementation details from the public API.
- Updated `pyproject.toml` to reflect changes in file paths and adjusted pre-commit policy limits for maximum file lines, directory entries, and snake binding words.
- Revised documentation to point to the new internal module paths for tokenizer artifacts and dependency strategies.
- Enhanced unit tests to accommodate the refactored module structure and ensure continued functionality.

Author: GregoryKogan

docs/advanced/tokenizer-artifact.md

@@ -47,7 +47,7 @@ client:
 
 ## API
 
-- `init_tokenizer_artifact_directory` and helpers: **Tokenizer artifact** in [API Reference](../reference/api.md) (`yt_framework.operations.tokenizer_artifact`).
+- `init_tokenizer_artifact_directory` and helpers: **Tokenizer artifact** in [API Reference](../reference/api.md) (`yt_framework.operations._internal.tokenizer_artifact`).
 - Exported on `yt_framework.operations` for advanced callers.
 
 ## See also

docs/operations/command-mode-map-reduce.md

@@ -67,7 +67,7 @@ If omitted, the uploader picks defaults (e.g. first existing among `reducer.py`,
 
 ## Removability
 
-- Logic lives mainly in `yt_framework/operations/tar_command_wiring.py`, `yt_framework/job_command/`, and branches in `dependency_strategy.py` / `map_reduce.py`.
+- Logic lives mainly in `yt_framework/operations/_internal/tar_command_wiring.py`, `yt_framework/job_command/`, and branches in `_internal/dependency_strategy.py` / `map_reduce.py`.
 - Disable by omitting `tar_command_bootstrap` or setting it `false`.
 
 ## Dev client

docs/reference/api.md

@@ -149,7 +149,7 @@ YQL operations are implemented as methods on `BaseYTClient` and its subclasses (
 ### Tokenizer artifact
 
 ```{eval-rst}
-.. automodule:: yt_framework.operations.tokenizer_artifact
+.. automodule:: yt_framework.operations._internal.tokenizer_artifact
    :members:
    :undoc-members:
    :show-inheritance:

pyproject.toml

@@ -92,12 +92,17 @@ ignore = [
 # Subprocess jobs run bash -c with pipeline-built commands (Bandit cannot verify).
 "yt_framework/yt/client_dev.py" = ["ARG002", "PLR0913"]
 # Complexity: remaining high-arity API surfaces are isolated to explicit modules.
-"yt_framework/operations/dependency_strategy.py" = ["PLR0913"]
+"yt_framework/operations/_internal/dependency_strategy.py" = ["PLR0913"]
 "yt_framework/operations/map_reduce.py" = ["PLR0913"]
 "yt_framework/operations/s3.py" = ["PLR0913"]
 "yt_framework/operations/upload.py" = ["PLR0913"]
 "yt_framework/yt/client_base.py" = ["PLR0913"]
 "yt_framework/yt/client_prod.py" = ["PLR0913"]
+# Split-out client bodies: same API arity and dev unused-arg rules as monolithic clients.
+"yt_framework/yt/_client_split/_client_dev_ops_mixin.py" = ["ARG002", "PLR0913"]
+"yt_framework/yt/_client_split/_client_dev_yql_mixin.py" = ["PLR0913"]
+"yt_framework/yt/_client_split/_client_prod_ops_mixin.py" = ["PLR0913"]
+"yt_framework/yt/_client_split/_client_prod_yql_mixin.py" = ["PLR0913"]
 "yt_framework/yt/_client_prod_runtime.py" = ["PLR0913", "ANN401", "TC003", "TC001"]
 "yt_framework/yt/_client_dev_runtime.py" = ["PLR0913", "ANN401", "TC003"]
 "yt_framework/yt/yql_builder.py" = ["PLR0913"]
@@ -200,17 +205,17 @@ line-ending = "auto"
 
 [tool.yt_framework.pre_commit.max_file_lines]
 enabled = true
-limit = 1500
+limit = 800
 roots = ["yt_framework", "ytjobs"]
 
 [tool.yt_framework.pre_commit.max_dir_entries]
 enabled = true
-limit = 15
+limit = 12
 roots = ["yt_framework", "ytjobs"]
 
 [tool.yt_framework.pre_commit.max_snake_binding_words]
 enabled = true
-limit = 8
+limit = 6
 roots = ["yt_framework", "ytjobs"]
 
 [tool.vulture]

tests/test_client_prod.py

@@ -11,8 +11,8 @@
 
 from yt_framework.yt._client_prod_runtime import (
     _apply_command_leg_format,
-    _apply_max_row_weight_to_spec_builder,
-    _apply_spec_options_and_split_run_operation_kwargs,
+    _apply_max_row_weight_spec_builder,
+    _apply_spec_options_split_run_kwargs,
 )
 from yt_framework.yt.client_base import OperationResources
 from yt_framework.yt.client_prod import YTProdClient
@@ -52,7 +52,7 @@ def title(self, value: str) -> "_FakeSpecBuilder":
 
 def test_apply_spec_options_splits_run_operation_kwargs_from_builder_chain() -> None:
     b = _FakeSpecBuilder()
-    b2, run_op = _apply_spec_options_and_split_run_operation_kwargs(
+    b2, run_op = _apply_spec_options_split_run_kwargs(
         b,
         {"title": "my_job", "sync": True},
     )
@@ -64,7 +64,7 @@ def test_apply_spec_options_splits_run_operation_kwargs_from_builder_chain() ->
 def test_apply_spec_options_raises_value_error_on_unknown_operation_kwarg() -> None:
     b = _FakeSpecBuilder()
     with pytest.raises(ValueError, match="Unknown YT operation option 'bad_kw'"):
-        _apply_spec_options_and_split_run_operation_kwargs(b, {"bad_kw": 1})
+        _apply_spec_options_split_run_kwargs(b, {"bad_kw": 1})
 
 
 class _LegBuilderWithFormat:
@@ -134,7 +134,7 @@ def _prod_client_with_run_operation_id(
 
 def _stub_split_run_operation_kwargs(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(
-        "yt_framework.yt._client_prod_runtime._apply_spec_options_and_split_run_operation_kwargs",
+        "yt_framework.yt._client_prod_runtime._apply_spec_options_split_run_kwargs",
         lambda sb, kw: (sb, {}),
     )
 
@@ -152,25 +152,23 @@ def test_apply_command_leg_format_skips_format_for_typed_job_leg() -> None:
     assert b.format_specs == []
 
 
-def test_apply_max_row_weight_to_spec_builder_writes_bytes_to_table_writer() -> None:
+def test_apply_max_row_weight_spec_builder_writes_bytes_to_table_writer() -> None:
     b = _BuilderWithTableWriter()
-    out = _apply_max_row_weight_to_spec_builder(b, "128M")
+    out = _apply_max_row_weight_spec_builder(b, "128M")
     assert out is b
     assert b.payload == {"max_row_weight": 134217728}
 
 
-def test_apply_max_row_weight_to_spec_builder_uses_job_io_fallback_with_bytes() -> None:
+def test_apply_max_row_weight_spec_builder_uses_job_io_fallback_with_bytes() -> None:
     b = _BuilderWithJobIo()
-    out = _apply_max_row_weight_to_spec_builder(b, "64M")
+    out = _apply_max_row_weight_spec_builder(b, "64M")
     assert out is b
     assert b.payload == {"table_writer": {"max_row_weight": 67108864}}
 
 
-def test_apply_max_row_weight_to_spec_builder_prefers_table_writer_over_job_io() -> (
-    None
-):
+def test_apply_max_row_weight_spec_builder_prefers_table_writer_over_job_io() -> None:
     b = _BuilderWithTableWriterAndJobIo()
-    out = _apply_max_row_weight_to_spec_builder(b, "64M")
+    out = _apply_max_row_weight_spec_builder(b, "64M")
     assert out is b
     assert b.table_writer_payload == {"max_row_weight": 67108864}
     assert b.job_io_payload is None
@@ -286,7 +284,7 @@ def test_yt_prod_client_run_map_partitions_env_into_vault_and_wraps_string_comma
         "yt_framework.yt._client_prod_runtime.MapSpecBuilder", lambda: spec
     )
     monkeypatch.setattr(
-        "yt_framework.yt._client_prod_runtime._apply_spec_options_and_split_run_operation_kwargs",
+        "yt_framework.yt._client_prod_runtime._apply_spec_options_split_run_kwargs",
         lambda sb, kw: (sb, {}),
     )
 
@@ -485,7 +483,7 @@ def _otp(paths: Any) -> Any:
     )
 
     monkeypatch.setattr(
-        "yt_framework.yt._client_prod_runtime._apply_spec_options_and_split_run_operation_kwargs",
+        "yt_framework.yt._client_prod_runtime._apply_spec_options_split_run_kwargs",
         lambda sb, kw: (sb, {}),
     )
 

tests/test_dependency_strategy.py

@@ -1,12 +1,14 @@
-"""Tests for yt_framework.operations.dependency_strategy.TarArchiveDependencyBuilder."""
+"""Tests for yt_framework.operations._internal.dependency_strategy.TarArchiveDependencyBuilder."""
 
 import logging
 from pathlib import Path
 
 import pytest
 from omegaconf import OmegaConf
 
-from yt_framework.operations.dependency_strategy import TarArchiveDependencyBuilder
+from yt_framework.operations._internal.dependency_strategy import (
+    TarArchiveDependencyBuilder,
+)
 
 _LOG = logging.getLogger("tests.dependency_strategy")
 

tests/test_map.py

@@ -9,7 +9,9 @@
 
 from yt_framework.core.dependencies import PipelineStageDependencies
 from yt_framework.core.stage import StageContext
-from yt_framework.operations.dependency_strategy import DependencyBuildResult
+from yt_framework.operations._internal.dependency_strategy import (
+    DependencyBuildResult,
+)
 from yt_framework.operations.map import run_map
 from yt_framework.yt.client_base import BaseYTClient
 

tests/test_map_reduce.py

@@ -9,7 +9,9 @@
 
 from yt_framework.core.dependencies import PipelineStageDependencies
 from yt_framework.core.stage import StageContext
-from yt_framework.operations.dependency_strategy import DependencyBuildResult
+from yt_framework.operations._internal.dependency_strategy import (
+    DependencyBuildResult,
+)
 from yt_framework.operations.map_reduce import run_map_reduce, run_reduce
 from yt_framework.yt.client_base import BaseYTClient
 

tests/test_operation_secure_env.py

@@ -10,7 +10,7 @@
     merge_secure_vault,
     partition_env_for_yt_spec,
     promote_secure_vault_environment,
-    wrap_shell_command_with_secure_vault_promotion,
+    wrap_shell_cmd_secure_vault_promote,
 )
 
 
@@ -67,15 +67,15 @@ def test_promote_skips_pickling_key() -> None:
 
 def test_wrap_command_roundtrip_shell_words() -> None:
     inner = "python3 mapper.py 'a b'"
-    wrapped = wrap_shell_command_with_secure_vault_promotion(inner)
+    wrapped = wrap_shell_cmd_secure_vault_promote(inner)
     assert wrapped.startswith("python3 -c ")
     assert wrapped.count(" bash -c ") == 1
     _, tail = wrapped.split(" bash -c ", 1)
     assert shlex.split(tail, posix=True) == [inner]
 
 
 def test_wrap_command_contract_requires_python3_and_bash() -> None:
-    wrapped = wrap_shell_command_with_secure_vault_promotion("echo ok")
+    wrapped = wrap_shell_cmd_secure_vault_promote("echo ok")
     assert wrapped.startswith("python3 -c ")
     assert " bash -c " in wrapped
 

tests/test_tar_command_wiring.py

@@ -1,8 +1,8 @@
-"""Tests for yt_framework.operations.tar_command_wiring helpers."""
+"""Tests for yt_framework.operations._internal.tar_command_wiring helpers."""
 
 import logging
 
-from yt_framework.operations.tar_command_wiring import (
+from yt_framework.operations._internal.tar_command_wiring import (
     bootstrap_shell_run_wrapper,
     map_reduce_wrapper_names,
     reduce_wrapper_name,