Skip to content

docs: explain string paths in get_in - #642

Open
guhou-hvi wants to merge 1 commit into
pytoolz:masterfrom
guhou-hvi:docs/get-in-string-path
Open

guhou-hvi wants to merge 1 commit into
pytoolz:masterfrom
guhou-hvi:docs/get-in-string-path

Conversation

@guhou-hvi

Copy link
Copy Markdown

Addresses #548.

get_in treats its first argument as a sequence of successive keys. A caller
may try get_in('x', {'x': 5}), see it work, and expect a longer string to name
one key too. Instead, get_in('name', {'name': 'Alice'}) returns the default,
and a string like 'xy' can silently select data['x']['y'] instead of
data['xy'].

Explain this in the function's API documentation and show both outcomes next
to the single-key list spelling. The examples use explicit return values,
including a dictionary where the nested path and whole string key differ.
They execute with the project's existing doctest command. This is documentation
of the current behavior; the function body and public API are unchanged.

Validation: the existing pytest/doctest entry reports 268 passed and 2 skipped,
the benchmark suite reports 19 passed, and pycodestyle and strict HTML building
pass. Five new doctest steps live within the existing function's doctest item;
they do not add five pytest items. Independent review checked both direct and
curried usage and confirmed that only the docstring changes.

Codex drafted and tested the documentation; a separate Codex agent reviewed it.
I have reviewed and understand the changes.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant