fractions --- اعداد گویا

کد منبع: Lib/fractions.py

---

ماژول fractions از حساب اعداد گویا پشتیبانی می‌کند.

یک نمونه از Fraction می‌تواند از یک جفت عدد گویا، از یک عدد، یا از یک رشته ساخته شود.

class fractions.Fraction(numerator=0, denominator=1)

class fractions.Fraction(number)

class fractions.Fraction(string)

اولین نسخه نیاز دارد که numerator و denominator نمونه‌هایی از numbers.Rational باشند و یک نمونه جدید از Fraction را با مقداری برابر با numerator/denominator برمی‌گرداند. اگر denominator صفر باشد، ZeroDivisionError را پرتاب می‌کند.

نسخه دوم مستلزم آن است که number نمونه‌ای از numbers.Rational باشد یا دارای متد as_integer_ratio() باشد (این شامل float و decimal.Decimal می‌شود). این نسخه یک نمونه Fraction با دقیقاً همان مقدار برمی‌گرداند. فرض می‌شود که متد as_integer_ratio() جفتی از اعداد صحیح اول نسبت به هم برمی‌گرداند و دومی مثبت است. توجه داشته باشید که به دلیل مسائل معمول ممیز دودویی (به حساب ممیز شناور: مشکلات و محدودیت‌ها مراجعه کنید)، آرگومان Fraction(1.1) دقیقاً برابر با ۱۱/۱۰ نیست، و بنابراین Fraction(1.1)، Fraction(11, 10) را آن‌گونه که ممکن است انتظار رود برنمی‌گرداند. (اما مستندات متد limit_denominator() را در زیر ببینید.)

آخرین نسخه‌ی سازنده انتظار یک رشته را دارد. شکل معمول برای این نمونه به این صورت است:

[علامت] صورت ['/' مخرج]

که در آن sign اختیاری می‌تواند '+' یا '-' باشد و numerator و denominator (در صورت وجود) رشته‌هایی از ارقام ده‌دهی هستند (می‌توان از زیرسطرها برای جدا کردن ارقام استفاده کرد، همان‌طور که در لفظ‌های عدد صحیح در کد استفاده می‌شود). علاوه بر این، هر رشته‌ای که نشان‌دهنده‌ی یک مقدار متناهی باشد و توسط سازنده‌ی float پذیرفته شود، توسط سازنده‌ی Fraction نیز پذیرفته می‌شود. در هر یک از این قالب‌ها، رشته‌ی ورودی همچنین می‌تواند در ابتدا و/یا انتها دارای فضای خالی باشد. در اینجا چند مثال آمده است:

>>> 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)

کلاس Fraction از کلاس پایه انتزاعی numbers.Rational ارث می‌برد و تمام متدها و عملیات‌های آن کلاس را پیاده‌سازی می‌کند. نمونه‌های Fraction، hashable هستند و باید به‌عنوان تغییرناپذیر در نظر گرفته شوند. علاوه بر این، Fraction دارای ویژگی‌ها و متدهای زیر است:

تغییر یافته در نسخه‌ی 3.2: سازنده‌ی Fraction اکنون نمونه‌های float و decimal.Decimal را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.9: اکنون از تابع math.gcd() برای به‌هنجار کردن numerator و denominator استفاده می‌شود. math.gcd() همیشه مقداری از نوع int برمی‌گرداند. پیش از این، نوع ب.م.م به numerator و denominator بستگی داشت.

تغییر یافته در نسخه‌ی 3.11: اکنون استفاده از زیرسطرها هنگام ایجاد یک نمونه از Fraction از روی یک رشته، مطابق قوانین PEP 515 مجاز است.

تغییر یافته در نسخه‌ی 3.11: Fraction اکنون __int__ را پیاده‌سازی می‌کند تا بررسی‌های نمونه از typing.SupportsInt برآورده شوند.

تغییر یافته در نسخه‌ی 3.12: برای ورودی‌های رشته‌ای، وجود فاصله در اطراف اسلش مجاز است: Fraction('2 / 3').

تغییر یافته در نسخه‌ی 3.12: نمونه‌های Fraction اکنون از قالب‌بندی به‌سبک float با انواع نمایش "e"، "E"، "f"، "F"، "g"، "G" و "%"" پشتیبانی می‌کنند.

تغییر یافته در نسخه‌ی 3.13: قالب‌بندی نمونه‌های Fraction بدون نوع نمایش، اکنون از پرکننده، تراز، مدیریت علامت، حداقل عرض و گروه‌بندی پشتیبانی می‌کند.

تغییر یافته در نسخه‌ی 3.14: سازنده‌ی Fraction اکنون هر شیء دارای متد as_integer_ratio() را می‌پذیرد.

numerator

صورت کسر در ساده‌ترین شکل.

denominator

مخرج کسر در ساده‌ترین شکل. تضمین می‌شود که مثبت باشد.

as_integer_ratio()

یک تاپل از دو عدد صحیح برمی‌گرداند، که نسبت آن‌ها برابر با Fraction اصلی است. این نسبت در ساده‌ترین شکل است و مخرج آن مثبت است.

اضافه شده در نسخه‌ی 3.8.

is_integer()

اگر Fraction یک عدد صحیح باشد، True برمی‌گرداند.

اضافه شده در نسخه‌ی 3.12.

classmethod from_float(f)

سازنده جایگزین که فقط نمونه‌های float یا numbers.Integral را می‌پذیرد. توجه داشته باشید که مقدار Fraction.from_float(0.3) با مقدار Fraction(3, 10) یکسان نیست.

توجه

از پایتون 3.2 به بعد، می‌توانید نمونه‌ای از Fraction را مستقیماً از یک float بسازید.

classmethod from_decimal(dec)

سازنده جایگزینی که فقط نمونه‌های decimal.Decimal یا numbers.Integral را می‌پذیرد.

توجه

از پایتون 3.2 به بعد، همچنین می‌توانید یک نمونه Fraction را مستقیماً از یک نمونه decimal.Decimal ایجاد کنید.

classmethod from_number(number)

سازنده جایگزینی که فقط نمونه‌های numbers.Integral، numbers.Rational، float یا decimal.Decimal و اشیایی که متد as_integer_ratio() دارند را می‌پذیرد، اما رشته‌ها را نمی‌پذیرد.

اضافه شده در نسخه‌ی 3.14.

limit_denominator(max_denominator=1000000)

نزدیک‌ترین Fraction به self را که مخرج آن حداکثر max_denominator باشد، پیدا می‌کند و برمی‌گرداند. این متد برای یافتن تقریب‌های گویای یک عدد ممیز شناور داده‌شده مفید است:

>>> from fractions import Fraction
>>> Fraction('3.1415926535897932').limit_denominator(1000)
Fraction(355, 113)

یا برای بازیابی عدد گویایی که به‌صورت یک شناور نمایش داده شده است:

>>> 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)

__floor__()

بزرگ‌ترین int <= self را برمی‌گرداند. این متد همچنین از طریق تابع math.floor() نیز قابل دسترسی است:

>>> from math import floor
>>> floor(Fraction(355, 113))
3

__ceil__()

کوچک‌ترین int که >= self باشد را برمی‌گرداند. همچنین می‌توان از طریق تابع math.ceil() به این متد دسترسی داشت.

__round__()

__round__(ndigits)

نسخه‌ی نخست نزدیک‌ترین int به self را بازمی‌گرداند، با گرد کردن نیمه به سمت زوج. نسخه‌ی دوم self را به نزدیک‌ترین مضرب Fraction(1, 10**ndigits) گرد می‌کند (از نظر منطقی، اگر ndigits منفی باشد)، باز هم با گرد کردن نیمه به سمت زوج. می‌توان به این متد از طریق تابع round() نیز دسترسی داشت.

__format__(format_spec, /)

پشتیبانی از قالب‌بندی نمونه‌های Fraction را از طریق متد str.format()، تابع توکار format()، یا رشته‌های قالب‌بندی‌شده فراهم می‌کند.

اگر رشته مشخصات قالب‌بندی format_spec به یکی از انواع نمایش 'e'، 'E'، 'f'، 'F'، 'g'، 'G' یا '%' ختم نشود، قالب‌بندی از قواعد عمومی مربوط به پر کردن، ترازبندی، مدیریت علامت، حداقل عرض و گروه‌بندی پیروی می‌کند، همان‌طور که در زبان کوچک مشخصات قالب‌بندی توضیح داده شده است. پرچم «شکل جایگزین» (alternate form) '#' پشتیبانی می‌شود: در صورت وجود، رشته خروجی را وادار می‌کند که همیشه شامل یک مخرج صریح باشد، حتی وقتی که مقدار مورد قالب‌بندی یک عدد صحیح دقیق باشد. از پرچم پرکننده با صفر '0' پشتیبانی نمی‌شود.

اگر رشته مشخصات قالب format_spec به یکی از انواع نمایش 'e'، 'E'، 'f'، 'F'، 'g'، 'G' یا '%' ختم شود، قالب‌بندی از قواعدی پیروی می‌کند که برای نوع float در بخش زبان کوچک مشخصات قالب‌بندی شرح داده شده است.

در ادامه چند مثال آمده است:

>>> from fractions import Fraction
>>> format(Fraction(103993, 33102), '_')
'103_993/33_102'
>>> format(Fraction(1, 7), '.^+10')
'...+1/7...'
>>> format(Fraction(3, 1), '')
'3'
>>> format(Fraction(3, 1), '#')
'3/1'
>>> 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'

همچنین ملاحظه نمائید

ماژول numbers

کلاس‌های پایه انتزاعی که برج عددی (numeric tower) را تشکیل می‌دهند.