sh_cpl/docs/build/html/quickstart.html
2023-04-05 21:43:21 +02:00

320 lines
22 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Getting started with CPL &mdash; Common Python Library documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script src="_static/jquery.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></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="Setting up the local environment and workspace" href="setup.html" />
<link rel="prev" title="Getting started" href="getting_started.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">
Common Python Library
</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">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction to the CPL Docs</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="getting_started.html">Getting started</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Getting started with CPL</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#table-of-contents">Table of Contents</a></li>
<li class="toctree-l3"><a class="reference internal" href="#prerequisites">Prerequisites</a></li>
<li class="toctree-l3"><a class="reference internal" href="#create-the-project">Create the project</a></li>
<li class="toctree-l3"><a class="reference internal" href="#create-a-menu">Create a menu</a></li>
<li class="toctree-l3"><a class="reference internal" href="#what-s-next">Whats next</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="setup.html">Setting up the local environment and workspace</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Contributing to CPL</a></li>
<li class="toctree-l1"><a class="reference internal" href="deprecated.html">Deprecated</a></li>
<li class="toctree-l1"><a class="reference internal" href="cpl_cli.html">CLI reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="cpl_core.html">API reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="cpl_discord.html">Discord Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="cpl_query.html">Query reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="cpl_translation.html">Translation reference</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">Common Python Library</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="getting_started.html">Getting started</a></li>
<li class="breadcrumb-item active">Getting started with CPL</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/quickstart.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-with-cpl">
<h1>Getting started with CPL<a class="headerlink" href="#getting-started-with-cpl" title="Permalink to this heading"></a></h1>
<p>Welcome to CPL!</p>
<p>This tutorial introduces you to the essentials of the CPL package by walking through building an console based app.</p>
<section id="table-of-contents">
<h2>Table of Contents<a class="headerlink" href="#table-of-contents" title="Permalink to this heading"></a></h2>
<ol class="arabic simple">
<li><p><a class="reference internal" href="#prerequisites"><span class="xref myst">Prerequisites</span></a></p></li>
<li><p><a class="reference internal" href="#create-the-project"><span class="xref myst">Create the project</span></a></p></li>
<li><p><a class="reference internal" href="#create-a-menu"><span class="xref myst">Create a menu</span></a></p></li>
<li><p><a class="reference internal" href="#whats-next"><span class="xref myst">Whats next</span></a></p></li>
</ol>
</section>
<section id="prerequisites">
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this heading"></a></h2>
<p>To get most out of this tutorial you should already have a basic understanding of the following.</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.python.org/">Python</a></p></li>
</ul>
<p>Also you need to have the following installed.</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.python.org/">Python</a></p></li>
<li><p><a class="reference external" href="https://pip.sh-edraft.de">Pip</a></p></li>
<li><p><a class="reference internal" href="setup.html"><span class="doc std std-doc">CPL</span></a></p></li>
<li><p><a class="reference internal" href="setup.html"><span class="doc std std-doc">CPL-CLI</span></a></p></li>
</ul>
</section>
<section id="create-the-project">
<h2>Create the project<a class="headerlink" href="#create-the-project" title="Permalink to this heading"></a></h2>
<p>To create the sample project to the following:</p>
<ol class="arabic">
<li><p>Open a terminal</p></li>
<li><p>Run</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>cpl<span class="w"> </span>new<span class="w"> </span>console<span class="w"> </span>sample-project
</pre></div>
</div>
</li>
<li><p>We dont want to use Application base or Dependency injection:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>Do<span class="w"> </span>you<span class="w"> </span>want<span class="w"> </span>to<span class="w"> </span>use<span class="w"> </span>application<span class="w"> </span>base?<span class="w"> </span><span class="o">(</span>y/n<span class="o">)</span><span class="w"> </span>n
Do<span class="w"> </span>you<span class="w"> </span>want<span class="w"> </span>to<span class="w"> </span>use<span class="w"> </span>service<span class="w"> </span>providing?<span class="w"> </span><span class="o">(</span>y/n<span class="o">)</span><span class="w"> </span>n
</pre></div>
</div>
<p>The ouput should look like this:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>Creating<span class="w"> </span>sample-project/LICENSE<span class="w"> </span><span class="k">done</span>
Creating<span class="w"> </span>sample-project/README.md<span class="w"> </span><span class="k">done</span>
Creating<span class="w"> </span>sample-project/src/tests/__init__.py<span class="w"> </span><span class="k">done</span>
Creating<span class="w"> </span>sample-project/appsettings.json<span class="w"> </span><span class="k">done</span>
Creating<span class="w"> </span>sample-project/src/sample-project/__init__.py<span class="w"> </span><span class="k">done</span>
Creating<span class="w"> </span>sample-project/src/sample-projectmain.py<span class="w"> </span><span class="k">done</span>
</pre></div>
</div>
</li>
<li><p>Open the project with an IDE like VS Code or PyCharm</p>
<p><img alt="IDE" src="_images/ide.png" /></p>
</li>
<li><p>Set the src directory as source folder</p>
<p><img alt="IDE set src folder" src="_images/ide-src.png" /></p>
</li>
<li><p>Run the application</p>
<p>You should see an output like:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>Hello<span class="w"> </span>World
</pre></div>
</div>
</li>
<li><p>In PyCharm you have to enable <code class="docutils literal notranslate"><span class="pre">Emulate</span> <span class="pre">terminal</span> <span class="pre">in</span> <span class="pre">output</span> <span class="pre">console</span></code>!</p>
<p><img alt="IDE emulate console" src="_images/ide-emulate.png" /></p>
</li>
</ol>
</section>
<section id="create-a-menu">
<h2>Create a menu<a class="headerlink" href="#create-a-menu" title="Permalink to this heading"></a></h2>
<ol class="arabic">
<li><p>Open the sample-project/main.py</p></li>
<li><p>Change Hello World to Password generator: in line 5</p></li>
<li><p>Add <code class="docutils literal notranslate"><span class="pre">Console.select</span></code> as follows:</p>
<div class="highlight-py notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">cpl_core.console</span> <span class="kn">import</span> <span class="n">Console</span>
<span class="k">def</span> <span class="nf">main</span><span class="p">():</span>
<span class="n">Console</span><span class="o">.</span><span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;Password generator:&#39;</span><span class="p">)</span>
<span class="n">options</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">&#39;Only lower case&#39;</span><span class="p">,</span>
<span class="s1">&#39;Only upper case&#39;</span><span class="p">,</span>
<span class="s1">&#39;Lower and upper case&#39;</span>
<span class="s1">&#39;Exit&#39;</span>
<span class="p">]</span>
<span class="n">option</span> <span class="o">=</span> <span class="n">Console</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s1">&#39;&gt;&#39;</span><span class="p">,</span> <span class="s1">&#39;Select option: &#39;</span><span class="p">,</span> <span class="n">options</span><span class="p">)</span>
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>
<span class="n">main</span><span class="p">()</span>
</pre></div>
</div>
</li>
<li><p>Get Id of the selected option:</p>
<div class="highlight-py notranslate"><div class="highlight"><pre><span></span><span class="n">index</span> <span class="o">=</span> <span class="n">options</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="n">option</span><span class="p">)</span>
</pre></div>
</div>
</li>
<li><p>Create the generate function as follows:</p>
<div class="highlight-py notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">generate_password</span><span class="p">(</span><span class="n">letters</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">length</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
<span class="k">return</span> <span class="s1">&#39;&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">letters</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">length</span><span class="p">))</span>
</pre></div>
</div>
<p>Add imports:</p>
<div class="highlight-py notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">random</span>
<span class="kn">import</span> <span class="nn">string</span>
</pre></div>
</div>
</li>
<li><p>Get length of the password:</p>
<div class="highlight-py notranslate"><div class="highlight"><pre><span></span><span class="n">length</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">Console</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="s1">&#39;Length: &#39;</span><span class="p">))</span>
</pre></div>
</div>
</li>
<li><p>Validate the selected option:</p>
<div class="highlight-py notranslate"><div class="highlight"><pre><span></span><span class="n">index</span> <span class="o">=</span> <span class="n">options</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="n">option</span><span class="p">)</span>
<span class="n">letters</span> <span class="o">=</span> <span class="s1">&#39;&#39;</span>
<span class="k">if</span> <span class="n">index</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
<span class="n">letters</span> <span class="o">=</span> <span class="n">string</span><span class="o">.</span><span class="n">ascii_lowercase</span>
<span class="k">elif</span> <span class="n">index</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>
<span class="n">letters</span> <span class="o">=</span> <span class="n">string</span><span class="o">.</span><span class="n">ascii_uppercase</span>
<span class="k">elif</span> <span class="n">index</span> <span class="o">==</span> <span class="mi">2</span><span class="p">:</span>
<span class="n">letters</span> <span class="o">=</span> <span class="n">string</span><span class="o">.</span><span class="n">ascii_letters</span>
<span class="k">elif</span> <span class="n">index</span> <span class="o">==</span> <span class="nb">len</span><span class="p">(</span><span class="n">options</span><span class="p">)</span> <span class="o">-</span> <span class="mi">1</span><span class="p">:</span>
<span class="n">exit</span><span class="p">()</span>
</pre></div>
</div>
</li>
<li><p>Print the generated password:</p>
<div class="highlight-py notranslate"><div class="highlight"><pre><span></span><span class="n">Console</span><span class="o">.</span><span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;Password: &#39;</span><span class="p">,</span> <span class="n">generate_password</span><span class="p">(</span><span class="n">letters</span><span class="p">,</span> <span class="n">length</span><span class="p">))</span>
</pre></div>
</div>
</li>
<li><p>The full sample-project/main.py:</p>
<div class="highlight-py notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">random</span>
<span class="kn">import</span> <span class="nn">string</span>
<span class="kn">from</span> <span class="nn">cpl_core.console</span> <span class="kn">import</span> <span class="n">Console</span>
<span class="k">def</span> <span class="nf">generate_password</span><span class="p">(</span><span class="n">letters</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">length</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
<span class="k">return</span> <span class="s1">&#39;&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">letters</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">length</span><span class="p">))</span>
<span class="k">def</span> <span class="nf">main</span><span class="p">():</span>
<span class="n">Console</span><span class="o">.</span><span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;Password generator:&#39;</span><span class="p">)</span>
<span class="n">options</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">&#39;Only lower case&#39;</span><span class="p">,</span>
<span class="s1">&#39;Only upper case&#39;</span><span class="p">,</span>
<span class="s1">&#39;Lower and upper case&#39;</span><span class="p">,</span>
<span class="s1">&#39;Exit&#39;</span>
<span class="p">]</span>
<span class="n">option</span> <span class="o">=</span> <span class="n">Console</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s1">&#39;&gt;&#39;</span><span class="p">,</span> <span class="s1">&#39;Select option: &#39;</span><span class="p">,</span> <span class="n">options</span><span class="p">)</span>
<span class="n">length</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">Console</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="s1">&#39;Length: &#39;</span><span class="p">))</span>
<span class="n">index</span> <span class="o">=</span> <span class="n">options</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="n">option</span><span class="p">)</span>
<span class="n">letters</span> <span class="o">=</span> <span class="s1">&#39;&#39;</span>
<span class="k">if</span> <span class="n">index</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
<span class="n">letters</span> <span class="o">=</span> <span class="n">string</span><span class="o">.</span><span class="n">ascii_lowercase</span>
<span class="k">elif</span> <span class="n">index</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>
<span class="n">letters</span> <span class="o">=</span> <span class="n">string</span><span class="o">.</span><span class="n">ascii_uppercase</span>
<span class="k">elif</span> <span class="n">index</span> <span class="o">==</span> <span class="mi">2</span><span class="p">:</span>
<span class="n">letters</span> <span class="o">=</span> <span class="n">string</span><span class="o">.</span><span class="n">ascii_letters</span>
<span class="k">elif</span> <span class="n">index</span> <span class="o">==</span> <span class="nb">len</span><span class="p">(</span><span class="n">options</span><span class="p">)</span> <span class="o">-</span> <span class="mi">1</span><span class="p">:</span>
<span class="n">exit</span><span class="p">()</span>
<span class="n">Console</span><span class="o">.</span><span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;Password: &#39;</span><span class="p">,</span> <span class="n">generate_password</span><span class="p">(</span><span class="n">letters</span><span class="p">,</span> <span class="n">length</span><span class="p">))</span>
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>
<span class="n">main</span><span class="p">()</span>
</pre></div>
</div>
</li>
</ol>
</section>
<section id="what-s-next">
<h2>Whats next<a class="headerlink" href="#what-s-next" title="Permalink to this heading"></a></h2>
<p>In this section, youve created an application that uses user input to generate a password.</p>
<p>To continue exploring CPL and developing applications:</p>
<ul class="simple">
<li><p><a class="reference internal" href="cpl_core.application.html"><span class="doc std std-doc">Application base</span></a></p></li>
<li><p><a class="reference internal" href="cpl_core.dependency_injection.html"><span class="doc std std-doc">Dependency injection</span></a></p></li>
<li><p><a class="reference internal" href="cpl_core.console.html"><span class="doc std std-doc">Console</span></a></p></li>
</ul>
<!-- LINKS -->
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="getting_started.html" class="btn btn-neutral float-left" title="Getting started" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="setup.html" class="btn btn-neutral float-right" title="Setting up the local environment and workspace" 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 2021 - 2023, Sven Heidemann.</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>