LCORE-1608: improve docstrings in LCORE repository#1444
Merged
tisnik merged 4 commits intolightspeed-core:mainfrom Apr 1, 2026
Merged
Conversation
Contributor
|
Caution Review failedFailed to post review comments WalkthroughThis pull request systematically updates docstrings across the entire codebase to use consistent reStructuredText section markers. Specifically, it adds underline delimiters ( Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 34
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (5)
src/utils/quota.py (1)
30-42:⚠️ Potential issue | 🟠 MajorDocstring format violates Google Python docstring conventions.
The added underlines (
----------,-------,------) beneath section headers are NumPy/reStructuredText style, not Google style. Additionally, these docstrings use "Parameters:" instead of the Google-standard "Args:".Google Python docstring conventions (as specified in the coding guidelines) do not use underline delimiters and use "Args:" for parameters. This creates inconsistency with
get_available_quotas(lines 94-109), which correctly uses "Args:" without underlines.As per coding guidelines: "Follow Google Python docstring conventions with Parameters, Returns, Raises, and Attributes sections as needed"
📝 Proposed fix to align with Google style
For
consume_tokens:"""Consume tokens from cluster and/or user quotas. - Parameters: - ---------- + Args: quota_limiters: List of quota limiter instances to consume tokens from. token_usage_history: Optional instance of TokenUsageHistory class that records used tokens user_id: Identifier of the user consuming tokens. input_tokens: Number of input tokens to consume. output_tokens: Number of output tokens to consume. model_id: Model identification provider_id: Provider identification Returns: - ------- None """For
check_tokens_available:"""Check if tokens are available for user. - Parameters: - ---------- + Args: quota_limiters: List of quota limiter instances to check. user_id: Identifier of the user to check quota for. Returns: - ------- None Raises: - ------ HTTPException: With status 500 if database communication fails, or status 429 if quota is exceeded. """Also applies to: 65-78
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/utils/quota.py` around lines 30 - 42, Update the NumPy-style docstrings in functions consume_tokens and check_tokens_available to follow Google Python docstring conventions: replace the "Parameters:" header and its underline with "Args:" (no underlines), list each parameter as "param_name (type): description" matching the style used in get_available_quotas, and change the Returns block to a single "Returns:" header (no underline) with a one-line description of the return value; remove any underline delimiters (e.g., "----------", "-------") and ensure formatting is consistent across both functions.tests/unit/app/test_database.py (2)
311-325:⚠️ Potential issue | 🟠 MajorDocstring format violates coding guidelines.
The added underline converts this docstring to NumPy/reStructuredText style, but the coding guidelines require Google Python docstring conventions. Google style does not use underlines and uses "Args:" instead of "Parameters:".
Based on learnings: "Follow Google Python docstring conventions with Parameters, Returns, Raises, and Attributes sections as needed".
📝 Convert to Google style format
- """Verify common assertions for initialize_database tests. + """Verify common assertions for initialize_database tests. Assert that initialize_database set up the engine and session factory and that sessionmaker was invoked with the expected arguments. - Parameters: - ---------- - mock_sessionmaker (MockType): Mock of the sessionmaker factory; - expected to have been called with autocommit=False, - autoflush=False, bind=mock_engine. - mock_engine (MockType): Mock Engine instance expected to be - assigned to database.engine. - mock_session_local (MockType): Mock session factory expected to be - assigned to database.session_local. + Args: + mock_sessionmaker (MockType): Mock of the sessionmaker factory; + expected to have been called with autocommit=False, + autoflush=False, bind=mock_engine. + mock_engine (MockType): Mock Engine instance expected to be + assigned to database.engine. + mock_session_local (MockType): Mock session factory expected to be + assigned to database.session_local. """🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tests/unit/app/test_database.py` around lines 311 - 325, The docstring for the helper that verifies common assertions for initialize_database tests (referenced as verify_common_assertions) uses NumPy/reST style with an underline and "Parameters:"; change it to Google style by removing the underline, replace the "Parameters:" section header with "Args:", and list the parameters (mock_sessionmaker, mock_engine, mock_session_local) using Google-style "name (type): description" lines; keep the rest of the explanatory text but ensure the docstring follows Google Python docstring conventions.
278-297:⚠️ Potential issue | 🟠 MajorDocstring format violates coding guidelines.
The added underlines convert this docstring to NumPy/reStructuredText style, but the coding guidelines require Google Python docstring conventions. Google style does not use underlines and uses "Args:" instead of "Parameters:".
Based on learnings: "Follow Google Python docstring conventions with Parameters, Returns, Raises, and Attributes sections as needed".
📝 Convert to Google style format
- """Setup common mocks for initialize_database tests. + """Setup common mocks for initialize_database tests. Create and configure common mock objects used by initialize_database tests. - Parameters: - ---------- - mocker (MockerFixture): pytest-mock fixture used to create MagicMock instances. - mock_sessionmaker (MockType): Mocked sessionmaker whose return - value will be set to the mocked session-local factory. - mock_logger (MockType): Mock logger whose `isEnabledFor` behavior will be configured. - enable_debug (bool): If True, configures `mock_logger.isEnabledFor` to return True. + Args: + mocker (MockerFixture): pytest-mock fixture used to create MagicMock instances. + mock_sessionmaker (MockType): Mocked sessionmaker whose return + value will be set to the mocked session-local factory. + mock_logger (MockType): Mock logger whose `isEnabledFor` behavior will be configured. + enable_debug (bool): If True, configures `mock_logger.isEnabledFor` to return True. Returns: - ------- - tuple[MockType, MockType]: A tuple (mock_engine, - mock_session_local) where `mock_engine` is a mocked SQLAlchemy - Engine and `mock_session_local` is the mocked session-local - factory. + tuple[MockType, MockType]: A tuple (mock_engine, + mock_session_local) where `mock_engine` is a mocked SQLAlchemy + Engine and `mock_session_local` is the mocked session-local + factory. """🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tests/unit/app/test_database.py` around lines 278 - 297, The function/docstring for the setup helper used in initialize_database tests uses NumPy/reST-style underlines and "Parameters:"; convert it to Google style by removing any section underlines, replace the "Parameters:" header with "Args:", keep the descriptive top-line and blank line before sections, list each argument under "Args:" with name followed by a colon and type/description (e.g., mocker (MockerFixture): ...), and retain a "Returns:" section in Google style (Returns: tuple[MockType, MockType]: description) ensuring consistent punctuation and spacing; locate the docstring around the setup helper used by the initialize_database tests (the docstring that currently contains "Parameters:" and the underlines) and update it accordingly.src/utils/suid.py (1)
1-118: 🛠️ Refactor suggestion | 🟠 MajorStandardize all docstrings to Google conventions throughout the file.
The file currently mixes Google Python docstring style (
Args:,Returns:innormalize_conversation_id) with NumPy/reStructuredText style (Parameters:with underlines incheck_suidandto_llama_stack_conversation_id). This PR adds underlines that increase the inconsistency.For maintainability and compliance with coding guidelines, all docstrings in this file should follow Google Python docstring conventions consistently:
- Use
Args:instead ofParameters:- Use
Note:instead ofNotes:- Remove all underline delimiters
- Keep
Returns:andExamples:without underlinesBased on coding guidelines: "Follow Google Python docstring conventions with Parameters, Returns, Raises, and Attributes sections as needed".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/utils/suid.py` around lines 1 - 118, Update all docstrings in this module to Google style: for functions get_suid, check_suid, normalize_conversation_id, to_llama_stack_conversation_id, and is_moderation_id replace any "Parameters:" sections and underlines with an "Args:" section, rename "Notes:"/ "Notes" to "Note:", remove underline delimiters, and keep "Returns:" and "Examples:" as-is (use Google formatting for descriptions and types inside Args/Returns). Ensure the check_suid and to_llama_stack_conversation_id docstrings no longer use NumPy/reST-style headings or underlines and that normalize_conversation_id already follows the Google format consistently.src/quota/revokable_quota_limiter.py (1)
40-49:⚠️ Potential issue | 🟠 MajorDocstring style conflicts with coding guidelines.
The changes systematically add NumPy/reStructuredText-style section delimiters (
----------,-------,------,-----) beneath section headers (Parameters:,Returns:,Raises:,Notes:). This conflicts with the requirement to follow Google Python docstring conventions forsrc/**/*.pyfiles.Google-style docstrings use
Args:,Returns:,Raises:, andNotes:with simple indentation and no underline delimiters.As per coding guidelines: "Follow Google Python docstring conventions with Parameters, Returns, Raises, and Attributes sections as needed".
Also applies to: 63-72, 90-98, 120-124, 142-147, 166-172, 194-201, 214-223, 250-254, 289-300, 341-344
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/quota/revokable_quota_limiter.py` around lines 40 - 49, Several docstrings in src/quota/revokable_quota_limiter.py use NumPy/reStructuredText-style underlined section headers (e.g., "Parameters:" followed by "----------"); update them to Google-style docstrings by replacing "Parameters:" with "Args:", removing all underline/dash lines, and similarly remove underlines under "Returns:", "Raises:", and "Notes:" while keeping the existing parameter/return/raise text and indentation intact; apply this change to every docstring region called out in the review (the blocks around the initial_quota/increase_by/subject_type docstring and the other listed ranges) so function and class docstrings (e.g., the limiter class and its methods) conform to Google Python docstring conventions.
♻️ Duplicate comments (1)
src/quota/quota_exceed_error.py (1)
24-25:⚠️ Potential issue | 🟡 MinorRemove reStructuredText underline to comply with Google docstring style.
The added underline separator (
----------) beneath theAttributes:header is not part of Google Python docstring conventions. This is the same style inconsistency as theParameters:section above.📝 Proposed fix to remove the underline
Attributes: - ---------- subject_id (str): Copied from the `subject_id` parameter.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/quota/quota_exceed_error.py` around lines 24 - 25, The docstring for the QuotaExceedError class contains a reStructuredText-style underline ("----------") under the "Attributes:" header; remove that underline so the docstring follows Google Python docstring style (match how "Parameters:" was fixed). Locate the class docstring in quota_exceed_error.py (search for QuotaExceedError) and delete the line with the dashes so "Attributes:" stands alone with the attribute descriptions beneath it.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/app/endpoints/query.py`:
- Around line 279-286: The docstring in the function that accepts parameters
client, responses_params, and moderation_result and returns a TurnSummary uses
Sphinx-style underlines; change it to Google Python docstring style by removing
the dashed underlines and replacing "Parameters:" with "Args:" (listing client,
responses_params, moderation_result with their short type/description) and
"Returns:" without underlines describing the TurnSummary return value; ensure
formatting matches other Google-style docstrings in the repo (no section
delimiters, use "Args:" and "Returns:").
In `@src/app/routers.py`:
- Around line 43-44: The docstring in src/app/routers.py uses NumPy/Sphinx-style
"Parameters:" with an underline; update it to Google Python style by replacing
the underlined "Parameters"/separator with a Google-style "Args:" section and
reformat each parameter line as "name (type): description" (one parameter per
line, no underline). Locate the docstring containing the "Parameters:" header
(e.g., in the router function or class docstring) and ensure other sections
follow Google conventions (use "Returns:" and "Raises:" if present) so the file
conforms to the project's docstring guidelines.
In `@src/authorization/resolvers.py`:
- Around line 35-41: In src/authorization/resolvers.py, several NumPy-style
underlines under docstring headers must be removed and converted to Google
style: locate the docstrings that reference the auth parameter (the one showing
"auth (AuthTuple): Authentication tuple...") and the other affected docstrings
at the listed ranges and delete the dashed underline lines (e.g., "----------",
"-------") so each section header is simply "Parameters:", "Returns:", "Raises:"
etc. followed by the indented content; ensure you keep the existing header text
and colons and only remove the underline separator lines across all affected
docstrings.
In `@src/models/config.py`:
- Around line 422-432: Replace the NumPy/reST-style docstring sections under the
function that validates root_path (the block mentioning "Parameters:",
"Returns:", "Raises:" with underline delimiters) with Google-style docstrings:
use "Args:", "Returns:", and "Raises:" headers without the underline dashes,
document the parameter "value" under Args:, keep the return description under
Returns:, and the ValueError under Raises:; apply the same change to the other
occurrences referenced (around the locations noted as 2004-2006) so all
docstrings in this module follow the Google Python docstring convention.
In `@src/models/requests.py`:
- Line 276: Remove the reStructuredText/NumPy-style underline delimiters (the
literal sequences like "----------", "-------", "------") that were added under
docstring section headers; update the docstrings so the sections use plain
Google-style headers such as "Parameters:", "Returns:", and "Raises:" (with the
usual indented parameter descriptions) instead of underlined headers—search for
docstrings containing "Parameters:", "Returns:", or "Raises:" and the underline
tokens and strip the underline lines so the docstrings match the existing
Google-style ones in this file.
In `@src/models/responses.py`:
- Around line 1134-1137: Replace the NumPy/reST-style docstring sections in this
file (e.g., the block starting with "Parameters:" followed by "----------") with
Google-style docstrings: change "Parameters:" to "Args:", remove the underline
dashes (e.g., "----------"), keep each parameter line as "name (type):
description" indented under Args, and similarly convert any "Returns:",
"Raises:", and "Notes:" sections by removing the underlines and using the Google
headers ("Returns:", "Raises:", "Notes:") with simple indented descriptions;
update the docstrings around the shown "deleted (bool): Whether the conversation
was successfully deleted." entry and the other occurrences noted so the all
docstrings in src/models/responses.py follow Google convention.
In `@src/quota/cluster_quota_limiter.py`:
- Around line 22-30: The docstring in ClusterQuotaLimiter (in
src/quota/cluster_quota_limiter.py, e.g., the __init__ docstring) uses
NumPy/reST underlines ("----------", "-----"); remove those underline lines and
convert the sections to Google-style docstring headings (use "Args:" instead of
"Parameters:" if following Google style) and keep each parameter on one line
like "configuration (QuotaHandlersConfiguration): ..." and "initial_quota (int):
..." and convert "Notes:" to a plain "Notes:" section without underlines or to a
brief sentence in the body; ensure there are no reST underline separators
anywhere in the docstring for ClusterQuotaLimiter or its __init__.
In `@src/quota/quota_exceed_error.py`:
- Around line 16-17: The docstring for the QuotaExceedError class (or its
__init__) contains a reStructuredText-style underline ("----------") under the
"Parameters:" header; remove that underline so the docstring follows Google
Python style (leave the "Parameters:" header line but delete the following
dashed line), and ensure other docstring section headers (e.g., Returns, Raises)
use the same header-only format without underlines.
In `@src/quota/quota_limiter_factory.py`:
- Around line 23-32: The docstring in src/quota/quota_limiter_factory.py uses
NumPy/reST-style underlines under "Parameters:", "Returns:", and "Raises:" which
conflicts with our Google docstring convention; remove the dashed underlines and
reformat those sections to Google style (use "Parameters:", "Returns:",
"Raises:" as plain headings and list entries using the Google indentation/colon
format) for the docstring that documents the config parameter of type
QuotaHandlersConfiguration and the returned list[QuotaLimiter]; also apply the
same change to the other docstring block around lines 70-86 so all docstrings in
this file conform to Google style.
In `@src/quota/quota_limiter.py`:
- Around line 57-63: Replace the NumPy/reST-style docstring sections in
src/quota/quota_limiter.py (the blocks that show "Parameters:" with dashed
underlines and "Returns:" with dashed underlines, referencing subject_id) with
Google-style docstrings: use "Args:" instead of "Parameters:", list subject_id
as "subject_id (str): ..." and use "Returns:" with a single-line type and
description like "int: Number of quota units currently available for the
subject.", removing the dashed underline lines; apply the same change to the
other similar docstring block around lines 99-105.
In `@src/quota/token_usage_history.py`:
- Around line 107-116: The docstring in src/quota/token_usage_history.py uses
NumPy/Sphinx underline sections; replace them with Google-style sections by
changing "Parameters:" to "Args:" and list each parameter (user_id, provider,
model, input_tokens, output_tokens) as "- name (type): description" under a
single "Args:" header, remove the underline separators, and change the "Raises:"
block to the Google style "Raises:" header followed by indented exception
descriptions; update any other sections (e.g., Returns) in the same docstring to
match Google Python docstring conventions.
- Around line 45-46: The docstring in src/quota/token_usage_history.py currently
uses a NumPy/Sphinx-style underlined "Parameters" section; replace that with
Google-style docstrings by renaming the section to "Args:" (or "Returns:",
"Raises:" as appropriate), remove the underline, and format each parameter as
"name (type): description". Update the surrounding docstring for the
function/class that contains the existing "Parameters:" block so it follows
Google conventions consistently.
In `@src/quota/user_quota_limiter.py`:
- Around line 22-23: The docstring in src/quota/user_quota_limiter.py uses
NumPy/Sphinx underline separators under "Parameters:" and other sections; update
the docstring to Google Python style by removing the underline lines and using
Google section headers (e.g., "Args:", "Returns:", "Raises:") and formatting
parameters as "name (type): description." Apply this change to the docstring
blocks that contain "Parameters:" and the similar underlined sections (and the
other affected sections referenced in the comment) so the docstring for the
UserQuotaLimiter-related functions/classes uses Google style.
In `@src/runners/quota_scheduler.py`:
- Around line 190-194: The docstring for quota_revocation is missing the
connection parameter; update the quota_revocation function docstring to include
connection (e.g., connection: DB-API connection or specific connection type
used) under the Parameters section, describing its purpose and expected
type/usage consistent with the existing entries for quota_limiter,
increase_quota_statement, and reset_quota_statement so the docstring follows
Google Python docstring conventions and stays complete and accurate.
In `@src/runners/uvicorn.py`:
- Around line 16-17: Docstring uses NumPy/Sphinx-style section underlines
("Parameters:" with "----------"); change it to Google Python docstring style by
removing the underline and using "Args:" as the section header, then list each
parameter with 4-space indentation and a short description (e.g., Args:
configuration: Description). Update the docstring where "Parameters:" appears so
it follows Google conventions (no underlines, use "Args:", proper indentation
and parameter names).
In `@src/utils/llama_stack_version.py`:
- Around line 85-95: The docstring for the function that validates semver
(referencing parameters version_info, minimal, maximal and raising
InvalidLlamaStackVersionException) uses underlined reST/NumPy-style headers;
change them to Google-style sections (e.g., "Args:", "Raises:") and reformat the
parameter descriptions to the Google style (name (type): description) so the
docstring matches the repository's Google Python docstring convention used
elsewhere in src/.
In `@src/utils/mcp_auth_headers.py`:
- Line 18: Docstrings in src/utils/mcp_auth_headers.py (and other listed files)
use NumPy-style delimiter lines and mixed headers; update them to Google-style
by removing delimiter lines (----) and using Google section names and
punctuation: change "Parameters:" to "Args:", "Returns:" and "Raises:" as
needed, and fix any module-level, class (e.g., classes in this module), and
function docstrings (search for functions like get_auth_headers,
build_mcp_headers or similar symbols in this file) to follow Google conventions
without the delimiter lines; apply the same change across the other files
mentioned in the review.
In `@src/utils/prompts.py`:
- Around line 24-35: The docstring in src/utils/prompts.py uses NumPy-style
underlines under the section headers (Parameters:, Returns:, Raises:); update
the docstring for the function handling the per-request system_prompt to
Google-style by removing the dashed underlines and formatting each section as a
header line followed by an indented description (e.g., "Parameters:", then the
param description on the next line), ensuring the same content (system_prompt,
return value, and HTTPException note) remains intact; locate the docstring
around the function that resolves the system prompt (the code that mentions
system_prompt and HTTPException) and apply this formatting change so the file
conforms to the repository's Google-style docstring convention.
In `@src/utils/responses.py`:
- Around line 408-413: Update the NumPy-style docstrings in the listed functions
to Google-style docstrings: replace underlined section headers and separators
with "Args:", format each parameter as "name (type): description", replace
"Returns:" block to "Returns:" with "type: description" (single line or
multi-line as needed), and convert any "Raises:" sections similarly; ensure the
functions extract_vector_store_ids_from_tools, tool_matches_allowed_entry,
group_mcp_filters_by_server_label, mcp_strip_name_from_allowlist_entries,
resolve_file_search_result_index_name,
resolve_file_search_result_retrieval_location, rag_id_map_vector_store_ids,
create_file_search_rag_context, prepare_mcp_envs, and format_mcp_tool_response
have consistent Google-style docstrings and preserve the same semantic details
and types as the original NumPy docs.
In `@src/utils/shields.py`:
- Around line 43-47: The docstrings in src/utils/shields.py (and other modified
files in this PR) use NumPy/Sphinx-style underlines; update them to Google
Python docstring style: remove the dashed underlines and use "Args:" for
parameters (e.g., client), "Returns:" for return values with type and
description (e.g., list[str]: ...), and "Raises:" or "Attributes:" only when
needed; specifically revise the docstring for the function that "Discover and
return available shield identifiers" to match the Google example (Args: client:
..., Returns: list[str]: ...), and apply the same change to all other modified
docstrings in this file/PR.
In `@src/utils/suid.py`:
- Around line 29-35: Update the docstring in src/utils/suid.py to use
Google-style docstrings: remove the reStructuredText underline delimiters (the
lines of dashes), change "Parameters:" to "Args:" and "Notes:" to "Note:", and
reformat the suid parameter description to a single indented bullet under Args
(e.g., "suid (str): ..."). Ensure the rest of the docstring follows Google
conventions (Args, Returns, Raises) and keep punctuation/spacing consistent
around the suid description.
- Around line 93-102: The docstring in src/utils/suid.py uses NumPy/Sphinx
reStructuredText underlines and "Parameters:" header; update the docstring for
the function that takes conversation_id to Google style by replacing the
underlined sections with "Args:" and "Returns:" (no underline delimiters), keep
the same parameter description for conversation_id and the return description
(str: conversation ID in llama-stack format), and ensure formatting matches
Google Python docstring conventions.
In `@src/utils/tool_formatter.py`:
- Around line 20-25: The docstrings in format_tool_response and the other
indicated blocks use NumPy/Sphinx-style underlines and mixed section headers;
replace them with Google Python style: remove the underlining, use "Args:" (or
"Parameters:" per project convention) and "Returns:" as simple headers, list
parameters with indentation and descriptions, and update the docstrings for
format_tool_response plus the docstrings at the other indicated ranges (lines
70-75, 130-135, 149-155) to match the Google-style format so all sections read
like "Args:" / "Returns:" without the dashed underlines.
In `@src/utils/types.py`:
- Around line 59-66: Update the docstring to follow Google-style formatting by
removing the NumPy/reST underline markers and using plain "Parameters:" and
"Returns:" section headers with Google-style parameter and return descriptions;
specifically edit the docstring for the function that normalizes content (the
block containing "Parameters:" / "Returns:" around the description of content
and its normalized string) to list the parameter name, type, and brief
description on one line (e.g., content: Optional[Union[str, Sequence, Any]] —
value to normalize) and a "Returns:" line describing the return type and value,
ensuring no underline delimiters remain.
In `@src/utils/vector_search.py`:
- Around line 684-690: The docstring currently uses NumPy/Sphinx-style
underlines; update it to Google Python docstring style for the function in
src/utils/vector_search.py that documents parameters input_value and
inline_rag_context_text: replace the underlined "Parameters:" and "Returns:"
blocks with a single "Args:" section listing input_value (str or
list[ResponseItem]) and inline_rag_context_text (str) and a "Returns:" section
describing the return value, and remove any reStructuredText underline
formatting so the docstring conforms to Google style.
In `@tests/benchmarks/test_app_database_comparison.py`:
- Around line 29-36: Several docstrings in this test file mix Google and NumPy
styles; update each to pure Google style by replacing NumPy/reST section
underlines and "Parameters/Returns" block formatting with Google-style "Args:"
and "Returns:" sections, use inline type hints in parentheses (e.g.,
sqlite_database: Fixture, benchmark (BenchmarkFixture)), and remove the
underlined headers and extra colons/underline formatting; apply this change to
all docstrings in the file that document sqlite_database, benchmark, and other
test parameters so they consistently follow Google Python docstring conventions.
- Line 31: The docstrings incorrectly document a parameter named
"sqlite_database" while the actual function signature uses "db_fixture"; update
each test function's docstring in this file to list the real parameters:
"request (pytest.FixtureRequest): Pytest request fixture to dynamically load
fixtures", "db_fixture (str): Name of the database fixture to use
(\"sqlite_database\" or \"postgres_database\")", and "benchmark
(BenchmarkFixture): pytest-benchmark fixture", replacing any mention of
"sqlite_database" with "db_fixture" (apply the same change to all test functions
that currently reference sqlite_database).
In `@tests/e2e/features/steps/place_holder.py`:
- Around line 11-15: The docstring parameter list is out of sync with the
function signature: it documents mcp_server and header_name while the actual
function accepts context and header_value; update the docstring for the function
to list and describe the actual parameters (context and header_value), remove or
replace references to mcp_server and header_name, and ensure the parameter
descriptions match the semantics used in the function body (use "context" for
the test context object and "header_value" for the header's value).
In `@tests/e2e/utils/utils.py`:
- Around line 97-101: The docstring incorrectly states the default for the
parameter max_attempts is 3 while the function signature sets max_attempts: int
= 6; update the docstring's Parameters section to reflect the actual default of
6 (and ensure the description matches the retry behavior), and while here align
the entire docstring to Google Python docstring conventions (Parameters,
Returns, Raises) for the function that declares max_attempts: int = 6 so future
readers aren't misled.
In `@tests/integration/endpoints/test_authorized_endpoint.py`:
- Around line 23-24: The docstring in
tests/integration/endpoints/test_authorized_endpoint.py currently uses
"Parameters:" header; update it to follow Google Python docstring style by
replacing "Parameters:" with "Args:" and reformatting each parameter line to
"name (type): description". Also ensure any Returns or Raises sections use
Google headers "Returns:" and "Raises:" and match the "name (type): description"
convention for consistency across the file.
In `@tests/integration/endpoints/test_root_endpoint.py`:
- Around line 59-60: The docstring in the tests currently uses a Numpy-style
"Parameters:\n----------" header; change it to Google-style by replacing the
"Parameters:" section header with "Args:" and reformat each parameter entry to
"name (type): description" (and likewise convert any "Returns:"/"Raises:"
sections to Google-style formatting if present) so the docstring under the test
root endpoint matches Google Python docstring conventions.
In `@tests/integration/test_openapi_json.py`:
- Around line 106-113: Fix the hybrid/underlined docstrings in
tests/integration/test_openapi_json.py by converting them to pure Google-style:
remove the underline rows beneath section headers and use simple "Parameters:"
and "Raises:" headers (no underlines), ensure the parameter entry for spec
(dict) and any other params use Google formatting (name: type — description),
and update all affected docstrings (the ones mentioning Parameters and Raises
and the other listed locations) to match the project's Google-style convention
consistently.
In `@tests/unit/cache/test_cache_factory.py`:
- Around line 91-95: The docstring under the Returns: section in
tests/unit/cache/test_cache_factory.py has an underline of 7 dashes which is
shorter than the "Returns:" header; update the underline to be at least as long
as the header (change "-------" to "--------" or longer) in the docstring that
describes the ConversationHistoryConfiguration/SQLiteDatabaseConfiguration
return so the reStructuredText underline length matches the header.
- Around line 86-89: The docstring in tests/unit/cache/test_cache_factory.py
uses reST-style underlines inconsistently; update the fixture docstrings for
sqlite and the other fixtures (noop_cache_config, memory_cache_config,
postgres_cache_config, invalid_cache_type_config) to remove the underlines
beneath "Parameters:" and "Returns:" so they match the other fixtures and follow
Google-style docstrings (i.e., keep the "Parameters:" and "Returns:" headers but
delete the dashed underline lines), ensuring the tmpdir parameter description
remains unchanged.
---
Outside diff comments:
In `@src/quota/revokable_quota_limiter.py`:
- Around line 40-49: Several docstrings in src/quota/revokable_quota_limiter.py
use NumPy/reStructuredText-style underlined section headers (e.g., "Parameters:"
followed by "----------"); update them to Google-style docstrings by replacing
"Parameters:" with "Args:", removing all underline/dash lines, and similarly
remove underlines under "Returns:", "Raises:", and "Notes:" while keeping the
existing parameter/return/raise text and indentation intact; apply this change
to every docstring region called out in the review (the blocks around the
initial_quota/increase_by/subject_type docstring and the other listed ranges) so
function and class docstrings (e.g., the limiter class and its methods) conform
to Google Python docstring conventions.
In `@src/utils/quota.py`:
- Around line 30-42: Update the NumPy-style docstrings in functions
consume_tokens and check_tokens_available to follow Google Python docstring
conventions: replace the "Parameters:" header and its underline with "Args:" (no
underlines), list each parameter as "param_name (type): description" matching
the style used in get_available_quotas, and change the Returns block to a single
"Returns:" header (no underline) with a one-line description of the return
value; remove any underline delimiters (e.g., "----------", "-------") and
ensure formatting is consistent across both functions.
In `@src/utils/suid.py`:
- Around line 1-118: Update all docstrings in this module to Google style: for
functions get_suid, check_suid, normalize_conversation_id,
to_llama_stack_conversation_id, and is_moderation_id replace any "Parameters:"
sections and underlines with an "Args:" section, rename "Notes:"/ "Notes" to
"Note:", remove underline delimiters, and keep "Returns:" and "Examples:" as-is
(use Google formatting for descriptions and types inside Args/Returns). Ensure
the check_suid and to_llama_stack_conversation_id docstrings no longer use
NumPy/reST-style headings or underlines and that normalize_conversation_id
already follows the Google format consistently.
In `@tests/unit/app/test_database.py`:
- Around line 311-325: The docstring for the helper that verifies common
assertions for initialize_database tests (referenced as
verify_common_assertions) uses NumPy/reST style with an underline and
"Parameters:"; change it to Google style by removing the underline, replace the
"Parameters:" section header with "Args:", and list the parameters
(mock_sessionmaker, mock_engine, mock_session_local) using Google-style "name
(type): description" lines; keep the rest of the explanatory text but ensure the
docstring follows Google Python docstring conventions.
- Around line 278-297: The function/docstring for the setup helper used in
initialize_database tests uses NumPy/reST-style underlines and "Parameters:";
convert it to Google style by removing any section underlines, replace the
"Parameters:" header with "Args:", keep the descriptive top-line and blank line
before sections, list each argument under "Args:" with name followed by a colon
and type/description (e.g., mocker (MockerFixture): ...), and retain a
"Returns:" section in Google style (Returns: tuple[MockType, MockType]:
description) ensuring consistent punctuation and spacing; locate the docstring
around the setup helper used by the initialize_database tests (the docstring
that currently contains "Parameters:" and the underlines) and update it
accordingly.
---
Duplicate comments:
In `@src/quota/quota_exceed_error.py`:
- Around line 24-25: The docstring for the QuotaExceedError class contains a
reStructuredText-style underline ("----------") under the "Attributes:" header;
remove that underline so the docstring follows Google Python docstring style
(match how "Parameters:" was fixed). Locate the class docstring in
quota_exceed_error.py (search for QuotaExceedError) and delete the line with the
dashes so "Attributes:" stands alone with the attribute descriptions beneath it.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 35198b08-c3fb-48e3-b664-71ab9218e8f8
📒 Files selected for processing (109)
dev-tools/mcp-mock-server/test_mock_mcp_server.pysrc/app/database.pysrc/app/endpoints/feedback.pysrc/app/endpoints/query.pysrc/app/endpoints/rags.pysrc/app/endpoints/stream_interrupt.pysrc/app/endpoints/streaming_query.pysrc/app/endpoints/tools.pysrc/app/routers.pysrc/authentication/__init__.pysrc/authentication/jwk_token.pysrc/authentication/k8s.pysrc/authentication/noop.pysrc/authentication/noop_with_token.pysrc/authentication/utils.pysrc/authorization/middleware.pysrc/authorization/resolvers.pysrc/cache/cache.pysrc/cache/in_memory_cache.pysrc/cache/noop_cache.pysrc/cache/postgres_cache.pysrc/cache/sqlite_cache.pysrc/configuration.pysrc/llama_stack_configuration.pysrc/log.pysrc/models/config.pysrc/models/requests.pysrc/models/responses.pysrc/quota/cluster_quota_limiter.pysrc/quota/connect_pg.pysrc/quota/connect_sqlite.pysrc/quota/quota_exceed_error.pysrc/quota/quota_limiter.pysrc/quota/quota_limiter_factory.pysrc/quota/revokable_quota_limiter.pysrc/quota/token_usage_history.pysrc/quota/user_quota_limiter.pysrc/runners/quota_scheduler.pysrc/runners/uvicorn.pysrc/telemetry/configuration_snapshot.pysrc/utils/checks.pysrc/utils/common.pysrc/utils/connection_decorator.pysrc/utils/endpoints.pysrc/utils/llama_stack_version.pysrc/utils/mcp_auth_headers.pysrc/utils/mcp_headers.pysrc/utils/mcp_oauth_probe.pysrc/utils/prompts.pysrc/utils/query.pysrc/utils/quota.pysrc/utils/responses.pysrc/utils/schema_dumper.pysrc/utils/shields.pysrc/utils/stream_interrupts.pysrc/utils/suid.pysrc/utils/tool_formatter.pysrc/utils/transcripts.pysrc/utils/types.pysrc/utils/vector_search.pytests/benchmarks/conftest.pytests/benchmarks/data_generators.pytests/benchmarks/db_benchmarks.pytests/benchmarks/test_app_database.pytests/benchmarks/test_app_database_comparison.pytests/e2e/features/environment.pytests/e2e/features/steps/auth.pytests/e2e/features/steps/common.pytests/e2e/features/steps/common_http.pytests/e2e/features/steps/health.pytests/e2e/features/steps/place_holder.pytests/e2e/features/steps/proxy.pytests/e2e/features/steps/tls.pytests/e2e/features/steps/token_counters.pytests/e2e/mock_tls_inference_server/server.pytests/e2e/proxy/interception_proxy.pytests/e2e/utils/utils.pytests/integration/endpoints/test_authorized_endpoint.pytests/integration/endpoints/test_config_integration.pytests/integration/endpoints/test_health_integration.pytests/integration/endpoints/test_info_integration.pytests/integration/endpoints/test_model_list.pytests/integration/endpoints/test_query_byok_integration.pytests/integration/endpoints/test_query_integration.pytests/integration/endpoints/test_root_endpoint.pytests/integration/endpoints/test_streaming_query_byok_integration.pytests/integration/test_configuration.pytests/integration/test_openapi_json.pytests/integration/test_rh_identity_integration.pytests/unit/app/endpoints/test_conversations.pytests/unit/app/endpoints/test_conversations_v2.pytests/unit/app/endpoints/test_rags.pytests/unit/app/endpoints/test_shields.pytests/unit/app/test_database.pytests/unit/app/test_routers.pytests/unit/authentication/test_api_key_token.pytests/unit/authentication/test_jwk_token.pytests/unit/authentication/test_k8s.pytests/unit/authentication/test_rh_identity.pytests/unit/authorization/test_middleware.pytests/unit/authorization/test_resolvers.pytests/unit/cache/test_cache_factory.pytests/unit/cache/test_postgres_cache.pytests/unit/cache/test_sqlite_cache.pytests/unit/models/config/test_conversation_history.pytests/unit/models/config/test_customization.pytests/unit/models/config/test_dump_configuration.pytests/unit/models/config/test_postgresql_database_configuration.pytests/unit/telemetry/conftest.py
Comment on lines
+279
to
286
| ---------- | ||
| client: The AsyncLlamaStackClient to use for the request. | ||
| responses_params: The Responses API parameters. | ||
| moderation_result: The moderation result. | ||
|
|
||
| Returns: | ||
| ------- | ||
| TurnSummary: Summary of the LLM response content |
Contributor
There was a problem hiding this comment.
Docstring style inconsistency with coding guidelines.
The changes add reStructuredText/Sphinx-style section delimiters (---------- under Parameters, ------- under Returns), but the coding guidelines specify "Follow Google Python docstring conventions." Google style does not use section underlines; it uses Args: and Returns: without delimiter lines.
Consider clarifying whether the project intends to use Google style (no underlines, uses Args:) or Sphinx/reStructuredText style (underlines, uses Parameters:). As per coding guidelines: "Follow Google Python docstring conventions with Parameters, Returns, Raises, and Attributes sections as needed".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/app/endpoints/query.py` around lines 279 - 286, The docstring in the
function that accepts parameters client, responses_params, and moderation_result
and returns a TurnSummary uses Sphinx-style underlines; change it to Google
Python docstring style by removing the dashed underlines and replacing
"Parameters:" with "Args:" (listing client, responses_params, moderation_result
with their short type/description) and "Returns:" without underlines describing
the TurnSummary return value; ensure formatting matches other Google-style
docstrings in the repo (no section delimiters, use "Args:" and "Returns:").
Comment on lines
43
to
+44
| Parameters: | ||
| ---------- |
Contributor
There was a problem hiding this comment.
Docstring style mismatch with coding guidelines.
The added underline separator is NumPy/Sphinx style, not Google Python docstring conventions as required.
♻️ Align with Google Python docstring style
- Parameters:
- ----------
+ Args:
app (FastAPI): The FastAPI application to which routers will be attached.As per coding guidelines: src/**/*.py files must "Follow Google Python docstring conventions with Parameters, Returns, Raises, and Attributes sections as needed"
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Parameters: | |
| ---------- | |
| Args: | |
| app (FastAPI): The FastAPI application to which routers will be attached. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/app/routers.py` around lines 43 - 44, The docstring in src/app/routers.py
uses NumPy/Sphinx-style "Parameters:" with an underline; update it to Google
Python style by replacing the underlined "Parameters"/separator with a
Google-style "Args:" section and reformat each parameter line as "name (type):
description" (one parameter per line, no underline). Locate the docstring
containing the "Parameters:" header (e.g., in the router function or class
docstring) and ensure other sections follow Google conventions (use "Returns:"
and "Raises:" if present) so the file conforms to the project's docstring
guidelines.
Comment on lines
+35
to
41
| ---------- | ||
| auth (AuthTuple): Authentication tuple (for example, a token and | ||
| associated metadata) used to determine roles. | ||
|
|
||
| Returns: | ||
| ------- | ||
| UserRoles: A set of role names associated with the authenticated subject. |
Contributor
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
🧩 Analysis chain
🏁 Script executed:
cat -n src/authorization/resolvers.py | head -350Repository: lightspeed-core/lightspeed-stack
Length of output: 15206
🏁 Script executed:
# Verify the docstrings at the other mentioned line ranges
sed -n '80,92p' src/authorization/resolvers.py
sed -n '110,127p' src/authorization/resolvers.py
sed -n '137,159p' src/authorization/resolvers.pyRepository: lightspeed-core/lightspeed-stack
Length of output: 2080
🏁 Script executed:
# Check a correctly formatted docstring
sed -n '48,57p' src/authorization/resolvers.py
sed -n '62,73p' src/authorization/resolvers.pyRepository: lightspeed-core/lightspeed-stack
Length of output: 889
Remove underline separators from docstring section headers.
The docstrings use NumPy-style underlines (----------, -------) beneath section headers, which violates the required Google Python docstring convention. Replace with standard Google format by removing the underline separators, keeping only the section headers with colons (e.g., Parameters:, Returns:, Raises:) followed by indented content.
Affected docstrings: Lines 35-41, 85-90, 117-126, 144-150, 177-186, 220-227, 237-244, 257-263, 294-302, 329-336
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/authorization/resolvers.py` around lines 35 - 41, In
src/authorization/resolvers.py, several NumPy-style underlines under docstring
headers must be removed and converted to Google style: locate the docstrings
that reference the auth parameter (the one showing "auth (AuthTuple):
Authentication tuple...") and the other affected docstrings at the listed ranges
and delete the dashed underline lines (e.g., "----------", "-------") so each
section header is simply "Parameters:", "Returns:", "Raises:" etc. followed by
the indented content; ensure you keep the existing header text and colons and
only remove the underline separator lines across all affected docstrings.
Comment on lines
422
to
432
| Parameters: | ||
| ---------- | ||
| value: The root path value to validate. | ||
|
|
||
| Returns: | ||
| ------- | ||
| The validated root path value. | ||
|
|
||
| Raises: | ||
| ------ | ||
| ValueError: If root_path is missing a leading slash or has |
Contributor
There was a problem hiding this comment.
Docstring style conflicts with coding guidelines.
The changes add NumPy/reStructuredText-style section delimiters (----------, -------, ------) beneath Parameters:, Returns:, and Raises: headers. This conflicts with the coding guideline requiring Google Python docstring conventions for src/**/*.py files.
Google-style docstrings use Args:, Returns:, and Raises: without underline delimiters.
As per coding guidelines: "Follow Google Python docstring conventions with Parameters, Returns, Raises, and Attributes sections as needed".
Also applies to: 2004-2006
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/models/config.py` around lines 422 - 432, Replace the NumPy/reST-style
docstring sections under the function that validates root_path (the block
mentioning "Parameters:", "Returns:", "Raises:" with underline delimiters) with
Google-style docstrings: use "Args:", "Returns:", and "Raises:" headers without
the underline dashes, document the parameter "value" under Args:, keep the
return description under Returns:, and the ValueError under Raises:; apply the
same change to the other occurrences referenced (around the locations noted as
2004-2006) so all docstrings in this module follow the Google Python docstring
convention.
| Validate that a conversation identifier matches the expected SUID format. | ||
|
|
||
| Parameters: | ||
| ---------- |
Contributor
There was a problem hiding this comment.
Docstring formatting violates coding guidelines and creates inconsistency.
The added underline delimiters (----------, -------, ------) beneath section headers follow reStructuredText/NumPy style conventions, but the coding guidelines explicitly require Google Python docstring conventions, which do not use underline delimiters.
Additionally, this creates inconsistency within the file itself:
- Updated methods (lines 271, 353, 489, 511, 535, 902, 923): Now have underline delimiters
- Unchanged methods (lines 293, 310, 562, 777, etc.): Continue using section headers without underlines
Google style uses simple section headers like:
Args:
param: Description
Returns:
Description
Raises:
ExceptionType: DescriptionTo align with coding guidelines and maintain consistency, either:
- Preferred: Remove the underline delimiters from all changed methods to match existing docstrings and Google conventions
- Alternative: Update all docstrings in the file to consistently use Google style with
Args:instead ofParameters:(without underlines)
As per coding guidelines: "Follow Google Python docstring conventions with Parameters, Returns, Raises, and Attributes sections as needed"
Also applies to: 280-280, 284-284, 357-357, 361-361, 365-365, 494-494, 498-498, 502-502, 516-516, 520-520, 524-524, 546-546, 550-550, 906-906, 910-910, 914-914, 934-934, 938-938, 942-942
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/models/requests.py` at line 276, Remove the reStructuredText/NumPy-style
underline delimiters (the literal sequences like "----------", "-------",
"------") that were added under docstring section headers; update the docstrings
so the sections use plain Google-style headers such as "Parameters:",
"Returns:", and "Raises:" (with the usual indented parameter descriptions)
instead of underlined headers—search for docstrings containing "Parameters:",
"Returns:", or "Raises:" and the underline tokens and strip the underline lines
so the docstrings match the existing Google-style ones in this file.
Comment on lines
23
to
+24
| Parameters: | ||
| ---------- |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider aligning with Google Python style for consistency.
♻️ Align with Google Python docstring style
- Parameters:
- ----------
+ Args:
test_config (AppConfig): Loads root configuration
test_auth (AuthTuple): noop authentication tupleBased on learnings: "Follow Google Python docstring conventions with Parameters, Returns, Raises, and Attributes sections as needed"
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Parameters: | |
| ---------- | |
| Args: | |
| test_config (AppConfig): Loads root configuration | |
| test_auth (AuthTuple): noop authentication tuple |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/integration/endpoints/test_authorized_endpoint.py` around lines 23 -
24, The docstring in tests/integration/endpoints/test_authorized_endpoint.py
currently uses "Parameters:" header; update it to follow Google Python docstring
style by replacing "Parameters:" with "Args:" and reformatting each parameter
line to "name (type): description". Also ensure any Returns or Raises sections
use Google headers "Returns:" and "Raises:" and match the "name (type):
description" convention for consistency across the file.
Comment on lines
59
to
+60
| Parameters: | ||
| ---------- |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider aligning with Google Python style for consistency.
♻️ Align with Google Python docstring style
- Parameters:
- ----------
+ Args:
test_config (AppConfig): Loads root configuration
test_request (Request): FastAPI request
test_auth (AuthTuple): noop authentication tupleBased on learnings: "Follow Google Python docstring conventions with Parameters, Returns, Raises, and Attributes sections as needed"
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Parameters: | |
| ---------- | |
| Args: | |
| test_config (AppConfig): Loads root configuration | |
| test_request (Request): FastAPI request | |
| test_auth (AuthTuple): noop authentication tuple |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/integration/endpoints/test_root_endpoint.py` around lines 59 - 60, The
docstring in the tests currently uses a Numpy-style "Parameters:\n----------"
header; change it to Google-style by replacing the "Parameters:" section header
with "Args:" and reformat each parameter entry to "name (type): description"
(and likewise convert any "Returns:"/"Raises:" sections to Google-style
formatting if present) so the docstring under the test root endpoint matches
Google Python docstring conventions.
Comment on lines
106
to
113
| Parameters: | ||
| ---------- | ||
| spec (dict): Parsed OpenAPI specification document. | ||
|
|
||
| Raises: | ||
| ------ | ||
| AssertionError: If any required top-level field is missing or does not | ||
| match the expected value. |
Contributor
There was a problem hiding this comment.
Docstring format is inconsistent with project conventions.
The added underlines create a hybrid format that deviates from Google Python docstring conventions and doesn't comply with reStructuredText/NumPy standards either:
- Google-style (per project learning) does not use underlines beneath section headers
- If switching to reStructuredText/NumPy-style, section headers should omit colons and underlines must be at least as long as the header text:
- "Parameters:" (11 chars) requires ≥11 dashes, not 10
- "Raises:" (7 chars) requires ≥7 dashes, not 6
This hybrid format may not render correctly in Sphinx or other documentation generators.
Based on learnings: "Follow Google Python docstring conventions with Parameters, Returns, Raises, and Attributes sections as needed."
📝 Recommended fix: Use pure Google-style (per project conventions)
Parameters:
- ----------
spec (dict): Parsed OpenAPI specification document.
Raises:
- ------
AssertionError: If any required top-level field is missing or does not
match the expected value.Note: This issue applies to all docstring changes throughout this file (lines 107, 111, 133, 137, 150, 157, 179, 194, 305, 409).
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Parameters: | |
| ---------- | |
| spec (dict): Parsed OpenAPI specification document. | |
| Raises: | |
| ------ | |
| AssertionError: If any required top-level field is missing or does not | |
| match the expected value. | |
| Parameters: | |
| spec (dict): Parsed OpenAPI specification document. | |
| Raises: | |
| AssertionError: If any required top-level field is missing or does not | |
| match the expected value. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/integration/test_openapi_json.py` around lines 106 - 113, Fix the
hybrid/underlined docstrings in tests/integration/test_openapi_json.py by
converting them to pure Google-style: remove the underline rows beneath section
headers and use simple "Parameters:" and "Raises:" headers (no underlines),
ensure the parameter entry for spec (dict) and any other params use Google
formatting (name: type — description), and update all affected docstrings (the
ones mentioning Parameters and Raises and the other listed locations) to match
the project's Google-style convention consistently.
Comment on lines
86
to
89
| Parameters: | ||
| ---------- | ||
| tmpdir (Path): Temporary directory path; the SQLite file will be | ||
| created at `tmpdir / "test.sqlite"`. |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check for inconsistent docstring formatting patterns in this test file
echo "=== Fixtures with 'Returns:' sections ==="
rg -n -A 1 '^\s+Returns:' tests/unit/cache/test_cache_factory.py
echo -e "\n=== Fixtures with 'Parameters:' sections ==="
rg -n -A 1 '^\s+Parameters:' tests/unit/cache/test_cache_factory.py
echo -e "\n=== Count of underlined sections in this file ==="
rg -c '^\s+[-]+$' tests/unit/cache/test_cache_factory.py || echo "0"Repository: lightspeed-core/lightspeed-stack
Length of output: 710
Fix incorrect underline lengths and remove inconsistent formatting from docstrings.
The underlines under Parameters: and Returns: are too short and create inconsistency within the file:
Parameters:underline (10 dashes) should be 11 dashes to match the header lengthReturns:underline (7 dashes) should be 8 dashes to match the header length
However, only this fixture uses underlined section headers; the other four fixtures (noop_cache_config, memory_cache_config, postgres_cache_config, invalid_cache_type_config) omit them. Since Google Python docstring conventions do not use underlines beneath section headers, either correct the underline lengths to match reStructuredText requirements or remove the underlines entirely to align with the rest of the file.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/unit/cache/test_cache_factory.py` around lines 86 - 89, The docstring
in tests/unit/cache/test_cache_factory.py uses reST-style underlines
inconsistently; update the fixture docstrings for sqlite and the other fixtures
(noop_cache_config, memory_cache_config, postgres_cache_config,
invalid_cache_type_config) to remove the underlines beneath "Parameters:" and
"Returns:" so they match the other fixtures and follow Google-style docstrings
(i.e., keep the "Parameters:" and "Returns:" headers but delete the dashed
underline lines), ensuring the tmpdir parameter description remains unchanged.
Comment on lines
91
to
95
| Returns: | ||
| ------- | ||
| ConversationHistoryConfiguration: Configuration with `type` set to the | ||
| SQLite cache constant and `sqlite` set to a SQLiteDatabaseConfiguration | ||
| pointing to the test database path. |
Contributor
There was a problem hiding this comment.
Underline length is too short.
The underline ------- (7 dashes) is one character shorter than the section header Returns: (8 characters). According to reStructuredText conventions, underlines must be at least as long as the text they underline.
📏 Proposed fix for underline length
Returns:
- -------
+ --------
ConversationHistoryConfiguration: Configuration with `type` set to the📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Returns: | |
| ------- | |
| ConversationHistoryConfiguration: Configuration with `type` set to the | |
| SQLite cache constant and `sqlite` set to a SQLiteDatabaseConfiguration | |
| pointing to the test database path. | |
| Returns: | |
| -------- | |
| ConversationHistoryConfiguration: Configuration with `type` set to the | |
| SQLite cache constant and `sqlite` set to a SQLiteDatabaseConfiguration | |
| pointing to the test database path. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/unit/cache/test_cache_factory.py` around lines 91 - 95, The docstring
under the Returns: section in tests/unit/cache/test_cache_factory.py has an
underline of 7 dashes which is shorter than the "Returns:" header; update the
underline to be at least as long as the header (change "-------" to "--------"
or longer) in the docstring that describes the
ConversationHistoryConfiguration/SQLiteDatabaseConfiguration return so the
reStructuredText underline length matches the header.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
LCORE-1608: improve docstrings in LCORE repository
Type of change
Tools used to create PR
Related Tickets & Documents
Summary by CodeRabbit
Documentation
Chores