mirror of
https://github.com/redoules/redoules.github.io.git
synced 2025-12-12 15:59:34 +00:00
281 lines
17 KiB
HTML
281 lines
17 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="fr">
|
|
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags -->
|
|
<meta name="description" content="Data Science for Political and Social Phenomena">
|
|
<meta name="author" content="Guillaume Redoulès">
|
|
<link rel="icon" href="../favicon.ico">
|
|
|
|
<title>Advice for designing your own libraries - Python</title>
|
|
|
|
<!-- JQuery -->
|
|
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
|
|
<script>
|
|
window.jQuery || document.write('<script src="../theme/js/jquery.min.js"><\/script>')
|
|
</script>
|
|
|
|
<!-- Bootstrap core CSS -->
|
|
<link rel="stylesheet" href="../theme/css/bootstrap.css" />
|
|
<!-- IE10 viewport hack for Surface/desktop Windows 8 bug -->
|
|
<link rel="stylesheet" type="text/css" href="../theme/css/ie10-viewport-bug-workaround.css" />
|
|
<!-- Custom styles for this template -->
|
|
<link rel="stylesheet" type="text/css" href="../theme/css/style.css" />
|
|
<link rel="stylesheet" type="text/css" href="../theme/css/notebooks.css" />
|
|
<link href='https://fonts.googleapis.com/css?family=PT+Serif:400,700|Roboto:400,500,700' rel='stylesheet' type='text/css'>
|
|
|
|
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
|
|
<!--[if lt IE 9]>
|
|
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
|
|
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
|
|
<![endif]-->
|
|
|
|
|
|
<meta name="tags" content="Basics" />
|
|
|
|
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div class="navbar navbar-fixed-top">
|
|
<div class="container">
|
|
<div class="navbar-header">
|
|
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
</button>
|
|
<a class="navbar-brand" href="..">Guillaume Redoulès</a>
|
|
</div>
|
|
<div class="navbar-collapse collapse" id="searchbar">
|
|
|
|
<ul class="nav navbar-nav navbar-right">
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">About<span class="caret"></span></a>
|
|
<ul class="dropdown-menu">
|
|
<li><a href="../pages/about.html">About Guillaume</a></li>
|
|
<li><a href="https://github.com/redoules">GitHub</a></li>
|
|
<li><a href="https://www.linkedin.com/in/guillaume-redoul%C3%A8s-33923860/">LinkedIn</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Data Science<span class="caret"></span></a>
|
|
<ul class="dropdown-menu">
|
|
<li><a href="..#Blog">Blog</a></li>
|
|
<li><a href="..#Python">Python</a></li>
|
|
<li><a href="..#Bash">Bash</a></li>
|
|
<li><a href="..#SQL">SQL</a></li>
|
|
<li><a href="..#Mathematics">Mathematics</a></li>
|
|
<li><a href="..#Machine_Learning">Machine Learning</a></li>
|
|
<li><a href="..#Projects">Projects</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Projects<span class="caret"></span></a>
|
|
<ul class="dropdown-menu">
|
|
<li><a href="https://github.com/redoules/redoules.github.io">Notes (Github)</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<!--<li class="dropdown">
|
|
<a href="../feeds/blog.rss.xml">Blog RSS</a>
|
|
</li>-->
|
|
|
|
|
|
</ul>
|
|
|
|
<form class="navbar-form" action="../search.html" onsubmit="return validateForm(this.elements['q'].value);">
|
|
<div class="form-group" style="display:inline;">
|
|
<div class="input-group" style="display:table;">
|
|
<span class="input-group-addon" style="width:1%;"><span class="glyphicon glyphicon-search"></span></span>
|
|
<input class="form-control search-query" name="q" id="tipue_search_input" placeholder="e.g. scikit KNN, pandas merge" required autocomplete="off" type="text">
|
|
</div>
|
|
</div>
|
|
</form>
|
|
|
|
</div>
|
|
<!--/.nav-collapse -->
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
<!-- end of header section -->
|
|
<div class="container">
|
|
<!-- <div class="alert alert-warning" role="alert">
|
|
Did you find this page useful? Please do me a quick favor and <a href="#" class="alert-link">endorse me for data science on LinkedIn</a>.
|
|
</div> -->
|
|
<section id="content" class="body">
|
|
<header>
|
|
<h1>
|
|
Advice for designing your own libraries
|
|
</h1>
|
|
<ol class="breadcrumb">
|
|
<li>
|
|
<time class="published" datetime="2018-10-29T20:31:00+01:00">
|
|
29 octobre 2018
|
|
</time>
|
|
</li>
|
|
<li>Python</li>
|
|
<li>Basics</li>
|
|
</ol>
|
|
</header>
|
|
<div class='article_content'>
|
|
<h1>Advice for designing your own libraries</h1>
|
|
<p>When designing your own library make sure to think of the following things. I will add new paragraphs to this article as I dicover new good practices. </p>
|
|
<h2>Use standard python objects</h2>
|
|
<p>Try to use standard python objects as much as possible. That way, your library becomes compatible with all the other python libaries.</p>
|
|
<p>For instance, when I created SAMpy : a library for reading and writing SAMCEF results, it returned dictonnaries, lists and pandas dataframes. Hence the results extracted from SAMCEF where compatible with all the scientific stack of python.</p>
|
|
<h2>Limit the number of functionnalities</h2>
|
|
<p>Following the same logic as before, the objects should do only one thing but do it well. Indeed, having a simple interface will reduce the complexity of your code and make it easier to use your library.</p>
|
|
<p>Again, with SAMpy, I decided to strictly limit the functionnalities to reading and writing SAMCEF files. </p>
|
|
<h2>Define an exception class for your library</h2>
|
|
<p>You should define your own exceptions in order to make it easier for your users to debug their code thanks to clearer messages that convey more meaning. That way, the user will know if the error comes from your library or something else.</p>
|
|
<p>Bonus if you group similar exceptions in a hierachy of inerited Exception classes.</p>
|
|
<p>Example : let's create a Exception related to the age of a person :</p>
|
|
<div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">check_age</span><span class="p">(</span><span class="n">age</span><span class="p">):</span>
|
|
<span class="k">if</span> <span class="n">age</span> <span class="o"><</span> <span class="mi">0</span> <span class="ow">and</span> <span class="n">age</span> <span class="o">></span> <span class="mi">130</span><span class="p">:</span>
|
|
<span class="k">raise</span> <span class="ne">ValueError</span>
|
|
</pre></div>
|
|
|
|
|
|
<p>If the user inputed an invalid age, the ValueError exception would be thrown. That's fine but imagine you wan't to provide more feedback to your users that don't know the internal of your library. Let's now create a selfexplanatory Exception </p>
|
|
<div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">AgeInvalidError</span><span class="p">(</span><span class="ne">ValueError</span><span class="p">):</span>
|
|
<span class="k">pass</span>
|
|
<span class="k">def</span> <span class="nf">check_age</span><span class="p">(</span><span class="n">age</span><span class="p">):</span>
|
|
<span class="k">if</span> <span class="n">age</span> <span class="o"><</span> <span class="mi">0</span> <span class="ow">and</span> <span class="n">age</span> <span class="o">></span> <span class="mi">130</span><span class="p">:</span>
|
|
<span class="k">raise</span> <span class="n">AgeInvalidError</span><span class="p">(</span><span class="n">age</span><span class="p">)</span>
|
|
</pre></div>
|
|
|
|
|
|
<p>You can also add some helpful text to guide your users along the way:</p>
|
|
<div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">AgeInvalidError</span><span class="p">(</span><span class="ne">ValueError</span><span class="p">):</span>
|
|
<span class="k">print</span><span class="p">(</span><span class="s2">"Age invalid, must be between 0 and 130"</span><span class="p">)</span>
|
|
<span class="k">pass</span>
|
|
<span class="k">def</span> <span class="nf">check_age</span><span class="p">(</span><span class="n">age</span><span class="p">):</span>
|
|
<span class="k">if</span> <span class="n">age</span> <span class="o"><</span> <span class="mi">0</span> <span class="ow">and</span> <span class="n">age</span> <span class="o">></span> <span class="mi">130</span><span class="p">:</span>
|
|
<span class="k">raise</span> <span class="n">AgeInvalidError</span><span class="p">(</span><span class="n">age</span><span class="p">)</span>
|
|
</pre></div>
|
|
|
|
|
|
<p>If you want to group all the logically linked exceptions, you can create a base class and inherit from it :</p>
|
|
<div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">BaseAgeInvalidError</span><span class="p">(</span><span class="ne">ValueError</span><span class="p">):</span>
|
|
<span class="k">pass</span>
|
|
<span class="k">class</span> <span class="nc">TooYoungError</span><span class="p">(</span><span class="n">BaseAgeInvalidError</span><span class="p">):</span>
|
|
<span class="k">pass</span>
|
|
<span class="k">class</span> <span class="nc">TooOldError</span><span class="p">(</span><span class="n">BaseAgeInvalidError</span><span class="p">):</span>
|
|
<span class="k">pass</span>
|
|
|
|
|
|
<span class="k">def</span> <span class="nf">check_age</span><span class="p">(</span><span class="n">age</span><span class="p">):</span>
|
|
<span class="k">if</span> <span class="n">age</span> <span class="o"><</span> <span class="mi">0</span><span class="p">:</span>
|
|
<span class="k">raise</span> <span class="n">TooYoungError</span><span class="p">(</span><span class="n">age</span><span class="p">)</span>
|
|
<span class="k">elif</span> <span class="n">age</span> <span class="o">></span> <span class="mi">130</span> <span class="p">:</span>
|
|
<span class="k">raise</span> <span class="n">TooOldError</span><span class="p">(</span><span class="n">age</span><span class="p">)</span>
|
|
</pre></div>
|
|
|
|
|
|
<h2>Structure your repository</h2>
|
|
<p>You should have a file structure in your repository. It will help other contributers especially future contributers.</p>
|
|
<p>A nice directory structure for your project should look like this:</p>
|
|
<div class="highlight"><pre><span></span>README.md
|
|
LICENSE
|
|
setup.py
|
|
requirements.txt
|
|
./MyPackage
|
|
./docs
|
|
./tests
|
|
</pre></div>
|
|
|
|
|
|
<p>Some prefer to use reStructured Text, I personnaly prefer Markdown</p>
|
|
<p><a href="https://choosealicense.com">choosealicense.com</a> will help you pick the license to use for your project.</p>
|
|
<p>For package and distribution management, create a setup.py file a the root of the directory
|
|
The list of dependencies required to test, build and generate the doc are listed in a <a href="https://pip.pypa.io/en/stable/user_guide/#requirements-files">pip requirement file</a> placed a the root of the directory and named requirements.txt </p>
|
|
<p>Put the documentation of your library in the docs directory.</p>
|
|
<p>Put your tests in the tests directory. Since your tests will need to import your library, I recommend modifying the path to resolve your package property.</p>
|
|
<p>In order to do so, you can create a context.py file located in the tests directory : </p>
|
|
<div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span>
|
|
<span class="kn">import</span> <span class="nn">sys</span>
|
|
<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="vm">__file__</span><span class="p">),</span> <span class="s1">'..'</span><span class="p">)))</span>
|
|
|
|
<span class="kn">import</span> <span class="nn">MyPackage</span>
|
|
</pre></div>
|
|
|
|
|
|
<p>Then within your individual test files you can import your package like so :</p>
|
|
<div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">.context</span> <span class="kn">import</span> <span class="n">MyPackage</span>
|
|
</pre></div>
|
|
|
|
|
|
<p>Finally, your code will go into the MyPackage directory</p>
|
|
<h2>Test your code</h2>
|
|
<p>Once your library is in production, you have to guaranty some level of forward compatibility. Once your interface is defined, write some tests. In the future, when your code is modified, having those tests will make sure that the behaviour of your functions and objects won't be altered.</p>
|
|
<h2>Document your code</h2>
|
|
<p>Of course, you should have a documentation to go along with your library. Make sure to add a lot of commun examples as most users tend to learn from examples.</p>
|
|
<p>I recommend writing your documentation using Sphinx. </p>
|
|
</div>
|
|
<aside>
|
|
<div class="bug-reporting__panel">
|
|
<h3>Find an error or bug? Have a suggestion?</h3>
|
|
<p>Everything on this site is avaliable on GitHub. Head on over and <a href='https://github.com/redoules/redoules.github.io/issues/new'>submit an issue.</a> You can also message me directly by <a href='mailto:guillaume.redoules@gadz.org'>email</a>.</p>
|
|
</div>
|
|
</aside>
|
|
</section>
|
|
|
|
</div>
|
|
<!-- start of footer section -->
|
|
<footer class="footer">
|
|
<div class="container">
|
|
<p class="text-muted">
|
|
<center>This project contains 79 pages and is available on <a href="https://github.com/redoules/redoules.github.io">GitHub</a>.
|
|
<br/>
|
|
Copyright © Guillaume Redoulès,
|
|
<time datetime="2018">2018</time>.
|
|
</center>
|
|
</p>
|
|
</div>
|
|
</footer>
|
|
|
|
<!-- This jQuery line finds any span that contains code highlighting classes and then selects the parent <pre> tag and adds a border. This is done as a workaround to visually distinguish the code inputs and outputs -->
|
|
<script>
|
|
$( ".hll, .n, .c, .err, .k, .o, .cm, .cp, .c1, .cs, .gd, .ge, .gr, .gh, .gi, .go, .gp, .gs, .gu, .gt, .kc, .kd, .kn, .kp, .kr, .kt, .m, .s, .na, .nb, .nc, .no, .nd, .ni, .ne, .nf, .nl, .nn, .nt, .nv, .ow, .w, .mf, .mh, .mi, .mo, .sb, .sc, .sd, .s2, .se, .sh, .si, .sx, .sr, .s1, .ss, .bp, .vc, .vg, .vi, .il" ).parent( "pre" ).css( "border", "1px solid #DEDEDE" );
|
|
</script>
|
|
|
|
|
|
<!-- Load Google Analytics -->
|
|
<script>
|
|
/*
|
|
(function(i, s, o, g, r, a, m) {
|
|
i['GoogleAnalyticsObject'] = r;
|
|
i[r] = i[r] || function() {
|
|
(i[r].q = i[r].q || []).push(arguments)
|
|
}, i[r].l = 1 * new Date();
|
|
a = s.createElement(o),
|
|
m = s.getElementsByTagName(o)[0];
|
|
a.async = 1;
|
|
a.src = g;
|
|
m.parentNode.insertBefore(a, m)
|
|
})(window, document, 'script', '//www.google-analytics.com/analytics.js', 'ga');
|
|
|
|
ga('create', 'UA-66582-32', 'auto');
|
|
ga('send', 'pageview');
|
|
*/
|
|
</script>
|
|
<!-- End of Google Analytics -->
|
|
|
|
<!-- Bootstrap core JavaScript
|
|
================================================== -->
|
|
<!-- Placed at the end of the document so the pages load faster -->
|
|
<script src="../theme/js/bootstrap.min.js"></script>
|
|
<!-- IE10 viewport hack for Surface/desktop Windows 8 bug -->
|
|
<script src="../theme/js/ie10-viewport-bug-workaround.js"></script>
|
|
|
|
|
|
</body>
|
|
|
|
</html> |