Mark --worker option as experimental and default to single process

This is probably safest for now. I don't want to break peoples setup
the new version of docstub suddenly hangs or fails. This way they users
have to opt in explicitly and will now what might have caused it.

Author: lagru

docs/command_line.md

@@ -49,10 +49,6 @@ Options:
           Set output directory explicitly. Stubs will be directly written into
           that directory while preserving the directory structure under
           PACKAGE_PATH. Otherwise, stubs are generated inplace.
-      --config PATH
-          Set one or more configuration file(s) explicitly. Otherwise, it will
-          look for a `pyproject.toml` or `docstub.toml` in the current
-          directory.
       --ignore GLOB
           Ignore files matching this glob-style pattern. Can be used multiple
           times.
@@ -68,10 +64,14 @@ Options:
           Return non-zero exit code when a warning is raised. Will add to
           --allow-errors.
       --workers INT
-          Set the number of workers to process files in parallel. By default
-          docstub will attempt to choose an appropriate number.  [x>=1]
+          Experimental: Process files in parallel with the desired number of
+          workers. By default, no multiprocessing is used.  [default: 1]
       --no-cache
           Ignore pre-existing cache and don't create a new one.
+      --config PATH
+          Set one or more configuration file(s) explicitly. Otherwise, it will
+          look for a `pyproject.toml` or `docstub.toml` in the current
+          directory.
   -v, --verbose
           Print more details. Use once to show information messages. Use -vv to
           print debug messages.

src/docstub-stubs/_cli.pyi

@@ -60,7 +60,7 @@ def run(
     group_errors: bool,
     allow_errors: int,
     fail_on_warning: bool,
-    desired_worker_count: int | None,
+    desired_worker_count: int,
     no_cache: bool,
     verbose: int,
     quiet: int,

src/docstub-stubs/_concurrency.pyi

@@ -42,5 +42,5 @@ class LoggingProcessExecutor:
     ) -> bool: ...
 
 def guess_concurrency_params(
-    *, task_count: int, worker_count: int | None = ...
+    *, task_count: int, desired_worker_count: int | None = ...
 ) -> tuple[int, int]: ...

src/docstub/_cli.py

@@ -316,16 +316,6 @@ def _transform_to_stub(task):
     "structure under PACKAGE_PATH. "
     "Otherwise, stubs are generated inplace.",
 )
-@click.option(
-    "--config",
-    "config_paths",
-    type=click.Path(exists=True, dir_okay=False),
-    metavar="PATH",
-    multiple=True,
-    help="Set one or more configuration file(s) explicitly. "
-    "Otherwise, it will look for a `pyproject.toml` or `docstub.toml` in the "
-    "current directory.",
-)
 @click.option(
     "--ignore",
     type=str,
@@ -361,16 +351,28 @@ def _transform_to_stub(task):
 @click.option(
     "--workers",
     "desired_worker_count",
-    type=click.IntRange(min=1),
+    type=int,
+    default=1,
     metavar="INT",
-    help="Set the number of workers to process files in parallel. "
-    "By default docstub will attempt to choose an appropriate number.",
+    help="Experimental: Process files in parallel with the desired number of workers. "
+    "By default, no multiprocessing is used.",
+    show_default=True,
 )
 @click.option(
     "--no-cache",
     is_flag=True,
     help="Ignore pre-existing cache and don't create a new one.",
 )
+@click.option(
+    "--config",
+    "config_paths",
+    type=click.Path(exists=True, dir_okay=False),
+    metavar="PATH",
+    multiple=True,
+    help="Set one or more configuration file(s) explicitly. "
+    "Otherwise, it will look for a `pyproject.toml` or `docstub.toml` in the "
+    "current directory.",
+)
 @_add_verbosity_options
 @click.help_option("-h", "--help")
 @log_execution_time()
@@ -404,7 +406,7 @@ def run(
     group_errors : bool
     allow_errors : int
     fail_on_warning : bool
-    desired_worker_count : int | None
+    desired_worker_count : int
     no_cache : bool
     verbose : int
     quiet : int
@@ -480,7 +482,7 @@ def run(
     task_count = len(task_args)
 
     worker_count, chunk_size = guess_concurrency_params(
-        task_count=task_count, worker_count=desired_worker_count
+        task_count=task_count, desired_worker_count=desired_worker_count
     )
 
     logger.info("Using %i parallel jobs to write %i stubs", worker_count, task_count)

src/docstub/_concurrency.py

@@ -175,16 +175,16 @@ def __exit__(self, exc_type, exc_val, exc_tb):
         return False
 
 
-def guess_concurrency_params(*, task_count, worker_count=None):
+def guess_concurrency_params(*, task_count, desired_worker_count=None):
     """Estimate how tasks should be distributed to how many workers.
 
     Parameters
     ----------
     task_count : int
         The number of task that need to be processed.
-    worker_count : int, optional
+    desired_worker_count : int, optional
         If not set, the number of workers is estimated. Set this explicitly
-        to force a number of workers.
+        to force a number of workers. Passing `-1` will also trigger estimation.
 
     Returns
     -------
@@ -196,15 +196,17 @@ def guess_concurrency_params(*, task_count, worker_count=None):
     Examples
     --------
     >>> worker_count, chunk_size = guess_concurrency_params(
-    ...     task_count=9, worker_count=None
+    ...     task_count=9, desired_worker_count=None
     ... )
-    >>> (worker_count, chunk_size)
+    >>> (desired_worker_count, chunk_size)
     (1, 9)
     """
+    worker_count = desired_worker_count
+
     # `process_cpu_count` was added in Python 3.13 onwards
     cpu_count = getattr(os, "process_cpu_count", os.cpu_count)()
 
-    if worker_count is None:
+    if worker_count is None or worker_count == -1:
         # These crude heuristics were only ever "measured" on one computer
         worker_count = cpu_count
         # Clip to `worker_count <= task_count // 3`