python-gtkmvc-doc 1.99.1-1build1 / usr / share / doc / python-gtkmvc-doc / userman / op_logical.html

This file is indexed.

/usr/share/doc/python-gtkmvc-doc/userman/op_logical.html is in python-gtkmvc-doc 1.99.1-1build1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Logical Observable Properties &mdash; Model-View-Controller and Observer patterns for PyGTK 1.99.1 documentation</title>
    
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '1.99.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="Model-View-Controller and Observer patterns for PyGTK 1.99.1 documentation" href="index.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li><a href="index.html">Model-View-Controller and Observer patterns for PyGTK 1.99.1 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="logical-observable-properties">
<h1>Logical Observable Properties<a class="headerlink" href="#logical-observable-properties" title="Permalink to this headline"></a></h1>
<p><em>Logical</em> OPs are properties whose values are not necessarily
stored in the model, but which are read and written by a pair of
getter/setter methods.</p>
<p>This make logical OPs ideal for:</p>
<ul class="simple">
<li>Values calculated out of other OPs (which can be either logical
or concrete).</li>
<li>Values living outside the model, like e.g. in a database, or in a
remote server.</li>
</ul>
<p>Logical OPs are declared like concrete OPs, but no correspoding
attributes have to appear in the class. Their name have to appear
only within the special member <tt class="docutils literal"><span class="pre">__observables__</span></tt>.
For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">gtkmvc</span> <span class="kn">import</span> <span class="n">Model</span>
<span class="c"># ----------------------------</span>
<span class="k">class</span> <span class="nc">MyModel</span> <span class="p">(</span><span class="n">Model</span><span class="p">):</span>
   <span class="n">name</span> <span class="o">=</span> <span class="s">&quot;Roberto&quot;</span>

   <span class="n">__observables__</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;name&quot;</span><span class="p">,</span> <span class="s">&quot;happiness&quot;</span><span class="p">)</span>
   <span class="k">pass</span> <span class="c"># end of class</span>
<span class="c"># ----------------------------</span>
</pre></div>
</div>
<p>In the example, <tt class="docutils literal"><span class="pre">name</span></tt> is a concrete property, whereas
<tt class="docutils literal"><span class="pre">happiness</span></tt> is a logical property, as no corresponding attribute
exists in class <tt class="docutils literal"><span class="pre">MyModel</span></tt>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Notice that names of logical OPs occurring within the
special member <tt class="docutils literal"><span class="pre">__observables__</span></tt> cannot contain wildcards like
concrete properties.</p>
<p class="last">The reasons for this limitation is obvious, as wildcards
can be used to match only class attributes.)</p>
</div>
<p>However, a logical OP&#8217;s value is taken from a getter method, and
for a read/write OP the values are stored through a setter
method. Defining a getter is mandatory, while defining a setter is
required only for writable logical OPs.</p>
<p>getter/setter methods can be defined by exploiting decorators, or
by exploiting a naming convention.</p>
<div class="section" id="use-of-decorators-for-defining-getters-and-or-setters">
<h2>Use of decorators for defining getters and/or setters<a class="headerlink" href="#use-of-decorators-for-defining-getters-and-or-setters" title="Permalink to this headline"></a></h2>
<p>Decorators <tt class="docutils literal"><span class="pre">&#64;Model.getter</span></tt> and <tt class="docutils literal"><span class="pre">&#64;Model.setter</span></tt> can be used for
defining logical OPs getter and setter respectively. The syntax and
semantics are very similar to the python <tt class="docutils literal"><span class="pre">&#64;property</span></tt>
decorator.</p>
<p>E.g. for logical OP <tt class="docutils literal"><span class="pre">happiness</span></tt> in the previous example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">gtkmvc</span> <span class="kn">import</span> <span class="n">Model</span>
<span class="c"># ----------------------------</span>
<span class="k">class</span> <span class="nc">MyModel</span> <span class="p">(</span><span class="n">Model</span><span class="p">):</span>
   <span class="n">name</span> <span class="o">=</span> <span class="s">&quot;Roberto&quot;</span>

   <span class="n">__observables__</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;name&quot;</span><span class="p">,</span> <span class="s">&quot;happiness&quot;</span><span class="p">)</span>

   <span class="n">_a_value</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="c"># support for happiness</span>
   <span class="nd">@Model.getter</span>
   <span class="k">def</span> <span class="nf">happiness</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_a_value</span>

   <span class="nd">@Model.setter</span>
   <span class="k">def</span> <span class="nf">happiness</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span> <span class="bp">self</span><span class="o">.</span><span class="n">_a_value</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="mf">1.0</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

   <span class="k">pass</span> <span class="c"># end of class</span>
<span class="c"># ----------------------------</span>
</pre></div>
</div>
<p>It is possible to define getter/setter methods which serve multiple
logical OPs.
For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">gtkmvc</span> <span class="kn">import</span> <span class="n">Model</span>
<span class="c"># ----------------------------</span>
<span class="k">class</span> <span class="nc">MyModel</span> <span class="p">(</span><span class="n">Model</span><span class="p">):</span>
   <span class="n">name</span> <span class="o">=</span> <span class="s">&quot;Roberto&quot;</span>

   <span class="n">__observables__</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;name&quot;</span><span class="p">,</span> <span class="s">&quot;happiness&quot;</span><span class="p">,</span> <span class="s">&quot;energy&quot;</span><span class="p">)</span>

   <span class="n">_a_value</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="c"># support for happiness</span>
   <span class="nd">@Model.getter</span><span class="p">(</span><span class="s">&quot;happiness&quot;</span><span class="p">,</span> <span class="s">&quot;energy&quot;</span><span class="p">)</span>
   <span class="k">def</span> <span class="nf">a_getter_for_several_ops</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
     <span class="k">if</span> <span class="s">&quot;energy&quot;</span> <span class="o">==</span> <span class="n">name</span><span class="p">:</span> <span class="k">return</span> <span class="mf">0.1</span> <span class="c"># constantly need holidays!</span>
     <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_a_value</span>

   <span class="nd">@Model.setter</span>
   <span class="k">def</span> <span class="nf">happiness</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span> <span class="bp">self</span><span class="o">.</span><span class="n">_a_value</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="mf">1.0</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

   <span class="k">pass</span> <span class="c"># end of class</span>
<span class="c"># ----------------------------</span>
</pre></div>
</div>
<p>In the example, the decorator <tt class="docutils literal"><span class="pre">&#64;Model.getter</span></tt> is used with
arguments, which have to be the string names of all properties
which have to be handled by the decorated method. The method (the
getter in this case) will receive the name of the property along
with its other arguments.</p>
<p>Use of wildcards is allowed in decorators names, and will match all
logical OPs not exactly matched by other decorators. It is an error
condition if multiple matches are found when matching logical OPs
specified with wildcards. For example this is perfectly legal:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">gtkmvc</span> <span class="kn">import</span> <span class="n">Model</span>
<span class="c"># ----------------------------</span>
<span class="k">class</span> <span class="nc">MyModel</span> <span class="p">(</span><span class="n">Model</span><span class="p">):</span>
   <span class="n">name</span> <span class="o">=</span> <span class="s">&quot;Roberto&quot;</span>

   <span class="n">__observables__</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;name&quot;</span><span class="p">,</span> <span class="s">&quot;energy&quot;</span><span class="p">,</span> <span class="s">&quot;entropy&quot;</span><span class="p">,</span> <span class="s">&quot;enology&quot;</span><span class="p">)</span>

   <span class="nd">@Model.getter</span>
   <span class="k">def</span> <span class="nf">energy</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">return</span> <span class="mf">0.1</span>  <span class="c"># constantly need holidays!</span>

   <span class="nd">@Model.getter</span><span class="p">(</span><span class="s">&quot;enology&quot;</span><span class="p">)</span>
   <span class="k">def</span> <span class="nf">getter1</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span> <span class="k">return</span> <span class="s">&quot;good science!&quot;</span>

   <span class="nd">@Model.getter</span><span class="p">(</span><span class="s">&quot;en*&quot;</span><span class="p">)</span> <span class="c"># matches only remaining &#39;entropy&#39;</span>
   <span class="k">def</span> <span class="nf">getter2</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
     <span class="k">assert</span> <span class="s">&quot;entropy&quot;</span> <span class="o">==</span> <span class="n">name</span>
     <span class="k">return</span> <span class="mi">0</span>

   <span class="nd">@Model.setter</span><span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">)</span> <span class="c"># matches &quot;energy&quot;, &quot;entropy&quot;, &quot;enology&quot;</span>
   <span class="k">def</span> <span class="nf">happiness</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
       <span class="k">print</span> <span class="s">&quot;setter for&quot;</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span>
       <span class="o">...</span>
       <span class="k">return</span>


   <span class="k">pass</span> <span class="c"># end of class</span>
<span class="c"># ----------------------------</span>
</pre></div>
</div>
<p>However, this example is not legal:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">gtkmvc</span> <span class="kn">import</span> <span class="n">Model</span>
<span class="c"># ----------------------------</span>
<span class="k">class</span> <span class="nc">MyModel</span> <span class="p">(</span><span class="n">Model</span><span class="p">):</span>

   <span class="n">__observables__</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;energy&quot;</span><span class="p">,</span> <span class="s">&quot;entropy&quot;</span><span class="p">,</span> <span class="s">&quot;enology&quot;</span><span class="p">)</span>

   <span class="nd">@Model.getter</span><span class="p">(</span><span class="s">&quot;en*&quot;</span><span class="p">)</span> <span class="c"># matches energy, entropy, and enology</span>
   <span class="k">def</span> <span class="nf">getter1</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span> <span class="o">...</span>

   <span class="nd">@Model.getter</span><span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">)</span> <span class="c"># matches energy, entropy, and enology</span>
   <span class="k">def</span> <span class="nf">getter2</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span> <span class="o">...</span>

   <span class="k">pass</span> <span class="c"># end of class</span>
<span class="c"># ----------------------------</span>
</pre></div>
</div>
<p>The example does not work as ambiguity is found when resolving
wilcards.</p>
</div>
<div class="section" id="use-of-naming-convention-for-defining-getters-and-or-setters">
<h2>Use of naming convention for defining getters and/or setters<a class="headerlink" href="#use-of-naming-convention-for-defining-getters-and-or-setters" title="Permalink to this headline"></a></h2>
<p>In some cases, the use of decorators for defining getters/setters
can be a limitation. For example, when the model is built
dynamically, like when generating proxy classes.</p>
<p>In these and other cases, the framework supports a <em>naming
convention</em> which can be used to define implicitly getters and/or
setters for logical OPs.</p>
<p>The naming convention applies to Model&#8217;s method names which are
implicitly declared as getters or setters.</p>
<ul class="simple">
<li><cite>get_&lt;prop_name&gt;_value(self)</cite>: A specific getter for OP <cite>&lt;prop_name&gt;</cite>.</li>
<li><cite>set_&lt;prop_name&gt;_value(self, value)</cite>: A specific setter for OP <cite>&lt;prop_name&gt;</cite>.</li>
<li><cite>get__value(self, name)</cite>: A generic getter receiving the name of
the property to be get.</li>
<li><cite>set__value(self, name, value)</cite>: A generic setter receiving the name of
the property to be set.</li>
</ul>
<p>As you see getters/setters can be either <em>specific</em> or
<em>generic</em>. In the former case, the getter/setter is specific for
one OP. In the latter case, getter/setter is general and will
receive the name of the property.</p>
<p>Generic getter/setter will not be called for OPs which have
specific getter/setter defined. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">gtkmvc</span> <span class="kn">import</span> <span class="n">Model</span>
<span class="c"># ----------------------------</span>
<span class="k">class</span> <span class="nc">MyModel</span> <span class="p">(</span><span class="n">Model</span><span class="p">):</span>
   <span class="n">__observables__</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;energy&quot;</span><span class="p">,</span> <span class="s">&quot;entropy&quot;</span><span class="p">,</span> <span class="s">&quot;enology&quot;</span><span class="p">)</span>

   <span class="k">def</span> <span class="nf">get_energy_value</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">return</span> <span class="mf">0.1</span>  <span class="c"># constantly need holidays!</span>

   <span class="c"># getter for entropy and enology only, as energy has a specific getter</span>
   <span class="k">def</span> <span class="nf">get__value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span> <span class="o">...</span>

   <span class="c"># setter for all properties</span>
   <span class="k">def</span> <span class="nf">set_value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span> <span class="o">...</span>

   <span class="k">pass</span> <span class="c"># end of class</span>
<span class="c"># ----------------------------</span>
</pre></div>
</div>
<p>The first example we presented for decorators could be rewritten
as:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">gtkmvc</span> <span class="kn">import</span> <span class="n">Model</span>
<span class="c"># ----------------------------</span>
<span class="k">class</span> <span class="nc">MyModel</span> <span class="p">(</span><span class="n">Model</span><span class="p">):</span>
   <span class="n">name</span> <span class="o">=</span> <span class="s">&quot;Roberto&quot;</span>

   <span class="n">__observables__</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;name&quot;</span><span class="p">,</span> <span class="s">&quot;energy&quot;</span><span class="p">,</span> <span class="s">&quot;entropy&quot;</span><span class="p">,</span> <span class="s">&quot;enology&quot;</span><span class="p">)</span>

   <span class="k">def</span> <span class="nf">get_energy_value</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">return</span> <span class="mf">0.1</span>  <span class="c"># constantly need holidays!</span>

   <span class="k">def</span> <span class="nf">get_enology_value</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">return</span> <span class="s">&quot;good science!&quot;</span>

   <span class="k">def</span> <span class="nf">get__value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
     <span class="k">assert</span> <span class="s">&quot;entropy&quot;</span> <span class="o">==</span> <span class="n">name</span>
     <span class="k">return</span> <span class="mi">0</span>

   <span class="k">def</span> <span class="nf">set__value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
       <span class="k">print</span> <span class="s">&quot;setter for&quot;</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span>
       <span class="o">...</span>
       <span class="k">return</span>

   <span class="k">pass</span> <span class="c"># end of class</span>
<span class="c"># ----------------------------</span>
</pre></div>
</div>
<p>Of course, since in naming conventions names <em>matters</em>, some names
in the example had to be adapted.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Logical Observable Properties</a><ul>
<li><a class="reference internal" href="#use-of-decorators-for-defining-getters-and-or-setters">Use of decorators for defining getters and/or setters</a></li>
<li><a class="reference internal" href="#use-of-naming-convention-for-defining-getters-and-or-setters">Use of naming convention for defining getters and/or setters</a></li>
</ul>
</li>
</ul>

  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/op_logical.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li><a href="index.html">Model-View-Controller and Observer patterns for PyGTK 1.99.1 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2010, Roberto Cavada.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
    </div>
  </body>
</html>

APT Browse - Built by Thomas Orozco.