hansken-extraction-plugin-s…/0.9.16/dev/python/getting_started.html



<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../../">
<head>
  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Getting started &mdash; Hansken Extraction Plugins for plugin developers 0.9.16
 documentation</title>
      <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=d75fae25" />
      <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=e59714d7" />
      <link rel="stylesheet" type="text/css" href="../../_static/wider_pages.css?v=32ad70ab" />


      <script src="../../_static/jquery.js?v=5d32c60e"></script>
      <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
      <script src="../../_static/documentation_options.js?v=433a2a34"></script>
      <script src="../../_static/doctools.js?v=9a2dae69"></script>
      <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Packaging" href="packaging.html" />
    <link rel="prev" title="Prerequisites" href="prerequisites.html" />
</head>

<body class="wy-body-for-nav">
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >


          <a href="../../index.html" class="icon icon-home">
            Hansken Extraction Plugins for plugin developers
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../introduction.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../concepts.html">General concepts</a></li>
<li class="toctree-l1"><a class="reference internal" href="../spec.html">Extraction Plugin specifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../java.html">Java</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../python.html">Python</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="api_changelog.html">Python API Changelog</a></li>
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">Prerequisites</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Getting started</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#install-required-software-on-ubuntu">Install required software on Ubuntu</a></li>
<li class="toctree-l3"><a class="reference internal" href="#install-required-software-on-windows">Install required software on Windows</a></li>
<li class="toctree-l3"><a class="reference internal" href="#install-docker-ubuntu-windows">Install Docker (Ubuntu, Windows)</a></li>
<li class="toctree-l3"><a class="reference internal" href="#set-up-your-ide-pycharm">Set up your IDE: PyCharm</a></li>
<li class="toctree-l3"><a class="reference internal" href="#download-an-extraction-plugin-template-empty-plugin">Download an extraction plugin template (empty plugin)</a></li>
<li class="toctree-l3"><a class="reference internal" href="#import-the-extraction-plugins-skeleton-in-pycharm">Import the Extraction Plugins Skeleton in PyCharm</a></li>
<li class="toctree-l3"><a class="reference internal" href="#verify-full-setup">Verify full setup</a></li>
<li class="toctree-l3"><a class="reference internal" href="#next-steps">Next steps</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="packaging.html">Packaging</a></li>
<li class="toctree-l2"><a class="reference internal" href="snippets.html">Python code snippets</a></li>
<li class="toctree-l2"><a class="reference internal" href="transformers.html">Using Transformers for on-demand execution</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html">Advanced use of the Test Framework in Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="hanskenpy.html">Run plugins with Hansken.py</a></li>
<li class="toctree-l2"><a class="reference internal" href="debugging.html">How to debug an Extraction Plugin</a></li>
<li class="toctree-l2"><a class="reference internal" href="../python.html#api-documentation">API Documentation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq.html">Frequently Asked Questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../changes.html">Changelog</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../../index.html">Hansken Extraction Plugins for plugin developers</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="../python.html">Python</a></li>
      <li class="breadcrumb-item active">Getting started</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../../_sources/dev/python/getting_started.md.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">

  <section id="getting-started">
<h1>Getting started<a class="headerlink" href="#getting-started" title="Link to this heading"></a></h1>
<p>Set up a development environment: step by step.</p>
<p>The following section describes how to set up a fully working development environment for extraction plugins with Python.
This is written for those who are not comfortable setting up a working build environment.
This is <strong>optional</strong>; advanced users may choose a different development environment setup, and can skip this section completely.</p>
<p>If you fail to set up a development environment, feel free to ask for help at our Discord channel.</p>
<section id="install-required-software-on-ubuntu">
<h2>Install required software on Ubuntu<a class="headerlink" href="#install-required-software-on-ubuntu" title="Link to this heading"></a></h2>
<p>In order to be able to develop Hansken Extraction Plugins in Python on Ubuntu, the following build tools need be installed on your system: python, pip, tox, Java, Docker.</p>
<ul>
<li><p><strong>Python, pip, tox, Java</strong>
To install, run the following commands in your terminal:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>apt<span class="w"> </span>update
sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>python3.10<span class="w"> </span>python3-pip<span class="w"> </span>tox<span class="w"> </span>default-jdk
</pre></div>
</div>
<p>You can check whether all versions are installed correctly by running the following commands (and validate the output):</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python<span class="w"> </span>--version
<span class="c1"># should return version 3.10.15 or higher</span>

pip3<span class="w"> </span>--version
<span class="c1"># should return version 20.0.2 or higher</span>

tox<span class="w"> </span>--version
<span class="c1"># should return version 3.11.2 or higher</span>

java<span class="w"> </span>-version
<span class="c1"># should return version 11.0.4 or higher</span>
</pre></div>
</div>
</li>
</ul>
<p>If the above software is installed, you can continue with “Install Docker”,
or if you don’t want to install Docker, continue with “Install your IDE: Pycharm”.</p>
</section>
<section id="install-required-software-on-windows">
<h2>Install required software on Windows<a class="headerlink" href="#install-required-software-on-windows" title="Link to this heading"></a></h2>
<p>In order to be able to develop Hansken Extraction Plugins in Python on Windows, follow the next steps:</p>
<ul>
<li><p>For verification of the installation of each program we will use commands on the command prompt.
This can be opened by clicking the Windows Start button and typing:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>cmd
</pre></div>
</div>
<p>Then hit Enter . This will open the command prompt where you can enter the commands given in the following steps.</p>
</li>
<li><p><strong>Python 3.10 or higher &amp; pip</strong>
Download the installer from <a class="reference external" href="https://www.python.org/downloads/">python.org/Downloads</a> (click the yellow “Download Python” button)
and run it to install Python and pip.
Pip is the standard package manager for Python.
It allows you to install and manage additional packages that are not part of the Python standard library, like the Extraction Plugins SDK.</p>
<p>Be sure to select the option “Add python to PATH”.</p>
<p>When the installation is complete, verify the installation by checking the Python and pip versions:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python<span class="w"> </span>--version
<span class="c1"># should return your downloaded Python version (&gt;3.10.4)</span>

pip3<span class="w"> </span>--version
<span class="c1"># should return 20.2.3 or higher</span>
</pre></div>
</div>
</li>
<li><p><strong>tox</strong>
Tox is used to automate and standardize testing in Python. Use Pip to install Tox with this command:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>tox
</pre></div>
</div>
<p>Verify that Tox is installed by running:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>tox<span class="w"> </span>--version
<span class="c1"># should return 3.23.0 or higher</span>
</pre></div>
</div>
</li>
<li><p><strong>Java JDK 11.0.4 (or higher)</strong>
Java JDK 11.0.4 or higher is needed to run the test framework of the Extraction Plugins SDK.
This enables you to test without actually deploying the plugin in Hansken.
Installing Java on Windows can be done in many different way, but for now we can not recommend one method.
Please have a look at <a class="reference external" href="https://docs.microsoft.com/en-us/java/openjdk/install">Install the Microsoft Build of OpenJDK</a> for more details.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>java<span class="w"> </span>-version
<span class="c1"># should return 11.0.4 or higher</span>
</pre></div>
</div>
<p>N.b. Make sure to set the environment variable in case the installed JDK is not detected by the system.
You can follow the below-mentioned steps to set the environment variable:</p>
<ol class="arabic simple">
<li><p>Click the Windows start button</p></li>
<li><p>Type “advanced system settings”</p></li>
<li><p>Hit enter</p></li>
<li><p>Now click on Environment Variables, select Path under System Variables section and click on Edit. We need to add the path of installed JDK to system Path.</p></li>
<li><p>Click on New Button and add the path to installed JDK bin which is C:javajava-11jdk-11.0.4bin in our case.</p></li>
<li><p>Press OK Button 3 times to close all the windows. This sets the JDK 11 on system environment variables to access the same from the console.</p></li>
</ol>
</li>
</ul>
<p>If the above software is installed, you can continue with “Install Docker”,
or if you don’t want to install Docker, continue with “Install your IDE: Pycharm”.</p>
</section>
<section id="install-docker-ubuntu-windows">
<h2>Install Docker (Ubuntu, Windows)<a class="headerlink" href="#install-docker-ubuntu-windows" title="Link to this heading"></a></h2>
<p>Installing Docker is a bit more complicated. The Docker website describes the installation instructions in detail.
Please follow the instructions on <a class="reference external" href="https://docs.docker.com/get-docker/">docs.docker.gom/get-docker/</a> to install docker.</p>
<ul>
<li><p>To check you have Docker installed correctly, run</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>docker<span class="w"> </span>--version
<span class="c1"># should return version 20.10.17 or higher</span>
</pre></div>
</div>
</li>
</ul>
<p>Note: if you run Docker inside a managed network, you might also need to configure proxies and/or certificates.
Please contact your system administrator if you need help with this.</p>
</section>
<section id="set-up-your-ide-pycharm">
<h2>Set up your IDE: PyCharm<a class="headerlink" href="#set-up-your-ide-pycharm" title="Link to this heading"></a></h2>
<p>We recommend that you use an IDE to aid you in your development of Extraction Plugins. PyCharm is a good choice.</p>
<ul class="simple">
<li><p>JetBrains has an excellent installation guide on their webpage: <a class="reference external" href="https://www.jetbrains.com/help/pycharm/installation-guide.html">Click here to go to the Pycharm Installation Guide</a></p></li>
</ul>
</section>
<section id="download-an-extraction-plugin-template-empty-plugin">
<h2>Download an extraction plugin template (empty plugin)<a class="headerlink" href="#download-an-extraction-plugin-template-empty-plugin" title="Link to this heading"></a></h2>
<p>You can download an extraction plugin template.
This is an empty plugin, from which you can rapidly start your plugin development.</p>
<ul>
<li><p>The template is hosted on GitHub <a class="reference external" href="https://github.com/NetherlandsForensicInstitute/hansken-extraction-plugin-template-python">here</a>.
You can download a zip with the template from here. The below screenshot shows where the download button is located:</p>
<a class="reference external image-reference" href="getting_started/download_template.png"><img alt="" src="../../_images/download_template.png" /></a>
</li>
</ul>
</section>
<section id="import-the-extraction-plugins-skeleton-in-pycharm">
<h2>Import the Extraction Plugins Skeleton in PyCharm<a class="headerlink" href="#import-the-extraction-plugins-skeleton-in-pycharm" title="Link to this heading"></a></h2>
<ul>
<li><p>First unzip the skeleton plugin downloaded from the previous step.</p></li>
<li><p>Next, start PyCharm.</p></li>
<li><p>When PyCharm starts, choose “Open” and select the folder where you placed the Extraction Plugin Skeleton.</p>
<a class="reference external image-reference" href="getting_started/pycharm_open_project.png"><img alt="" src="../../_images/pycharm_open_project.png" /></a>
</li>
<li><p>The following popup will appear, click OK .</p>
<a class="reference external image-reference" href="getting_started/pycharm_open_project_venv.png"><img alt="" src="../../_images/pycharm_open_project_venv.png" /></a>
</li>
<li><p>The Extraction Plugins Skeleton is now loaded in PyCharm, which should look as follows:</p>
<a class="reference external image-reference" href="getting_started/pycharm_project_start_page.png"><img alt="" src="../../_images/pycharm_project_start_page.png" /></a>
</li>
<li><p>Be sure to give the <code class="docutils literal notranslate"><span class="pre">README.md</span></code> a read when you are done with the Prerequisites.</p></li>
</ul>
</section>
<section id="verify-full-setup">
<h2>Verify full setup<a class="headerlink" href="#verify-full-setup" title="Link to this heading"></a></h2>
<p>To verify that your system has been setup correctly, you can run the test suite in the Extraction Plugin Skeleton:</p>
<ul>
<li><p>First, press <code class="docutils literal notranslate"><span class="pre">alt-F12</span></code> at the same time to open a terminal in PyCharm in the project root folder.</p></li>
<li><p>To run the tests of the Skeleton, run this command in the terminal from the root folder:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>tox
</pre></div>
</div>
<p>The first time running tox may take a few minutes! Please be patient 😊</p>
<p>Tox will install all required plugin dependencies, and start your tests.
N.b. The plugin template demonstrates how to build a plugin with tox.
Some plugin developers choose a different tool than tox.</p>
</li>
<li><p>If your system has been set up correctly, the output should end with a summary like this:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>py38:<span class="w"> </span>commands<span class="w"> </span>succeeded
congratulations<span class="w"> </span>:<span class="o">)</span>
</pre></div>
</div>
<p>This means the setup is finished. You now have everything installed to start coding your own plugin!</p>
</li>
</ul>
</section>
<section id="next-steps">
<h2>Next steps<a class="headerlink" href="#next-steps" title="Link to this heading"></a></h2>
<p>Now that you have a working environment, you can start doing cool stuff.
Please have a look at the following pages for more information:</p>
<ul class="simple">
<li><p><a class="reference internal" href="packaging.html"><span class="doc">Packaging</span></a>: how to package your plugin and use it in Hansken</p></li>
<li><p><a class="reference internal" href="hanskenpy.html"><span class="doc">Run plugins with Hansken.py</span></a>: run your plugin on a case without uploading the plugin to Hansken, useful for quick prototyping</p></li>
<li><p><a class="reference internal" href="transformers.html"><span class="doc">Transformers for on-demand execution</span></a>: how to write a transformer to execute code on-demand outside extraction time.</p></li>
<li><p><a class="reference internal" href="testing.html"><span class="doc">Testing</span></a>: how to write tests for your plugin</p></li>
<li><p><a class="reference internal" href="debugging.html"><span class="doc">Debugging</span></a>: if your plugin isn’t working as expected, you can debug it</p></li>
<li><p><a class="reference internal" href="snippets.html"><span class="doc">Snippets</span></a>: code snippets to demonstrate common plugin usage patterns</p></li>
</ul>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="prerequisites.html" class="btn btn-neutral float-left" title="Prerequisites" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="packaging.html" class="btn btn-neutral float-right" title="Packaging" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2020-2026 Netherlands Forensic Institute.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.


</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

</body>
</html>