docs: Use and enforce imperative mood (#371)

- 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

@@ -78,6 +78,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
@@ -137,9 +140,6 @@ inline-quotes = "single"
 [tool.ruff.lint.flake8-builtins]
 builtins-ignorelist = ["id"]
 
-[tool.ruff.lint.pydocstyle]
-convention = "google"
-
 [tool.ruff.lint.isort]
 known-local-folder = ["apify_client"]
 

src/apify_client/_errors.py

@@ -18,7 +18,7 @@ class ApifyApiError(ApifyClientError):
 
     @ignore_docs
     def __init__(self, response: httpx.Response, attempt: int) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             response: The response to the failed API call.
@@ -62,7 +62,7 @@ class InvalidResponseBodyError(ApifyClientError):
 
     @ignore_docs
     def __init__(self, response: httpx.Response) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             response: The response which failed to be parsed.

src/apify_client/client.py

@@ -70,7 +70,7 @@ def __init__(
         min_delay_between_retries_millis: int | None = 500,
         timeout_secs: int | None = 360,
     ) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             token: The Apify API token.
@@ -109,7 +109,7 @@ def __init__(
         min_delay_between_retries_millis: int | None = 500,
         timeout_secs: int | None = 360,
     ) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             token: The Apify API token.
@@ -292,7 +292,7 @@ def __init__(
         min_delay_between_retries_millis: int | None = 500,
         timeout_secs: int | None = 360,
     ) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             token: The Apify API token.

src/apify_client/clients/base/base_client.py

@@ -63,7 +63,7 @@ def __init__(
         resource_path: str,
         params: dict | None = None,
     ) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             base_url: Base URL of the API server.
@@ -106,7 +106,7 @@ def __init__(
         resource_path: str,
         params: dict | None = None,
     ) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             base_url: Base URL of the API server.

src/apify_client/clients/resource_clients/actor_env_var.py

@@ -13,7 +13,7 @@ def get_actor_env_var_representation(
     name: str | None = None,
     value: str | None = None,
 ) -> dict:
-    """Returns an environment variable representation of the Actor in a dictionary."""
+    """Return an environment variable representation of the Actor in a dictionary."""
     return {
         'isSecret': is_secret,
         'name': name,

src/apify_client/clients/resource_clients/request_queue.py

@@ -61,7 +61,7 @@ def __init__(  # noqa: D417
         client_key: str | None = None,
         **kwargs: Any,
     ) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             client_key: A unique identifier of the client accessing the request queue.
@@ -415,7 +415,7 @@ def __init__(  # noqa: D417
         client_key: str | None = None,
         **kwargs: Any,
     ) -> None:
-        """A default constructor.
+        """Initialize a new instance.
 
         Args:
             client_key: A unique identifier of the client accessing the request queue.
@@ -648,7 +648,7 @@ async def _batch_add_requests_worker(
 
         This worker will process batches from the queue, retrying requests that fail until the retry limit is reached.
 
-        Returns result containing lists of processed and unprocessed requests by the worker.
+        Return result containing lists of processed and unprocessed requests by the worker.
         """
         processed_requests = list[dict]()
         unprocessed_requests = list[dict]()

src/apify_client/clients/resource_clients/user.py

@@ -58,7 +58,7 @@ def monthly_usage(self) -> dict | None:
         return None
 
     def limits(self) -> dict | None:
-        """Returns a complete summary of the user account's limits.
+        """Return a complete summary of the user account's limits.
 
         It is the same information which is available on the account's Limits page. The returned data includes
         the current usage cycle, a summary of the account's limits, and the current usage.
@@ -87,7 +87,7 @@ def update_limits(
         max_monthly_usage_usd: int | None = None,
         data_retention_days: int | None = None,
     ) -> None:
-        """Updates the account's limits manageable on your account's Limits page."""
+        """Update the account's limits manageable on your account's Limits page."""
         self.http_client.call(
             url=self._url('limits'),
             method='PUT',
@@ -150,7 +150,7 @@ async def monthly_usage(self) -> dict | None:
         return None
 
     async def limits(self) -> dict | None:
-        """Returns a complete summary of the user account's limits.
+        """Return a complete summary of the user account's limits.
 
         It is the same information which is available on the account's Limits page. The returned data includes
         the current usage cycle, a summary of the account's limits, and the current usage.
@@ -179,7 +179,7 @@ async def update_limits(
         max_monthly_usage_usd: int | None = None,
         data_retention_days: int | None = None,
     ) -> None:
-        """Updates the account's limits manageable on your account's Limits page."""
+        """Update the account's limits manageable on your account's Limits page."""
         await self.http_client.call(
             url=self._url('limits'),
             method='PUT',