site/docs/3.3.1/api/python/development/contributing.html - spark-website - Git at Google


 <!DOCTYPE html>

 <html>
   <head>
     <meta charset="utf-8" />
     <title>Contributing to PySpark &#8212; PySpark 3.3.1 documentation</title>

   <link rel="stylesheet" href="../_static/css/index.73d71520a4ca3b99cfee5594769eaaae.css">


   <link rel="stylesheet"
     href="../_static/vendor/fontawesome/5.13.0/css/all.min.css">
   <link rel="preload" as="font" type="font/woff2" crossorigin
     href="../_static/vendor/fontawesome/5.13.0/webfonts/fa-solid-900.woff2">
   <link rel="preload" as="font" type="font/woff2" crossorigin
     href="../_static/vendor/fontawesome/5.13.0/webfonts/fa-brands-400.woff2">


   <link rel="stylesheet"
     href="../_static/vendor/open-sans_all/1.44.1/index.css">
   <link rel="stylesheet"
     href="../_static/vendor/lato_latin-ext/1.44.1/index.css">


     <link rel="stylesheet" href="../_static/basic.css" type="text/css" />
     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
     <link rel="stylesheet" type="text/css" href="../_static/css/pyspark.css" />

   <link rel="preload" as="script" href="../_static/js/index.3da636dd464baa7582d2.js">

     <script id="documentation_options" data-url_root="../" 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/language_data.js"></script>
     <script src="../_static/copybutton.js"></script>
     <script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
     <script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
     <script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"inlineMath": [["$", "$"], ["\\(", "\\)"]], "processEscapes": true, "ignoreClass": "document", "processClass": "math|output_area"}})</script>
     <link rel="search" title="Search" href="../search.html" />
     <link rel="next" title="Testing PySpark" href="testing.html" />
     <link rel="prev" title="Development" href="index.html" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="docsearch:language" content="en" />
   </head>
   <body data-spy="scroll" data-target="#bd-toc-nav" data-offset="80">

     <nav class="navbar navbar-light navbar-expand-lg bg-light fixed-top bd-navbar" id="navbar-main">
 <div class="container-xl">

     <a class="navbar-brand" href="../index.html">

       <img src="../_static/spark-logo-reverse.png" class="logo" alt="logo" />

     </a>
     <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbar-menu" aria-controls="navbar-menu" aria-expanded="false" aria-label="Toggle navigation">
         <span class="navbar-toggler-icon"></span>
     </button>

     <div id="navbar-menu" class="col-lg-9 collapse navbar-collapse">
       <ul id="navbar-main-elements" class="navbar-nav mr-auto">


         <li class="nav-item ">
             <a class="nav-link" href="../getting_started/index.html">Getting Started</a>
         </li>

         <li class="nav-item ">
             <a class="nav-link" href="../user_guide/index.html">User Guide</a>
         </li>

         <li class="nav-item ">
             <a class="nav-link" href="../reference/index.html">API Reference</a>
         </li>

         <li class="nav-item active">
             <a class="nav-link" href="index.html">Development</a>
         </li>

         <li class="nav-item ">
             <a class="nav-link" href="../migration_guide/index.html">Migration Guide</a>
         </li>


       </ul>


       <ul class="navbar-nav">


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


     <div class="container-xl">
       <div class="row">

           <div class="col-12 col-md-3 bd-sidebar"><form class="bd-search d-flex align-items-center" action="../search.html" method="get">
   <i class="icon fas fa-search"></i>
   <input type="search" class="form-control" name="q" id="search-input" placeholder="Search the docs ..." aria-label="Search the docs ..." autocomplete="off" >
 </form>
 <nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">

     <div class="bd-toc-item active">


     <ul class="nav bd-sidenav">


                 <li class="active">
                     <a href="">Contributing to PySpark</a>
                 </li>


                 <li class="">
                     <a href="testing.html">Testing PySpark</a>
                 </li>


                 <li class="">
                     <a href="debugging.html">Debugging PySpark</a>
                 </li>


                 <li class="">
                     <a href="setting_ide.html">Setting up IDEs</a>
                 </li>


       </ul>

   </nav>
           </div>


           <div class="d-none d-xl-block col-xl-2 bd-toc">

 <div class="tocsection onthispage pt-5 pb-3">
     <i class="fas fa-list"></i> On this page
 </div>

 <nav id="bd-toc-nav">
     <ul class="nav section-nav flex-column">

         <li class="nav-item toc-entry toc-h2">
             <a href="#contributing-by-testing-releases" class="nav-link">Contributing by Testing Releases</a>
         </li>

         <li class="nav-item toc-entry toc-h2">
             <a href="#contributing-documentation-changes" class="nav-link">Contributing Documentation Changes</a>
         </li>

         <li class="nav-item toc-entry toc-h2">
             <a href="#preparing-to-contribute-code-changes" class="nav-link">Preparing to Contribute Code Changes</a>
         </li>

         <li class="nav-item toc-entry toc-h2">
             <a href="#environment-setup" class="nav-link">Environment Setup</a><ul class="nav section-nav flex-column">

         <li class="nav-item toc-entry toc-h3">
             <a href="#prerequisite" class="nav-link">Prerequisite</a>
         </li>

         <li class="nav-item toc-entry toc-h3">
             <a href="#conda" class="nav-link">Conda</a>
         </li>

         <li class="nav-item toc-entry toc-h3">
             <a href="#pip" class="nav-link">pip</a>
         </li>

             </ul>
         </li>

         <li class="nav-item toc-entry toc-h2">
             <a href="#contributing-and-maintaining-type-hints" class="nav-link">Contributing and Maintaining Type Hints</a>
         </li>

         <li class="nav-item toc-entry toc-h2">
             <a href="#code-and-docstring-guide" class="nav-link">Code and Docstring Guide</a><ul class="nav section-nav flex-column">

         <li class="nav-item toc-entry toc-h3">
             <a href="#code-conventions" class="nav-link">Code Conventions</a>
         </li>

         <li class="nav-item toc-entry toc-h3">
             <a href="#docstring-conventions" class="nav-link">Docstring Conventions</a>
         </li>

         <li class="nav-item toc-entry toc-h3">
             <a href="#doctest-conventions" class="nav-link">Doctest Conventions</a>
         </li>

             </ul>
         </li>

     </ul>
 </nav>


           </div>


           <main class="col-12 col-md-9 col-xl-7 py-md-5 pl-md-5 pr-md-4 bd-content" role="main">

               <div>

   <div class="section" id="contributing-to-pyspark">
 <h1>Contributing to PySpark<a class="headerlink" href="#contributing-to-pyspark" title="Permalink to this headline">¶</a></h1>
 <p>There are many types of contribution, for example, helping other users, testing releases, reviewing changes,
 documentation contribution, bug reporting, JIRA maintenance, code changes, etc.
 These are documented at <a class="reference external" href="https://spark.apache.org/contributing.html">the general guidelines</a>.
 This page focuses on PySpark and includes additional details specifically for PySpark.</p>
 <div class="section" id="contributing-by-testing-releases">
 <h2>Contributing by Testing Releases<a class="headerlink" href="#contributing-by-testing-releases" title="Permalink to this headline">¶</a></h2>
 <p>Before the official release, PySpark release candidates are shared in the <a class="reference external" href="https://mail-archives.apache.org/mod_mbox/spark-dev/">dev&#64;spark.apache.org</a> mailing list to vote on.
 This release candidates can be easily installed via pip. For example, in case of Spark 3.0.0 RC1, you can install as below:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip install https://dist.apache.org/repos/dist/dev/spark/v3.0.0-rc1-bin/pyspark-3.0.0.tar.gz
 </pre></div>
 </div>
 <p>The link for release files such as <code class="docutils literal notranslate"><span class="pre">https://dist.apache.org/repos/dist/dev/spark/v3.0.0-rc1-bin</span></code> can be found in the vote thread.</p>
 <p>Testing and verifying users’ existing workloads against release candidates is one of the vital contributions to PySpark.
 It prevents breaking users’ existing workloads before the official release.
 When there is an issue such as a regression, correctness problem or performance degradation worth enough to drop the release candidate,
 usually the release candidate is dropped and the community focuses on fixing it to include in the next release candidate.</p>
 </div>
 <div class="section" id="contributing-documentation-changes">
 <h2>Contributing Documentation Changes<a class="headerlink" href="#contributing-documentation-changes" title="Permalink to this headline">¶</a></h2>
 <p>The release documentation is located under Spark’s <a class="reference external" href="https://github.com/apache/spark/tree/master/docs">docs</a> directory.
 <a class="reference external" href="https://github.com/apache/spark/blob/master/docs/README.md">README.md</a> describes the required dependencies and steps
 to generate the documentations. Usually, PySpark documentation is tested with the command below
 under the <a class="reference external" href="https://github.com/apache/spark/tree/master/docs">docs</a> directory:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">SKIP_SCALADOC</span><span class="o">=</span><span class="m">1</span> <span class="nv">SKIP_RDOC</span><span class="o">=</span><span class="m">1</span> <span class="nv">SKIP_SQLDOC</span><span class="o">=</span><span class="m">1</span> bundle <span class="nb">exec</span> jekyll serve --watch
 </pre></div>
 </div>
 <p>PySpark uses Sphinx to generate its release PySpark documentation. Therefore, if you want to build only PySpark documentation alone,
 you can build under <a class="reference external" href="https://github.com/apache/spark/tree/master/python">python/docs</a> directory by:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make html
 </pre></div>
 </div>
 <p>It generates the corresponding HTMLs under <code class="docutils literal notranslate"><span class="pre">python/docs/build/html</span></code>.</p>
 <p>Lastly, please make sure that the new APIs are documented by manually adding methods and/or classes at the corresponding RST files
 under <code class="docutils literal notranslate"><span class="pre">python/docs/source/reference</span></code>. Otherwise, they would not be documented in PySpark documentation.</p>
 </div>
 <div class="section" id="preparing-to-contribute-code-changes">
 <h2>Preparing to Contribute Code Changes<a class="headerlink" href="#preparing-to-contribute-code-changes" title="Permalink to this headline">¶</a></h2>
 <p>Before starting to work on codes in PySpark, it is recommended to read <a class="reference external" href="https://spark.apache.org/contributing.html">the general guidelines</a>.
 Additionally, there are a couple of additional notes to keep in mind when contributing to codes in PySpark:</p>
 <ul class="simple">
 <li><dl class="simple">
 <dt>Be Pythonic</dt><dd><p>See <a class="reference external" href="https://www.python.org/dev/peps/pep-0020/">The Zen of Python</a>.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
 <dt>Match APIs with Scala and Java sides</dt><dd><p>Apache Spark is an unified engine that provides a consistent API layer. In general, the APIs are consistently supported across other languages.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
 <dt>PySpark-specific APIs can be accepted</dt><dd><p>As long as they are Pythonic and do not conflict with other existent APIs, it is fine to raise a API request, for example, decorator usage of UDFs.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
 <dt>Adjust the corresponding type hints if you extend or modify public API</dt><dd><p>See <a class="reference internal" href="#contributing-and-maintaining-type-hints">Contributing and Maintaining Type Hints</a> for details.</p>
 </dd>
 </dl>
 </li>
 </ul>
 <p>If you are fixing pandas API on Spark (<code class="docutils literal notranslate"><span class="pre">pyspark.pandas</span></code>) package, please consider the design principles below:</p>
 <ul>
 <li><dl class="simple">
 <dt>Return pandas-on-Spark data structure for big data, and pandas data structure for small data</dt><dd><p>Often developers face the question whether a particular function should return a pandas-on-Spark DataFrame/Series, or a pandas DataFrame/Series. The principle is: if the returned object can be large, use a pandas-on-Spark DataFrame/Series. If the data is bound to be small, use a pandas DataFrame/Series. For example, <code class="docutils literal notranslate"><span class="pre">DataFrame.dtypes</span></code> return a pandas Series, because the number of columns in a DataFrame is bounded and small, whereas <code class="docutils literal notranslate"><span class="pre">DataFrame.head()</span></code> or <code class="docutils literal notranslate"><span class="pre">Series.unique()</span></code> returns a pandas-on-Spark DataFrame/Series, because the resulting object can be large.</p>
 </dd>
 </dl>
 </li>
 <li><dl>
 <dt>Provide discoverable APIs for common data science tasks</dt><dd><p>At the risk of overgeneralization, there are two API design approaches: the first focuses on providing APIs for common tasks; the second starts with abstractions, and enables users to accomplish their tasks by composing primitives. While the world is not black and white, pandas takes more of the former approach, while Spark has taken more of the latter.</p>
 <p>One example is value count (count by some key column), one of the most common operations in data science. pandas <code class="docutils literal notranslate"><span class="pre">DataFrame.value_counts()</span></code> returns the result in sorted order, which in 90% of the cases is what users prefer when exploring data, whereas Spark’s does not sort, which is more desirable when building data pipelines, as users can accomplish the pandas behavior by adding an explicit <code class="docutils literal notranslate"><span class="pre">orderBy</span></code>.</p>
 <p>Similar to pandas, pandas API on Spark should also lean more towards the former, providing discoverable APIs for common data science tasks. In most cases, this principle is well taken care of by simply implementing pandas’ APIs. However, there will be circumstances in which pandas’ APIs don’t address a specific need, e.g. plotting for big data.</p>
 </dd>
 </dl>
 </li>
 <li><dl>
 <dt>Guardrails to prevent users from shooting themselves in the foot</dt><dd><p>Certain operations in pandas are prohibitively expensive as data scales, and we don’t want to give users the illusion that they can rely on such operations in pandas API on Spark. That is to say, methods implemented in pandas API on Spark should be safe to perform by default on large datasets. As a result, the following capabilities are not implemented in pandas API on Spark:</p>
 <ul class="simple">
 <li><p>Capabilities that are fundamentally not parallelizable: e.g. imperatively looping over each element</p></li>
 <li><p>Capabilities that require materializing the entire working set in a single node’s memory. This is why we do not implement <a class="reference external" href="https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_xarray.html">pandas.DataFrame.to_xarray</a>. Another example is the <code class="docutils literal notranslate"><span class="pre">_repr_html_</span></code> call caps the total number of records shown to a maximum of 1000, to prevent users from blowing up their driver node simply by typing the name of the DataFrame in a notebook.</p></li>
 </ul>
 <p>A few exceptions, however, exist. One common pattern with “big data science” is that while the initial dataset is large, the working set becomes smaller as the analysis goes deeper. For example, data scientists often perform aggregation on datasets and want to then convert the aggregated dataset to some local data structure. To help data scientists, we offer the following:</p>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">DataFrame.to_pandas</span></code>: returns a pandas DataFrame (pandas-on-Spark only)</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">DataFrame.to_numpy</span></code>: returns a numpy array, works with both pandas and pandas API on Spark</p></li>
 </ul>
 <p>Note that it is clear from the names that these functions return some local data structure that would require materializing data in a single node’s memory. For these functions, we also explicitly document them with a warning note that the resulting data structure must be small.</p>
 </dd>
 </dl>
 </li>
 </ul>
 </div>
 <div class="section" id="environment-setup">
 <h2>Environment Setup<a class="headerlink" href="#environment-setup" title="Permalink to this headline">¶</a></h2>
 <div class="section" id="prerequisite">
 <h3>Prerequisite<a class="headerlink" href="#prerequisite" title="Permalink to this headline">¶</a></h3>
 <p>PySpark development requires to build Spark that needs a proper JDK installed, etc. See <a class="reference external" href="https://spark.apache.org/docs/latest/building-spark.html">Building Spark</a> for more details.</p>
 </div>
 <div class="section" id="conda">
 <h3>Conda<a class="headerlink" href="#conda" title="Permalink to this headline">¶</a></h3>
 <p>If you are using Conda, the development environment can be set as follows.</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Python 3.7+ is required</span>
 conda create --name pyspark-dev-env <span class="nv">python</span><span class="o">=</span><span class="m">3</span>.9
 conda activate pyspark-dev-env
 pip install -r dev/requirements.txt
 </pre></div>
 </div>
 <p>Once it is set up, make sure you switch to <cite>pyspark-dev-env</cite> before starting the development:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>conda activate pyspark-dev-env
 </pre></div>
 </div>
 <p>Now, you can start developing and <a class="reference internal" href="testing.html"><span class="doc">running the tests</span></a>.</p>
 </div>
 <div class="section" id="pip">
 <h3>pip<a class="headerlink" href="#pip" title="Permalink to this headline">¶</a></h3>
 <p>With Python 3.7+, pip can be used as below to install and set up the development environment.</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip install -r dev/requirements.txt
 </pre></div>
 </div>
 <p>Now, you can start developing and <a class="reference internal" href="testing.html"><span class="doc">running the tests</span></a>.</p>
 </div>
 </div>
 <div class="section" id="contributing-and-maintaining-type-hints">
 <h2>Contributing and Maintaining Type Hints<a class="headerlink" href="#contributing-and-maintaining-type-hints" title="Permalink to this headline">¶</a></h2>
 <p>PySpark type hints are provided using stub files, placed in the same directory as the annotated module, with exception to:</p>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">type:</span> <span class="pre">ignore</span></code> in modules which don’t have their own stubs (tests, examples and non-public API).</p></li>
 <li><p>pandas API on Spark (<code class="docutils literal notranslate"><span class="pre">pyspark.pandas</span></code> package) where the type hints are inlined.</p></li>
 </ul>
 <p>As a rule of thumb, only public API is annotated.</p>
 <p>Annotations should, when possible:</p>
 <ul>
 <li><p>Reflect expectations of the underlying JVM API, to help avoid type related failures outside Python interpreter.</p></li>
 <li><p>In case of conflict between too broad (<code class="docutils literal notranslate"><span class="pre">Any</span></code>) and too narrow argument annotations, prefer the latter as one, as long as it is covering most of the typical use cases.</p></li>
 <li><p>Indicate nonsensical combinations of arguments using <code class="docutils literal notranslate"><span class="pre">&#64;overload</span></code>  annotations. For example, to indicate that <code class="docutils literal notranslate"><span class="pre">*Col</span></code> and <code class="docutils literal notranslate"><span class="pre">*Cols</span></code> arguments are mutually exclusive:</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@overload</span>
 <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span>
     <span class="bp">self</span><span class="p">,</span>
     <span class="o">*</span><span class="p">,</span>
     <span class="n">threshold</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="o">...</span><span class="p">,</span>
     <span class="n">inputCol</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="o">...</span><span class="p">,</span>
     <span class="n">outputCol</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="o">...</span>
 <span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span> <span class="o">...</span>
 <span class="nd">@overload</span>
 <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span>
     <span class="bp">self</span><span class="p">,</span>
     <span class="o">*</span><span class="p">,</span>
     <span class="n">thresholds</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">List</span><span class="p">[</span><span class="nb">float</span><span class="p">]]</span> <span class="o">=</span> <span class="o">...</span><span class="p">,</span>
     <span class="n">inputCols</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">List</span><span class="p">[</span><span class="nb">str</span><span class="p">]]</span> <span class="o">=</span> <span class="o">...</span><span class="p">,</span>
     <span class="n">outputCols</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">List</span><span class="p">[</span><span class="nb">str</span><span class="p">]]</span> <span class="o">=</span> <span class="o">...</span>
 <span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span> <span class="o">...</span>
 </pre></div>
 </div>
 </li>
 <li><p>Be compatible with the current stable MyPy release.</p></li>
 </ul>
 <p>Complex supporting type definitions, should be placed in dedicated <code class="docutils literal notranslate"><span class="pre">_typing.pyi</span></code> stubs. See for example <a class="reference external" href="https://github.com/apache/spark/blob/master/python/pyspark/sql/_typing.pyi">pyspark.sql._typing.pyi</a>.</p>
 <p>Annotations can be validated using <code class="docutils literal notranslate"><span class="pre">dev/lint-python</span></code> script or by invoking mypy directly:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mypy --config python/mypy.ini python/pyspark
 </pre></div>
 </div>
 </div>
 <div class="section" id="code-and-docstring-guide">
 <h2>Code and Docstring Guide<a class="headerlink" href="#code-and-docstring-guide" title="Permalink to this headline">¶</a></h2>
 <div class="section" id="code-conventions">
 <h3>Code Conventions<a class="headerlink" href="#code-conventions" title="Permalink to this headline">¶</a></h3>
 <p>Please follow the style of the existing codebase as is, which is virtually PEP 8 with one exception: lines can be up
 to 100 characters in length, not 79.</p>
 <p>Note that:</p>
 <ul class="simple">
 <li><p>the method and variable names in PySpark are the similar case is <code class="docutils literal notranslate"><span class="pre">threading</span></code> library in Python itself where the APIs were inspired by Java. PySpark also follows <cite>camelCase</cite> for exposed APIs that match with Scala and Java.</p></li>
 <li><p>In contrast, <code class="docutils literal notranslate"><span class="pre">functions.py</span></code> uses <cite>snake_case</cite> in order to make APIs SQL (and Python) friendly.</p></li>
 <li><p>In addition, pandas-on-Spark (<code class="docutils literal notranslate"><span class="pre">pyspark.pandas</span></code>) also uses <cite>snake_case</cite> because this package is free from API consistency with other languages.</p></li>
 </ul>
 <p>PySpark leverages linters such as <a class="reference external" href="https://pycodestyle.pycqa.org/en/latest/">pycodestyle</a> and <a class="reference external" href="https://flake8.pycqa.org/en/latest/">flake8</a>, which <code class="docutils literal notranslate"><span class="pre">dev/lint-python</span></code> runs. Therefore, make sure to run that script to double check.</p>
 </div>
 <div class="section" id="docstring-conventions">
 <h3>Docstring Conventions<a class="headerlink" href="#docstring-conventions" title="Permalink to this headline">¶</a></h3>
 <p>PySpark follows <a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">NumPy documentation style</a>.</p>
 </div>
 <div class="section" id="doctest-conventions">
 <h3>Doctest Conventions<a class="headerlink" href="#doctest-conventions" title="Permalink to this headline">¶</a></h3>
 <p>In general, doctests should be grouped logically by separating a newline.</p>
 <p>For instance, the first block is for the statements for preparation, the second block is for using the function with a specific argument,
 and third block is for another argument. As a example, please refer <a class="reference external" href="https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.rsub.html#pandas.DataFrame.rsub">DataFrame.rsub</a> in pandas.</p>
 <p>These blocks should be consistently separated in PySpark doctests, and more doctests should be added if the coverage of the doctests or the number of examples to show is not enough.</p>
 </div>
 </div>
 </div>


               </div>


               <div class='prev-next-bottom'>

     <a class='left-prev' id="prev-link" href="index.html" title="previous page">Development</a>
     <a class='right-next' id="next-link" href="testing.html" title="next page">Testing PySpark</a>

               </div>

           </main>


       </div>
     </div>


   <script src="../_static/js/index.3da636dd464baa7582d2.js"></script>


     <footer class="footer mt-5 mt-md-0">
   <div class="container">
     <p>
           &copy; Copyright .<br/>
         Created using <a href="http://sphinx-doc.org/">Sphinx</a> 3.0.4.<br/>
     </p>
   </div>
 </footer>
   </body>
 </html>