From 0523264aae349f359519a380d638b74d4fe45150 Mon Sep 17 00:00:00 2001 From: Griatch Date: Fri, 14 Jul 2023 14:07:15 +0200 Subject: [PATCH] Clarify in searching-things tutorial. Resolve #3212 --- .../Beginner-Tutorial-Searching-Things.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Searching-Things.md b/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Searching-Things.md index 622be9127b..4b44cae06c 100644 --- a/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Searching-Things.md +++ b/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Searching-Things.md @@ -1,7 +1,6 @@ # Searching for things -We have gone through how to create the various entities in Evennia. But creating something is of little use -if we cannot find and use it afterwards. +We have gone through how to create the various entities in Evennia. But creating something is of little use if we cannot find and use it afterwards. ## Main search functions @@ -10,8 +9,8 @@ The base tools are the `evennia.search_*` functions, such as `evennia.search_obj ```python import evennia -roses = evennia.search_object(key="rose") -accts = evennia.search_account(key="MyAccountName", email="foo@bar.com") +roses = evennia.search_object("rose") +accts = evennia.search_account("MyAccountName", email="foo@bar.com") ``` ```{sidebar} Querysets @@ -19,14 +18,14 @@ accts = evennia.search_account(key="MyAccountName", email="foo@bar.com") What is returned from the main search functions is actually a `queryset`. They can be treated like lists except that they can't modified in-place. We'll discuss querysets in the `next lesson` `_. ``` -Strings are always case-insensitive, so searching for `"rose"`, `"Rose"` or `"rOsE"` give the same results. It's important to remember that what is returned from these search methods is a _listing_ of zero, one or more elements - all the matches to your search. To get the first match: +This searches by `key` of the object. Strings are always case-insensitive, so searching for `"rose"`, `"Rose"` or `"rOsE"` give the same results. It's important to remember that what is returned from these search methods is a _listing_ of zero, one or more elements - all the matches to your search. To get the first match: rose = roses[0] Often you really want all matches to the search parameters you specify. In other situations, having zero or more than one match is a sign of a problem and you need to handle this case yourself. ```python - the_one_ring = evennia.search_object(key="The one Ring") + the_one_ring = evennia.search_object("The one Ring") if not the_one_ring: # handle not finding the ring at all elif len(the_one_ring) > 1: @@ -43,13 +42,14 @@ There are equivalent search functions for all the main resources. You can find a On the `DefaultObject` is a `.search` method which we have already tried out when we made Commands. For this to be used you must already have an object available: + obj = evennia.search_object("My Object")[0] # assuming this exists rose = obj.search("rose") This searches for objects based on `key` or aliases. The `.search` method wraps `evennia.search_object` and handles its output in various ways. - By default it will always search for objects among those in `obj.location.contents` and `obj.contents` (that is, things in obj's inventory or in the same room). -- It will always return exactly one match. If it found zero or more than one match, the return is `None`. -- On a no-match or multimatch, `.search` will automatically send an error message to `obj`. +- It will always return exactly one match. If it found zero or more than one match, the return is `None`. This is different from `evennia.search`, which always returns a list. +- On a no-match or multimatch, `.search` will automatically send an error message to `obj`. So you don't have to worry about reporting messages if the result is `None`. So this method handles error messaging for you. A very common way to use it is in commands: @@ -76,7 +76,7 @@ class CmdQuickFind(Command): ``` Remember, `self.caller` is the one calling the command. This is usually a Character, which -inherits from `DefaultObject`! +inherits from `DefaultObject`. So it has `.search()` available on it. This simple little Command takes its arguments and searches for a match. If it can't find it, `result` will be `None`. The error has already been reported to `self.caller` so we just abort with `return`.