diff options
Diffstat (limited to 'devdocs/python~3.12/library%2Ffractions.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Ffractions.html | 99 |
1 files changed, 99 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Ffractions.html b/devdocs/python~3.12/library%2Ffractions.html new file mode 100644 index 00000000..1c160c4e --- /dev/null +++ b/devdocs/python~3.12/library%2Ffractions.html @@ -0,0 +1,99 @@ + <span id="fractions-rational-numbers"></span><h1>fractions — Rational numbers</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/fractions.py">Lib/fractions.py</a></p> <p>The <a class="reference internal" href="#module-fractions" title="fractions: Rational numbers."><code>fractions</code></a> module provides support for rational number arithmetic.</p> <p>A Fraction instance can be constructed from a pair of integers, from another rational number, or from a string.</p> <dl class="py class"> <dt class="sig sig-object py" id="fractions.Fraction"> +<code>class fractions.Fraction(numerator=0, denominator=1)</code> </dt> <dt class="sig sig-object py"> <em class="property">class<span class="w"> </span></em><span class="sig-prename descclassname">fractions.</span><span class="sig-name descname">Fraction</span><span class="sig-paren">(</span><em class="sig-param"><span class="n">other_fraction</span></em><span class="sig-paren">)</span> +</dt> <dt class="sig sig-object py"> <em class="property">class<span class="w"> </span></em><span class="sig-prename descclassname">fractions.</span><span class="sig-name descname">Fraction</span><span class="sig-paren">(</span><em class="sig-param"><span class="n">float</span></em><span class="sig-paren">)</span> +</dt> <dt class="sig sig-object py"> <em class="property">class<span class="w"> </span></em><span class="sig-prename descclassname">fractions.</span><span class="sig-name descname">Fraction</span><span class="sig-paren">(</span><em class="sig-param"><span class="n">decimal</span></em><span class="sig-paren">)</span> +</dt> <dt class="sig sig-object py"> <em class="property">class<span class="w"> </span></em><span class="sig-prename descclassname">fractions.</span><span class="sig-name descname">Fraction</span><span class="sig-paren">(</span><em class="sig-param"><span class="n">string</span></em><span class="sig-paren">)</span> +</dt> <dd> +<p>The first version requires that <em>numerator</em> and <em>denominator</em> are instances of <a class="reference internal" href="numbers#numbers.Rational" title="numbers.Rational"><code>numbers.Rational</code></a> and returns a new <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> instance with value <code>numerator/denominator</code>. If <em>denominator</em> is <code>0</code>, it raises a <a class="reference internal" href="exceptions#ZeroDivisionError" title="ZeroDivisionError"><code>ZeroDivisionError</code></a>. The second version requires that <em>other_fraction</em> is an instance of <a class="reference internal" href="numbers#numbers.Rational" title="numbers.Rational"><code>numbers.Rational</code></a> and returns a <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> instance with the same value. The next two versions accept either a <a class="reference internal" href="functions#float" title="float"><code>float</code></a> or a <a class="reference internal" href="decimal#decimal.Decimal" title="decimal.Decimal"><code>decimal.Decimal</code></a> instance, and return a <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> instance with exactly the same value. Note that due to the usual issues with binary floating-point (see <a class="reference internal" href="../tutorial/floatingpoint#tut-fp-issues"><span class="std std-ref">Floating Point Arithmetic: Issues and Limitations</span></a>), the argument to <code>Fraction(1.1)</code> is not exactly equal to 11/10, and so <code>Fraction(1.1)</code> does <em>not</em> return <code>Fraction(11, 10)</code> as one might expect. (But see the documentation for the <a class="reference internal" href="#fractions.Fraction.limit_denominator" title="fractions.Fraction.limit_denominator"><code>limit_denominator()</code></a> method below.) The last version of the constructor expects a string or unicode instance. The usual form for this instance is:</p> <pre data-language="python">[sign] numerator ['/' denominator] +</pre> <p>where the optional <code>sign</code> may be either ‘+’ or ‘-’ and <code>numerator</code> and <code>denominator</code> (if present) are strings of decimal digits (underscores may be used to delimit digits as with integral literals in code). In addition, any string that represents a finite value and is accepted by the <a class="reference internal" href="functions#float" title="float"><code>float</code></a> constructor is also accepted by the <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> constructor. In either form the input string may also have leading and/or trailing whitespace. Here are some examples:</p> <pre data-language="python">>>> from fractions import Fraction +>>> Fraction(16, -10) +Fraction(-8, 5) +>>> Fraction(123) +Fraction(123, 1) +>>> Fraction() +Fraction(0, 1) +>>> Fraction('3/7') +Fraction(3, 7) +>>> Fraction(' -3/7 ') +Fraction(-3, 7) +>>> Fraction('1.414213 \t\n') +Fraction(1414213, 1000000) +>>> Fraction('-.125') +Fraction(-1, 8) +>>> Fraction('7e-6') +Fraction(7, 1000000) +>>> Fraction(2.25) +Fraction(9, 4) +>>> Fraction(1.1) +Fraction(2476979795053773, 2251799813685248) +>>> from decimal import Decimal +>>> Fraction(Decimal('1.1')) +Fraction(11, 10) +</pre> <p>The <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> class inherits from the abstract base class <a class="reference internal" href="numbers#numbers.Rational" title="numbers.Rational"><code>numbers.Rational</code></a>, and implements all of the methods and operations from that class. <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> instances are <a class="reference internal" href="../glossary#term-hashable"><span class="xref std std-term">hashable</span></a>, and should be treated as immutable. In addition, <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> has the following properties and methods:</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>The <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> constructor now accepts <a class="reference internal" href="functions#float" title="float"><code>float</code></a> and <a class="reference internal" href="decimal#decimal.Decimal" title="decimal.Decimal"><code>decimal.Decimal</code></a> instances.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>The <a class="reference internal" href="math#math.gcd" title="math.gcd"><code>math.gcd()</code></a> function is now used to normalize the <em>numerator</em> and <em>denominator</em>. <a class="reference internal" href="math#math.gcd" title="math.gcd"><code>math.gcd()</code></a> always return a <a class="reference internal" href="functions#int" title="int"><code>int</code></a> type. Previously, the GCD type depended on <em>numerator</em> and <em>denominator</em>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>Underscores are now permitted when creating a <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> instance from a string, following <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0515/"><strong>PEP 515</strong></a> rules.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span><a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> implements <code>__int__</code> now to satisfy <code>typing.SupportsInt</code> instance checks.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>Space is allowed around the slash for string inputs: <code>Fraction('2 / 3')</code>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span><a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> instances now support float-style formatting, with presentation types <code>"e"</code>, <code>"E"</code>, <code>"f"</code>, <code>"F"</code>, <code>"g"</code>, <code>"G"</code> and <code>"%""</code>.</p> </div> <dl class="py attribute"> <dt class="sig sig-object py" id="fractions.Fraction.numerator"> +<code>numerator</code> </dt> <dd> +<p>Numerator of the Fraction in lowest term.</p> </dd> +</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="fractions.Fraction.denominator"> +<code>denominator</code> </dt> <dd> +<p>Denominator of the Fraction in lowest term.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="fractions.Fraction.as_integer_ratio"> +<code>as_integer_ratio()</code> </dt> <dd> +<p>Return a tuple of two integers, whose ratio is equal to the original Fraction. The ratio is in lowest terms and has a positive denominator.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.8.</span></p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="fractions.Fraction.is_integer"> +<code>is_integer()</code> </dt> <dd> +<p>Return <code>True</code> if the Fraction is an integer.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.12.</span></p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="fractions.Fraction.from_float"> +<code>classmethod from_float(flt)</code> </dt> <dd> +<p>Alternative constructor which only accepts instances of <a class="reference internal" href="functions#float" title="float"><code>float</code></a> or <a class="reference internal" href="numbers#numbers.Integral" title="numbers.Integral"><code>numbers.Integral</code></a>. Beware that <code>Fraction.from_float(0.3)</code> is not the same value as <code>Fraction(3, 10)</code>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>From Python 3.2 onwards, you can also construct a <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> instance directly from a <a class="reference internal" href="functions#float" title="float"><code>float</code></a>.</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="fractions.Fraction.from_decimal"> +<code>classmethod from_decimal(dec)</code> </dt> <dd> +<p>Alternative constructor which only accepts instances of <a class="reference internal" href="decimal#decimal.Decimal" title="decimal.Decimal"><code>decimal.Decimal</code></a> or <a class="reference internal" href="numbers#numbers.Integral" title="numbers.Integral"><code>numbers.Integral</code></a>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>From Python 3.2 onwards, you can also construct a <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> instance directly from a <a class="reference internal" href="decimal#decimal.Decimal" title="decimal.Decimal"><code>decimal.Decimal</code></a> instance.</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="fractions.Fraction.limit_denominator"> +<code>limit_denominator(max_denominator=1000000)</code> </dt> <dd> +<p>Finds and returns the closest <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> to <code>self</code> that has denominator at most max_denominator. This method is useful for finding rational approximations to a given floating-point number:</p> <pre data-language="python">>>> from fractions import Fraction +>>> Fraction('3.1415926535897932').limit_denominator(1000) +Fraction(355, 113) +</pre> <p>or for recovering a rational number that’s represented as a float:</p> <pre data-language="python">>>> from math import pi, cos +>>> Fraction(cos(pi/3)) +Fraction(4503599627370497, 9007199254740992) +>>> Fraction(cos(pi/3)).limit_denominator() +Fraction(1, 2) +>>> Fraction(1.1).limit_denominator() +Fraction(11, 10) +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="fractions.Fraction.__floor__"> +<code>__floor__()</code> </dt> <dd> +<p>Returns the greatest <a class="reference internal" href="functions#int" title="int"><code>int</code></a> <code><= self</code>. This method can also be accessed through the <a class="reference internal" href="math#math.floor" title="math.floor"><code>math.floor()</code></a> function:</p> <pre data-language="python">>>> from math import floor +>>> floor(Fraction(355, 113)) +3 +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="fractions.Fraction.__ceil__"> +<code>__ceil__()</code> </dt> <dd> +<p>Returns the least <a class="reference internal" href="functions#int" title="int"><code>int</code></a> <code>>= self</code>. This method can also be accessed through the <a class="reference internal" href="math#math.ceil" title="math.ceil"><code>math.ceil()</code></a> function.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="fractions.Fraction.__round__"> +<code>__round__()</code> </dt> <dt class="sig sig-object py"> <span class="sig-name descname">__round__</span><span class="sig-paren">(</span><em class="sig-param"><span class="n">ndigits</span></em><span class="sig-paren">)</span> +</dt> <dd> +<p>The first version returns the nearest <a class="reference internal" href="functions#int" title="int"><code>int</code></a> to <code>self</code>, rounding half to even. The second version rounds <code>self</code> to the nearest multiple of <code>Fraction(1, 10**ndigits)</code> (logically, if <code>ndigits</code> is negative), again rounding half toward even. This method can also be accessed through the <a class="reference internal" href="functions#round" title="round"><code>round()</code></a> function.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="fractions.Fraction.__format__"> +<code>__format__(format_spec, /)</code> </dt> <dd> +<p>Provides support for float-style formatting of <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> instances via the <a class="reference internal" href="stdtypes#str.format" title="str.format"><code>str.format()</code></a> method, the <a class="reference internal" href="functions#format" title="format"><code>format()</code></a> built-in function, or <a class="reference internal" href="../reference/lexical_analysis#f-strings"><span class="std std-ref">Formatted string literals</span></a>. The presentation types <code>"e"</code>, <code>"E"</code>, <code>"f"</code>, <code>"F"</code>, <code>"g"</code>, <code>"G"</code> and <code>"%"</code> are supported. For these presentation types, formatting for a <a class="reference internal" href="#fractions.Fraction" title="fractions.Fraction"><code>Fraction</code></a> object <code>x</code> follows the rules outlined for the <a class="reference internal" href="functions#float" title="float"><code>float</code></a> type in the <a class="reference internal" href="string#formatspec"><span class="std std-ref">Format Specification Mini-Language</span></a> section.</p> <p>Here are some examples:</p> <pre data-language="python">>>> from fractions import Fraction +>>> format(Fraction(1, 7), '.40g') +'0.1428571428571428571428571428571428571429' +>>> format(Fraction('1234567.855'), '_.2f') +'1_234_567.86' +>>> f"{Fraction(355, 113):*>20.6e}" +'********3.141593e+00' +>>> old_price, new_price = 499, 672 +>>> "{:.2%} price increase".format(Fraction(new_price, old_price) - 1) +'34.67% price increase' +</pre> </dd> +</dl> </dd> +</dl> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt> +<code>Module</code> <a class="reference internal" href="numbers#module-numbers" title="numbers: Numeric abstract base classes (Complex, Real, Integral, etc.)."><code>numbers</code></a> +</dt> +<dd> +<p>The abstract base classes making up the numeric tower.</p> </dd> </dl> </div> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/library/fractions.html" class="_attribution-link">https://docs.python.org/3.12/library/fractions.html</a> + </p> +</div> |