CINXE.COM

<!doctype html> <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> <title>Handle Client documentation — B2Handle 1.2.0-dev0 documentation</title> <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/bizstyle.css" /> <script data-url_root="./" id="documentation_options" 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/bizstyle.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Authentication at a Handle Server" href="authentication.html" /> <link rel="prev" title="Welcome to the B2Handle documentation" href="index.html" /> <meta name="viewport" content="width=device-width,initial-scale=1.0" />  </head><body> <div class="related" role="navigation" aria-label="related navigation"> <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="authentication.html" title="Authentication at a Handle Server" accesskey="N">next</a> |</li> <li class="right" > <a href="index.html" title="Welcome to the B2Handle documentation" accesskey="P">previous</a> |</li> <li class="nav-item nav-item-0"><a href="index.html">B2Handle 1.2.0-dev0 documentation</a> »</li> <li class="nav-item nav-item-this"><a href="">Handle Client documentation</a></li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <section id="handle-client-documentation"> <h1>Handle Client documentation<a class="headerlink" href="#handle-client-documentation" title="Permalink to this headline">¶</a></h1> <div class="admonition important"> <p class="admonition-title">Important</p> <p>If you encounter security warnings when using the library, contact your Handle server administrators and ask them to set up the server certificates correctly! (see <a class="reference internal" href="handleserverconfig.html"><span class="doc">Handle Server Configuration</span></a>)</p> </div> <p>The EUDATHandleClient class provides a Python-level interface for interactions with a Handle server through its native REST interface. The class provides common methods for working with Handles and their records:</p> <ul class="simple"> <li><p>Create and modify Handles</p></li> <li><p>Search across Handles (using an additional servlet)</p></li> <li><p>Manage multiple URLs through special 10320/loc entries</p></li> </ul> <section id="general-usage"> <h2>General usage<a class="headerlink" href="#general-usage" title="Permalink to this headline">¶</a></h2> <p>First, you create an instance of the client. It holds all necessary information, such as from which handle server to read, which user credentials to use etc. Several different instantiation methods are available for different usages (see below).</p> <blockquote> <div><div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">client</span> <span class="o">=</span> <span class="n">EUDATHandleClient</span><span class="o">.</span><span class="n">instantiate_</span><span class="o">...</span><span class="p">(</span><span class="o">...</span><span class="p">)</span> </pre></div> </div> </div></blockquote> <p>Then, use the client’s methods to read, create and modify handles.</p> <blockquote> <div><div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">value</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">some_method</span><span class="p">(</span><span class="o">...</span><span class="p">)</span> </pre></div> </div> </div></blockquote> <p>Search functionality is not offered by the Handle System. For searching, you need access to a customized search servlet.</p> </section> <section id="instantiation"> <h2>Instantiation<a class="headerlink" href="#instantiation" title="Permalink to this headline">¶</a></h2> <p>Before reading or modifying handles, you need to instantiate the client. The client class offers several constructors with differences in the permissions and thus possible actions on the Handle server. Aside from the default constructor <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code>, there are several shorthand constructors:</p> <dl class="simple"> <dt><code class="xref py py-meth docutils literal notranslate"><span class="pre">instantiate_for_read_access()</span></code></dt><dd><p>Anonymous read-only access, no credentials needed, no search capabilities. Handles are read from the global Handle Registry.</p> </dd> <dt><code class="xref py py-meth docutils literal notranslate"><span class="pre">instantiate_for_read_and_search()</span></code></dt><dd><p>Read-only access, credentials for search functions required.</p> </dd> <dt><code class="xref py py-meth docutils literal notranslate"><span class="pre">instantiate_with_username_and_password()</span></code></dt><dd><p>Full read and write access, credentials required (username and password).</p> </dd> <dt><code class="xref py py-meth docutils literal notranslate"><span class="pre">instantiate_with_credentials()</span></code></dt><dd><p>Full read and write access, credentials required (username and password or client certificates). Credentials can conveniently be loaded from a JSON file. For this, please see documentation of <code class="xref py py-mod docutils literal notranslate"><span class="pre">cliencredentials</span></code>.</p> </dd> </dl> <p>On top of the required arguments, more arguments can be passed to the constructors as key-value pairs. Please see the documentation of the default constructor to find out which values are understood.</p> </section> <section id="authentication"> <h2>Authentication<a class="headerlink" href="#authentication" title="Permalink to this headline">¶</a></h2> <p>For creating and modifying handles* you need to authenticate at the Handle Server you’d like to write to. Authentication using b2handle is straightforward. There are two possibilities:</p> <ul class="simple"> <li><p>Authenticating using username and password</p></li> <li><p>Authenticating using client certificates</p></li> </ul> <div class="admonition important"> <p class="admonition-title">Important</p> <p>Here we assume that you know your username and password or have your private key file and your certificate file ready. If you need to set these up, please see <a class="reference internal" href="authentication.html"><span class="doc">Authentication at a Handle Server</span></a>.</p> </div> <section id="authentication-using-client-certificates"> <h3>Authentication using client certificates<a class="headerlink" href="#authentication-using-client-certificates" title="Permalink to this headline">¶</a></h3> <p>Using client certificates, you need to provide paths to the file containing your private key and to the certificate in a JSON file. The class <code class="xref py py-class docutils literal notranslate"><span class="pre">PIDClientCredentials</span></code> provides a method <code class="xref py py-meth docutils literal notranslate"><span class="pre">load_from_JSON()</span></code>. This can be read as follows:</p> <blockquote> <div><div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">cred</span> <span class="o">=</span> <span class="n">PIDClientCredentials</span><span class="o">.</span><span class="n">load_from_JSON</span><span class="p">(</span><span class="s1">'my_credentials.json'</span><span class="p">)</span> <span class="n">client</span> <span class="o">=</span> <span class="n">EUDATHandleClient</span><span class="o">.</span><span class="n">instantiate_with_credentials</span><span class="p">(</span><span class="n">cred</span><span class="p">)</span> </pre></div> </div> </div></blockquote> <p>The JSON file should look like this:</p> <blockquote> <div><div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span> <span class="nt">"baseuri"</span><span class="p">:</span> <span class="s2">"https://my.handle.server"</span><span class="p">,</span> <span class="nt">"private_key"</span><span class="p">:</span> <span class="s2">"my_private_key.pem"</span><span class="p">,</span> <span class="nt">"certificate_only"</span><span class="p">:</span> <span class="s2">"my_certificate.pem"</span> <span class="p">}</span> </pre></div> </div> </div></blockquote> </section> <section id="authentication-using-username-and-password"> <h3>Authentication using username and password<a class="headerlink" href="#authentication-using-username-and-password" title="Permalink to this headline">¶</a></h3> <p>If you have a username (something that looks like <strong>300:foo/bar</strong>) and a password, we recommend using this constructor: <code class="xref py py-meth docutils literal notranslate"><span class="pre">instantiate_with_username_and_password()</span></code>:</p> <blockquote> <div><div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">client</span> <span class="o">=</span> <span class="n">EUDATHandleClient</span><span class="o">.</span><span class="n">instantiate_with_username_and_password</span><span class="p">(</span> <span class="s1">'https://my.handle.server'</span><span class="p">,</span> <span class="s1">'300:foo/bar'</span><span class="p">,</span> <span class="s1">'mypassword123'</span> <span class="p">)</span> </pre></div> </div> </div></blockquote> <dl class="simple"> <dt>Alternatively, you can store your username and password in a JSON file, instead of paths to certificate and key::</dt><dd><p>{ “baseuri”: “<a class="reference external" href="https://my.handle.server">https://my.handle.server</a>”, “username”: “300:foo/bar”, “password”: “mypassword123” }</p> </dd> </dl> <p>Like above, you can read the JSON like as shown above:</p> <blockquote> <div><div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">cred</span> <span class="o">=</span> <span class="n">PIDClientCredentials</span><span class="o">.</span><span class="n">load_from_JSON</span><span class="p">(</span><span class="s1">'my_credentials.json'</span><span class="p">)</span> <span class="n">client</span> <span class="o">=</span> <span class="n">EUDATHandleClient</span><span class="o">.</span><span class="n">instantiate_with_credentials</span><span class="p">(</span><span class="n">cred</span><span class="p">)</span> </pre></div> </div> </div></blockquote> </section> <section id="credentials-json-file"> <h3>Credentials JSON file<a class="headerlink" href="#credentials-json-file" title="Permalink to this headline">¶</a></h3> <p>The JSON file can contain more information. All items it contains are passed to the client constructor as config. Please see <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> to find out which configuration items the client constructor understands.</p> </section> </section> <section id="basic-handle-interaction"> <h2>Basic Handle interaction<a class="headerlink" href="#basic-handle-interaction" title="Permalink to this headline">¶</a></h2> <dl class="simple"> <dt>Creating a Handle</dt><dd><p>Use <code class="xref py py-meth docutils literal notranslate"><span class="pre">register_handle()</span></code> to create a Handle with a custom name or <code class="xref py py-meth docutils literal notranslate"><span class="pre">generate_and_register_handle()</span></code> to create a Handle with a random UUID-based name.</p> </dd> <dt>Deleting a Handle</dt><dd><p>Use <code class="xref py py-meth docutils literal notranslate"><span class="pre">delete_handle()</span></code>.</p> </dd> <dt>Retrieving a full Handle record</dt><dd><p>This can be done either through <code class="xref py py-meth docutils literal notranslate"><span class="pre">retrieve_handle_record()</span></code> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">retrieve_handle_record_json()</span></code>.</p> </dd> <dt>Retrieving a single value</dt><dd><p>Use <code class="xref py py-meth docutils literal notranslate"><span class="pre">get_value_from_handle()</span></code> to retrieve a single Handle record value.</p> </dd> <dt>Modifying a Handle record</dt><dd><p>Use <code class="xref py py-meth docutils literal notranslate"><span class="pre">modify_handle_value()</span></code> to modify any number of values in a specific Handle record. To remove individual values, use <code class="xref py py-meth docutils literal notranslate"><span class="pre">delete_handle_value()</span></code>.</p> </dd> <dt>Searching for a Handle</dt><dd><p>Use <code class="xref py py-meth docutils literal notranslate"><span class="pre">search_handle()</span></code> to search for Handles with a specific key and value. Please note that searching requires access to a search servlet whose access information, if it differs from the handle server, has to be specified at client instantiation.</p> </dd> </dl> </section> <section id="managing-multiple-urls-with-10320-loc"> <h2>Managing multiple URLs with 10320/loc<a class="headerlink" href="#managing-multiple-urls-with-10320-loc" title="Permalink to this headline">¶</a></h2> <p>The client class offers several methods to adequately manage multiple URLs in a single Handle record. The Handle System mechanism used for this are entries with type <em>10320/loc</em>. Use <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_additional_URL()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">exchange_additional_URL()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">remove_additional_URL()</span></code> to manage such entries.</p> <p>In addition to these basic management methods, there are also two helper methods. Use <code class="xref py py-meth docutils literal notranslate"><span class="pre">is_10320LOC_empty()</span></code> to check whether a Handle already contains a 10320/loc entry and <code class="xref py py-meth docutils literal notranslate"><span class="pre">is_URL_contained_in_10320LOC()</span></code> to check whether a given URL is already present in a record.</p> </section> <section id="full-method-documentation"> <h2>Full method documentation<a class="headerlink" href="#full-method-documentation" title="Permalink to this headline">¶</a></h2> <section id="constructors"> <h3>Constructors<a class="headerlink" href="#constructors" title="Permalink to this headline">¶</a></h3> </section> <section id="handle-record-methods"> <h3>Handle record methods<a class="headerlink" href="#handle-record-methods" title="Permalink to this headline">¶</a></h3> </section> <section id="methods-for-managing-10320-loc-entries"> <h3>Methods for managing 10320/loc entries<a class="headerlink" href="#methods-for-managing-10320-loc-entries" title="Permalink to this headline">¶</a></h3> </section> <section id="helper-methods"> <h3>Helper methods<a class="headerlink" href="#helper-methods" title="Permalink to this headline">¶</a></h3> </section> </section> <section id="utilities"> <h2>Utilities<a class="headerlink" href="#utilities" title="Permalink to this headline">¶</a></h2> </section> <section id="client-credentials"> <h2>Client credentials<a class="headerlink" href="#client-credentials" title="Permalink to this headline">¶</a></h2> </section> <section id="exceptions"> <h2>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h2> </section> </section> <div class="clearer"></div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h3><a href="index.html">Table of Contents</a></h3> <ul> <li><a class="reference internal" href="#">Handle Client documentation</a><ul> <li><a class="reference internal" href="#general-usage">General usage</a></li> <li><a class="reference internal" href="#instantiation">Instantiation</a></li> <li><a class="reference internal" href="#authentication">Authentication</a><ul> <li><a class="reference internal" href="#authentication-using-client-certificates">Authentication using client certificates</a></li> <li><a class="reference internal" href="#authentication-using-username-and-password">Authentication using username and password</a></li> <li><a class="reference internal" href="#credentials-json-file">Credentials JSON file</a></li> </ul> </li> <li><a class="reference internal" href="#basic-handle-interaction">Basic Handle interaction</a></li> <li><a class="reference internal" href="#managing-multiple-urls-with-10320-loc">Managing multiple URLs with 10320/loc</a></li> <li><a class="reference internal" href="#full-method-documentation">Full method documentation</a><ul> <li><a class="reference internal" href="#constructors">Constructors</a></li> <li><a class="reference internal" href="#handle-record-methods">Handle record methods</a></li> <li><a class="reference internal" href="#methods-for-managing-10320-loc-entries">Methods for managing 10320/loc entries</a></li> <li><a class="reference internal" href="#helper-methods">Helper methods</a></li> </ul> </li> <li><a class="reference internal" href="#utilities">Utilities</a></li> <li><a class="reference internal" href="#client-credentials">Client credentials</a></li> <li><a class="reference internal" href="#exceptions">Exceptions</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="index.html" title="previous chapter">Welcome to the B2Handle documentation</a></p> <h4>Next topic</h4> <p class="topless"><a href="authentication.html" title="next chapter">Authentication at a Handle Server</a></p> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/handleclient.rst.txt" rel="nofollow">Show Source</a></li> </ul> </div> <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" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> <input type="submit" value="Go" /> </form> </div> </div> <script>$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related" role="navigation" aria-label="related navigation"> <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="authentication.html" title="Authentication at a Handle Server" >next</a> |</li> <li class="right" > <a href="index.html" title="Welcome to the B2Handle documentation" >previous</a> |</li> <li class="nav-item nav-item-0"><a href="index.html">B2Handle 1.2.0-dev0 documentation</a> »</li> <li class="nav-item nav-item-this"><a href="">Handle Client documentation</a></li> </ul> </div> <div class="footer" role="contentinfo"> © Copyright 2015-2017, Deutsches Klimarechenzentrum GmbH, GRNET S.A., SURFsara. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.1.2. </div> </body> </html>