docs: add Raises sections to client docstrings (fixes #348)

[Muhammad-Danyal353]

Summary

This PR adds explicit Raises sections to public client docstrings to improve API error discoverability and align documentation with actual runtime behavior.

Scope of updates:

• Added Raises documentation in sync client methods.
• Added matching Raises documentation in async client methods.
• Documented explicit ValueError, NotImplementedError, and AssertionError cases where applicable.

Why

Issue #348 requests documenting exceptions in docstrings. This change makes expected failures clearer for users and improves IDE/help output quality.

Validation

• Ran local validation with Docker-backed integration setup.
• Most tests passed in this environment.

Checklist

All Submissions:

• Contributions should target the dev branch. Did you create your branch from dev?
• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?

New Feature Submissions:

1. Does your submission pass tests?
2. Have you installed pre-commit with pip3 install pre-commit and set up hooks with pre-commit install?

Changes to Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable? (Not applicable, docstring-only change)
• Have you successfully ran tests with your changes locally?

[netlify]

✅ Deploy Preview for poetic-froyo-8baba7 ready!

Name	Link
🔨 Latest commit	6e6500f
🔍 Latest deploy log	https://app.netlify.com/projects/poetic-froyo-8baba7/deploys/69cc1ba85e04f90008b470f8
😎 Deploy Preview	https://deploy-preview-1185--poetic-froyo-8baba7.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

This PR updates the public sync and async Qdrant client docstrings to explicitly document exceptions that can be raised at runtime, improving API error discoverability (fixes #348).

Changes:

• Added Raises: sections to client constructors and gRPC/REST accessors to document ValueError / NotImplementedError.
• Added Raises: sections to many public client methods to document the current “unknown **kwargs” failure behavior.
• Documented additional ValueError cases for specific methods (e.g., update_collection, migrate).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
qdrant_client/qdrant_client.py	Adds Raises: sections across the sync client’s public surface area (constructor, accessors, and many methods).
qdrant_client/async_qdrant_client.py	Mirrors the same Raises: documentation updates for the async client methods and accessors.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 55462b74-b09e-4661-8c91-80a217e350be

📥 Commits

Reviewing files that changed from the base of the PR and between 75b1efc and 6e6500f.

📒 Files selected for processing (2)

• qdrant_client/async_qdrant_client.py
• qdrant_client/qdrant_client.py

🚧 Files skipped from review as they are similar to previous changes (2)

• qdrant_client/async_qdrant_client.py
• qdrant_client/qdrant_client.py

---

📝 Walkthrough

Walkthrough

The pull request expands Raises: documentation across qdrant_client/async_qdrant_client.py and qdrant_client/qdrant_client.py, documenting error conditions for constructor arguments (mutually exclusive init args and cloud inference vs local mode), protocol-property access (NotImplementedError for unsupported modes), unexpected **kwargs in many endpoint methods (AssertionError), and validation conflicts in update_collection and migrate (ValueError). One behavioral change: query_batch_points replaces an assert len(kwargs) == 0 with an explicit runtime check that raises TypeError when unknown keyword arguments are provided. No function signatures were changed.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• tbung

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding Raises sections to client docstrings, with a reference to the resolved issue.
Description check	✅ Passed	The description is directly related to the changeset, explaining the purpose of adding Raises documentation, scope of updates, and validation approach.
Docstring Coverage	✅ Passed	Docstring coverage is 95.88% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

qdrant_client/qdrant_client.py (1)

263-265: Replace assert validation with explicit exception for public API kwargs.

The assertion at line 266 (assert len(kwargs) == 0) can be silently disabled when Python runs with optimizations (python -O), breaking the documented AssertionError contract. Use explicit validation instead: if kwargs: raise TypeError(f"Unknown arguments: {list(kwargs.keys())}") and update the docstring accordingly.

This pattern appears in 46 methods across the file and should be refactored consistently.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@qdrant_client/qdrant_client.py` around lines 263 - 265, Several public API
methods (e.g., functions that currently use assert len(kwargs) == 0) must
replace the assert with explicit validation to avoid being bypassed under python
-O; locate each occurrence (about 46 methods in qdrant_client.py) and change the
pattern to: if kwargs: raise TypeError(f"Unknown arguments:
{list(kwargs.keys())}"), and update the corresponding docstring Raises: section
to reflect TypeError instead of AssertionError; ensure you update all functions
using assert len(kwargs) == 0 (search for that exact expression) and keep
behavior and message consistent across methods.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@qdrant_client/qdrant_client.py`:
- Around line 263-265: Several public API methods (e.g., functions that
currently use assert len(kwargs) == 0) must replace the assert with explicit
validation to avoid being bypassed under python -O; locate each occurrence
(about 46 methods in qdrant_client.py) and change the pattern to: if kwargs:
raise TypeError(f"Unknown arguments: {list(kwargs.keys())}"), and update the
corresponding docstring Raises: section to reflect TypeError instead of
AssertionError; ensure you update all functions using assert len(kwargs) == 0
(search for that exact expression) and keep behavior and message consistent
across methods.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9e8102e4-c562-4b33-8423-553463b1f50f

📥 Commits

Reviewing files that changed from the base of the PR and between df76e0b and 75b1efc.

📒 Files selected for processing (2)

• qdrant_client/async_qdrant_client.py
• qdrant_client/qdrant_client.py