1120 lines
109 KiB
HTML
1120 lines
109 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<meta property="og:title" content="random — Generate pseudo-random numbers" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="https://docs.python.org/3/library/random.html" />
|
||
<meta property="og:site_name" content="Python documentation" />
|
||
<meta property="og:description" content="Source code: Lib/random.py This module implements pseudo-random number generators for various distributions. For integers, there is uniform selection from a range. For sequences, there is uniform s..." />
|
||
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<meta name="description" content="Source code: Lib/random.py This module implements pseudo-random number generators for various distributions. For integers, there is uniform selection from a range. For sequences, there is uniform s..." />
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="theme-color" content="#3776ab">
|
||
|
||
<title>random — Generate pseudo-random numbers — Python 3.13.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=23252803" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
|
||
|
||
<script src="../_static/documentation_options.js?v=5d57ca2d"></script>
|
||
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.13.3 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="statistics — Mathematical statistics functions" href="statistics.html" />
|
||
<link rel="prev" title="fractions — Rational numbers" href="fractions.html" />
|
||
|
||
<link rel="canonical" href="https://docs.python.org/3/library/random.html">
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
<script type="text/javascript" src="../_static/search-focus.js"></script>
|
||
<script type="text/javascript" src="../_static/themetoggle.js"></script>
|
||
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
|
||
<meta name="readthedocs-addons-api-version" content="1">
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<nav class="nav-content" role="navigation">
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<span class="nav-items-wrapper">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Python logo"/>
|
||
</a>
|
||
<span class="version_switcher_placeholder"></span>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
|
||
</svg>
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />
|
||
<input type="submit" value="Go"/>
|
||
</form>
|
||
</span>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label>
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">random</span></code> — Generate pseudo-random numbers</a><ul>
|
||
<li><a class="reference internal" href="#bookkeeping-functions">Bookkeeping functions</a></li>
|
||
<li><a class="reference internal" href="#functions-for-bytes">Functions for bytes</a></li>
|
||
<li><a class="reference internal" href="#functions-for-integers">Functions for integers</a></li>
|
||
<li><a class="reference internal" href="#functions-for-sequences">Functions for sequences</a></li>
|
||
<li><a class="reference internal" href="#discrete-distributions">Discrete distributions</a></li>
|
||
<li><a class="reference internal" href="#real-valued-distributions">Real-valued distributions</a></li>
|
||
<li><a class="reference internal" href="#alternative-generator">Alternative Generator</a></li>
|
||
<li><a class="reference internal" href="#notes-on-reproducibility">Notes on Reproducibility</a></li>
|
||
<li><a class="reference internal" href="#examples">Examples</a></li>
|
||
<li><a class="reference internal" href="#recipes">Recipes</a></li>
|
||
<li><a class="reference internal" href="#command-line-usage">Command-line usage</a></li>
|
||
<li><a class="reference internal" href="#command-line-example">Command-line example</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="fractions.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">fractions</span></code> — Rational numbers</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="statistics.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">statistics</span></code> — Mathematical statistics functions</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/main/Doc/library/random.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="statistics.html" title="statistics — Mathematical statistics functions"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="fractions.html" title="fractions — Rational numbers"
|
||
accesskey="P">previous</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="numeric.html" accesskey="U">Numeric and Mathematical Modules</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">random</span></code> — Generate pseudo-random numbers</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="module-random">
|
||
<span id="random-generate-pseudo-random-numbers"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">random</span></code> — Generate pseudo-random numbers<a class="headerlink" href="#module-random" title="Link to this heading">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.13/Lib/random.py">Lib/random.py</a></p>
|
||
<hr class="docutils" />
|
||
<p>This module implements pseudo-random number generators for various
|
||
distributions.</p>
|
||
<p>For integers, there is uniform selection from a range. For sequences, there is
|
||
uniform selection of a random element, a function to generate a random
|
||
permutation of a list in-place, and a function for random sampling without
|
||
replacement.</p>
|
||
<p>On the real line, there are functions to compute uniform, normal (Gaussian),
|
||
lognormal, negative exponential, gamma, and beta distributions. For generating
|
||
distributions of angles, the von Mises distribution is available.</p>
|
||
<p>Almost all module functions depend on the basic function <a class="reference internal" href="#random.random" title="random.random"><code class="xref py py-func docutils literal notranslate"><span class="pre">random()</span></code></a>, which
|
||
generates a random float uniformly in the half-open range <code class="docutils literal notranslate"><span class="pre">0.0</span> <span class="pre"><=</span> <span class="pre">X</span> <span class="pre"><</span> <span class="pre">1.0</span></code>.
|
||
Python uses the Mersenne Twister as the core generator. It produces 53-bit precision
|
||
floats and has a period of 2**19937-1. The underlying implementation in C is
|
||
both fast and threadsafe. The Mersenne Twister is one of the most extensively
|
||
tested random number generators in existence. However, being completely
|
||
deterministic, it is not suitable for all purposes, and is completely unsuitable
|
||
for cryptographic purposes.</p>
|
||
<p>The functions supplied by this module are actually bound methods of a hidden
|
||
instance of the <a class="reference internal" href="#random.Random" title="random.Random"><code class="xref py py-class docutils literal notranslate"><span class="pre">random.Random</span></code></a> class. You can instantiate your own
|
||
instances of <a class="reference internal" href="#random.Random" title="random.Random"><code class="xref py py-class docutils literal notranslate"><span class="pre">Random</span></code></a> to get generators that don’t share state.</p>
|
||
<p>Class <a class="reference internal" href="#random.Random" title="random.Random"><code class="xref py py-class docutils literal notranslate"><span class="pre">Random</span></code></a> can also be subclassed if you want to use a different
|
||
basic generator of your own devising: see the documentation on that class for
|
||
more details.</p>
|
||
<p>The <a class="reference internal" href="#module-random" title="random: Generate pseudo-random numbers with various common distributions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">random</span></code></a> module also provides the <a class="reference internal" href="#random.SystemRandom" title="random.SystemRandom"><code class="xref py py-class docutils literal notranslate"><span class="pre">SystemRandom</span></code></a> class which
|
||
uses the system function <a class="reference internal" href="os.html#os.urandom" title="os.urandom"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.urandom()</span></code></a> to generate random numbers
|
||
from sources provided by the operating system.</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>The pseudo-random generators of this module should not be used for
|
||
security purposes. For security or cryptographic uses, see the
|
||
<a class="reference internal" href="secrets.html#module-secrets" title="secrets: Generate secure random numbers for managing secrets."><code class="xref py py-mod docutils literal notranslate"><span class="pre">secrets</span></code></a> module.</p>
|
||
</div>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p>M. Matsumoto and T. Nishimura, “Mersenne Twister: A 623-dimensionally
|
||
equidistributed uniform pseudorandom number generator”, ACM Transactions on
|
||
Modeling and Computer Simulation Vol. 8, No. 1, January pp.3–30 1998.</p>
|
||
<p><a class="reference external" href="https://code.activestate.com/recipes/576707-long-period-random-number-generator/">Complementary-Multiply-with-Carry recipe</a> for a compatible alternative
|
||
random number generator with a long period and comparatively simple update
|
||
operations.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The global random number generator and instances of <a class="reference internal" href="#random.Random" title="random.Random"><code class="xref py py-class docutils literal notranslate"><span class="pre">Random</span></code></a> are thread-safe.
|
||
However, in the free-threaded build, concurrent calls to the global generator or
|
||
to the same instance of <a class="reference internal" href="#random.Random" title="random.Random"><code class="xref py py-class docutils literal notranslate"><span class="pre">Random</span></code></a> may encounter contention and poor performance.
|
||
Consider using separate instances of <a class="reference internal" href="#random.Random" title="random.Random"><code class="xref py py-class docutils literal notranslate"><span class="pre">Random</span></code></a> per thread instead.</p>
|
||
</div>
|
||
<section id="bookkeeping-functions">
|
||
<h2>Bookkeeping functions<a class="headerlink" href="#bookkeeping-functions" title="Link to this heading">¶</a></h2>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.seed">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">seed</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">version</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.seed" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Initialize the random number generator.</p>
|
||
<p>If <em>a</em> is omitted or <code class="docutils literal notranslate"><span class="pre">None</span></code>, the current system time is used. If
|
||
randomness sources are provided by the operating system, they are used
|
||
instead of the system time (see the <a class="reference internal" href="os.html#os.urandom" title="os.urandom"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.urandom()</span></code></a> function for details
|
||
on availability).</p>
|
||
<p>If <em>a</em> is an int, it is used directly.</p>
|
||
<p>With version 2 (the default), a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>, or <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>
|
||
object gets converted to an <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> and all of its bits are used.</p>
|
||
<p>With version 1 (provided for reproducing random sequences from older versions
|
||
of Python), the algorithm for <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> and <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> generates a
|
||
narrower range of seeds.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Moved to the version 2 scheme which uses all of the bits in a string seed.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>The <em>seed</em> must be one of the following types:
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>, <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>, <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>,
|
||
<a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>, or <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.getstate">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">getstate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#random.getstate" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return an object capturing the current internal state of the generator. This
|
||
object can be passed to <a class="reference internal" href="#random.setstate" title="random.setstate"><code class="xref py py-func docutils literal notranslate"><span class="pre">setstate()</span></code></a> to restore the state.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.setstate">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">setstate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">state</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.setstate" title="Link to this definition">¶</a></dt>
|
||
<dd><p><em>state</em> should have been obtained from a previous call to <a class="reference internal" href="#random.getstate" title="random.getstate"><code class="xref py py-func docutils literal notranslate"><span class="pre">getstate()</span></code></a>, and
|
||
<a class="reference internal" href="#random.setstate" title="random.setstate"><code class="xref py py-func docutils literal notranslate"><span class="pre">setstate()</span></code></a> restores the internal state of the generator to what it was at
|
||
the time <a class="reference internal" href="#random.getstate" title="random.getstate"><code class="xref py py-func docutils literal notranslate"><span class="pre">getstate()</span></code></a> was called.</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="functions-for-bytes">
|
||
<h2>Functions for bytes<a class="headerlink" href="#functions-for-bytes" title="Link to this heading">¶</a></h2>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.randbytes">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">randbytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">n</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.randbytes" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Generate <em>n</em> random bytes.</p>
|
||
<p>This method should not be used for generating security tokens.
|
||
Use <a class="reference internal" href="secrets.html#secrets.token_bytes" title="secrets.token_bytes"><code class="xref py py-func docutils literal notranslate"><span class="pre">secrets.token_bytes()</span></code></a> instead.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.9.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="functions-for-integers">
|
||
<h2>Functions for integers<a class="headerlink" href="#functions-for-integers" title="Link to this heading">¶</a></h2>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.randrange">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">randrange</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stop</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.randrange" title="Link to this definition">¶</a></dt>
|
||
<dt class="sig sig-object py">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">randrange</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">start</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stop</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">step</span></span></em><span class="optional">]</span><span class="sig-paren">)</span></dt>
|
||
<dd><p>Return a randomly selected element from <code class="docutils literal notranslate"><span class="pre">range(start,</span> <span class="pre">stop,</span> <span class="pre">step)</span></code>.</p>
|
||
<p>This is roughly equivalent to <code class="docutils literal notranslate"><span class="pre">choice(range(start,</span> <span class="pre">stop,</span> <span class="pre">step))</span></code> but
|
||
supports arbitrarily large ranges and is optimized for common cases.</p>
|
||
<p>The positional argument pattern matches the <a class="reference internal" href="stdtypes.html#range" title="range"><code class="xref py py-func docutils literal notranslate"><span class="pre">range()</span></code></a> function.</p>
|
||
<p>Keyword arguments should not be used because they can be interpreted
|
||
in unexpected ways. For example <code class="docutils literal notranslate"><span class="pre">randrange(start=100)</span></code> is interpreted
|
||
as <code class="docutils literal notranslate"><span class="pre">randrange(0,</span> <span class="pre">100,</span> <span class="pre">1)</span></code>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span><a class="reference internal" href="#random.randrange" title="random.randrange"><code class="xref py py-meth docutils literal notranslate"><span class="pre">randrange()</span></code></a> is more sophisticated about producing equally distributed
|
||
values. Formerly it used a style like <code class="docutils literal notranslate"><span class="pre">int(random()*n)</span></code> which could produce
|
||
slightly uneven distributions.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.12: </span>Automatic conversion of non-integer types is no longer supported.
|
||
Calls such as <code class="docutils literal notranslate"><span class="pre">randrange(10.0)</span></code> and <code class="docutils literal notranslate"><span class="pre">randrange(Fraction(10,</span> <span class="pre">1))</span></code>
|
||
now raise a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.randint">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">randint</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">b</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.randint" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a random integer <em>N</em> such that <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">N</span> <span class="pre"><=</span> <span class="pre">b</span></code>. Alias for
|
||
<code class="docutils literal notranslate"><span class="pre">randrange(a,</span> <span class="pre">b+1)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.getrandbits">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">getrandbits</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">k</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.getrandbits" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Returns a non-negative Python integer with <em>k</em> random bits. This method
|
||
is supplied with the Mersenne Twister generator and some other generators
|
||
may also provide it as an optional part of the API. When available,
|
||
<a class="reference internal" href="#random.getrandbits" title="random.getrandbits"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getrandbits()</span></code></a> enables <a class="reference internal" href="#random.randrange" title="random.randrange"><code class="xref py py-meth docutils literal notranslate"><span class="pre">randrange()</span></code></a> to handle arbitrarily large
|
||
ranges.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.9: </span>This method now accepts zero for <em>k</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="functions-for-sequences">
|
||
<h2>Functions for sequences<a class="headerlink" href="#functions-for-sequences" title="Link to this heading">¶</a></h2>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.choice">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">choice</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">seq</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.choice" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a random element from the non-empty sequence <em>seq</em>. If <em>seq</em> is empty,
|
||
raises <a class="reference internal" href="exceptions.html#IndexError" title="IndexError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.choices">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">choices</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">population</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">weights</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">cum_weights</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">k</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.choices" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a <em>k</em> sized list of elements chosen from the <em>population</em> with replacement.
|
||
If the <em>population</em> is empty, raises <a class="reference internal" href="exceptions.html#IndexError" title="IndexError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code></a>.</p>
|
||
<p>If a <em>weights</em> sequence is specified, selections are made according to the
|
||
relative weights. Alternatively, if a <em>cum_weights</em> sequence is given, the
|
||
selections are made according to the cumulative weights (perhaps computed
|
||
using <a class="reference internal" href="itertools.html#itertools.accumulate" title="itertools.accumulate"><code class="xref py py-func docutils literal notranslate"><span class="pre">itertools.accumulate()</span></code></a>). For example, the relative weights
|
||
<code class="docutils literal notranslate"><span class="pre">[10,</span> <span class="pre">5,</span> <span class="pre">30,</span> <span class="pre">5]</span></code> are equivalent to the cumulative weights
|
||
<code class="docutils literal notranslate"><span class="pre">[10,</span> <span class="pre">15,</span> <span class="pre">45,</span> <span class="pre">50]</span></code>. Internally, the relative weights are converted to
|
||
cumulative weights before making selections, so supplying the cumulative
|
||
weights saves work.</p>
|
||
<p>If neither <em>weights</em> nor <em>cum_weights</em> are specified, selections are made
|
||
with equal probability. If a weights sequence is supplied, it must be
|
||
the same length as the <em>population</em> sequence. It is a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>
|
||
to specify both <em>weights</em> and <em>cum_weights</em>.</p>
|
||
<p>The <em>weights</em> or <em>cum_weights</em> can use any numeric type that interoperates
|
||
with the <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> values returned by <a class="reference internal" href="#module-random" title="random: Generate pseudo-random numbers with various common distributions."><code class="xref py py-func docutils literal notranslate"><span class="pre">random()</span></code></a> (that includes
|
||
integers, floats, and fractions but excludes decimals). Weights are assumed
|
||
to be non-negative and finite. A <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised if all
|
||
weights are zero.</p>
|
||
<p>For a given seed, the <a class="reference internal" href="#random.choices" title="random.choices"><code class="xref py py-func docutils literal notranslate"><span class="pre">choices()</span></code></a> function with equal weighting
|
||
typically produces a different sequence than repeated calls to
|
||
<a class="reference internal" href="#random.choice" title="random.choice"><code class="xref py py-func docutils literal notranslate"><span class="pre">choice()</span></code></a>. The algorithm used by <a class="reference internal" href="#random.choices" title="random.choices"><code class="xref py py-func docutils literal notranslate"><span class="pre">choices()</span></code></a> uses floating-point
|
||
arithmetic for internal consistency and speed. The algorithm used
|
||
by <a class="reference internal" href="#random.choice" title="random.choice"><code class="xref py py-func docutils literal notranslate"><span class="pre">choice()</span></code></a> defaults to integer arithmetic with repeated selections
|
||
to avoid small biases from round-off error.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.6.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.9: </span>Raises a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if all weights are zero.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.shuffle">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">shuffle</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.shuffle" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Shuffle the sequence <em>x</em> in place.</p>
|
||
<p>To shuffle an immutable sequence and return a new shuffled list, use
|
||
<code class="docutils literal notranslate"><span class="pre">sample(x,</span> <span class="pre">k=len(x))</span></code> instead.</p>
|
||
<p>Note that even for small <code class="docutils literal notranslate"><span class="pre">len(x)</span></code>, the total number of permutations of <em>x</em>
|
||
can quickly grow larger than the period of most random number generators.
|
||
This implies that most permutations of a long sequence can never be
|
||
generated. For example, a sequence of length 2080 is the largest that
|
||
can fit within the period of the Mersenne Twister random number generator.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>Removed the optional parameter <em>random</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.sample">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">sample</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">population</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">k</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">counts</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.sample" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a <em>k</em> length list of unique elements chosen from the population
|
||
sequence. Used for random sampling without replacement.</p>
|
||
<p>Returns a new list containing elements from the population while leaving the
|
||
original population unchanged. The resulting list is in selection order so that
|
||
all sub-slices will also be valid random samples. This allows raffle winners
|
||
(the sample) to be partitioned into grand prize and second place winners (the
|
||
subslices).</p>
|
||
<p>Members of the population need not be <a class="reference internal" href="../glossary.html#term-hashable"><span class="xref std std-term">hashable</span></a> or unique. If the population
|
||
contains repeats, then each occurrence is a possible selection in the sample.</p>
|
||
<p>Repeated elements can be specified one at a time or with the optional
|
||
keyword-only <em>counts</em> parameter. For example, <code class="docutils literal notranslate"><span class="pre">sample(['red',</span> <span class="pre">'blue'],</span>
|
||
<span class="pre">counts=[4,</span> <span class="pre">2],</span> <span class="pre">k=5)</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">sample(['red',</span> <span class="pre">'red',</span> <span class="pre">'red',</span> <span class="pre">'red',</span>
|
||
<span class="pre">'blue',</span> <span class="pre">'blue'],</span> <span class="pre">k=5)</span></code>.</p>
|
||
<p>To choose a sample from a range of integers, use a <a class="reference internal" href="stdtypes.html#range" title="range"><code class="xref py py-func docutils literal notranslate"><span class="pre">range()</span></code></a> object as an
|
||
argument. This is especially fast and space efficient for sampling from a large
|
||
population: <code class="docutils literal notranslate"><span class="pre">sample(range(10000000),</span> <span class="pre">k=60)</span></code>.</p>
|
||
<p>If the sample size is larger than the population size, a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>
|
||
is raised.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.9: </span>Added the <em>counts</em> parameter.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>The <em>population</em> must be a sequence. Automatic conversion of sets
|
||
to lists is no longer supported.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="discrete-distributions">
|
||
<h2>Discrete distributions<a class="headerlink" href="#discrete-distributions" title="Link to this heading">¶</a></h2>
|
||
<p>The following function generates a discrete distribution.</p>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.binomialvariate">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">binomialvariate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">n</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0.5</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.binomialvariate" title="Link to this definition">¶</a></dt>
|
||
<dd><p><a class="reference external" href="https://mathworld.wolfram.com/BinomialDistribution.html">Binomial distribution</a>.
|
||
Return the number of successes for <em>n</em> independent trials with the
|
||
probability of success in each trial being <em>p</em>:</p>
|
||
<p>Mathematically equivalent to:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nb">sum</span><span class="p">(</span><span class="n">random</span><span class="p">()</span> <span class="o"><</span> <span class="n">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">n</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The number of trials <em>n</em> should be a non-negative integer.
|
||
The probability of success <em>p</em> should be between <code class="docutils literal notranslate"><span class="pre">0.0</span> <span class="pre"><=</span> <span class="pre">p</span> <span class="pre"><=</span> <span class="pre">1.0</span></code>.
|
||
The result is an integer in the range <code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">X</span> <span class="pre"><=</span> <span class="pre">n</span></code>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.12.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="real-valued-distributions">
|
||
<span id="id1"></span><h2>Real-valued distributions<a class="headerlink" href="#real-valued-distributions" title="Link to this heading">¶</a></h2>
|
||
<p>The following functions generate specific real-valued distributions. Function
|
||
parameters are named after the corresponding variables in the distribution’s
|
||
equation, as used in common mathematical practice; most of these equations can
|
||
be found in any statistics text.</p>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.random">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">random</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#random.random" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the next random floating-point number in the range <code class="docutils literal notranslate"><span class="pre">0.0</span> <span class="pre"><=</span> <span class="pre">X</span> <span class="pre"><</span> <span class="pre">1.0</span></code></p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.uniform">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">uniform</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">b</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.uniform" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a random floating-point number <em>N</em> such that <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">N</span> <span class="pre"><=</span> <span class="pre">b</span></code> for
|
||
<code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">b</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span> <span class="pre"><=</span> <span class="pre">N</span> <span class="pre"><=</span> <span class="pre">a</span></code> for <code class="docutils literal notranslate"><span class="pre">b</span> <span class="pre"><</span> <span class="pre">a</span></code>.</p>
|
||
<p>The end-point value <code class="docutils literal notranslate"><span class="pre">b</span></code> may or may not be included in the range
|
||
depending on floating-point rounding in the expression
|
||
<code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">(b-a)</span> <span class="pre">*</span> <span class="pre">random()</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.triangular">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">triangular</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">low</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">high</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.triangular" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a random floating-point number <em>N</em> such that <code class="docutils literal notranslate"><span class="pre">low</span> <span class="pre"><=</span> <span class="pre">N</span> <span class="pre"><=</span> <span class="pre">high</span></code> and
|
||
with the specified <em>mode</em> between those bounds. The <em>low</em> and <em>high</em> bounds
|
||
default to zero and one. The <em>mode</em> argument defaults to the midpoint
|
||
between the bounds, giving a symmetric distribution.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.betavariate">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">betavariate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">alpha</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">beta</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.betavariate" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Beta distribution. Conditions on the parameters are <code class="docutils literal notranslate"><span class="pre">alpha</span> <span class="pre">></span> <span class="pre">0</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">beta</span> <span class="pre">></span> <span class="pre">0</span></code>. Returned values range between 0 and 1.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.expovariate">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">expovariate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lambd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1.0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.expovariate" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Exponential distribution. <em>lambd</em> is 1.0 divided by the desired
|
||
mean. It should be nonzero. (The parameter would be called
|
||
“lambda”, but that is a reserved word in Python.) Returned values
|
||
range from 0 to positive infinity if <em>lambd</em> is positive, and from
|
||
negative infinity to 0 if <em>lambd</em> is negative.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.12: </span>Added the default value for <code class="docutils literal notranslate"><span class="pre">lambd</span></code>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.gammavariate">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">gammavariate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">alpha</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">beta</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.gammavariate" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Gamma distribution. (<em>Not</em> the gamma function!) The shape and
|
||
scale parameters, <em>alpha</em> and <em>beta</em>, must have positive values.
|
||
(Calling conventions vary and some sources define ‘beta’
|
||
as the inverse of the scale).</p>
|
||
<p>The probability distribution function is:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span> <span class="n">x</span> <span class="o">**</span> <span class="p">(</span><span class="n">alpha</span> <span class="o">-</span> <span class="mi">1</span><span class="p">)</span> <span class="o">*</span> <span class="n">math</span><span class="o">.</span><span class="n">exp</span><span class="p">(</span><span class="o">-</span><span class="n">x</span> <span class="o">/</span> <span class="n">beta</span><span class="p">)</span>
|
||
<span class="n">pdf</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="o">=</span> <span class="o">--------------------------------------</span>
|
||
<span class="n">math</span><span class="o">.</span><span class="n">gamma</span><span class="p">(</span><span class="n">alpha</span><span class="p">)</span> <span class="o">*</span> <span class="n">beta</span> <span class="o">**</span> <span class="n">alpha</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.gauss">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">gauss</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">mu</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0.0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sigma</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1.0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.gauss" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Normal distribution, also called the Gaussian distribution.
|
||
<em>mu</em> is the mean,
|
||
and <em>sigma</em> is the standard deviation. This is slightly faster than
|
||
the <a class="reference internal" href="#random.normalvariate" title="random.normalvariate"><code class="xref py py-func docutils literal notranslate"><span class="pre">normalvariate()</span></code></a> function defined below.</p>
|
||
<p>Multithreading note: When two threads call this function
|
||
simultaneously, it is possible that they will receive the
|
||
same return value. This can be avoided in three ways.
|
||
1) Have each thread use a different instance of the random
|
||
number generator. 2) Put locks around all calls. 3) Use the
|
||
slower, but thread-safe <a class="reference internal" href="#random.normalvariate" title="random.normalvariate"><code class="xref py py-func docutils literal notranslate"><span class="pre">normalvariate()</span></code></a> function instead.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span><em>mu</em> and <em>sigma</em> now have default arguments.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.lognormvariate">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">lognormvariate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">mu</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sigma</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.lognormvariate" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Log normal distribution. If you take the natural logarithm of this
|
||
distribution, you’ll get a normal distribution with mean <em>mu</em> and standard
|
||
deviation <em>sigma</em>. <em>mu</em> can have any value, and <em>sigma</em> must be greater than
|
||
zero.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.normalvariate">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">normalvariate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">mu</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0.0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sigma</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1.0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.normalvariate" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Normal distribution. <em>mu</em> is the mean, and <em>sigma</em> is the standard deviation.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span><em>mu</em> and <em>sigma</em> now have default arguments.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.vonmisesvariate">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">vonmisesvariate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">mu</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">kappa</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.vonmisesvariate" title="Link to this definition">¶</a></dt>
|
||
<dd><p><em>mu</em> is the mean angle, expressed in radians between 0 and 2*<em>pi</em>, and <em>kappa</em>
|
||
is the concentration parameter, which must be greater than or equal to zero. If
|
||
<em>kappa</em> is equal to zero, this distribution reduces to a uniform random angle
|
||
over the range 0 to 2*<em>pi</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.paretovariate">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">paretovariate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">alpha</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.paretovariate" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Pareto distribution. <em>alpha</em> is the shape parameter.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="random.weibullvariate">
|
||
<span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">weibullvariate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">alpha</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">beta</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.weibullvariate" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Weibull distribution. <em>alpha</em> is the scale parameter and <em>beta</em> is the shape
|
||
parameter.</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="alternative-generator">
|
||
<h2>Alternative Generator<a class="headerlink" href="#alternative-generator" title="Link to this heading">¶</a></h2>
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="random.Random">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">Random</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">seed</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#random.Random" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Class that implements the default pseudo-random number generator used by the
|
||
<a class="reference internal" href="#module-random" title="random: Generate pseudo-random numbers with various common distributions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">random</span></code></a> module.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>Formerly the <em>seed</em> could be any hashable object. Now it is limited to:
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>, <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>, <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>,
|
||
<a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>, or <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>.</p>
|
||
</div>
|
||
<p>Subclasses of <code class="xref py py-class docutils literal notranslate"><span class="pre">Random</span></code> should override the following methods if they
|
||
wish to make use of a different basic generator:</p>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="random.Random.seed">
|
||
<span class="sig-name descname"><span class="pre">seed</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">a</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">version</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.Random.seed" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Override this method in subclasses to customise the <a class="reference internal" href="#random.seed" title="random.seed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">seed()</span></code></a>
|
||
behaviour of <code class="xref py py-class docutils literal notranslate"><span class="pre">Random</span></code> instances.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="random.Random.getstate">
|
||
<span class="sig-name descname"><span class="pre">getstate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#random.Random.getstate" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Override this method in subclasses to customise the <a class="reference internal" href="#random.getstate" title="random.getstate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getstate()</span></code></a>
|
||
behaviour of <code class="xref py py-class docutils literal notranslate"><span class="pre">Random</span></code> instances.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="random.Random.setstate">
|
||
<span class="sig-name descname"><span class="pre">setstate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">state</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.Random.setstate" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Override this method in subclasses to customise the <a class="reference internal" href="#random.setstate" title="random.setstate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setstate()</span></code></a>
|
||
behaviour of <code class="xref py py-class docutils literal notranslate"><span class="pre">Random</span></code> instances.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="random.Random.random">
|
||
<span class="sig-name descname"><span class="pre">random</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#random.Random.random" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Override this method in subclasses to customise the <a class="reference internal" href="#random.random" title="random.random"><code class="xref py py-meth docutils literal notranslate"><span class="pre">random()</span></code></a>
|
||
behaviour of <code class="xref py py-class docutils literal notranslate"><span class="pre">Random</span></code> instances.</p>
|
||
</dd></dl>
|
||
|
||
<p>Optionally, a custom generator subclass can also supply the following method:</p>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="random.Random.getrandbits">
|
||
<span class="sig-name descname"><span class="pre">getrandbits</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">k</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#random.Random.getrandbits" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Override this method in subclasses to customise the
|
||
<a class="reference internal" href="#random.getrandbits" title="random.getrandbits"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getrandbits()</span></code></a> behaviour of <code class="xref py py-class docutils literal notranslate"><span class="pre">Random</span></code> instances.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="random.SystemRandom">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">random.</span></span><span class="sig-name descname"><span class="pre">SystemRandom</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">seed</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#random.SystemRandom" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Class that uses the <a class="reference internal" href="os.html#os.urandom" title="os.urandom"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.urandom()</span></code></a> function for generating random numbers
|
||
from sources provided by the operating system. Not available on all systems.
|
||
Does not rely on software state, and sequences are not reproducible. Accordingly,
|
||
the <a class="reference internal" href="#random.seed" title="random.seed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">seed()</span></code></a> method has no effect and is ignored.
|
||
The <a class="reference internal" href="#random.getstate" title="random.getstate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getstate()</span></code></a> and <a class="reference internal" href="#random.setstate" title="random.setstate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setstate()</span></code></a> methods raise
|
||
<a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a> if called.</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="notes-on-reproducibility">
|
||
<h2>Notes on Reproducibility<a class="headerlink" href="#notes-on-reproducibility" title="Link to this heading">¶</a></h2>
|
||
<p>Sometimes it is useful to be able to reproduce the sequences given by a
|
||
pseudo-random number generator. By reusing a seed value, the same sequence should be
|
||
reproducible from run to run as long as multiple threads are not running.</p>
|
||
<p>Most of the random module’s algorithms and seeding functions are subject to
|
||
change across Python versions, but two aspects are guaranteed not to change:</p>
|
||
<ul class="simple">
|
||
<li><p>If a new seeding method is added, then a backward compatible seeder will be
|
||
offered.</p></li>
|
||
<li><p>The generator’s <a class="reference internal" href="#random.Random.random" title="random.Random.random"><code class="xref py py-meth docutils literal notranslate"><span class="pre">random()</span></code></a> method will continue to produce the same
|
||
sequence when the compatible seeder is given the same seed.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="examples">
|
||
<span id="random-examples"></span><h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h2>
|
||
<p>Basic examples:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">random</span><span class="p">()</span> <span class="c1"># Random float: 0.0 <= x < 1.0</span>
|
||
<span class="go">0.37444887175646646</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">uniform</span><span class="p">(</span><span class="mf">2.5</span><span class="p">,</span> <span class="mf">10.0</span><span class="p">)</span> <span class="c1"># Random float: 2.5 <= x <= 10.0</span>
|
||
<span class="go">3.1800146073117523</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">expovariate</span><span class="p">(</span><span class="mi">1</span> <span class="o">/</span> <span class="mi">5</span><span class="p">)</span> <span class="c1"># Interval between arrivals averaging 5 seconds</span>
|
||
<span class="go">5.148957571865031</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">randrange</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span> <span class="c1"># Integer from 0 to 9 inclusive</span>
|
||
<span class="go">7</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">randrange</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">101</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span> <span class="c1"># Even integer from 0 to 100 inclusive</span>
|
||
<span class="go">26</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">choice</span><span class="p">([</span><span class="s1">'win'</span><span class="p">,</span> <span class="s1">'lose'</span><span class="p">,</span> <span class="s1">'draw'</span><span class="p">])</span> <span class="c1"># Single random element from a sequence</span>
|
||
<span class="go">'draw'</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">deck</span> <span class="o">=</span> <span class="s1">'ace two three four'</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">shuffle</span><span class="p">(</span><span class="n">deck</span><span class="p">)</span> <span class="c1"># Shuffle a list</span>
|
||
<span class="gp">>>> </span><span class="n">deck</span>
|
||
<span class="go">['four', 'two', 'ace', 'three']</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">sample</span><span class="p">([</span><span class="mi">10</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="mi">30</span><span class="p">,</span> <span class="mi">40</span><span class="p">,</span> <span class="mi">50</span><span class="p">],</span> <span class="n">k</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span> <span class="c1"># Four samples without replacement</span>
|
||
<span class="go">[40, 10, 50, 30]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Simulations:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="c1"># Six roulette wheel spins (weighted sampling with replacement)</span>
|
||
<span class="gp">>>> </span><span class="n">choices</span><span class="p">([</span><span class="s1">'red'</span><span class="p">,</span> <span class="s1">'black'</span><span class="p">,</span> <span class="s1">'green'</span><span class="p">],</span> <span class="p">[</span><span class="mi">18</span><span class="p">,</span> <span class="mi">18</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="n">k</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span>
|
||
<span class="go">['red', 'green', 'black', 'black', 'red', 'black']</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Deal 20 cards without replacement from a deck</span>
|
||
<span class="gp">>>> </span><span class="c1"># of 52 playing cards, and determine the proportion of cards</span>
|
||
<span class="gp">>>> </span><span class="c1"># with a ten-value: ten, jack, queen, or king.</span>
|
||
<span class="gp">>>> </span><span class="n">deal</span> <span class="o">=</span> <span class="n">sample</span><span class="p">([</span><span class="s1">'tens'</span><span class="p">,</span> <span class="s1">'low cards'</span><span class="p">],</span> <span class="n">counts</span><span class="o">=</span><span class="p">[</span><span class="mi">16</span><span class="p">,</span> <span class="mi">36</span><span class="p">],</span> <span class="n">k</span><span class="o">=</span><span class="mi">20</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">deal</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="s1">'tens'</span><span class="p">)</span> <span class="o">/</span> <span class="mi">20</span>
|
||
<span class="go">0.15</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Estimate the probability of getting 5 or more heads from 7 spins</span>
|
||
<span class="gp">>>> </span><span class="c1"># of a biased coin that settles on heads 60% of the time.</span>
|
||
<span class="gp">>>> </span><span class="nb">sum</span><span class="p">(</span><span class="n">binomialvariate</span><span class="p">(</span><span class="n">n</span><span class="o">=</span><span class="mi">7</span><span class="p">,</span> <span class="n">p</span><span class="o">=</span><span class="mf">0.6</span><span class="p">)</span> <span class="o">>=</span> <span class="mi">5</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="mi">10_000</span><span class="p">))</span> <span class="o">/</span> <span class="mi">10_000</span>
|
||
<span class="go">0.4169</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Probability of the median of 5 samples being in middle two quartiles</span>
|
||
<span class="gp">>>> </span><span class="k">def</span><span class="w"> </span><span class="nf">trial</span><span class="p">():</span>
|
||
<span class="gp">... </span> <span class="k">return</span> <span class="mi">2_500</span> <span class="o"><=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">choices</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">10_000</span><span class="p">),</span> <span class="n">k</span><span class="o">=</span><span class="mi">5</span><span class="p">))[</span><span class="mi">2</span><span class="p">]</span> <span class="o"><</span> <span class="mi">7_500</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="nb">sum</span><span class="p">(</span><span class="n">trial</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="mi">10_000</span><span class="p">))</span> <span class="o">/</span> <span class="mi">10_000</span>
|
||
<span class="go">0.7958</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Example of <a class="reference external" href="https://en.wikipedia.org/wiki/Bootstrapping_(statistics)">statistical bootstrapping</a> using resampling
|
||
with replacement to estimate a confidence interval for the mean of a sample:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># https://www.thoughtco.com/example-of-bootstrapping-3126155</span>
|
||
<span class="kn">from</span><span class="w"> </span><span class="nn">statistics</span><span class="w"> </span><span class="kn">import</span> <span class="n">fmean</span> <span class="k">as</span> <span class="n">mean</span>
|
||
<span class="kn">from</span><span class="w"> </span><span class="nn">random</span><span class="w"> </span><span class="kn">import</span> <span class="n">choices</span>
|
||
|
||
<span class="n">data</span> <span class="o">=</span> <span class="p">[</span><span class="mi">41</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">29</span><span class="p">,</span> <span class="mi">37</span><span class="p">,</span> <span class="mi">81</span><span class="p">,</span> <span class="mi">30</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">63</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="mi">35</span><span class="p">,</span> <span class="mi">68</span><span class="p">,</span> <span class="mi">22</span><span class="p">,</span> <span class="mi">60</span><span class="p">,</span> <span class="mi">31</span><span class="p">,</span> <span class="mi">95</span><span class="p">]</span>
|
||
<span class="n">means</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">mean</span><span class="p">(</span><span class="n">choices</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">k</span><span class="o">=</span><span class="nb">len</span><span class="p">(</span><span class="n">data</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="mi">100</span><span class="p">))</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">'The sample mean of </span><span class="si">{</span><span class="n">mean</span><span class="p">(</span><span class="n">data</span><span class="p">)</span><span class="si">:</span><span class="s1">.1f</span><span class="si">}</span><span class="s1"> has a 90% confidence '</span>
|
||
<span class="sa">f</span><span class="s1">'interval from </span><span class="si">{</span><span class="n">means</span><span class="p">[</span><span class="mi">5</span><span class="p">]</span><span class="si">:</span><span class="s1">.1f</span><span class="si">}</span><span class="s1"> to </span><span class="si">{</span><span class="n">means</span><span class="p">[</span><span class="mi">94</span><span class="p">]</span><span class="si">:</span><span class="s1">.1f</span><span class="si">}</span><span class="s1">'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Example of a <a class="reference external" href="https://en.wikipedia.org/wiki/Resampling_(statistics)#Permutation_tests">resampling permutation test</a>
|
||
to determine the statistical significance or <a class="reference external" href="https://en.wikipedia.org/wiki/P-value">p-value</a> of an observed difference
|
||
between the effects of a drug versus a placebo:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Example from "Statistics is Easy" by Dennis Shasha and Manda Wilson</span>
|
||
<span class="kn">from</span><span class="w"> </span><span class="nn">statistics</span><span class="w"> </span><span class="kn">import</span> <span class="n">fmean</span> <span class="k">as</span> <span class="n">mean</span>
|
||
<span class="kn">from</span><span class="w"> </span><span class="nn">random</span><span class="w"> </span><span class="kn">import</span> <span class="n">shuffle</span>
|
||
|
||
<span class="n">drug</span> <span class="o">=</span> <span class="p">[</span><span class="mi">54</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">53</span><span class="p">,</span> <span class="mi">70</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">68</span><span class="p">,</span> <span class="mi">52</span><span class="p">,</span> <span class="mi">65</span><span class="p">,</span> <span class="mi">65</span><span class="p">]</span>
|
||
<span class="n">placebo</span> <span class="o">=</span> <span class="p">[</span><span class="mi">54</span><span class="p">,</span> <span class="mi">51</span><span class="p">,</span> <span class="mi">58</span><span class="p">,</span> <span class="mi">44</span><span class="p">,</span> <span class="mi">55</span><span class="p">,</span> <span class="mi">52</span><span class="p">,</span> <span class="mi">42</span><span class="p">,</span> <span class="mi">47</span><span class="p">,</span> <span class="mi">58</span><span class="p">,</span> <span class="mi">46</span><span class="p">]</span>
|
||
<span class="n">observed_diff</span> <span class="o">=</span> <span class="n">mean</span><span class="p">(</span><span class="n">drug</span><span class="p">)</span> <span class="o">-</span> <span class="n">mean</span><span class="p">(</span><span class="n">placebo</span><span class="p">)</span>
|
||
|
||
<span class="n">n</span> <span class="o">=</span> <span class="mi">10_000</span>
|
||
<span class="n">count</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="n">combined</span> <span class="o">=</span> <span class="n">drug</span> <span class="o">+</span> <span class="n">placebo</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">n</span><span class="p">):</span>
|
||
<span class="n">shuffle</span><span class="p">(</span><span class="n">combined</span><span class="p">)</span>
|
||
<span class="n">new_diff</span> <span class="o">=</span> <span class="n">mean</span><span class="p">(</span><span class="n">combined</span><span class="p">[:</span><span class="nb">len</span><span class="p">(</span><span class="n">drug</span><span class="p">)])</span> <span class="o">-</span> <span class="n">mean</span><span class="p">(</span><span class="n">combined</span><span class="p">[</span><span class="nb">len</span><span class="p">(</span><span class="n">drug</span><span class="p">):])</span>
|
||
<span class="n">count</span> <span class="o">+=</span> <span class="p">(</span><span class="n">new_diff</span> <span class="o">>=</span> <span class="n">observed_diff</span><span class="p">)</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">'</span><span class="si">{</span><span class="n">n</span><span class="si">}</span><span class="s1"> label reshufflings produced only </span><span class="si">{</span><span class="n">count</span><span class="si">}</span><span class="s1"> instances with a difference'</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">'at least as extreme as the observed difference of </span><span class="si">{</span><span class="n">observed_diff</span><span class="si">:</span><span class="s1">.1f</span><span class="si">}</span><span class="s1">.'</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">'The one-sided p-value of </span><span class="si">{</span><span class="n">count</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">n</span><span class="si">:</span><span class="s1">.4f</span><span class="si">}</span><span class="s1"> leads us to reject the null'</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">'hypothesis that there is no difference between the drug and the placebo.'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Simulation of arrival times and service deliveries for a multiserver queue:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">heapq</span><span class="w"> </span><span class="kn">import</span> <span class="n">heapify</span><span class="p">,</span> <span class="n">heapreplace</span>
|
||
<span class="kn">from</span><span class="w"> </span><span class="nn">random</span><span class="w"> </span><span class="kn">import</span> <span class="n">expovariate</span><span class="p">,</span> <span class="n">gauss</span>
|
||
<span class="kn">from</span><span class="w"> </span><span class="nn">statistics</span><span class="w"> </span><span class="kn">import</span> <span class="n">mean</span><span class="p">,</span> <span class="n">quantiles</span>
|
||
|
||
<span class="n">average_arrival_interval</span> <span class="o">=</span> <span class="mf">5.6</span>
|
||
<span class="n">average_service_time</span> <span class="o">=</span> <span class="mf">15.0</span>
|
||
<span class="n">stdev_service_time</span> <span class="o">=</span> <span class="mf">3.5</span>
|
||
<span class="n">num_servers</span> <span class="o">=</span> <span class="mi">3</span>
|
||
|
||
<span class="n">waits</span> <span class="o">=</span> <span class="p">[]</span>
|
||
<span class="n">arrival_time</span> <span class="o">=</span> <span class="mf">0.0</span>
|
||
<span class="n">servers</span> <span class="o">=</span> <span class="p">[</span><span class="mf">0.0</span><span class="p">]</span> <span class="o">*</span> <span class="n">num_servers</span> <span class="c1"># time when each server becomes available</span>
|
||
<span class="n">heapify</span><span class="p">(</span><span class="n">servers</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="mi">1_000_000</span><span class="p">):</span>
|
||
<span class="n">arrival_time</span> <span class="o">+=</span> <span class="n">expovariate</span><span class="p">(</span><span class="mf">1.0</span> <span class="o">/</span> <span class="n">average_arrival_interval</span><span class="p">)</span>
|
||
<span class="n">next_server_available</span> <span class="o">=</span> <span class="n">servers</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
|
||
<span class="n">wait</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="mf">0.0</span><span class="p">,</span> <span class="n">next_server_available</span> <span class="o">-</span> <span class="n">arrival_time</span><span class="p">)</span>
|
||
<span class="n">waits</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">wait</span><span class="p">)</span>
|
||
<span class="n">service_duration</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="mf">0.0</span><span class="p">,</span> <span class="n">gauss</span><span class="p">(</span><span class="n">average_service_time</span><span class="p">,</span> <span class="n">stdev_service_time</span><span class="p">))</span>
|
||
<span class="n">service_completed</span> <span class="o">=</span> <span class="n">arrival_time</span> <span class="o">+</span> <span class="n">wait</span> <span class="o">+</span> <span class="n">service_duration</span>
|
||
<span class="n">heapreplace</span><span class="p">(</span><span class="n">servers</span><span class="p">,</span> <span class="n">service_completed</span><span class="p">)</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">'Mean wait: </span><span class="si">{</span><span class="n">mean</span><span class="p">(</span><span class="n">waits</span><span class="p">)</span><span class="si">:</span><span class="s1">.1f</span><span class="si">}</span><span class="s1"> Max wait: </span><span class="si">{</span><span class="nb">max</span><span class="p">(</span><span class="n">waits</span><span class="p">)</span><span class="si">:</span><span class="s1">.1f</span><span class="si">}</span><span class="s1">'</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Quartiles:'</span><span class="p">,</span> <span class="p">[</span><span class="nb">round</span><span class="p">(</span><span class="n">q</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span> <span class="k">for</span> <span class="n">q</span> <span class="ow">in</span> <span class="n">quantiles</span><span class="p">(</span><span class="n">waits</span><span class="p">)])</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p><a class="reference external" href="https://www.youtube.com/watch?v=Iq9DzN6mvYA">Statistics for Hackers</a>
|
||
a video tutorial by
|
||
<a class="reference external" href="https://us.pycon.org/2016/speaker/profile/295/">Jake Vanderplas</a>
|
||
on statistical analysis using just a few fundamental concepts
|
||
including simulation, sampling, shuffling, and cross-validation.</p>
|
||
<p><a class="reference external" href="https://nbviewer.org/url/norvig.com/ipython/Economics.ipynb">Economics Simulation</a>
|
||
a simulation of a marketplace by
|
||
<a class="reference external" href="https://norvig.com/bio.html">Peter Norvig</a> that shows effective
|
||
use of many of the tools and distributions provided by this module
|
||
(gauss, uniform, sample, betavariate, choice, triangular, and randrange).</p>
|
||
<p><a class="reference external" href="https://nbviewer.org/url/norvig.com/ipython/Probability.ipynb">A Concrete Introduction to Probability (using Python)</a>
|
||
a tutorial by <a class="reference external" href="https://norvig.com/bio.html">Peter Norvig</a> covering
|
||
the basics of probability theory, how to write simulations, and
|
||
how to perform data analysis using Python.</p>
|
||
</div>
|
||
</section>
|
||
<section id="recipes">
|
||
<h2>Recipes<a class="headerlink" href="#recipes" title="Link to this heading">¶</a></h2>
|
||
<p>These recipes show how to efficiently make random selections
|
||
from the combinatoric iterators in the <a class="reference internal" href="itertools.html#module-itertools" title="itertools: Functions creating iterators for efficient looping."><code class="xref py py-mod docutils literal notranslate"><span class="pre">itertools</span></code></a> module:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">random_product</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="n">repeat</span><span class="o">=</span><span class="mi">1</span><span class="p">):</span>
|
||
<span class="s2">"Random selection from itertools.product(*args, **kwds)"</span>
|
||
<span class="n">pools</span> <span class="o">=</span> <span class="p">[</span><span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">)</span> <span class="k">for</span> <span class="n">pool</span> <span class="ow">in</span> <span class="n">args</span><span class="p">]</span> <span class="o">*</span> <span class="n">repeat</span>
|
||
<span class="k">return</span> <span class="nb">tuple</span><span class="p">(</span><span class="nb">map</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">pools</span><span class="p">))</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">random_permutation</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">r</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
|
||
<span class="s2">"Random selection from itertools.permutations(iterable, r)"</span>
|
||
<span class="n">pool</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>
|
||
<span class="n">r</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">pool</span><span class="p">)</span> <span class="k">if</span> <span class="n">r</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">r</span>
|
||
<span class="k">return</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">random</span><span class="o">.</span><span class="n">sample</span><span class="p">(</span><span class="n">pool</span><span class="p">,</span> <span class="n">r</span><span class="p">))</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">random_combination</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>
|
||
<span class="s2">"Random selection from itertools.combinations(iterable, r)"</span>
|
||
<span class="n">pool</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>
|
||
<span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">pool</span><span class="p">)</span>
|
||
<span class="n">indices</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">random</span><span class="o">.</span><span class="n">sample</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="p">),</span> <span class="n">r</span><span class="p">))</span>
|
||
<span class="k">return</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">random_combination_with_replacement</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>
|
||
<span class="s2">"Choose r elements with replacement. Order the result to match the iterable."</span>
|
||
<span class="c1"># Result will be in set(itertools.combinations_with_replacement(iterable, r)).</span>
|
||
<span class="n">pool</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">iterable</span><span class="p">)</span>
|
||
<span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">pool</span><span class="p">)</span>
|
||
<span class="n">indices</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">random</span><span class="o">.</span><span class="n">choices</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="p">),</span> <span class="n">k</span><span class="o">=</span><span class="n">r</span><span class="p">))</span>
|
||
<span class="k">return</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">pool</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The default <a class="reference internal" href="#random.random" title="random.random"><code class="xref py py-func docutils literal notranslate"><span class="pre">random()</span></code></a> returns multiples of 2⁻⁵³ in the range
|
||
<em>0.0 ≤ x < 1.0</em>. All such numbers are evenly spaced and are exactly
|
||
representable as Python floats. However, many other representable
|
||
floats in that interval are not possible selections. For example,
|
||
<code class="docutils literal notranslate"><span class="pre">0.05954861408025609</span></code> isn’t an integer multiple of 2⁻⁵³.</p>
|
||
<p>The following recipe takes a different approach. All floats in the
|
||
interval are possible selections. The mantissa comes from a uniform
|
||
distribution of integers in the range <em>2⁵² ≤ mantissa < 2⁵³</em>. The
|
||
exponent comes from a geometric distribution where exponents smaller
|
||
than <em>-53</em> occur half as often as the next larger exponent.</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">random</span><span class="w"> </span><span class="kn">import</span> <span class="n">Random</span>
|
||
<span class="kn">from</span><span class="w"> </span><span class="nn">math</span><span class="w"> </span><span class="kn">import</span> <span class="n">ldexp</span>
|
||
|
||
<span class="k">class</span><span class="w"> </span><span class="nc">FullRandom</span><span class="p">(</span><span class="n">Random</span><span class="p">):</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">random</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="n">mantissa</span> <span class="o">=</span> <span class="mh">0x10_0000_0000_0000</span> <span class="o">|</span> <span class="bp">self</span><span class="o">.</span><span class="n">getrandbits</span><span class="p">(</span><span class="mi">52</span><span class="p">)</span>
|
||
<span class="n">exponent</span> <span class="o">=</span> <span class="o">-</span><span class="mi">53</span>
|
||
<span class="n">x</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="k">while</span> <span class="ow">not</span> <span class="n">x</span><span class="p">:</span>
|
||
<span class="n">x</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">getrandbits</span><span class="p">(</span><span class="mi">32</span><span class="p">)</span>
|
||
<span class="n">exponent</span> <span class="o">+=</span> <span class="n">x</span><span class="o">.</span><span class="n">bit_length</span><span class="p">()</span> <span class="o">-</span> <span class="mi">32</span>
|
||
<span class="k">return</span> <span class="n">ldexp</span><span class="p">(</span><span class="n">mantissa</span><span class="p">,</span> <span class="n">exponent</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>All <a class="reference internal" href="#real-valued-distributions"><span class="std std-ref">real valued distributions</span></a>
|
||
in the class will use the new method:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">fr</span> <span class="o">=</span> <span class="n">FullRandom</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">fr</span><span class="o">.</span><span class="n">random</span><span class="p">()</span>
|
||
<span class="go">0.05954861408025609</span>
|
||
<span class="gp">>>> </span><span class="n">fr</span><span class="o">.</span><span class="n">expovariate</span><span class="p">(</span><span class="mf">0.25</span><span class="p">)</span>
|
||
<span class="go">8.87925541791544</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The recipe is conceptually equivalent to an algorithm that chooses from
|
||
all the multiples of 2⁻¹⁰⁷⁴ in the range <em>0.0 ≤ x < 1.0</em>. All such
|
||
numbers are evenly spaced, but most have to be rounded down to the
|
||
nearest representable Python float. (The value 2⁻¹⁰⁷⁴ is the smallest
|
||
positive unnormalized float and is equal to <code class="docutils literal notranslate"><span class="pre">math.ulp(0.0)</span></code>.)</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p><a class="reference external" href="https://allendowney.com/research/rand/downey07randfloat.pdf">Generating Pseudo-random Floating-Point Values</a> a
|
||
paper by Allen B. Downey describing ways to generate more
|
||
fine-grained floats than normally generated by <a class="reference internal" href="#random.random" title="random.random"><code class="xref py py-func docutils literal notranslate"><span class="pre">random()</span></code></a>.</p>
|
||
</div>
|
||
</section>
|
||
<section id="command-line-usage">
|
||
<span id="random-cli"></span><h2>Command-line usage<a class="headerlink" href="#command-line-usage" title="Link to this heading">¶</a></h2>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.13.</span></p>
|
||
</div>
|
||
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">random</span></code> module can be executed from the command line.</p>
|
||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>python<span class="w"> </span>-m<span class="w"> </span>random<span class="w"> </span><span class="o">[</span>-h<span class="o">]</span><span class="w"> </span><span class="o">[</span>-c<span class="w"> </span>CHOICE<span class="w"> </span><span class="o">[</span>CHOICE<span class="w"> </span>...<span class="o">]</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>-i<span class="w"> </span>N<span class="w"> </span><span class="p">|</span><span class="w"> </span>-f<span class="w"> </span>N<span class="o">]</span><span class="w"> </span><span class="o">[</span>input<span class="w"> </span>...<span class="o">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The following options are accepted:</p>
|
||
<dl class="std option">
|
||
<dt class="sig sig-object std" id="cmdoption-random-h">
|
||
<span id="cmdoption-random-help"></span><span class="sig-name descname"><span class="pre">-h</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--help</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-random-h" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Show the help message and exit.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="std option">
|
||
<dt class="sig sig-object std" id="cmdoption-random-c">
|
||
<span class="sig-name descname"><span class="pre">-c</span></span><span class="sig-prename descclassname"> <span class="pre">CHOICE</span> <span class="pre">[CHOICE</span> <span class="pre">...]</span></span><a class="headerlink" href="#cmdoption-random-c" title="Link to this definition">¶</a></dt>
|
||
<dt class="sig sig-object std" id="cmdoption-random-choice">
|
||
<span class="sig-name descname"><span class="pre">--choice</span></span><span class="sig-prename descclassname"> <span class="pre">CHOICE</span> <span class="pre">[CHOICE</span> <span class="pre">...]</span></span><a class="headerlink" href="#cmdoption-random-choice" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Print a random choice, using <a class="reference internal" href="#random.choice" title="random.choice"><code class="xref py py-meth docutils literal notranslate"><span class="pre">choice()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="std option">
|
||
<dt class="sig sig-object std" id="cmdoption-random-i">
|
||
<span class="sig-name descname"><span class="pre">-i</span></span><span class="sig-prename descclassname"> <span class="pre"><N></span></span><a class="headerlink" href="#cmdoption-random-i" title="Link to this definition">¶</a></dt>
|
||
<dt class="sig sig-object std" id="cmdoption-random-integer">
|
||
<span class="sig-name descname"><span class="pre">--integer</span></span><span class="sig-prename descclassname"> <span class="pre"><N></span></span><a class="headerlink" href="#cmdoption-random-integer" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Print a random integer between 1 and N inclusive, using <a class="reference internal" href="#random.randint" title="random.randint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">randint()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="std option">
|
||
<dt class="sig sig-object std" id="cmdoption-random-f">
|
||
<span class="sig-name descname"><span class="pre">-f</span></span><span class="sig-prename descclassname"> <span class="pre"><N></span></span><a class="headerlink" href="#cmdoption-random-f" title="Link to this definition">¶</a></dt>
|
||
<dt class="sig sig-object std" id="cmdoption-random-float">
|
||
<span class="sig-name descname"><span class="pre">--float</span></span><span class="sig-prename descclassname"> <span class="pre"><N></span></span><a class="headerlink" href="#cmdoption-random-float" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Print a random floating-point number between 0 and N inclusive,
|
||
using <a class="reference internal" href="#random.uniform" title="random.uniform"><code class="xref py py-meth docutils literal notranslate"><span class="pre">uniform()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<p>If no options are given, the output depends on the input:</p>
|
||
<ul class="simple">
|
||
<li><p>String or multiple: same as <a class="reference internal" href="#cmdoption-random-choice"><code class="xref std std-option docutils literal notranslate"><span class="pre">--choice</span></code></a>.</p></li>
|
||
<li><p>Integer: same as <a class="reference internal" href="#cmdoption-random-integer"><code class="xref std std-option docutils literal notranslate"><span class="pre">--integer</span></code></a>.</p></li>
|
||
<li><p>Float: same as <a class="reference internal" href="#cmdoption-random-float"><code class="xref std std-option docutils literal notranslate"><span class="pre">--float</span></code></a>.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="command-line-example">
|
||
<span id="random-cli-example"></span><h2>Command-line example<a class="headerlink" href="#command-line-example" title="Link to this heading">¶</a></h2>
|
||
<p>Here are some examples of the <code class="xref py py-mod docutils literal notranslate"><span class="pre">random</span></code> command-line interface:</p>
|
||
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="c1"># Choose one at random</span>
|
||
<span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>random<span class="w"> </span>egg<span class="w"> </span>bacon<span class="w"> </span>sausage<span class="w"> </span>spam<span class="w"> </span><span class="s2">"Lobster Thermidor aux crevettes with a Mornay sauce"</span>
|
||
<span class="go">Lobster Thermidor aux crevettes with a Mornay sauce</span>
|
||
|
||
<span class="gp">$ </span><span class="c1"># Random integer</span>
|
||
<span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>random<span class="w"> </span><span class="m">6</span>
|
||
<span class="go">6</span>
|
||
|
||
<span class="gp">$ </span><span class="c1"># Random floating-point number</span>
|
||
<span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>random<span class="w"> </span><span class="m">1</span>.8
|
||
<span class="go">1.7080016272295635</span>
|
||
|
||
<span class="gp">$ </span><span class="c1"># With explicit arguments</span>
|
||
<span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>random<span class="w"> </span>--choice<span class="w"> </span>egg<span class="w"> </span>bacon<span class="w"> </span>sausage<span class="w"> </span>spam<span class="w"> </span><span class="s2">"Lobster Thermidor aux crevettes with a Mornay sauce"</span>
|
||
<span class="go">egg</span>
|
||
|
||
<span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>random<span class="w"> </span>--integer<span class="w"> </span><span class="m">6</span>
|
||
<span class="go">3</span>
|
||
|
||
<span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>random<span class="w"> </span>--float<span class="w"> </span><span class="m">1</span>.8
|
||
<span class="go">1.5666339105010318</span>
|
||
|
||
<span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>random<span class="w"> </span>--integer<span class="w"> </span><span class="m">6</span>
|
||
<span class="go">5</span>
|
||
|
||
<span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>random<span class="w"> </span>--float<span class="w"> </span><span class="m">6</span>
|
||
<span class="go">3.1942323316565915</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">random</span></code> — Generate pseudo-random numbers</a><ul>
|
||
<li><a class="reference internal" href="#bookkeeping-functions">Bookkeeping functions</a></li>
|
||
<li><a class="reference internal" href="#functions-for-bytes">Functions for bytes</a></li>
|
||
<li><a class="reference internal" href="#functions-for-integers">Functions for integers</a></li>
|
||
<li><a class="reference internal" href="#functions-for-sequences">Functions for sequences</a></li>
|
||
<li><a class="reference internal" href="#discrete-distributions">Discrete distributions</a></li>
|
||
<li><a class="reference internal" href="#real-valued-distributions">Real-valued distributions</a></li>
|
||
<li><a class="reference internal" href="#alternative-generator">Alternative Generator</a></li>
|
||
<li><a class="reference internal" href="#notes-on-reproducibility">Notes on Reproducibility</a></li>
|
||
<li><a class="reference internal" href="#examples">Examples</a></li>
|
||
<li><a class="reference internal" href="#recipes">Recipes</a></li>
|
||
<li><a class="reference internal" href="#command-line-usage">Command-line usage</a></li>
|
||
<li><a class="reference internal" href="#command-line-example">Command-line example</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="fractions.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">fractions</span></code> — Rational numbers</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="statistics.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">statistics</span></code> — Mathematical statistics functions</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/main/Doc/library/random.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="sidebarbutton" title="Collapse sidebar">
|
||
<span>«</span>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="statistics.html" title="statistics — Mathematical statistics functions"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="fractions.html" title="fractions — Rational numbers"
|
||
>previous</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="numeric.html" >Numeric and Mathematical Modules</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">random</span></code> — Generate pseudo-random numbers</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
©
|
||
<a href="../copyright.html">
|
||
|
||
Copyright
|
||
|
||
</a>
|
||
2001-2025, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br />
|
||
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
Last updated on Apr 08, 2025 (14:33 UTC).
|
||
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |