docs: Use and enforce imperative mood (#1100)

- Currently, our docstrings use a mix of imperative and indicative moods
basically randomly.
- PEP 257 recommends using the imperative mood for the first line of
docstrings, which is also enforced by the Ruff rule
[D401](https://docs.astral.sh/ruff/rules/non-imperative-mood/#non-imperative-mood-d401).
So I believe the imperative form is more suitable for the docs purposes.
- In most cases, I have simply changed the verb form, but a few cases
required more rewording.
- I updated the pyproject configuration to enforce it.

Author: vdusek

pyproject.toml

@@ -131,6 +131,9 @@ ignore = [
     "D100",     # Missing docstring in public module
     "D104",     # Missing docstring in public package
     "D107",     # Missing docstring in `__init__`
+    "D203",     # One blank line required before class docstring
+    "D213",     # Multi-line docstring summary should start at the second line
+    "D413",     # Missing blank line after last section
     "EM",       # flake8-errmsg
     "G004",     # Logging statement uses f-string
     "ISC001",   # This rule may cause conflicts when used with the formatter
@@ -188,9 +191,6 @@ runtime-evaluated-base-classes = [
 [tool.ruff.lint.flake8-builtins]
 builtins-ignorelist = ["id"]
 
-[tool.ruff.lint.pydocstyle]
-convention = "google"
-
 [tool.ruff.lint.isort]
 known-first-party = ["crawlee"]
 

src/crawlee/_autoscaling/autoscaled_pool.py

@@ -70,7 +70,7 @@ def __init__(
         is_task_ready_function: Callable[[], Awaitable[bool]],
         is_finished_function: Callable[[], Awaitable[bool]],
     ) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             system_status: Provides data about system utilization (load).
@@ -211,7 +211,7 @@ def _log_system_status(self) -> None:
         )
 
     async def _worker_task_orchestrator(self, run: _AutoscaledPoolRun) -> None:
-        """Launches worker tasks whenever there is free capacity and a task is ready.
+        """Launch worker tasks whenever there is free capacity and a task is ready.
 
         Exits when `is_finished_function` returns True.
         """
@@ -260,11 +260,11 @@ async def _worker_task_orchestrator(self, run: _AutoscaledPoolRun) -> None:
                 run.result.set_result(object())
 
     def _reap_worker_task(self, task: asyncio.Task, run: _AutoscaledPoolRun) -> None:
-        """A callback for finished worker tasks.
+        """Handle cleanup and tracking of a completed worker task.
 
-        - It interrupts the run in case of an exception,
-        - keeps track of tasks in progress,
-        - notifies the orchestrator
+        - Interrupt the run if the task encountered an exception.
+        - Update the list of tasks in progress.
+        - Notify the orchestrator about the task completion.
         """
         run.worker_tasks_updated.set()
         run.worker_tasks.remove(task)

src/crawlee/_autoscaling/snapshotter.py

@@ -65,7 +65,7 @@ def __init__(
         max_client_errors: int,
         max_memory_size: ByteSize,
     ) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         In most cases, you should use the `from_config` constructor to create a new instance based on
         the provided configuration.
@@ -102,7 +102,7 @@ def __init__(
 
     @classmethod
     def from_config(cls, config: Configuration | None = None) -> Snapshotter:
-        """Create a new instance based on the provided `Configuration`.
+        """Initialize a new instance based on the provided `Configuration`.
 
         Args:
             config: The `Configuration` instance. Uses the global (default) one if not provided.
@@ -136,7 +136,7 @@ def active(self) -> bool:
         return self._active
 
     async def __aenter__(self) -> Snapshotter:
-        """Starts capturing snapshots at configured intervals.
+        """Start capturing snapshots at configured intervals.
 
         Raises:
             RuntimeError: If the context manager is already active.
@@ -158,7 +158,7 @@ async def __aexit__(
         exc_value: BaseException | None,
         exc_traceback: TracebackType | None,
     ) -> None:
-        """Stops all resource capturing.
+        """Stop all resource capturing.
 
         This method stops capturing snapshots of system resources (CPU, memory, event loop, and client information).
         It should be called to terminate resource capturing when it is no longer needed.
@@ -241,7 +241,7 @@ def _get_sample(snapshots: list[Snapshot], duration: timedelta | None = None) ->
         return [snapshot for snapshot in snapshots if latest_time - snapshot.created_at <= duration]
 
     def _snapshot_cpu(self, event_data: EventSystemInfoData) -> None:
-        """Captures a snapshot of the current CPU usage.
+        """Capture a snapshot of the current CPU usage.
 
         This method does not perform CPU usage measurement. Instead, it just reads the data received through
         the `event_data` parameter, which is expected to be supplied by the event manager.
@@ -260,7 +260,7 @@ def _snapshot_cpu(self, event_data: EventSystemInfoData) -> None:
         self._cpu_snapshots.add(snapshot)
 
     def _snapshot_memory(self, event_data: EventSystemInfoData) -> None:
-        """Captures a snapshot of the current memory usage.
+        """Capture a snapshot of the current memory usage.
 
         This method does not perform memory usage measurement. Instead, it just reads the data received through
         the `event_data` parameter, which is expected to be supplied by the event manager.
@@ -281,7 +281,7 @@ def _snapshot_memory(self, event_data: EventSystemInfoData) -> None:
         self._evaluate_memory_load(event_data.memory_info.current_size, event_data.memory_info.created_at)
 
     def _snapshot_event_loop(self) -> None:
-        """Captures a snapshot of the current event loop usage.
+        """Capture a snapshot of the current event loop usage.
 
         This method evaluates the event loop's latency by comparing the expected time between snapshots to the actual
         time elapsed since the last snapshot. The delay in the snapshot reflects the time deviation due to event loop
@@ -300,7 +300,7 @@ def _snapshot_event_loop(self) -> None:
         self._event_loop_snapshots.add(snapshot)
 
     def _snapshot_client(self) -> None:
-        """Captures a snapshot of the current API state by checking for rate limit errors (HTTP 429).
+        """Capture a snapshot of the current API state by checking for rate limit errors (HTTP 429).
 
         Only errors produced by a 2nd retry of the API call are considered for snapshotting since earlier errors may
         just be caused by a random spike in the number of requests and do not necessarily signify API overloading.
@@ -317,7 +317,7 @@ def _snapshot_client(self) -> None:
         self._client_snapshots.add(snapshot)
 
     def _prune_snapshots(self, snapshots: list[Snapshot], now: datetime) -> None:
-        """Removes snapshots that are older than the `self._snapshot_history`.
+        """Remove snapshots that are older than the `self._snapshot_history`.
 
         This method modifies the list of snapshots in place, removing all snapshots that are older than the defined
         snapshot history relative to the `now` parameter.
@@ -342,7 +342,7 @@ def _prune_snapshots(self, snapshots: list[Snapshot], now: datetime) -> None:
             snapshots.clear()
 
     def _evaluate_memory_load(self, current_memory_usage_size: ByteSize, snapshot_timestamp: datetime) -> None:
-        """Evaluates and logs critical memory load conditions based on the system information.
+        """Evaluate and logs critical memory load conditions based on the system information.
 
         Args:
             current_memory_usage_size: The current memory usage.

src/crawlee/_autoscaling/system_status.py

@@ -46,7 +46,7 @@ def __init__(
         event_loop_overload_threshold: float = 0.6,
         client_overload_threshold: float = 0.3,
     ) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             snapshotter: The `Snapshotter` instance to be queried for `SystemStatus`.
@@ -69,7 +69,7 @@ def __init__(
         self._client_overload_threshold = client_overload_threshold
 
     def get_current_system_info(self) -> SystemInfo:
-        """Retrieves and evaluates the current status of system resources.
+        """Retrieve and evaluates the current status of system resources.
 
         Considers snapshots within the `_max_snapshot_age` timeframe and determines if the system is currently
         overloaded based on predefined thresholds for each resource type.
@@ -80,7 +80,7 @@ def get_current_system_info(self) -> SystemInfo:
         return self._get_system_info(sample_duration=self._max_snapshot_age)
 
     def get_historical_system_info(self) -> SystemInfo:
-        """Retrieves and evaluates the historical status of system resources.
+        """Retrieve and evaluates the historical status of system resources.
 
         Considers the entire history of snapshots from the Snapshotter to assess long-term system performance and
         determines if the system has been historically overloaded.

src/crawlee/_log_config.py

@@ -91,7 +91,7 @@ def __init__(
         *args: Any,
         **kwargs: Any,
     ) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             include_logger_name: Include logger name at the beginning of the log line.

src/crawlee/_types.py

@@ -51,7 +51,7 @@
 
 
 def _normalize_headers(headers: Mapping[str, str]) -> dict[str, str]:
-    """Converts all header keys to lowercase, strips whitespace, and returns them sorted by key."""
+    """Convert all header keys to lowercase, strips whitespace, and returns them sorted by key."""
     normalized_headers = {k.lower().strip(): v.strip() for k, v in headers.items()}
     sorted_headers = sorted(normalized_headers.items())
     return dict(sorted_headers)
@@ -106,7 +106,7 @@ def __init__(
         max_tasks_per_minute: float = float('inf'),
         desired_concurrency: int | None = None,
     ) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             min_concurrency: The minimum number of tasks running in parallel. If you set this value too high
@@ -340,7 +340,7 @@ def __call__(
         transform_request_function: Callable[[RequestOptions], RequestOptions | RequestTransformAction] | None = None,
         **kwargs: Unpack[EnqueueLinksKwargs],
     ) -> Coroutine[None, None, None]:
-        """A call dunder method.
+        """Call enqueue links function.
 
         Args:
             selector: A selector used to find the elements containing the links. The behaviour differs based
@@ -488,7 +488,7 @@ def __call__(
         method: HttpMethod = 'GET',
         headers: HttpHeaders | dict[str, str] | None = None,
     ) -> Coroutine[None, None, HttpResponse]:
-        """A call dunder method.
+        """Call send request function.
 
         Args:
             url: The URL to send the request to.

src/crawlee/_utils/console.py

@@ -9,7 +9,7 @@
 
 
 def make_table(rows: Sequence[Sequence[str]], width: int = 100) -> str:
-    """Creates a text table using Unicode characters.
+    """Create a text table using Unicode characters.
 
     Args:
         rows: A list of tuples/lists to be displayed in the table.

src/crawlee/_utils/context.py

@@ -8,13 +8,19 @@
 
 
 def ensure_context(method: T) -> T:
-    """Decorator to ensure the (async) context manager is initialized before calling the method.
+    """Ensure the (async) context manager is initialized before executing the method.
+
+    This decorator checks if the calling instance has an `active` attribute and verifies that it is set to `True`.
+    If the instance is inactive, it raises a `RuntimeError`. Works for both synchronous and asynchronous methods.
 
     Args:
         method: The method to wrap.
 
     Returns:
         The wrapped method with context checking applied.
+
+    Raises:
+        RuntimeError: If the instance lacks an `active` attribute or is not active.
     """
 
     @wraps(method)

src/crawlee/_utils/crypto.py

@@ -5,7 +5,7 @@
 
 
 def compute_short_hash(data: bytes, *, length: int = 8) -> str:
-    """Computes a hexadecimal SHA-256 hash of the provided data and returns a substring (prefix) of it.
+    """Compute a hexadecimal SHA-256 hash of the provided data and returns a substring (prefix) of it.
 
     Args:
         data: The binary data to be hashed.
@@ -19,6 +19,6 @@ def compute_short_hash(data: bytes, *, length: int = 8) -> str:
 
 
 def crypto_random_object_id(length: int = 17) -> str:
-    """Generates a random object ID."""
+    """Generate a random object ID."""
     chars = 'abcdefghijklmnopqrstuvwxyzABCEDFGHIJKLMNOPQRSTUVWXYZ0123456789'
     return ''.join(secrets.choice(chars) for _ in range(length))

src/crawlee/_utils/docs.py

@@ -6,10 +6,16 @@
 
 
 def docs_group(group_name: GroupName) -> Callable:  # noqa: ARG001
-    """Decorator to mark symbols for rendering and grouping in documentation.
+    """Mark a symbol for rendering and grouping in documentation.
 
-    This decorator is used purely for documentation purposes and does not alter the behavior
+    This decorator is used solely for documentation purposes and does not modify the behavior
     of the decorated callable.
+
+    Args:
+        group_name: The documentation group to which the symbol belongs.
+
+    Returns:
+        The original callable without modification.
     """
 
     def wrapper(func: Callable) -> Callable: