mirror of
https://github.com/evennia/evennia.git
synced 2026-03-19 06:16:31 +01:00
444 lines
54 KiB
HTML
444 lines
54 KiB
HTML
|
|
|||
|
|
<!DOCTYPE html>
|
|||
|
|
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8" />
|
|||
|
|
<title>Tutorial Searching For Objects — Evennia 1.0-dev documentation</title>
|
|||
|
|
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
|
|||
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|||
|
|
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
|||
|
|
<script src="_static/jquery.js"></script>
|
|||
|
|
<script src="_static/underscore.js"></script>
|
|||
|
|
<script src="_static/doctools.js"></script>
|
|||
|
|
<script src="_static/language_data.js"></script>
|
|||
|
|
<link rel="index" title="Index" href="genindex.html" />
|
|||
|
|
<link rel="search" title="Search" href="search.html" />
|
|||
|
|
|
|||
|
|
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
|
|||
|
|
|
|||
|
|
|
|||
|
|
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
|
|||
|
|
|
|||
|
|
</head><body>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="document">
|
|||
|
|
<div class="documentwrapper">
|
|||
|
|
<div class="bodywrapper">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="body" role="main">
|
|||
|
|
|
|||
|
|
<div class="section" id="tutorial-searching-for-objects">
|
|||
|
|
<h1>Tutorial Searching For Objects<a class="headerlink" href="#tutorial-searching-for-objects" title="Permalink to this headline">¶</a></h1>
|
|||
|
|
<p>You will often want to operate on a specific object in the database. For example when a player attacks a named target you’ll need to find that target so it can be attacked. Or when a rain storm draws in you need to find all outdoor-rooms so you can show it raining in them. This tutorial explains Evennia’s tools for searching.</p>
|
|||
|
|
<div class="section" id="things-to-search-for">
|
|||
|
|
<h2>Things to search for<a class="headerlink" href="#things-to-search-for" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>The first thing to consider is the base type of the thing you are searching for. Evennia organizes its database into a few main tables: <a class="reference internal" href="Objects.html"><span class="doc">Objects</span></a>, <a class="reference internal" href="Accounts.html"><span class="doc">Accounts</span></a>, <a class="reference internal" href="Scripts.html"><span class="doc">Scripts</span></a>, <a class="reference external" href="/Communications.html#channels">Channels</a>, <a class="reference external" href="Communication#Msg">Messages</a> and <a class="reference internal" href="Help-System.html"><span class="doc">Help Entries</span></a>. Most of the time you’ll likely spend your time searching for Objects and the occasional Accounts.</p>
|
|||
|
|
<p>So to find an entity, what can be searched for?</p>
|
|||
|
|
<ul class="simple">
|
|||
|
|
<li><p>The <code class="docutils literal notranslate"><span class="pre">key</span></code> is the name of the entity. While you can get this from <code class="docutils literal notranslate"><span class="pre">obj.key</span></code> the <em>database field</em> is actually named <code class="docutils literal notranslate"><span class="pre">obj.db_key</span></code> - this is useful to know only when you do <a class="reference external" href="/Tutorial-Searching-For-Objects.html#queries-in-django">direct database queries</a>. The one exception is <code class="docutils literal notranslate"><span class="pre">Accounts</span></code>, where the database field for <code class="docutils literal notranslate"><span class="pre">.key</span></code> is instead named <code class="docutils literal notranslate"><span class="pre">username</span></code> (this is a Django requirement). When you don’t specify search-type, you’ll usually search based on key. <em>Aliases</em> are extra names given to Objects using something like <code class="docutils literal notranslate"><span class="pre">@alias</span></code> or <code class="docutils literal notranslate"><span class="pre">obj.aliases.add('name')</span></code>. The main search functions (see below) will automatically search for aliases whenever you search by-key.</p></li>
|
|||
|
|
<li><p><a class="reference internal" href="Tags.html"><span class="doc">Tags</span></a> are the main way to group and identify objects in Evennia. Tags can most often be used (sometimes together with keys) to uniquely identify an object. For example, even though you have two locations with the same name, you can separate them by their tagging (this is how Evennia implements ‘zones’ seen in other systems). Tags can also have categories, to further organize your data for quick lookups.</p></li>
|
|||
|
|
<li><p>An object’s <a class="reference internal" href="Attributes.html"><span class="doc">Attributes</span></a> can also used to find an object. This can be very useful but since Attributes can store almost any data they are far less optimized to search for than Tags or keys.</p></li>
|
|||
|
|
<li><p>The object’s <a class="reference internal" href="Typeclasses.html"><span class="doc">Typeclass</span></a> indicate the sub-type of entity. A Character, Flower or Sword are all types of Objects. A Bot is a kind of Account. The database field is called <code class="docutils literal notranslate"><span class="pre">typeclass_path</span></code> and holds the full Python-path to the class. You can usually specify the <code class="docutils literal notranslate"><span class="pre">typeclass</span></code> as an argument to Evennia’s search functions as well as use the class directly to limit queries.</p></li>
|
|||
|
|
<li><p>The <code class="docutils literal notranslate"><span class="pre">location</span></code> is only relevant for <a class="reference internal" href="Objects.html"><span class="doc">Objects</span></a> but is a very common way to weed down the number of candidates before starting to search. The reason is that most in-game commands tend to operate on things nearby (in the same room) so the choices can be limited from the start.</p></li>
|
|||
|
|
<li><p>The database id or the ‘#dbref’ is unique (and never re-used) within each database table. So while there is one and only one Object with dbref <code class="docutils literal notranslate"><span class="pre">#42</span></code> there could also be an Account or Script with the dbref <code class="docutils literal notranslate"><span class="pre">#42</span></code> at the same time. In almost all search methods you can replace the “key” search criterion with <code class="docutils literal notranslate"><span class="pre">"#dbref"</span></code> to search for that id. This can occasionally be practical and may be what you are used to from other code bases. But it is considered <em>bad practice</em> in Evennia to rely on hard-coded #dbrefs to do your searches. It makes your code tied to the exact layout of the database. It’s also not very maintainable to have to remember abstract numbers. Passing the actual objects around and searching by Tags and/or keys will usually get you what you need.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="getting-objects-inside-another">
|
|||
|
|
<h2>Getting objects inside another<a class="headerlink" href="#getting-objects-inside-another" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>All in-game <a class="reference internal" href="Objects.html"><span class="doc">Objects</span></a> have a <code class="docutils literal notranslate"><span class="pre">.contents</span></code> property that returns all objects ‘inside’ them (that is, all objects which has its <code class="docutils literal notranslate"><span class="pre">.location</span></code> property set to that object. This is a simple way to get everything in a room and is also faster since this lookup is cached and won’t hit the database.</p>
|
|||
|
|
<ul class="simple">
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">roomobj.contents</span></code> returns a list of all objects inside <code class="docutils literal notranslate"><span class="pre">roomobj</span></code>.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">obj.contents</span></code> same as for a room, except this usually represents the object’s inventory</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">obj.location.contents</span></code> gets everything in <code class="docutils literal notranslate"><span class="pre">obj</span></code>’s location (including <code class="docutils literal notranslate"><span class="pre">obj</span></code> itself).</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">roomobj.exits</span></code> returns all exits starting from <code class="docutils literal notranslate"><span class="pre">roomobj</span></code> (Exits are here defined as Objects with their <code class="docutils literal notranslate"><span class="pre">destination</span></code> field set).</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">obj.location.contents_get(exclude=obj)</span></code> - this helper method returns all objects in <code class="docutils literal notranslate"><span class="pre">obj</span></code>’s location except <code class="docutils literal notranslate"><span class="pre">obj</span></code>.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="searching-using-object-search">
|
|||
|
|
<h2>Searching using <code class="docutils literal notranslate"><span class="pre">Object.search</span></code><a class="headerlink" href="#searching-using-object-search" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>Say you have a <a class="reference internal" href="Commands.html"><span class="doc">command</span></a>, and you want it to do something to a target. You might be wondering how you retrieve that target in code, and that’s where Evennia’s search utilities come in. In the most common case, you’ll often use the <code class="docutils literal notranslate"><span class="pre">search</span></code> method of the <code class="docutils literal notranslate"><span class="pre">Object</span></code> or <code class="docutils literal notranslate"><span class="pre">Account</span></code> typeclasses. In a command, the <code class="docutils literal notranslate"><span class="pre">.caller</span></code> property will refer back to the object using the command (usually a <code class="docutils literal notranslate"><span class="pre">Character</span></code>, which is a type of <code class="docutils literal notranslate"><span class="pre">Object</span></code>) while <code class="docutils literal notranslate"><span class="pre">.args</span></code> will contain Command’s arguments:</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
|
|||
|
|
2
|
|||
|
|
3
|
|||
|
|
4
|
|||
|
|
5
|
|||
|
|
6
|
|||
|
|
7
|
|||
|
|
8
|
|||
|
|
9
|
|||
|
|
10
|
|||
|
|
11
|
|||
|
|
12
|
|||
|
|
13
|
|||
|
|
14
|
|||
|
|
15
|
|||
|
|
16
|
|||
|
|
17
|
|||
|
|
18
|
|||
|
|
19
|
|||
|
|
20
|
|||
|
|
21
|
|||
|
|
22</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># e.g. in file mygame/commands/command.py</span>
|
|||
|
|
|
|||
|
|
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">default_cmds</span>
|
|||
|
|
|
|||
|
|
<span class="k">class</span> <span class="nc">CmdPoke</span><span class="p">(</span><span class="n">default_cmds</span><span class="o">.</span><span class="n">MuxCommand</span><span class="p">):</span>
|
|||
|
|
<span class="sd">"""</span>
|
|||
|
|
<span class="sd"> Pokes someone.</span>
|
|||
|
|
|
|||
|
|
<span class="sd"> Usage: poke <target></span>
|
|||
|
|
<span class="sd"> """</span>
|
|||
|
|
<span class="n">key</span> <span class="o">=</span> <span class="s2">"poke"</span>
|
|||
|
|
|
|||
|
|
<span class="k">def</span> <span class="nf">func</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
|||
|
|
<span class="sd">"""Executes poke command"""</span>
|
|||
|
|
<span class="n">target</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">)</span>
|
|||
|
|
<span class="k">if</span> <span class="ow">not</span> <span class="n">target</span><span class="p">:</span>
|
|||
|
|
<span class="c1"># we didn't find anyone, but search has already let the </span>
|
|||
|
|
<span class="c1"># caller know. We'll just return, since we're done</span>
|
|||
|
|
<span class="k">return</span>
|
|||
|
|
<span class="c1"># we found a target! we'll do stuff to them.</span>
|
|||
|
|
<span class="n">target</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">"You have been poked by </span><span class="si">%s</span><span class="s2">."</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="p">)</span>
|
|||
|
|
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">"You have poked </span><span class="si">%s</span><span class="s2">."</span> <span class="o">%</span> <span class="n">target</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>By default, the search method of a Character will attempt to find a unique object match for the string sent to it (<code class="docutils literal notranslate"><span class="pre">self.args</span></code>, in this case, which is the arguments passed to the command by the player) in the surroundings of the Character - the room or their inventory. If there is no match found, the return value (which is assigned to <code class="docutils literal notranslate"><span class="pre">target</span></code>) will be <code class="docutils literal notranslate"><span class="pre">None</span></code>, and an appropriate failure message will be sent to the Character. If there’s not a unique match, <code class="docutils literal notranslate"><span class="pre">None</span></code> will again be returned, and a different error message will be sent asking them to disambiguate the multi-match. By default, the user can then pick out a specific match using with a number and dash preceding the name of the object: <code class="docutils literal notranslate"><span class="pre">character.search("2-pink</span> <span class="pre">unicorn")</span></code> will try to find the second pink unicorn in the room.</p>
|
|||
|
|
<p>The search method has many <a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia.objects.objects#defaultcharactersearch">arguments</a> that allow you to refine the search, such as by designating the location to search in or only matching specific typeclasses.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="searching-using-utils-search">
|
|||
|
|
<h2>Searching using <code class="docutils literal notranslate"><span class="pre">utils.search</span></code><a class="headerlink" href="#searching-using-utils-search" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>Sometimes you will want to find something that isn’t tied to the search methods of a character or account. In these cases, Evennia provides a <a class="reference external" href="https://github.com/evennia/evennia/blob/master/evennia.utils.search">utility module with a number of search functions</a>. For example, suppose you want a command that will find and display all the rooms that are tagged as a ‘hangout’, for people to gather by. Here’s a simple Command to do this:</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
|
|||
|
|
2
|
|||
|
|
3
|
|||
|
|
4
|
|||
|
|
5
|
|||
|
|
6
|
|||
|
|
7
|
|||
|
|
8
|
|||
|
|
9
|
|||
|
|
10
|
|||
|
|
11
|
|||
|
|
12
|
|||
|
|
13
|
|||
|
|
14
|
|||
|
|
15</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># e.g. in file mygame/commands/command.py</span>
|
|||
|
|
|
|||
|
|
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">default_cmds</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">evennia.utils.search</span> <span class="kn">import</span> <span class="n">search_tag</span>
|
|||
|
|
|
|||
|
|
<span class="k">class</span> <span class="nc">CmdListHangouts</span><span class="p">(</span><span class="n">default_cmds</span><span class="o">.</span><span class="n">MuxCommand</span><span class="p">):</span>
|
|||
|
|
<span class="sd">"""Lists hangouts"""</span>
|
|||
|
|
<span class="n">key</span> <span class="o">=</span> <span class="s2">"hangouts"</span>
|
|||
|
|
|
|||
|
|
<span class="k">def</span> <span class="nf">func</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
|||
|
|
<span class="sd">"""Executes 'hangouts' command"""</span>
|
|||
|
|
<span class="n">hangouts</span> <span class="o">=</span> <span class="n">search_tag</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="s2">"hangout"</span><span class="p">,</span>
|
|||
|
|
<span class="n">category</span><span class="o">=</span><span class="s2">"location tags"</span><span class="p">)</span>
|
|||
|
|
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">"Hangouts available: {}"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
|
|||
|
|
<span class="s2">", "</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">ob</span><span class="p">)</span> <span class="k">for</span> <span class="n">ob</span> <span class="ow">in</span> <span class="n">hangouts</span><span class="p">)))</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>This uses the <code class="docutils literal notranslate"><span class="pre">search_tag</span></code> function to find all objects previously tagged with <a class="reference internal" href="Tags.html"><span class="doc">Tags</span></a> “hangout” and with category “location tags”.</p>
|
|||
|
|
<p>Other important search methods in <code class="docutils literal notranslate"><span class="pre">utils.search</span></code> are</p>
|
|||
|
|
<ul class="simple">
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_object</span></code></p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_account</span></code></p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_scripts</span></code></p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_channel</span></code></p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_message</span></code></p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_help</span></code></p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_tag</span></code> - find Objects with a given Tag.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_account_tag</span></code> - find Accounts with a given Tag.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_script_tag</span></code> - find Scripts with a given Tag.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_channel_tag</span></code> - find Channels with a given Tag.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_object_attribute</span></code> - find Objects with a given Attribute.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_account_attribute</span></code> - find Accounts with a given Attribute.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">search_attribute_object</span></code> - this returns the actual Attribute, not the object it sits on.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<blockquote>
|
|||
|
|
<div><p>Note: All search functions return a Django <code class="docutils literal notranslate"><span class="pre">queryset</span></code> which is technically a list-like representation of the database-query it’s about to do. Only when you convert it to a real list, loop over it or try to slice or access any of its contents will the datbase-lookup happen. This means you could yourself customize the query further if you know what you are doing (see the next section).</p>
|
|||
|
|
</div></blockquote>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="queries-in-django">
|
|||
|
|
<h2>Queries in Django<a class="headerlink" href="#queries-in-django" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p><em>This is an advanced topic.</em></p>
|
|||
|
|
<p>Evennia’s search methods should be sufficient for the vast majority of situations. But eventually you might find yourself trying to figure out how to get searches for unusual circumstances: Maybe you want to find all characters who are <em>not</em> in rooms tagged as hangouts <em>and</em> have the lycanthrope tag <em>and</em> whose names start with a vowel, but <em>not</em> with ‘Ab’, and <em>only if</em> they have 3 or more objects in their inventory … You could in principle use one of the earlier search methods to find all candidates and then loop over them with a lot of if statements in raw Python. But you can do this much more efficiently by querying the database directly.</p>
|
|||
|
|
<p>Enter <a class="reference external" href="https://docs.djangoproject.com/en/1.11/ref/models/querysets/">django’s querysets</a>. A QuerySet is the representation of a database query and can be modified as desired. Only once one tries to retrieve the data of that query is it <em>evaluated</em> and does an actual database request. This is useful because it means you can modify a query as much as you want (even pass it around) and only hit the database once you are happy with it.
|
|||
|
|
Evennia’s search functions are themselves an even higher level wrapper around Django’s queries, and many search methods return querysets. That means that you could get the result from a search function and modify the resulting query to your own ends to further tweak what you search for.</p>
|
|||
|
|
<p>Evaluated querysets can either contain objects such as Character objects, or lists of values derived from the objects. Queries usually use the ‘manager’ object of a class, which by convention is the <code class="docutils literal notranslate"><span class="pre">.objects</span></code> attribute of a class. For example, a query of Accounts that contain the letter ‘a’ could be:</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
|
|||
|
|
2
|
|||
|
|
3</pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">typeclasses.accounts</span> <span class="kn">import</span> <span class="n">Account</span>
|
|||
|
|
|
|||
|
|
<span class="n">queryset</span> <span class="o">=</span> <span class="n">Account</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">username__contains</span><span class="o">=</span><span class="s1">'a'</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">filter</span></code> method of a manager takes arguments that allow you to define the query, and you can continue to refine the query by calling additional methods until you evaluate the queryset, causing the query to be executed and return a result. For example, if you have the result above, you could, without causing the queryset to be evaluated yet, get rid of matches that contain the letter ‘e by doing this:</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">queryset</span> <span class="o">=</span> <span class="n">result</span><span class="o">.</span><span class="n">exclude</span><span class="p">(</span><span class="n">username__contains</span><span class="o">=</span><span class="s1">'e'</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<blockquote>
|
|||
|
|
<div><p>You could also have chained <code class="docutils literal notranslate"><span class="pre">.exclude</span></code> directly to the end of the previous line.</p>
|
|||
|
|
</div></blockquote>
|
|||
|
|
<p>Once you try to access the result, the queryset will be evaluated automatically under the hood:</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
|
|||
|
|
2
|
|||
|
|
3
|
|||
|
|
4
|
|||
|
|
5
|
|||
|
|
6
|
|||
|
|
7
|
|||
|
|
8</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">accounts</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">queryset</span><span class="p">)</span> <span class="c1"># this fills list with matches</span>
|
|||
|
|
|
|||
|
|
<span class="k">for</span> <span class="n">account</span> <span class="ow">in</span> <span class="n">queryset</span><span class="p">:</span>
|
|||
|
|
<span class="c1"># do something with account</span>
|
|||
|
|
|
|||
|
|
<span class="n">accounts</span> <span class="o">=</span> <span class="n">queryset</span><span class="p">[:</span><span class="mi">4</span><span class="p">]</span> <span class="c1"># get first four matches</span>
|
|||
|
|
<span class="n">account</span> <span class="o">=</span> <span class="n">queryset</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="c1"># get first match</span>
|
|||
|
|
<span class="c1"># etc</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<div class="section" id="limiting-by-typeclass">
|
|||
|
|
<h3>Limiting by typeclass<a class="headerlink" href="#limiting-by-typeclass" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>Although <code class="docutils literal notranslate"><span class="pre">Character</span></code>s, <code class="docutils literal notranslate"><span class="pre">Exit</span></code>s, <code class="docutils literal notranslate"><span class="pre">Room</span></code>s, and other children of <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code> all shares the same underlying database table, Evennia provides a shortcut to do more specific queries only for those typeclasses. For example, to find only <code class="docutils literal notranslate"><span class="pre">Character</span></code>s whose names start with ‘A’, you might do:</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">Character</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">db_key__startswith</span><span class="o">=</span><span class="s2">"A"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>If Character has a subclass <code class="docutils literal notranslate"><span class="pre">Npc</span></code> and you wanted to find only Npc’s you’d instead do</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">Npc</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">db_key__startswith</span><span class="o">=</span><span class="s2">"A"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>If you wanted to search both Characters and all its subclasses (like Npc) you use the <code class="docutils literal notranslate"><span class="pre">*_family</span></code> method which is added by Evennia:</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">Character</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter_family</span><span class="p">(</span><span class="n">db_key__startswith</span><span class="o">=</span><span class="s2">"A"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>The higher up in the inheritance hierarchy you go the more objects will be included in these searches. There is one special case, if you really want to include <em>everything</em> from a given database table. You do that by searching on the database model itself. These are named <code class="docutils literal notranslate"><span class="pre">ObjectDB</span></code>, <code class="docutils literal notranslate"><span class="pre">AccountDB</span></code>, <code class="docutils literal notranslate"><span class="pre">ScriptDB</span></code> etc.</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
|
|||
|
|
2
|
|||
|
|
3
|
|||
|
|
4</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">AccountDB</span>
|
|||
|
|
|
|||
|
|
<span class="c1"># all Accounts in the database, regardless of typeclass</span>
|
|||
|
|
<span class="nb">all</span> <span class="o">=</span> <span class="n">AccountDB</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>Here are the most commonly used methods to use with the <code class="docutils literal notranslate"><span class="pre">objects</span></code> managers:</p>
|
|||
|
|
<ul class="simple">
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">filter</span></code> - query for a listing of objects based on search criteria. Gives empty queryset if none were found.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">get</span></code> - query for a single match - raises exception if none were found, or more than one was found.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">all</span></code> - get all instances of the particular type.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">filter_family</span></code> - like <code class="docutils literal notranslate"><span class="pre">filter</span></code>, but search all sub classes as well.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">get_family</span></code> - like <code class="docutils literal notranslate"><span class="pre">get</span></code>, but search all sub classes as well.</p></li>
|
|||
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">all_family</span></code> - like <code class="docutils literal notranslate"><span class="pre">all</span></code>, but return entities of all subclasses as well.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="multiple-conditions">
|
|||
|
|
<h2>Multiple conditions<a class="headerlink" href="#multiple-conditions" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>If you pass more than one keyword argument to a query method, the query becomes an <code class="docutils literal notranslate"><span class="pre">AND</span></code> relationship. For example, if we want to find characters whose names start with “A” <em>and</em> are also werewolves (have the <code class="docutils literal notranslate"><span class="pre">lycanthrope</span></code> tag), we might do:</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">queryset</span> <span class="o">=</span> <span class="n">Character</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">db_key__startswith</span><span class="o">=</span><span class="s2">"A"</span><span class="p">,</span> <span class="n">db_tags__db_key</span><span class="o">=</span><span class="s2">"lycanthrope"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>To exclude lycanthropes currently in rooms tagged as hangouts, we might tack on an <code class="docutils literal notranslate"><span class="pre">.exclude</span></code> as before:</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">queryset</span> <span class="o">=</span> <span class="n">quersyet</span><span class="o">.</span><span class="n">exclude</span><span class="p">(</span><span class="n">db_location__db_tags__db_key</span><span class="o">=</span><span class="s2">"hangout"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>Note the syntax of the keywords in building the queryset. For example, <code class="docutils literal notranslate"><span class="pre">db_location</span></code> is the name of the database field sitting on (in this case) the <code class="docutils literal notranslate"><span class="pre">Character</span></code> (Object). Double underscore <code class="docutils literal notranslate"><span class="pre">__</span></code> works like dot-notation in normal Python (it’s used since dots are not allowed in keyword names). So the instruction <code class="docutils literal notranslate"><span class="pre">db_location__db_tags__db_key="hangout"</span></code> should be read as such:</p>
|
|||
|
|
<ol class="simple">
|
|||
|
|
<li><p>“On the <code class="docutils literal notranslate"><span class="pre">Character</span></code> object … (this comes from us building this queryset using the <code class="docutils literal notranslate"><span class="pre">Character.objects</span></code> manager)</p></li>
|
|||
|
|
<li><p>… get the value of the <code class="docutils literal notranslate"><span class="pre">db_location</span></code> field … (this references a Room object, normally)</p></li>
|
|||
|
|
<li><p>… on that location, get the value of the <code class="docutils literal notranslate"><span class="pre">db_tags</span></code> field … (this is a many-to-many field that can be treated like an object for this purpose. It references all tags on the location)</p></li>
|
|||
|
|
<li><p>… through the <code class="docutils literal notranslate"><span class="pre">db_tag</span></code> manager, find all Tags having a field <code class="docutils literal notranslate"><span class="pre">db_key</span></code> set to the value “hangout”.”</p></li>
|
|||
|
|
</ol>
|
|||
|
|
<p>This may seem a little complex at first, but this syntax will work the same for all queries. Just remember that all <em>database-fields</em> in Evennia are prefaced with <code class="docutils literal notranslate"><span class="pre">db_</span></code>. So even though Evennia is nice enough to alias the <code class="docutils literal notranslate"><span class="pre">db_key</span></code> field so you can normally just do <code class="docutils literal notranslate"><span class="pre">char.key</span></code> to get a character’s name, the database field is actually called <code class="docutils literal notranslate"><span class="pre">db_key</span></code> and the real name must be used for the purpose of building a query.</p>
|
|||
|
|
<blockquote>
|
|||
|
|
<div><p>Don’t confuse database fields with <a class="reference internal" href="Attributes.html"><span class="doc">Attributes</span></a> you set via <code class="docutils literal notranslate"><span class="pre">obj.db.attr</span> <span class="pre">=</span> <span class="pre">'foo'</span></code> or <code class="docutils literal notranslate"><span class="pre">obj.attributes.add()</span></code>. Attributes are custom database entities <em>linked</em> to an object. They are not separate fields <em>on</em> that object like <code class="docutils literal notranslate"><span class="pre">db_key</span></code> or <code class="docutils literal notranslate"><span class="pre">db_location</span></code> are. You can get attached Attributes manually through the <code class="docutils literal notranslate"><span class="pre">db_attributes</span></code> many-to-many field in the same way as <code class="docutils literal notranslate"><span class="pre">db_tags</span></code> above.</p>
|
|||
|
|
</div></blockquote>
|
|||
|
|
<div class="section" id="complex-queries">
|
|||
|
|
<h3>Complex queries<a class="headerlink" href="#complex-queries" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>What if you want to have a query with with <code class="docutils literal notranslate"><span class="pre">OR</span></code> conditions or negated requirements (<code class="docutils literal notranslate"><span class="pre">NOT</span></code>)? Enter Django’s Complex Query object, <a class="reference external" href="https://docs.djangoproject.com/en/1.11/topics/db/queries/#complex-lookups-with-q-objects">Q</a>. <code class="docutils literal notranslate"><span class="pre">Q()</span></code> objects take a normal django keyword query as its arguments. The special thing is that these Q objects can then be chained together with set operations: <code class="docutils literal notranslate"><span class="pre">|</span></code> for OR, <code class="docutils literal notranslate"><span class="pre">&</span></code> for AND, and preceded with <code class="docutils literal notranslate"><span class="pre">~</span></code> for NOT to build a combined, complex query.</p>
|
|||
|
|
<p>In our original Lycanthrope example we wanted our werewolves to have names that could start with any vowel except for the specific beginning “ab”.</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
|
|||
|
|
2
|
|||
|
|
3
|
|||
|
|
4
|
|||
|
|
5
|
|||
|
|
6
|
|||
|
|
7
|
|||
|
|
8
|
|||
|
|
9
|
|||
|
|
10</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db.models</span> <span class="kn">import</span> <span class="n">Q</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">typeclasses.characters</span> <span class="kn">import</span> <span class="n">Character</span>
|
|||
|
|
|
|||
|
|
<span class="n">query</span> <span class="o">=</span> <span class="n">Q</span><span class="p">()</span>
|
|||
|
|
<span class="k">for</span> <span class="n">letter</span> <span class="ow">in</span> <span class="p">(</span><span class="s2">"aeiouy"</span><span class="p">):</span>
|
|||
|
|
<span class="n">query</span> <span class="o">|=</span> <span class="n">Q</span><span class="p">(</span><span class="n">db_key__istartswith</span><span class="o">=</span><span class="n">letter</span><span class="p">)</span>
|
|||
|
|
<span class="n">query</span> <span class="o">&=</span> <span class="o">~</span><span class="n">Q</span><span class="p">(</span><span class="n">db_key__istartswith</span><span class="o">=</span><span class="s2">"ab"</span><span class="p">)</span>
|
|||
|
|
<span class="n">query</span> <span class="o">=</span> <span class="n">Character</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">query</span><span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="n">list_of_lycanthropes</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">query</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>In the above example, we construct our query our of several Q objects that each represent one part of the query. We iterate over the list of vowels, and add an <code class="docutils literal notranslate"><span class="pre">OR</span></code> condition to the query using <code class="docutils literal notranslate"><span class="pre">|=</span></code> (this is the same idea as using <code class="docutils literal notranslate"><span class="pre">+=</span></code> which may be more familiar). Each <code class="docutils literal notranslate"><span class="pre">OR</span></code> condition checks that the name starts with one of the valid vowels. Afterwards, we add (using <code class="docutils literal notranslate"><span class="pre">&=</span></code>) an <code class="docutils literal notranslate"><span class="pre">AND</span></code> condition that is negated with the <code class="docutils literal notranslate"><span class="pre">~</span></code> symbol. In other words we require that any match should <em>not</em> start with the string “ab”. Note that we don’t actually hit the database until we convert the query to a list at the end (we didn’t need to do that either, but could just have kept the query until we needed to do something with the matches).</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="annotations-and-f-objects">
|
|||
|
|
<h3>Annotations and <code class="docutils literal notranslate"><span class="pre">F</span></code> objects<a class="headerlink" href="#annotations-and-f-objects" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>What if we wanted to filter on some condition that isn’t represented easily by a field on the object? Maybe we want to find rooms only containing five or more objects?</p>
|
|||
|
|
<p>We <em>could</em> retrieve all interesting candidates and run them through a for-loop to get and count their <code class="docutils literal notranslate"><span class="pre">.content</span></code> properties. We’d then just return a list of only those objects with enough contents. It would look something like this (note: don’t actually do this!):</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
|
|||
|
|
2
|
|||
|
|
3
|
|||
|
|
4
|
|||
|
|
5
|
|||
|
|
6</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># probably not a good idea to do it this way</span>
|
|||
|
|
|
|||
|
|
<span class="kn">from</span> <span class="nn">typeclasses.rooms</span> <span class="kn">import</span> <span class="n">Room</span>
|
|||
|
|
|
|||
|
|
<span class="n">queryset</span> <span class="o">=</span> <span class="n">Room</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span> <span class="c1"># get all Rooms</span>
|
|||
|
|
<span class="n">rooms</span> <span class="o">=</span> <span class="p">[</span><span class="n">room</span> <span class="k">for</span> <span class="n">room</span> <span class="ow">in</span> <span class="n">queryset</span> <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">room</span><span class="o">.</span><span class="n">contents</span><span class="p">)</span> <span class="o">>=</span> <span class="mi">5</span><span class="p">]</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>Once the number of rooms in your game increases, this could become quite expensive. Additionally, in some particular contexts, like when using the web features of Evennia, you must have the result as a queryset in order to use it in operations, such as in Django’s admin interface when creating list filters.</p>
|
|||
|
|
<p>Enter <a class="reference external" href="https://docs.djangoproject.com/en/1.11/ref/models/expressions/#f-expressions">F objects</a> and <em>annotations</em>. So-called F expressions allow you to do a query that looks at a value of each object in the database, while annotations allow you to calculate and attach a value to a query. So, let’s do the same example as before directly in the database:</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
|
|||
|
|
2
|
|||
|
|
3
|
|||
|
|
4
|
|||
|
|
5
|
|||
|
|
6
|
|||
|
|
7
|
|||
|
|
8
|
|||
|
|
9
|
|||
|
|
10</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">typeclasses.rooms</span> <span class="kn">import</span> <span class="n">Room</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">django.db.models</span> <span class="kn">import</span> <span class="n">Count</span>
|
|||
|
|
|
|||
|
|
<span class="n">room_count</span> <span class="o">=</span> <span class="n">Room</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">annotate</span><span class="p">(</span><span class="n">num_objects</span><span class="o">=</span><span class="n">Count</span><span class="p">(</span><span class="s1">'locations_set'</span><span class="p">))</span>
|
|||
|
|
<span class="n">queryset</span> <span class="o">=</span> <span class="n">room_count</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">num_objects__gte</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="n">rooms</span> <span class="o">=</span> <span class="p">(</span><span class="n">Room</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">annotate</span><span class="p">(</span><span class="n">num_objects</span><span class="o">=</span><span class="n">Count</span><span class="p">(</span><span class="s1">'locations_set'</span><span class="p">))</span>
|
|||
|
|
<span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">num_objects__gte</span><span class="o">=</span><span class="mi">5</span><span class="p">))</span>
|
|||
|
|
|
|||
|
|
<span class="n">rooms</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">rooms</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>Here we first create an annotation <code class="docutils literal notranslate"><span class="pre">num_objects</span></code> of type <code class="docutils literal notranslate"><span class="pre">Count</span></code>, which is a Django class. Note that use of <code class="docutils literal notranslate"><span class="pre">location_set</span></code> in that <code class="docutils literal notranslate"><span class="pre">Count</span></code>. The <code class="docutils literal notranslate"><span class="pre">*_set</span></code> is a back-reference automatically created by Django. In this case it allows you to find all objects that <em>has the current object as location</em>. Once we have those, they are counted.
|
|||
|
|
Next we filter on this annotation, using the name <code class="docutils literal notranslate"><span class="pre">num_objects</span></code> as something we can filter for. We use <code class="docutils literal notranslate"><span class="pre">num_objects__gte=5</span></code> which means that <code class="docutils literal notranslate"><span class="pre">num_objects</span></code> should be greater than 5. This is a little harder to get one’s head around but much more efficient than lopping over all objects in Python.</p>
|
|||
|
|
<p>What if we wanted to compare two parameters against one another in a query? For example, what if instead of having 5 or more objects, we only wanted objects that had a bigger inventory than they had tags? Here an F-object comes in handy:</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
|
|||
|
|
2
|
|||
|
|
3
|
|||
|
|
4
|
|||
|
|
5
|
|||
|
|
6</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db.models</span> <span class="kn">import</span> <span class="n">Count</span><span class="p">,</span> <span class="n">F</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">typeclasses.rooms</span> <span class="kn">import</span> <span class="n">Room</span>
|
|||
|
|
|
|||
|
|
<span class="n">result</span> <span class="o">=</span> <span class="p">(</span><span class="n">Room</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">annotate</span><span class="p">(</span><span class="n">num_objects</span><span class="o">=</span><span class="n">Count</span><span class="p">(</span><span class="s1">'locations_set'</span><span class="p">),</span>
|
|||
|
|
<span class="n">num_tags</span><span class="o">=</span><span class="n">Count</span><span class="p">(</span><span class="s1">'db_tags'</span><span class="p">))</span>
|
|||
|
|
<span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">num_objects__gt</span><span class="o">=</span><span class="n">F</span><span class="p">(</span><span class="s1">'num_tags'</span><span class="p">)))</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>F-objects allows for wrapping an annotated structure on the right-hand-side of the expression. It will be evaluated on-the-fly as needed.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="grouping-by-and-values">
|
|||
|
|
<h3>Grouping By and Values<a class="headerlink" href="#grouping-by-and-values" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>Suppose you used tags to mark someone belonging an organization. Now you want to make a list and need to get the membership count of every organization all at once. That’s where annotations and the <code class="docutils literal notranslate"><span class="pre">.values_list</span></code> queryset method come in. Values/Values Lists are an alternate way of returning a queryset - instead of objects, you get a list of dicts or tuples that hold selected properties from the the matches. It also allows you a way to ‘group up’ queries for returning information. For example, to get a display about each tag per Character and the names of the tag:</p>
|
|||
|
|
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
|
|||
|
|
2
|
|||
|
|
3
|
|||
|
|
4</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">result</span> <span class="o">=</span> <span class="p">(</span><span class="n">Character</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">db_tags__db_category</span><span class="o">=</span><span class="s2">"organization"</span><span class="p">)</span>
|
|||
|
|
<span class="o">.</span><span class="n">values_list</span><span class="p">(</span><span class="s1">'db_tags__db_key'</span><span class="p">)</span>
|
|||
|
|
<span class="o">.</span><span class="n">annotate</span><span class="p">(</span><span class="n">cnt</span><span class="o">=</span><span class="n">Count</span><span class="p">(</span><span class="s1">'id'</span><span class="p">))</span>
|
|||
|
|
<span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="s1">'-cnt'</span><span class="p">))</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</td></tr></table></div>
|
|||
|
|
<p>The result queryset will be a list of tuples ordered in descending order by the number of matches, in a format like the following:</p>
|
|||
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[(</span><span class="s1">'Griatch Fanclub'</span><span class="p">,</span> <span class="mi">3872</span><span class="p">),</span> <span class="p">(</span><span class="s2">"Chainsol's Ainneve Testers"</span><span class="p">,</span> <span class="mi">2076</span><span class="p">),</span> <span class="p">(</span><span class="s2">"Blaufeuer's Whitespace Fixers"</span><span class="p">,</span> <span class="mi">1903</span><span class="p">),</span>
|
|||
|
|
<span class="p">(</span><span class="s2">"Volund's Bikeshed Design Crew"</span><span class="p">,</span> <span class="mi">1764</span><span class="p">),</span> <span class="p">(</span><span class="s2">"Tehom's Misanthropes"</span><span class="p">,</span> <span class="mi">1</span><span class="p">)]</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
|||
|
|
<div class="sphinxsidebarwrapper">
|
|||
|
|
<div id="searchbox" style="display: none" role="search">
|
|||
|
|
<h3 id="searchlabel">Quick search</h3>
|
|||
|
|
<div class="searchformwrapper">
|
|||
|
|
<form class="search" action="search.html" method="get">
|
|||
|
|
<input type="text" name="q" aria-labelledby="searchlabel" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<script>$('#searchbox').show(0);</script>
|
|||
|
|
<p><h3><a href="index.html">Table of Contents</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><a class="reference internal" href="#">Tutorial Searching For Objects</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#things-to-search-for">Things to search for</a></li>
|
|||
|
|
<li><a class="reference internal" href="#getting-objects-inside-another">Getting objects inside another</a></li>
|
|||
|
|
<li><a class="reference internal" href="#searching-using-object-search">Searching using <code class="docutils literal notranslate"><span class="pre">Object.search</span></code></a></li>
|
|||
|
|
<li><a class="reference internal" href="#searching-using-utils-search">Searching using <code class="docutils literal notranslate"><span class="pre">utils.search</span></code></a></li>
|
|||
|
|
<li><a class="reference internal" href="#queries-in-django">Queries in Django</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#limiting-by-typeclass">Limiting by typeclass</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li><a class="reference internal" href="#multiple-conditions">Multiple conditions</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#complex-queries">Complex queries</a></li>
|
|||
|
|
<li><a class="reference internal" href="#annotations-and-f-objects">Annotations and <code class="docutils literal notranslate"><span class="pre">F</span></code> objects</a></li>
|
|||
|
|
<li><a class="reference internal" href="#grouping-by-and-values">Grouping By and Values</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
<div class="relations">
|
|||
|
|
<h3>Related Topics</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><a href="index.html">Documentation overview</a><ul>
|
|||
|
|
</ul></li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div role="note" aria-label="source link">
|
|||
|
|
<!--h3>This Page</h3-->
|
|||
|
|
<ul class="this-page-menu">
|
|||
|
|
<li><a href="_sources/Tutorial-Searching-For-Objects.md.txt"
|
|||
|
|
rel="nofollow">Show Page Source</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<h3>Versions</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><a href="Tutorial-Searching-For-Objects.html">1.0-dev (develop branch)</a></li>
|
|||
|
|
<li><a href="../../versions/0.9.1/index.html">0.9.1 (master branch)</a></li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="clearer"></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="footer">
|
|||
|
|
©2020, The Evennia developer community.
|
|||
|
|
|
|||
|
|
|
|
|||
|
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
|
|||
|
|
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
|||
|
|
|
|||
|
|
|
|
|||
|
|
<a href="_sources/Tutorial-Searching-For-Objects.md.txt"
|
|||
|
|
rel="nofollow">Page source</a>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
</body>
|
|||
|
|
</html>
|