numwords-to-nums 1.2.0

Python library for converting numerical words (textual numbers) to numbers

numwords_to_nums:

• numwords_to_nums not only handles a wide range of numeric conversions, including large numbers and Indian numbering systems but also ensures that it maintains the integrity of your input string.
• It won't alter punctuation marks like full stops, capitalization of characters, word order in sentences, or sentence arrangement.
• You can trust that it will provide you with your exact input string while making only the necessary conversions.
  • Exception : evaluate() method or evaluation mode as they return evaluation of mathematical expression found in your text.
• Large number support till quadrillion and Indian scale support till arab so no need to worry about large numbers.
• I find this useful when I've transcribed audio into text and need to seamlessly transform that textual data into numerical digits, mathematical operators, and ultimately, evaluate complex numerical expressions.

Table of Contents

1. Installation
2. Prerequisites
3. Usage
   • Method overview
   • numerical_words_to_numbers()
   • evaluate()
4. Examples
   • Sentence without any conversion
   • Convert digits from a random sentence
   • Large numbers
   • Indian numbering system
   • Convert ordinals
   • Dates and Years
   • Operator Conversion
   • Operator not with digits?
   • Decimal numbers
   • Have your own evaluate function?
   • Expression Evaluation
   • Numeric Calculation in Text
   • Handle all patterns at same time
5. Improvements or Issues
6. License
7. Contact
8. Acknowledgments

Installation

pip3 install numwords_to_nums

Prerequisites

• Python 3 or later

Usage

1. Import the NumWordsToNum class

   from numwords_to_nums.numwords_to_nums import NumWordsToNum
   

2. Initialize the NumWordsToNum object

   num = NumWordsToNum()
   

3. Select one of the below method based on your requirement

   • numerical_words_to_numbers()
   • evaluate()

4. Here's a basic example

   from numwords_to_nums.numwords_to_nums import NumWordsToNum
   num = NumWordsToNum()
      
   result = num.numerical_words_to_numbers("twenty ten and twenty one")
   print(result)  # Output: 2010 and 21
      
   eval_result = num.evaluate('Hey calculate 2+5')
   print(eval_result) # Output: 7
   

Method overview

• numerical_words_to_numbers()

  numerical_words_to_numbers(text, convert_operator=False, calculate_mode=False, evaluate=False)
  

  • Converts numerical words in the input text to their corresponding numeric digits. Optionally, it can also handle mathematical operator words and perform calculations.

  • Parameters:

    • text (str): The input text containing numerical words to be converted.
    • convert_operator (bool, optional): If True, converts operator words like "plus," "minus," etc., to their corresponding mathematical symbols (+, -, etc.). Use to display operators on UI or for user. Default is False.
    • calculate_mode (bool, optional): If True, activates the calculation mode, allowing mathematical operations to be performed later on if required, using converted numerical words and operators. Default is False
    • evaluate (bool, optional): If True, evaluates the mathematical expression in the text when in calculate_mode. Raises an exception if calculate_mode is not enabled. Default is False.

  • Returns:

    • str: The input text with numerical words and optionally operators converted to their numeric equivalents. If calculate_mode is enabled and evaluate is True, it returns the result of the mathematical expression.

  • Raises:

    • Exception: If convert_operator is set to False when calculate_mode is True, as operator conversion is required for calculation.
    • Exception: If evaluate is True but calculate_mode is not enabled, as calculation mode is necessary for evaluation.

• evaluate()

  evaluate()
  

  • Evaluates a mathematical expression represented as a string.

  • This method takes an input string containing a mathematical expression, cleans it by removing non-numeric and non-mathematical characters, and then attempts to evaluate the expression.

  • If the evaluation is successful, it returns the result as a string.

  • If an evaluation error occurs, it returns an error message indicating that the answer is undefined along with the specific evaluation error.

  • Args:

    • str: The input string containing a mathematical expression to be evaluated.

  • Returns:

    • str: The result of the mathematical expression as a string if evaluation is successful. If an error occurs during evaluation, it returns an error message with details of the error.

  • Example:

    • Input : '2 + 3 * 4' --> Output: '14'
    • Input : '10 / 0' --> Output: ' The answer is undefined. Evaluation error: division by zero'.

Examples

• Sentence without any conversion

  What happens if you feed a string which has no digits, ordinals or operators to be converted? Well we don't touch it

  • 'This is just a random sentence.' --> 'This is just a random sentence.'
  • How to use?

    • from numwords_to_nums.numwords_to_nums import NumWordsToNum
      scenario = 'This is just a random sentence.'
      num = NumWordsToNum()
      result = num.numerical_words_to_numbers(scenario)
      print(result)
      

• Convert digits from a random sentence

  Want to convert just the digits from your sentence? It's possible now. Here are a few examples

  • 'I am twenty five years old and my dad is fifty years old. I would like to get my father two cars!' --> 'I am 25 years old and my dad is 50 years old. I would like to get my father 2 cars!'
  • 'Joe Biden became the oldest person to assume the presidency at the age of seventy eight.' --> 'Joe Biden became the oldest person to assume the presidency at the age of 78.'
  • 'The event was held at the U.S. Capitol in Washington, D.C., and was attended by a limited number of people due to the COVID-nineteen pandemic.' --> 'The event was held at the U.S. Capitol in Washington, D.C., and was attended by a limited number of people due to the COVID-19 pandemic.'
  • How to use?

    • from numwords_to_nums.numwords_to_nums import NumWordsToNum
      scenario = 'Joe Biden became the oldest person to assume the presidency at the age of seventy eight.'
      num = NumWordsToNum()
      result = num.numerical_words_to_numbers(scenario)
      print(result)
      

• Large numbers

  Want support for large numbers? Sure, we will support you. We support till quadrillion

  • 'three hundred and forty five' --> '345'
  • 'five thousand three hundred and forty five' --> '5345'
  • 'sixty five thousand and twenty two' --> '65022'
  • 'one hundred thousand and sixty --> '100060'
  • 'ten million seventy thousand' --> '10070000'
  • 'one billion' --> '1000000000'
  • 'ten billion' --> '10000000000'
  • 'hundred billion' --> '100000000000'
  • 'thousand billion' --> '1000000000000'
  • 'one trillion' --> '1000000000000'
  • 'ten trillion' --> '10000000000000'
  • 'hundred trillion' --> '100000000000000'
  • 'thousand trillion' --> '1000000000000000'
  • 'one quadrillion' --> '1000000000000000'
  • 'ten quadrillion' --> '10000000000000000'
  • 'hundred quadrillion' --> '100000000000000000'
  • 'thousand quadrillion' --> '1000000000000000000'
  • 'That will be thousand Rs sir.' --> 'That will be 1000 Rs sir'
  • How to use?

    • from numwords_to_nums.numwords_to_nums import NumWordsToNum
      scenario = 'five thousand three hundred and forty five'
      num = NumWordsToNum()
      result = num.numerical_words_to_numbers(scenario)
      print(result)
      

• Indian numbering system

  Want support for large numbers in Indian scale? Sure, you have it. We support till arab

  • 'one lakh sixty thousand three hundred and twelve' --> '160312'
  • 'ten lakh thirty thousand' --> '1030000'
  • 'hundred lakh five thousand' --> '10005000'
  • 'thousand lakh' --> '100000000'
  • 'one crore two lakh thirty thousand' --> '10230000'
  • 'ten crore' --> '100000000'
  • 'hundred crore' --> '1000000000'
  • 'thousand crore' --> '10000000000'
  • 'one arab' --> '1000000000'
  • 'ten arab' --> '10000000000'
  • How to use?

    • from numwords_to_nums.numwords_to_nums import NumWordsToNum
      scenario = 'one crore two lakh thirty thousand'
      num = NumWordsToNum()
      result = num.numerical_words_to_numbers(scenario)
      print(result)
      

• Convert ordinals

  Looking for a way to convert ordinal numbers? Sure, you have it.

  • 'His inauguration took place on January twentieth, which marked the fifty ninth quadrennial presidential inauguration.' --> 'His inauguration took place on January 20th, which marked the 59th quadrennial presidential inauguration.'
  • 'Despite the challenges, the fifty ninth presidential inauguration was a historic moment for the country.' --> 'Despite the challenges, the 59th presidential inauguration was a historic moment for the country.'
  • How to use?

    • from numwords_to_nums.numwords_to_nums import NumWordsToNum
      scenario = 'Despite the challenges, the fifty ninth presidential inauguration was a historic moment for the country.'
      num = NumWordsToNum()
      result = num.numerical_words_to_numbers(scenario)
      print(result)
      

• Dates and Years

  Looking to manipulate dates and years? You're in the right place!

  • 'He was elected in November twenty twenty after defeating other contenders' --> 'He was elected in November 2020 after defeating other contenders'
  • 'I was born on first September nineteen ninety five' --> 'I was born on 1st September 1995'
  • 'I was born in two thousand and five and I an twenty five years old' --> 'I was born in 2005 and I an 25 years old'
  • How to use?

    • from numwords_to_nums.numwords_to_nums import NumWordsToNum
      scenario = 'I was born in two thousand and five and I an twenty five years old'
      num = NumWordsToNum()
      result = num.numerical_words_to_numbers(scenario)
      print(result)
      

• Operator Conversion

  Interested in converting operators for your programming needs? Want to display them on UI? Let's dive in!

  • plus
    • 'three plus five' --> '3+5'
  • minus
    • 'three minus five' --> '3-5'
  • multiply
    • 'multiply five by six' --> '5*6'
    • 'five multiplied by six' --> '5*6'
  • divide
    • 'five divided by six' --> '5/6'
    • 'divide five by six' --> '5/6'
  • equals
    • 'five is equal to five' --> '5=5'
    • 'five equals to five' --> '5=5'
    • 'five equal to five' --> '5=5'
    • 'five equal five' --> '5=5'
    • 'five equals five' --> '5=5'
  • not equal
    • 'four is not equal to five' --> '4≠5'
    • 'four is not equal five' --> '4≠5'
    • 'four is not equals five' --> '4≠5'
    • 'four not equal to five' --> '4≠5'
  • less than
    • 'three is less than seven' --> '3<7'
    • 'three less than seven' --> '3<7'
  • greater than
    • 'seven is greater than six' --> '7>6'
    • 'seven greater than six' --> '7>6'
  • less than equal to
    • 'three is less than or equals to three' --> '3≤3'
    • 'three is less than or equal to three' --> '3≤3'
    • 'three is less than equals to three' --> '3≤3'
    • 'three is less than equal to three' --> '3≤3'
    • 'three less than equals to three' --> '3≤3'
    • 'three less than equal to three' --> '3≤3'
  • greater than equal to
    • 'three is greater than or equals to three' --> '3≥3'
    • 'three is greater than or equal to three' --> '3≥3'
    • 'three is greater than equals to three' --> '3≥3'
    • 'three is greater than equal to three' --> '3≥3'
    • 'three greater than equals to three' --> '3≥3'
    • 'three greater than equal to three' --> '3≥3'
  • square root of
    • 'square root of seven' --> '√7'
  • square of
    • 'square of seven' --> '7 ²'
  • percent
    • 'ninety five percent' --> '95%'
  • How to use?

    • from numwords_to_nums.numwords_to_nums import NumWordsToNum
      scenario = 'ninety five percent'
      num = NumWordsToNum()
      result = num.numerical_words_to_numbers(scenario, convert_operator=True)
      print(result)
      

• Operators not with digits?

  Worried what will happen to operators if they are not with digits? Sure, we will take care of your input

  • 'Oxygen plus Hydrogen equals water' --> 'Oxygen plus Hydrogen equals water'
  • Note: We make sure to convert operators when you have digits with them

• Decimal numbers

  Want to convert decimal numbers? Sure, why not we support it

  • 'two point five equals two point five' --> '2.5=2.5'
  • 'two point five' --> '2.5'
  • 'The temperature outside is twenty five point five degrees Celsius.' --> 'The temperature outside is 25.5 degrees Celsius.'
  • How to use?

    • from numwords_to_nums.numwords_to_nums import NumWordsToNum
      scenario = 'The temperature outside is twenty five point five degrees Celsius.'
      num = NumWordsToNum()
      result = num.numerical_words_to_numbers(scenario, convert_operator=True)
      print(result)
      

• Have your own evaluate function?

  Want to convert operators so that you can pass it to your own evaluate function? Sure, we support it

  • 'four is not equal to five' --> '4!=5'
  • How to use?

    • from numwords_to_nums.numwords_to_nums import NumWordsToNum
      scenario = 'four is not equal to five'
      num = NumWordsToNum()
      result = num.numerical_words_to_numbers(scenario, convert_operator=True, calculate_mode=True)
      print(result)
      

• Expression Evaluation

  Need to evaluate expressions? We'll show you the way.

  • 'one point five plus zero point five' --> '2.0'
  • 'fifty percent of thousand' --> '500.0'
  • 'twenty-five percent of two hundred equals fifty' --> 'True'
  • 'three plus square of five' --> '28'
  • 'square root of four multiplied by square root of one plus six is equal to square root of twenty-five multiplied by three' --> 'False'
  • How to use?

    • from numwords_to_nums.numwords_to_nums import NumWordsToNum
      scenario = 'three plus square of five'
      num = NumWordsToNum()
      result = num.numerical_words_to_numbers(scenario, convert_operator=True, calculate_mode=True, evaluate=True)
      print(result)
      

• Numeric Calculation in Text

  Expressions along with different text? We'll show you the way.

  • 'Hey calculate three plus five' --> '8'
  • 'Hey calculate 3+5' --> '8'
  • How to use?

    • from numwords_to_nums.numwords_to_nums import NumWordsToNum
      scenario = 'Hey calculate three plus five'
      num = NumWordsToNum()
      result = num.numerical_words_to_numbers(scenario, convert_operator=True, calculate_mode=True, evaluate=True)
      print(result)
      

• Handle all patterns at same time

  Sure you can do that. Just go through above examples and you will get the idea

Improvements or Issues

• Complex arithmetic operations.
• Please email us if you find any issues.

License

• MIT License

Contact

• Please mail us if you have any issues.
• Make sure to put subject as --> Improvements for python library

Acknowledgements

I have heavily used code from the SO answers from here: https://stackoverflow.com/questions/493174/is-there-a-way-to-convert-number-words-to-integers and improved upon them