Python docstrings (Google style)

Mission

When editing or creating Python code, write high-quality Google-style docstrings for:

•Modules (top-of-file docstring)
•Public classes
•Public functions
•Public methods and properties

Docstrings must render well in mkdocs + mkdocs-material + mkdocstrings.

Trigger conditions

Use this skill when you:

•Add or modify a public module/class/function/method/property
•See missing, vague, outdated, or inconsistent docstrings
•Prepare code for API docs (mkdocstrings pages)
•Introduce non-obvious behavior, edge cases, or side effects

Definitions (for this repo)

•Public API: no leading underscore (e.g., fetch_prices, Client.get). Private/internal objects (leading underscore) are optional unless behavior is non-obvious.
•Type hints are the source of truth: do not repeat types in docstrings when type hints exist.

Authoring workflow

•Identify public objects changed/created.
•
For each object, draft:
- •A one-line summary (what it does)
- •What matters to callers: constraints, invariants, side effects
•Add only the sections that apply (e.g., include Raises: only when callers should care).
•Add at least one runnable Examples: snippet for every public callable.
•Read it like a user: “Can I use this without opening the source?”

Output requirements

For every public object, add/upgrade a docstring that:

•Follows Google style
•Is clear, concrete, and non-marketing
•Does not repeat type hints
•Includes runnable Examples: for every public callable

Google docstring structure (standard)

Include sections only when meaningful:

•Short summary (1 line)
•Optional extended summary (1–3 short paragraphs)
•Args:
•Returns:
•Raises:
•Attributes: (classes, when useful)
•Methods: (classes, when useful)
•Examples:

Extended docstring structure

As we are using mkdocstrings, we can leverage richer formatting:

•Use admonitions for important notes, warnings, tips
•Use content tabs for alternative examples (e.g., sync vs. async)

"""Fetch historical stock prices for a given ticker symbol.

Abstract: Component Summary
  This function retrieves historical stock price data from a third-party API
  for the specified ticker symbol over a defined time period. It returns the data
  as a pandas DataFrame for easy analysis.

Args:
  ticker: Stock ticker symbol (e.g., "AAPL").
  period: Time period to fetch. Defaults to "1y".

Returns:
  A DataFrame containing historical stock prices.

Note: Requires an active internet connection.
  The data is fetched from a third-party API. Ensure you handle network errors appropriately.

Tip: API calls limits
  Free tier allows up to 500 requests per day. Consider caching results to avoid hitting limits.

Question: FAQ
  Q: **What time zones are the timestamps in?**
  A: All timestamps are in UTC.

  Q: **Can I fetch intraday data?**
  A: Yes, set the `period` argument to "1d" or "5

Example:
  === "Basic usage"
      ```py
      from finance import fetch_prices

      df = fetch_prices("AAPL", period="6mo")
      print(df.head())
      ```
  === "Async usage"
      ```py
      import asyncio
      from finance import fetch_prices_async  

      async def main():
          df = await fetch_prices_async("AAPL", period="6mo")
          print(df.head())
      asyncio.run(main())
      ```
"""

Formatting rules

•Use triple double quotes: """Docstring..."""
•Summary line ends with a period.
•Wrap lines roughly ~88–100 chars when reasonable (don’t force ugly wrapping).
•Prefer imperative/active voice (“Fetch prices…”, “Validate payload…”).
•Examples must be copy-pastable (no pseudocode).

Markdown in docstrings (mkdocstrings-friendly)

•Prefer fenced code blocks with language identifiers in Examples: (e.g., ```py).
•You may use mkdocs-material admonitions and content tabs where they add clarity.
•Avoid nesting admonitions inside each other.
•Keep function/method docstrings simple; put richer narrative/context in module/class docstrings.

Content rules

1) Keep it user-facing

Explain what it does, what matters, and any side effects (I/O, network, mutation, caching).

2) Don’t repeat types in docstrings

Describe meaning, not types. The user will see type hints.

✅ Do

Args:
  ticker: Stock ticker symbol (e.g., "AAPL").
  period: Time period to fetch. Defaults to "1y".

Returns:
  A DataFrame containing historical stock prices.

❌ Don’t

Args:
  ticker (str): ...
  period (str, optional): ...

Returns:
  pd.DataFrame: ...

Object-specific rules

Module docstrings

Every module should start with a module docstring that answers:

•What the module provides/contains/implements
•Typical usage
•Important constraints (timezone assumptions, caching, side effects)

Class docstrings

Class docstrings should describe:

•What the class represents/does/implements
•Lifecycle/ownership (resources, caches)
•Key invariants
•Constructor expectations (especially if non-obvious)

If the class is primarily a data container, document fields in Attributes:. Otherwise, document the public attributes that matter to callers.

Method/property docstrings

•For obvious getters/setters, keep it brief but still include an example (even a tiny one).
•Mention side effects (writes to disk, network calls, mutates internal state).
•In Raises:, document meaningful error conditions (don’t list every low-level exception).

`Examples:` rules (important)

Every public callable must have Examples: with at least one runnable example.

Examples should:

•Use realistic values ("AAPL", "1d", etc.)
•Show the most common happy path first
•Avoid network calls in examples unless the module is literally a client library
•Prefer tiny examples that won’t rot quickly
•Don’t use >>> prompts; use standard script-style code blocks so users can copy-paste directly.

If a function is async, example must use asyncio.run(...).

Quality checklist (must pass)

• Module has a top-quality docstring following software engineering best practices
• Every public function/class/method/property has a docstring
• Every public callable has Examples: with runnable code
• Args/Attributes describe meaning but no types
• Returns describes meaning (and shape if non-obvious)
• Raises lists meaningful exceptions + when they occur
• No fluff; no internal implementation narration unless it affects use