"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.
