1
0
mirror of https://github.com/dkmstr/openuds.git synced 2025-10-15 19:35:45 +03:00
Files
openuds/server/documentation/_build/html/development/samples/services/Provider.html
Adolfo Gómez García ab5f51a3b1 * Fixed several bad formed literal strings
* Updated translations
2015-02-02 11:31:59 +01:00

523 lines
26 KiB
HTML

<!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>Sample Service Provider &mdash; UDS 1.0 documentation</title>
<link rel="stylesheet" href="../../../_static/sphinxdoc.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.0',
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>
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="top" title="UDS 1.0 documentation" href="../../../index.html" />
<link rel="up" title="UDS Modules Samples" href="../samples.html" />
<link rel="next" title="Sample service" href="Service.html" />
<link rel="prev" title="Needs for a service package" href="whatisneeded.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 class="right" >
<a href="../../../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Service.html" title="Sample service"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="whatisneeded.html" title="Needs for a service package"
accesskey="P">previous</a> |</li>
<li><a href="../../../index.html">UDS 1.0 documentation</a> &raquo;</li>
<li><a href="../../../api/index.html" >UDS&#8217;s core API</a> &raquo;</li>
<li><a href="../samples.html" accesskey="U">UDS Modules Samples</a> &raquo;</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="whatisneeded.html"
title="previous chapter">Needs for a service package</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Service.html"
title="next chapter">Sample service</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../../_sources/development/samples/services/Provider.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="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="sample-service-provider">
<h1>Sample Service Provider<a class="headerlink" href="#sample-service-provider" title="Permalink to this headline"></a></h1>
<p>The service provider is the top of the tree of services needed clases.
It main function is to provide a base for services, where this services contains
a common parent that is, for example, a server, a range of IPs, etc...</p>
<p>This sample covers a simple service provider, explains also a bit about FormFields
and shows what tasks must be done by a service provider.</p>
<p>You can easily follow the code to see what it does, and what you have to do if you
want to provide a new one.</p>
<p><a class="reference download internal" href="../../../_downloads/SampleProvider.py"><tt class="xref download docutils literal"><span class="pre">Download</span> <span class="pre">sample</span></tt></a></p>
<div class="highlight-python"><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
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</pre></div></td><td class="code"><div class="highlight"><pre><span class="c"># -*- coding: utf-8 -*-</span>
<span class="c">#</span>
<span class="c"># Copyright (c) 2012 Virtual Cable S.L.</span>
<span class="c"># All rights reserved.</span>
<span class="c">#</span>
<span class="c"># Redistribution and use in source and binary forms, with or without modification, </span>
<span class="c"># are permitted provided that the following conditions are met:</span>
<span class="c">#</span>
<span class="c"># * Redistributions of source code must retain the above copyright notice, </span>
<span class="c"># this list of conditions and the following disclaimer.</span>
<span class="c"># * Redistributions in binary form must reproduce the above copyright notice, </span>
<span class="c"># this list of conditions and the following disclaimer in the documentation </span>
<span class="c"># and/or other materials provided with the distribution.</span>
<span class="c"># * Neither the name of Virtual Cable S.L. nor the names of its contributors </span>
<span class="c"># may be used to endorse or promote products derived from this software </span>
<span class="c"># without specific prior written permission.</span>
<span class="c">#</span>
<span class="c"># THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS &quot;AS IS&quot; </span>
<span class="c"># AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE </span>
<span class="c"># IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE </span>
<span class="c"># DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE </span>
<span class="c"># FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL</span>
<span class="c"># DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR </span>
<span class="c"># SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER </span>
<span class="c"># CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, </span>
<span class="c"># OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE </span>
<span class="c"># OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</span>
<span class="sd">&#39;&#39;&#39;</span>
<span class="sd">Created on Jun 22, 2012</span>
<span class="sd">.. moduleauthor:: Adolfo Gómez, dkmaster at dkmon dot com</span>
<span class="sd">&#39;&#39;&#39;</span>
<span class="kn">from</span> <span class="nn">django.utils.translation</span> <span class="kn">import</span> <span class="n">ugettext_noop</span> <span class="k">as</span> <span class="n">translatable</span><span class="p">,</span> <span class="n">ugettext</span> <span class="k">as</span> <span class="n">_</span>
<span class="kn">from</span> <span class="nn">uds.core.services</span> <span class="kn">import</span> <span class="n">ServiceProvider</span>
<span class="kn">from</span> <span class="nn">SampleService</span> <span class="kn">import</span> <span class="n">ServiceOne</span><span class="p">,</span> <span class="n">ServiceTwo</span>
<span class="kn">from</span> <span class="nn">uds.core.ui</span> <span class="kn">import</span> <span class="n">gui</span>
<span class="kn">import</span> <span class="nn">logging</span>
<span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="n">__name__</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Provider</span><span class="p">(</span><span class="n">ServiceProvider</span><span class="p">):</span>
<span class="sd">&#39;&#39;&#39;</span>
<span class="sd"> This class represents the sample services provider</span>
<span class="sd"> </span>
<span class="sd"> In this class we provide:</span>
<span class="sd"> * The Provider functionality</span>
<span class="sd"> * The basic configuration parameters for the provider</span>
<span class="sd"> * The form fields needed by administrators to configure this provider</span>
<span class="sd"> </span>
<span class="sd"> :note: At class level, the translation must be simply marked as so</span>
<span class="sd"> using ugettext_noop. This is so cause we will translate the string when</span>
<span class="sd"> sent to the administration client.</span>
<span class="sd"> </span>
<span class="sd"> For this class to get visible at administration client as a provider type,</span>
<span class="sd"> we MUST register it at package __init__.</span>
<span class="sd"> </span>
<span class="sd"> &#39;&#39;&#39;</span>
<span class="c">#: What kind of services we offer, this are classes inherited from Service</span>
<span class="n">offers</span> <span class="o">=</span> <span class="p">[</span><span class="n">ServiceOne</span><span class="p">,</span> <span class="n">ServiceTwo</span><span class="p">]</span>
<span class="c">#: Name to show the administrator. This string will be translated BEFORE</span>
<span class="c">#: sending it to administration interface, so don&#39;t forget to</span>
<span class="c">#: mark it as translatable (using ugettext_noop)</span>
<span class="n">typeName</span> <span class="o">=</span> <span class="n">translatable</span><span class="p">(</span><span class="s">&#39;Sample Provider&#39;</span><span class="p">)</span>
<span class="c">#: Type used internally to identify this provider</span>
<span class="n">typeType</span> <span class="o">=</span> <span class="s">&#39;SampleProvider&#39;</span>
<span class="c">#: Description shown at administration interface for this provider</span>
<span class="n">typeDescription</span> <span class="o">=</span> <span class="n">translatable</span><span class="p">(</span><span class="s">&#39;Sample (and dummy) service provider&#39;</span><span class="p">)</span>
<span class="c">#: Icon file used as icon for this provider. This string will be translated </span>
<span class="c">#: BEFORE sending it to administration interface, so don&#39;t forget to</span>
<span class="c">#: mark it as translatable (using ugettext_noop)</span>
<span class="n">iconFile</span> <span class="o">=</span> <span class="s">&#39;provider.png&#39;</span>
<span class="c"># now comes the form fields</span>
<span class="c"># There is always two fields that are requested to the admin, that are:</span>
<span class="c"># Service Name, that is a name that the admin uses to name this provider</span>
<span class="c"># Description, that is a short description that the admin gives to this provider</span>
<span class="c"># Now we are going to add a few fields that we need to use this provider</span>
<span class="c"># Remember that these are &quot;dummy&quot; fields, that in fact are not required</span>
<span class="c"># but used for sample purposes</span>
<span class="c"># If we don&#39;t indicate an order, the output order of fields will be</span>
<span class="c"># &quot;random&quot;</span>
<span class="c">#: Remote host. Here core will translate label and tooltip, remember to</span>
<span class="c">#: mark them as translatable using ugettext_noop.</span>
<span class="n">remoteHost</span> <span class="o">=</span> <span class="n">gui</span><span class="o">.</span><span class="n">TextField</span><span class="p">(</span><span class="n">oder</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>
<span class="n">length</span> <span class="o">=</span> <span class="mi">64</span><span class="p">,</span>
<span class="n">label</span> <span class="o">=</span> <span class="n">translatable</span><span class="p">(</span><span class="s">&#39;Remote host&#39;</span><span class="p">),</span>
<span class="n">tooltip</span> <span class="o">=</span> <span class="n">translatable</span><span class="p">(</span><span class="s">&#39;This fields contains a remote host&#39;</span><span class="p">),</span>
<span class="n">required</span> <span class="o">=</span> <span class="bp">True</span><span class="p">,</span>
<span class="p">)</span>
<span class="c">#: Name of your pet (sample, not really needed :-) )</span>
<span class="n">petName</span> <span class="o">=</span> <span class="n">gui</span><span class="o">.</span><span class="n">TextField</span><span class="p">(</span><span class="n">order</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span>
<span class="n">length</span> <span class="o">=</span> <span class="mi">32</span><span class="p">,</span>
<span class="n">label</span> <span class="o">=</span> <span class="n">translatable</span><span class="p">(</span><span class="s">&#39;Your pet</span><span class="se">\&#39;</span><span class="s">s name&#39;</span><span class="p">),</span>
<span class="n">tooltip</span> <span class="o">=</span> <span class="n">translatable</span><span class="p">(</span><span class="s">&#39;If you like, write the name of your pet&#39;</span><span class="p">),</span>
<span class="n">requred</span> <span class="o">=</span> <span class="bp">False</span><span class="p">,</span>
<span class="n">defvalue</span> <span class="o">=</span> <span class="s">&#39;Tux&#39;</span> <span class="c">#: This will not get translated</span>
<span class="p">)</span>
<span class="c">#: Age of Methuselah (matusalén in spanish)</span>
<span class="c">#: in Spain there is a well-known to say that something is very old, </span>
<span class="c">#: &quot;Tiene mas años que matusalén&quot;(is older than Methuselah)</span>
<span class="n">methAge</span> <span class="o">=</span> <span class="n">gui</span><span class="o">.</span><span class="n">NumericField</span><span class="p">(</span><span class="n">order</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span>
<span class="n">length</span> <span class="o">=</span> <span class="mi">4</span><span class="p">,</span> <span class="c"># That is, max allowed value is 9999 </span>
<span class="n">label</span> <span class="o">=</span> <span class="n">translatable</span><span class="p">(</span><span class="s">&#39;Age of Methuselah&#39;</span><span class="p">),</span>
<span class="n">tooltip</span> <span class="o">=</span> <span class="n">translatable</span><span class="p">(</span><span class="s">&#39;If you know it, please, tell me!!!&#39;</span><span class="p">),</span>
<span class="n">required</span> <span class="o">=</span> <span class="bp">True</span><span class="p">,</span> <span class="c">#: Numeric fields have always a value, so this not really needed</span>
<span class="n">defvalue</span> <span class="o">=</span> <span class="s">&#39;4500&#39;</span>
<span class="p">)</span>
<span class="c">#: Is Methuselah istill alive?</span>
<span class="n">methAlive</span> <span class="o">=</span> <span class="n">gui</span><span class="o">.</span><span class="n">CheckBoxField</span><span class="p">(</span><span class="n">order</span> <span class="o">=</span> <span class="mi">4</span><span class="p">,</span>
<span class="n">label</span> <span class="o">=</span> <span class="n">translatable</span><span class="p">(</span><span class="s">&#39;Is Methuselah still alive?&#39;</span><span class="p">),</span>
<span class="n">tooltip</span> <span class="o">=</span> <span class="n">translatable</span><span class="p">(</span><span class="s">&#39;If you fail, this will not get saved :-)&#39;</span><span class="p">),</span>
<span class="n">required</span> <span class="o">=</span> <span class="bp">True</span><span class="p">,</span> <span class="c">#: Also means nothing. Check boxes has always a value</span>
<span class="n">defvalue</span> <span class="o">=</span> <span class="n">gui</span><span class="o">.</span><span class="n">TRUE</span> <span class="c">#: By default, at new item, check this</span>
<span class="p">)</span>
<span class="c"># There is more fields type, but not here the best place to cover it</span>
<span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">values</span> <span class="o">=</span> <span class="bp">None</span><span class="p">):</span>
<span class="sd">&#39;&#39;&#39;</span>
<span class="sd"> We will use the &quot;autosave&quot; feature for form fields, that is more than</span>
<span class="sd"> enought for most providers. (We simply need to store data provided by user</span>
<span class="sd"> and, maybe, initialize some kind of connection with this values).</span>
<span class="sd"> </span>
<span class="sd"> Normally provider values are rally used at sevice level, cause we never</span>
<span class="sd"> instantiate nothing except a service from a provider.</span>
<span class="sd"> &#39;&#39;&#39;</span>
<span class="c"># If you say meth is alive, you are wrong!!! (i guess..)</span>
<span class="c"># values are only passed from administration client. Internals </span>
<span class="c"># instantiations are always empty.</span>
<span class="k">if</span> <span class="n">values</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span> <span class="ow">and</span> <span class="bp">self</span><span class="o">.</span><span class="n">methAlive</span><span class="o">.</span><span class="n">isTrue</span><span class="p">():</span>
<span class="k">raise</span> <span class="n">ServiceProvider</span><span class="o">.</span><span class="n">ValidationException</span><span class="p">(</span><span class="n">_</span><span class="p">(</span><span class="s">&#39;Methuselah is not alive!!! :-)&#39;</span><span class="p">))</span>
<span class="c"># Marshal and unmarshal are defaults ones, also enought</span>
<span class="c"># As we use &quot;autosave&quot; fields feature, dictValues is also provided by</span>
<span class="c"># base class so we don&#39;t have to mess with all those things...</span>
<span class="nd">@staticmethod</span>
<span class="k">def</span> <span class="nf">test</span><span class="p">(</span><span class="n">env</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
<span class="sd">&#39;&#39;&#39;</span>
<span class="sd"> Create your test method here so the admin can push the &quot;check&quot; button</span>
<span class="sd"> and this gets executed.</span>
<span class="sd"> Args:</span>
<span class="sd"> env: environment passed for testing (temporal environment passed)</span>
<span class="sd"> </span>
<span class="sd"> data: data passed for testing (data obtained from the form </span>
<span class="sd"> definition)</span>
<span class="sd"> </span>
<span class="sd"> Returns: </span>
<span class="sd"> Array of two elements, first is True of False, depending on test </span>
<span class="sd"> (True is all right, false is error),</span>
<span class="sd"> second is an String with error, preferably internacionalizated..</span>
<span class="sd"> </span>
<span class="sd"> In this case, wi well do nothing more that use the provider params</span>
<span class="sd"> </span>
<span class="sd"> Note also that this is an static method, that will be invoked using</span>
<span class="sd"> the admin user provided data via administration client, and a temporary</span>
<span class="sd"> environment that will be erased after invoking this method</span>
<span class="sd"> &#39;&#39;&#39;</span>
<span class="k">try</span><span class="p">:</span>
<span class="c"># We instantiate the provider, but this may fail...</span>
<span class="n">instance</span> <span class="o">=</span> <span class="n">Provider</span><span class="p">(</span><span class="n">env</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
<span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s">&#39;Methuselah has {0} years and is {1} :-)&#39;</span>
<span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">instance</span><span class="o">.</span><span class="n">methAge</span><span class="o">.</span><span class="n">value</span><span class="p">,</span> <span class="n">instance</span><span class="o">.</span><span class="n">methAlive</span><span class="o">.</span><span class="n">value</span><span class="p">))</span>
<span class="k">except</span> <span class="n">ServiceProvider</span><span class="o">.</span><span class="n">ValidationException</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="c"># If we say that meth is alive, instantiation will </span>
<span class="k">return</span> <span class="p">[</span><span class="bp">False</span><span class="p">,</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">)]</span>
<span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="n">logger</span><span class="o">.</span><span class="n">exception</span><span class="p">(</span><span class="s">&quot;Exception caugth!!!&quot;</span><span class="p">)</span>
<span class="k">return</span> <span class="p">[</span><span class="bp">False</span><span class="p">,</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">)]</span>
<span class="k">return</span> <span class="p">[</span><span class="bp">True</span><span class="p">,</span> <span class="n">_</span><span class="p">(</span><span class="s">&#39;Nothing tested, but all went fine..&#39;</span><span class="p">)]</span>
<span class="c"># Congratulations!!!, the needed part of your first simple provider is done!</span>
<span class="c"># Now you can go to administration panel, and check it</span>
<span class="c">#</span>
<span class="c"># From now onwards, we implement our own methods, that will be used by, </span>
<span class="c"># for example, services derived from this provider</span>
<span class="k">def</span> <span class="nf">host</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">&#39;&#39;&#39;</span>
<span class="sd"> Sample method, in fact in this we just return </span>
<span class="sd"> the value of host field, that is an string</span>
<span class="sd"> &#39;&#39;&#39;</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">remoteHost</span><span class="o">.</span><span class="n">value</span>
<span class="k">def</span> <span class="nf">methYears</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">&#39;&#39;&#39;</span>
<span class="sd"> Another sample return, it will in fact return the Methuselah years</span>
<span class="sd"> &#39;&#39;&#39;</span>
</pre></div>
</td></tr></table></div>
</div>
</div>
</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 class="right" >
<a href="../../../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Service.html" title="Sample service"
>next</a> |</li>
<li class="right" >
<a href="whatisneeded.html" title="Needs for a service package"
>previous</a> |</li>
<li><a href="../../../index.html">UDS 1.0 documentation</a> &raquo;</li>
<li><a href="../../../api/index.html" >UDS&#8217;s core API</a> &raquo;</li>
<li><a href="../samples.html" >UDS Modules Samples</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; Copyright 2012, Virtual Cable S.L.U..
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>