Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix type and filter docs for search #1880

Merged
merged 2 commits into from
Dec 18, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changes/1880.doc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Fix typos in search documentation.
2 changes: 0 additions & 2 deletions docs/asdf/extending/extensions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -222,8 +222,6 @@ an additional list of class names that previously identified the extension:
Making converted object's contents visible to ``info`` and ``search``
---------------------------------------------------------------------

When an object is converted to YAML, the resulting YAML tree is stored in the
braingram marked this conversation as resolved.
Show resolved Hide resolved

If the object produced by the extension supports a class method
``.__asdf_traverse__`` then it can be used by those tools to expose the contents
of the object. That method should accept no arguments and return either a
Expand Down
28 changes: 14 additions & 14 deletions docs/asdf/features.rst
Original file line number Diff line number Diff line change
Expand Up @@ -555,10 +555,10 @@ also search by type, value, or any combination thereof:
.. code:: pycon

>>> af.search("foo") # Find nodes with key containing the string 'foo' # doctest: +SKIP
>>> af.search(type=int) # Find nodes that are instances of int # doctest: +SKIP
>>> af.search(type_=int) # Find nodes that are instances of int # doctest: +SKIP
>>> af.search(value=10) # Find nodes whose value is equal to 10 # doctest: +SKIP
>>> af.search(
... "foo", type=int, value=10
... "foo", type_=int, value=10
... ) # Find the intersection of the above # doctest: +SKIP

Chaining searches
Expand All @@ -571,8 +571,8 @@ to see intermediate results before deciding how to further narrow the search.
.. code:: pycon

>>> af.search() # See an overview of the entire ASDF tree # doctest: +SKIP
>>> af.search().search(type="NDArrayType") # Find only ndarrays # doctest: +SKIP
>>> af.search().search(type="NDArrayType").search(
>>> af.search().search(type_="NDArrayType") # Find only ndarrays # doctest: +SKIP
>>> af.search().search(type_="NDArrayType").search(
... "err"
... ) # Only ndarrays with 'err' in the key # doctest: +SKIP

Expand All @@ -586,7 +586,7 @@ a child node of the current tree root:

>>> af.search()["data"] # Restrict search to the 'data' child # doctest: +SKIP
>>> af.search()["data"].search(
... type=int
... type_=int
... ) # Find integer descendants of 'data' # doctest: +SKIP

Regular expression searches
Expand All @@ -607,15 +607,15 @@ the regular expression is matched:

>>> af.search("^7$") # Returns all nodes with key '7' or index 7 # doctest: +SKIP

When the ``type`` argument is a string, the search compares against the fully-qualified
When the ``type_`` argument is a string, the search compares against the fully-qualified
class name of each node:

.. code:: pycon

>>> af.search(
... type="asdf.tags.core.Software"
... type_="asdf.tags.core.Software"
... ) # Find instances of ASDF's Software type # doctest: +SKIP
>>> af.search(type="^asdf\.") # Find all ASDF objects # doctest: +SKIP
>>> af.search(type_="^asdf\.") # Find all ASDF objects # doctest: +SKIP

When the ``value`` argument is a string, the search compares against the string
representation of each node's value.
Expand All @@ -629,15 +629,15 @@ representation of each node's value.
Arbitrary search criteria
-------------------------

If ``key``, ``type``, and ``value`` aren't sufficient, we can also provide a callback
function to search by arbitrary criteria. The ``filter`` parameter accepts
If ``key``, ``type_``, and ``value`` aren't sufficient, we can also provide a callback
function to search by arbitrary criteria. The ``filter_`` parameter accepts
a callable that receives the node under consideration, and returns ``True``
to keep it or ``False`` to reject it from the search results. For example,
to search for NDArrayType with a particular shape:

.. code:: pycon

>>> af.search(type="NDArrayType", filter=lambda n: n.shape[0] == 1024) # doctest: +SKIP
>>> af.search(type_="NDArrayType", filter_=lambda n: n.shape[0] == 1024) # doctest: +SKIP

Formatting search results
-------------------------
Expand All @@ -650,14 +650,14 @@ change those values, we call `AsdfSearchResult.format`:

.. code:: pycon

>>> af.search(type=float) # Displays limited rows # doctest: +SKIP
>>> af.search(type=float).format(max_rows=None) # Show all matching rows # doctest: +SKIP
>>> af.search(type_=float) # Displays limited rows # doctest: +SKIP
>>> af.search(type_=float).format(max_rows=None) # Show all matching rows # doctest: +SKIP

Like `AsdfSearchResult.search`, calls to format may be chained:

.. code:: pycon

>>> af.search("time").format(max_rows=10).search(type=str).format(
>>> af.search("time").format(max_rows=10).search(type_=str).format(
... max_rows=None
... ) # doctest: +SKIP

Expand Down
Loading