<!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>Upgrading from Pyro 3 — Pyro 4.21 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: '4.21',
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="Pyro 4.21 documentation" href="index.html" />
<link rel="next" title="Pyro4 library API" href="api.html" />
<link rel="prev" title="Configuring Pyro" href="config.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="api.html" title="Pyro4 library API"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="config.html" title="Configuring Pyro"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Pyro 4.21 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="upgrading-from-pyro-3">
<h1>Upgrading from Pyro 3<a class="headerlink" href="#upgrading-from-pyro-3" title="Permalink to this headline">¶</a></h1>
<div class="section" id="should-i-choose-pyro4">
<span id="id1"></span><h2>Should I choose Pyro4?<a class="headerlink" href="#should-i-choose-pyro4" title="Permalink to this headline">¶</a></h2>
<p>Should you use Pyro 4 or Pyro 3 for your project? This depends on a few things.</p>
<p><strong>Dependencies on older systems</strong></p>
<p>Pyro 4 has more modern system requirements than Pyro 3.
It is unsupported on Python versions below 2.6.
Pyro 3 runs fine on Python 2.5, and Pyro versions before 3.13 should run on even older Python versions.
So if you cannot use Python 2.6 or newer, you should use Pyro 3.</p>
<p>Pyro 4 has been written from scratch. While it looks and feels much like Pyro 3 did, its API and implementation are incompatible.
If you need to connect to existing systems that use Pyro 3, you can only do that with Pyro 3. Pyro 4 can’t talk to them.</p>
<p><strong>Features</strong></p>
<p>Pyro 4 has several features that are not present in Pyro 3, but the reverse is also true.
If you require one of the following features for your system, you can only find them -for now- in Pyro 3:</p>
<ul class="simple">
<li>SSL support</li>
<li>connection authentication</li>
<li>mobile code</li>
<li>remote attribute access</li>
<li>Event server</li>
</ul>
<p>Some of them may appear in the future in Pyro 4, but for now they’re all exclusive to Pyro 3.</p>
<p><strong>Availability in package forms</strong></p>
<p>Some people can’t or won’t install software from source and rather use the package manager of their OS.
Pyro 4 might not yet be available in your package manager because it is rather new.
Pyro 3 is available as a Debian package.
So if you are on Debian (or a derivative like Ubuntu or Mint) and you only accept software from the distribution packages,
Pyro 3 is your only choice for now.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The Pyro project itself does not provide any OS-specific packaging.
Things like the Debian Pyro package are created and maintained by
different people (thanks for that!)</p>
</div>
<p><strong>Maturity</strong></p>
<p>Pyro 3 has been around for many years and has a proven track record. It also has a very stable API.
It only gets bug fixes and much effort is taken to keep it backward compatible with previous 3.x versions.
Pyro 4 on the other hand is still under active development.
The important API parts are more or less stabilized but as features are being added or changed, stuff might break.
So depending on your requirements of maturity and API stability you might choose one or the other.</p>
</div>
<div class="section" id="differences">
<h2>Differences<a class="headerlink" href="#differences" title="Permalink to this headline">¶</a></h2>
<p>Here you can find what is different in Pyro4 compared to Pyro3.
This should help with converting existing Pyro3 applications to Pyro4.
It also serves as a quick overview for developers that are used to Pyro3,
to see what the new API and features of Pyro4 are like.</p>
<div class="section" id="general-differences-from-pyro-3-x">
<h3>General differences from Pyro 3.x<a class="headerlink" href="#general-differences-from-pyro-3-x" title="Permalink to this headline">¶</a></h3>
<ul>
<li><p class="first">Pyro4 requires Python 2.6 or newer. Pyro 3.x supports Python 2.5 (Pyro 3.12 and older, even support Python 2.4)</p>
</li>
<li><p class="first">Toplevel package name has been changed from <tt class="docutils literal"><span class="pre">Pyro</span></tt> into <tt class="docutils literal"><span class="pre">Pyro4</span></tt></p>
</li>
<li><p class="first">Mobile code support has been removed.</p>
</li>
<li><p class="first">Remote attribute access (<tt class="docutils literal"><span class="pre">DynamicProxyWithAttrs</span></tt>) has been removed (slight chance it appears again in the future in a different form)</p>
</li>
<li><p class="first">Event server has been removed (slight chance it appears again in the future in a different form).</p>
</li>
<li><p class="first">SSL support has been removed. Likely to appear again in a future version.</p>
</li>
<li><p class="first">You don’t need to import the various sub packages. Just <tt class="docutils literal"><span class="pre">import</span> <span class="pre">Pyro4</span></tt> and you’re done: the main Pyro API elements are available directly in the <tt class="docutils literal"><span class="pre">Pyro4</span></tt> package.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">Pyro.core.PyroURI</span></tt> has been renamed to <tt class="docutils literal"><span class="pre">Pyro4.URI</span></tt></p>
</li>
<li><p class="first">You can choose from two server types to use in your daemon, a threadpool server (that can process requests concurrently, most similar to Pyro3)
and a select/poll based server (that processes requests in a single thread by multiplexing all client connections).</p>
</li>
<li><p class="first">Pyro objects in the daemon don’t have a forced objectId UUID anymore. They just use the name you give them, or an auto generated one if you don’t provide a name yourself.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">PYROLOC</span></tt> protocol has been removed. Just use the <tt class="docutils literal"><span class="pre">PYRO</span></tt> protocol with the logical name instead of the object id in the URI.</p>
</li>
<li><p class="first">Pyro daemon binds on a random free port by default, instead of on a fixed port. Name server still is on a fixed port by default.</p>
</li>
<li><p class="first">Pyro daemons (including the Name server) bind on localhost by default. This prevents exposure to the outside world in a default install.
You have to explicitly tell Pyro4 to bind on another network interface. With Pyro3, it was the other way around,
it would bind on all network interfaces by default (potentially exposing unwanted servers).</p>
</li>
<li><p class="first">Logging is done using Python’s standard logging module instead of custom logger stuff from <tt class="docutils literal"><span class="pre">Pyro.util</span></tt>. There is some autoconfig voodoo in the package init code that reacts to some environment variable settings.</p>
</li>
<li><p class="first">All classes are new style classes, so you can use super() etc. (this was already the case in the later Pyro 3.x releases but not in earlier ones)</p>
</li>
<li><dl class="first docutils">
<dt>There are no batch files for the utilities (yet), but you can use aliases like this:</dt>
<dd><div class="first last line-block">
<div class="line"><tt class="docutils literal"><span class="pre">alias</span> <span class="pre">pyro-ns=python</span> <span class="pre">-m</span> <span class="pre">Pyro4.naming</span></tt></div>
<div class="line"><tt class="docutils literal"><span class="pre">alias</span> <span class="pre">pyro-nsc=python</span> <span class="pre">-m</span> <span class="pre">Pyro4.nsc</span></tt></div>
</div>
</dd>
</dl>
</li>
<li><p class="first">The command line syntax of these tools has changed, just check out the new usage with ‘-h’.</p>
</li>
<li><p class="first">The name server doesn’t have any groups anymore. The namespace is now ‘flat’. You don’t have to use the ‘:’ in front of names, or separate parts using ‘.’ anymore. You can look up names matching a prefix string or a regular expression now, so with clever names you can still achieve mostly the same as with the old group based namespace.</p>
</li>
<li><p class="first">The name server doesn’t have a default group any longer. Name server proxies are regular Pyro proxies and don’t perform any voodoo magic on the names anymore.</p>
</li>
<li><p class="first">Config items are in <tt class="docutils literal"><span class="pre">Pyro4.config</span></tt> (as they were in <tt class="docutils literal"><span class="pre">Pyro.config</span></tt> in Pyro3) but have changed quite a bit. Most of them have been removed. Some may return in a later version.</p>
</li>
<li><p class="first">Exception traceback processing: <tt class="docutils literal"><span class="pre">Pyro4.util.getPyroTraceback</span></tt> shouldn’t be called with an exception object anymore. Either simply call it without parameters, or supply the usual ex_type, ex_value, ex_tb objects that you can get from sys.exc_info.
Or even easier, install Pyro4’s custom excepthook.</p>
</li>
</ul>
</div>
<div class="section" id="client-code-differences">
<h3>Client code differences<a class="headerlink" href="#client-code-differences" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">Pyro.core.initClient</span></tt> was deprecated for a long time already, and has been removed.</li>
<li>locating the name server: instead of <tt class="docutils literal"><span class="pre">locator=Pyro.naming.NameServerLocator();</span> <span class="pre">ns=locator.getNS()</span></tt> simply use <tt class="docutils literal"><span class="pre">ns=Pyro4.locateNS()</span></tt></li>
<li>Pyro’s internal methods and attributes have been renamed and are all prefixed with <tt class="docutils literal"><span class="pre">_pyro</span></tt>.</li>
<li>getting the uri from a proxy: <tt class="docutils literal"><span class="pre">proxy.URI</span></tt> is now <tt class="docutils literal"><span class="pre">proxy._pyroUri</span></tt></li>
<li>the <tt class="docutils literal"><span class="pre">Pyro.core.PyroURI</span></tt> object has changed quite a bit. It has been renamed to <tt class="docutils literal"><span class="pre">Pyro4.URI</span></tt> and many of its attributes are different. It knows two types of protocols: <tt class="docutils literal"><span class="pre">PYRO</span></tt> and <tt class="docutils literal"><span class="pre">PYRONAME</span></tt> (<tt class="docutils literal"><span class="pre">PYROLOC</span></tt> has gone). The syntax is different too: <tt class="docutils literal"><span class="pre"><protocol>:<objectid>@<location></span></tt></li>
<li>looking up stuff in the name server: <tt class="docutils literal"><span class="pre">ns.resolve</span></tt> is now <tt class="docutils literal"><span class="pre">ns.lookup</span></tt></li>
<li>there is only one proxy class: <tt class="docutils literal"><span class="pre">Pyro4.Proxy</span></tt></li>
<li>creating proxies: use the Proxy class constructor, pass in an URI or an uri string directly.</li>
<li>rebinding a disconnected proxy: instead of <tt class="docutils literal"><span class="pre">obj.adapter.rebindURI</span></tt> now use: <tt class="docutils literal"><span class="pre">obj._pyroReconnect</span></tt></li>
<li>proxies for ‘meta’ uris (<tt class="docutils literal"><span class="pre">PYRONAME</span></tt> etc) are not updated anymore with the resolved uri. If you want the old behavior, you have to call <tt class="docutils literal"><span class="pre">proxy._pyroBind()</span></tt> explicitly to bind the proxy on the resolved PYRO uri.</li>
<li>You can manually resolve a ‘meta’ uri by using <tt class="docutils literal"><span class="pre">Pyro4.resolve</span></tt>, it will return a new normal PYRO uri.</li>
<li>Oneway methods: <tt class="docutils literal"><span class="pre">proxy._setOneway</span></tt> got replaced by the <tt class="docutils literal"><span class="pre">proxy._pyroOneway</span></tt> attribute. That is a set (or sequence) so simply add method names to it that need to be oneway.</li>
</ul>
</div>
<div class="section" id="server-code-differences">
<h3>Server code differences<a class="headerlink" href="#server-code-differences" title="Permalink to this headline">¶</a></h3>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">Pyro.core.initServer</span></tt> was deprecated for a long time already, and has been removed.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">Pyro.core.ObjBase</span></tt> is gone, just use any class directly as a Pyro object. Pyro4 injects a few magic attributes in your object. Their names start with <tt class="docutils literal"><span class="pre">_pyro</span></tt> for easy identification.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">Pyro.core.SynchronizedObjBase</span></tt> is gone as well, you need to create your own thread safety measures if required (locks, Queues, etc)</p>
</li>
<li><p class="first">see above for changes concerning how to locate the name server.</p>
</li>
<li><p class="first">Daemons are created much in the same way as before. But they don’t automagically register anything in the name server anymore so you have to do that yourself (<tt class="docutils literal"><span class="pre">daemon.useNameServer</span></tt> is gone)</p>
</li>
<li><p class="first">Daemons now bind on a random free port by default instead of a fixed port. You need to specify a port yourself when creating a daemon if you want a fixed port.</p>
</li>
<li><p class="first">Daemons bind on localhost by default, instead of 0.0.0.0. If you want to expose to the network, you’ll have to provide a proper hostname or ip address yourself. There is a utility method in the <tt class="docutils literal"><span class="pre">Pyro4.socketutil</span></tt> module that can help you with that: <tt class="docutils literal"><span class="pre">getIpAddress</span></tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">daemon.connect</span></tt> has been renamed to <tt class="docutils literal"><span class="pre">daemon.register</span></tt>. It still returns the URI for the object, as usual.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">daemon.disconnect</span></tt> has been renamed to <tt class="docutils literal"><span class="pre">daemon.unregister</span></tt></p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">daemon.connectPersistent</span></tt> is gone, just pass the existing object id as a parameter to the normal register.</p>
</li>
<li><p class="first">getting an object’s uri and registering in the name server: use the URI you got from the register call, or use <tt class="docutils literal"><span class="pre">daemon.uriFor</span></tt> to get a new URI for a given object. Use <tt class="docutils literal"><span class="pre">ns.register(objName,</span> <span class="pre">uri)</span></tt> as usual to register it in the name server.</p>
</li>
<li><p class="first">creating new pyro objects on the server and returning them (factory methods): <tt class="docutils literal"><span class="pre">server.getDaemon()</span></tt> is replaced by the <tt class="docutils literal"><span class="pre">_pyroDaemon</span></tt> attribute, and <tt class="docutils literal"><span class="pre">obj.getProxy()</span></tt> is gone. Typical pattern is now:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">uri</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_pyroDaemon</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="nb">object</span><span class="p">)</span>
<span class="k">return</span> <span class="n">Pyro4</span><span class="o">.</span><span class="n">Proxy</span><span class="p">(</span><span class="n">uri</span><span class="p">)</span>
</pre></div>
</div>
<p><strong>However</strong> Pyro4 has an ‘AUTOPROXY’ feature (on by default) that makes the above unneeded (Pyro4 will wrap pyro objects with a proxy
automatically for you). You can turn this feature off to make it look more like Pyro3’s behavior.</p>
</li>
<li><p class="first">Unregistering objects from the daemon is done with <tt class="docutils literal"><span class="pre">some_pyro_object._pyroDaemon.unregister(some_pyro_object)</span></tt> (or use the object’s URI).</p>
</li>
</ul>
</div>
<div class="section" id="new-features">
<h3>New features<a class="headerlink" href="#new-features" title="Permalink to this headline">¶</a></h3>
<p>Pyro4 introduces several new features that weren’t available in Pyro3, so there is no migration path needed for those.
(Things like batched calls, async calls, new config items etc).</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/pyro.png" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Upgrading from Pyro 3</a><ul>
<li><a class="reference internal" href="#should-i-choose-pyro4">Should I choose Pyro4?</a></li>
<li><a class="reference internal" href="#differences">Differences</a><ul>
<li><a class="reference internal" href="#general-differences-from-pyro-3-x">General differences from Pyro 3.x</a></li>
<li><a class="reference internal" href="#client-code-differences">Client code differences</a></li>
<li><a class="reference internal" href="#server-code-differences">Server code differences</a></li>
<li><a class="reference internal" href="#new-features">New features</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="config.html"
title="previous chapter">Configuring Pyro</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="api.html"
title="next chapter">Pyro4 library API</a></p>
<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 class="right" >
<a href="api.html" title="Pyro4 library API"
>next</a> |</li>
<li class="right" >
<a href="config.html" title="Configuring Pyro"
>previous</a> |</li>
<li><a href="index.html">Pyro 4.21 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright Irmen de Jong.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
