fractions — Números racionais

Código-fonte: Lib/fractions.py

O módulo fractions fornece suporte para aritmética de números racionais.

Uma instância de Fraction pode ser construída a partir de um par de números inteiros, de outro número racional ou de uma string.

class fractions.Fraction(numerator=0, denominator=1)
class fractions.Fraction(other_fraction)
class fractions.Fraction(float)
class fractions.Fraction(decimal)
class fractions.Fraction(string)

A primeira versão requer que numerator e denominator sejam instâncias de numbers.Rational e retorna uma nova instância de Fraction com o valor numerator/denominator. Se denominator for 0, ele levanta uma ZeroDivisionError. A segunda versão requer que other_fraction seja uma instância de numbers.Rational e retorna uma instância de Fraction com o mesmo valor. As próximas duas versões aceitam uma instância de float ou decimal.Decimal e retornam uma instância de Fraction com exatamente o mesmo valor. Note que devido aos problemas usuais com ponto flutuante binário (veja Aritmética de ponto flutuante: problemas e limitações), o argumento para Fraction(1.1) não é exatamente igual a 11/10, e então Fraction(1.1) não retorna Fraction(11, 10) como seria de se esperar. (Mas veja a documentação para o método limit_denominator() abaixo.) A última versão do construtor espera uma instância de string ou unicode. A forma usual para esta instância é:

[sinal] numerador ['/' denominador]

onde o sign opcional pode ser ‘+’ ou ‘-’ e numerator e denominator (se presente) são strings de dígitos decimais (sublinhados podem ser usados para delimitar dígitos como com literais integrais no código). Além disso, qualquer string que represente um valor finito e seja aceita pelo construtor float também é aceita pelo construtor Fraction. Em qualquer forma, a string de entrada também pode ter espaços em branco à esquerda e/ou à direita. Aqui estão alguns exemplos:

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

A classe Fraction herda da classe base abstrata numbers.Rational e implementa todos os métodos e operações dessa classe. As instâncias de Fraction são hasheável e devem ser tratadas como imutáveis. Além disso, Fraction tem as seguintes propriedades e métodos:

Alterado na versão 3.2: O construtor Fraction agora aceita instâncias float e decimal.Decimal.

Alterado na versão 3.9: A função math.gcd() agora é usada para normalizar o numerator e o denominator. math.gcd() sempre retorna um tipo int. Anteriormente, o tipo GCD dependia do numerator e do denominator.

Alterado na versão 3.11: Sublinhados agora são permitidos ao criar uma instância Fraction a partir de uma string, seguindo as regras PEP 515.

Alterado na versão 3.11: Fraction implementa __int__ agora para satisfazer verificações de instância typing.SupportsInt.

Alterado na versão 3.12: É permitido espaço ao redor da barra para entradas de string: Fraction('2 / 3').

Alterado na versão 3.12: Instâncias de Fraction agora oferecem suporte à formatação no estilo float, com tipos de apresentação "e", "E", "f", "F", "g", "G" e "%"".

numerator

Numerador de Fraction no menor termo.

denominator

Denominador de Fraction no menor termo.

as_integer_ratio()

Retorna uma tupla de dois inteiros, cuja razão é igual a Fraction original. A razão está em termos mais baixos e tem um denominador positivo.

Adicionado na versão 3.8.

is_integer()

Retorna True se a Fraction for um inteiro.

Adicionado na versão 3.12.

classmethod from_float(flt)

Construtor alternativo que aceita apenas instâncias de float ou numbers.Integral. Esteja ciente de que Fraction.from_float(0.3) não é o mesmo valor que Fraction(3, 10).

Nota

A partir do Python 3.2, você também pode construir uma instância Fraction diretamente de um float.

classmethod from_decimal(dec)

Construtor alternativo que aceita somente instâncias de decimal.Decimal ou numbers.Integral.

Nota

A partir do Python 3.2, você também pode construir uma instância Fraction diretamente de uma instância de decimal.Decimal.

limit_denominator(max_denominator=1000000)

Encontra e retorna o Fraction mais próximo de self que tem denominador no máximo max_denominator. Este método é útil para encontrar aproximações racionais para um dado número de ponto flutuante:

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

ou para recuperar um número racional que é representado como um ponto flutuante:

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

Retorna o maior int <= self. Este método também pode ser acessado por meio da função math.floor():

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

Retorna o menor int >= self. Este método também pode ser acessado por meio da função math.ceil().

__round__()
__round__(ndigits)

A primeira versão retorna o int mais próximo de self, arredondando a metade para par. A segunda versão arredonda self para o múltiplo mais próximo de Fraction(1, 10**ndigits) (logicamente, se ndigits for negativo), novamente arredondando a metade para par. Este método também pode ser acessado por meio da função round().

__format__(format_spec, /)

Fornece suporte para formatação em estilo float de instâncias Fraction por meio do método str.format(), da função embutida format() ou literais de strings formatadas. Os tipos de apresentação "e", "E", "f", "F", "g", "G" e "%" são suportados. Para esses tipos de apresentação, a formatação para um objeto Fraction x segue as regras descritas para o tipo float na seção Minilinguagem de especificação de formato.

Veja alguns exemplos:

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

Ver também

Módulo numbers

As classes base abstratas que compõem a torre numérica.