/usr/share/doc/pyqi/html/guidelines/optparse.html is in pyqi 0.3.2+dfsg-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | <!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=cp1252" />
<title>Guidelines for creating pyqi-based optparse interfaces</title>
<link rel="stylesheet" href="../_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="top" title="pyqi: expose your interface" href="../index.html" />
</head>
<body role="document">
<div class="header" role="banner"><h1 class="heading"><a href="../index.html">
<span>pyqi: expose your interface</span></a></h1>
<h2 class="heading"><span>Guidelines for creating pyqi-based optparse interfaces</span></h2>
</div>
<div class="topnav" role="navigation" aria-label="top navigation">
<p>
<a class="uplink" href="../index.html">Contents</a>
</p>
</div>
<div class="content">
<div class="section" id="guidelines-for-creating-pyqi-based-optparse-interfaces">
<span id="optparse-guidelines"></span><h1>Guidelines for creating pyqi-based optparse interfaces</h1>
<p>This document covers some general suggestions for <code class="docutils literal"><span class="pre">OptparseInterfaces</span></code> with pyqi. These ideas have evolved from our experiences with <a class="reference external" href="http://www.qiime.org">QIIME</a>. Ideally this document will continue to evolve with time, so if you have suggestions for things that should be included please consider submitting them as a <a class="reference external" href="https://help.github.com/articles/using-pull-requests">pull request</a>.</p>
<p><strong>Design convenient command line interfaces.</strong> The goal of your interface is to make things easy for the user (who is often you). This section covers some guidelines for how to do that.</p>
<p><strong>Have people who are better programmers than you interact with your command line interface and give you feedback on it.</strong> If your script is difficult to work with, or has requirements that are not intuitive for users who frequently work with command line applications, people won’t use your code.</p>
<p><strong>If there are tasks that are automatable, automate them.</strong> For example, if you can make a good guess at what an output file should be named from an input file and a parameter choice, do that and use it as the default output path (but allow the user to overwrite it with a command line option).</p>
<p><strong>Define sensible default values for your command line options.</strong> If most of the time that a script is used it will require a parameter to be set to a certain value, make that value the default to simplify the interface.</p>
<p><strong>Have the user specify named options rather than positional arguments.</strong> The latter are more difficult to work with as users need to remember the order that they need to be passed. pyqi scripts do not allow positional arguments. Note that the idea of avoiding positional arguments contradicts <a class="reference external" href="http://docs.python.org/2/library/optparse.html#what-are-options-for">what Python’s optparse docs say</a>. We disagree with their comment that all required options should be passed as positional arguments.</p>
<p><strong>Avoid making assumptions about how a script will be run.</strong> Perhaps most importantly, don’t assume that the script will be run from the same directory that the script lives in. Users often want to copy executables into a centralized directory on their system (e.g., <code class="docutils literal"><span class="pre">/usr/local/bin</span></code>). Facilitate that by not requiring that the script is run from a specific location. If you rely on data files, you have other options such as having users set an environment variable that defines where data files live on the system. Test your script from multiple locations on the file system!</p>
<p><strong>Test calling your script in invalid ways to ensure that it provides informative error messages.</strong> Python’s traceback errors are generally not very informative for users, so you should test calling your scripts incorrectly to detect cases when the script might result in uninformative error messages. You should then catch these cases and provide useful error messages.</p>
<p><strong>Define where output will be stored based on how many output files are created.</strong> If a single file is created by your script, give the user control over the output filepath on the command line (usually with a parameter named <code class="docutils literal"><span class="pre">-o</span></code> or <code class="docutils literal"><span class="pre">--output-fp</span></code>). If multiple files are created by your script, allow the user to define a directory name, and store all of the output files in that directory with names that you pre-define within your script. Define these options using the option types <code class="docutils literal"><span class="pre">new_filepath</span></code> and <code class="docutils literal"><span class="pre">new_dirpath</span></code>, respectively. These will raise errors if the file or directory already exists, which is generally good as it avoids overwriting results that may have taken a long time to generate. We’ve found that this is the most convenient way for users to define where the output of scripts should live, but there are likely special cases where you’d want to deviate from this general guideline. Do <em>always</em> give the user control over the name of either the file or the directory where output will be created. You don’t want them to have to move a file to a different location if they want to run your script multiple times.</p>
</div>
</div>
<div class="bottomnav" role="navigation" aria-label="bottom navigation">
<p>
<a class="uplink" href="../index.html">Contents</a>
</p>
</div>
<div class="footer" role="contentinfo">
© Copyright 2016, The BiPy Development Team.
Last updated on Jul 11, 2016.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.4.
</div>
</body>
</html>
|