mathparse 0.2.0__tar.gz → 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,12 +1,12 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: mathparse
3
- Version: 0.2.0
3
+ Version: 0.2.2
4
4
  Summary: mathparse is a library for solving mathematical equations contained in strings
5
5
  Author: Gunther Cox
6
6
  License-Expression: MIT
7
- Project-URL: Documentation, https://docs.chatterbot.us
8
- Project-URL: Repository, https://github.com/gunthercox/ChatterBot
9
- Project-URL: Changelog, https://github.com/gunthercox/ChatterBot/releases
7
+ Project-URL: Documentation, https://mathparse.chatterbot.us
8
+ Project-URL: Repository, https://github.com/gunthercox/mathparse
9
+ Project-URL: Changelog, https://github.com/gunthercox/mathparse/releases
10
10
  Keywords: mathparse,mathematics,math,nlp
11
11
  Classifier: Development Status :: 4 - Beta
12
12
  Classifier: Intended Audience :: Developers
@@ -36,24 +36,34 @@ from mathparse import mathparse
36
36
  mathparse.parse('50 * (85 / 100)')
37
37
  >>> 42.5
38
38
 
39
- mathparse.parse('one hundred times fifty four', mathparse.codes.ENG)
39
+ mathparse.parse('one hundred times fifty four', language='ENG')
40
40
  >>> 5400
41
41
 
42
42
  mathparse.parse('(seven * nine) + 8 - (45 plus two)', language='ENG')
43
43
  >>> 24
44
44
  ```
45
45
 
46
+ ## Security
47
+
48
+ Mathparse does not employ the use of Python's [`eval` function](https://docs.python.org/3/library/functions.html#eval) when evaluating provided mathematical expressions. This is a measure to prevent arbitrary code execution vulnerabilities. See https://mathparse.chatterbot.us/postfix/ for additional details.
49
+
50
+ Mathparse is a standalone Python package and requires zero dependencies to function.
51
+
52
+ ## Language Support
53
+
54
+ The language parameter must be set in order to evaluate an equation that uses word operators.
55
+ The language code should be a valid [ISO 639-2](https://www.loc.gov/standards/iso639-2/php/code_list.php) language code.
56
+
46
57
  ## Installation
47
58
 
48
59
  ```bash
49
60
  pip install mathparse
50
61
  ```
51
62
 
52
- ## Language support
63
+ ## Documentation
53
64
 
54
- The language parameter must be set in order to evaluate an equation that uses word operators.
55
- The language code should be a valid [ISO 639-2](https://www.loc.gov/standards/iso639-2/php/code_list.php) language code.
65
+ See the full documentation at https://mathparse.chatterbot.us
56
66
 
57
- ## History
67
+ ## Changelog
58
68
 
59
- See [release notes](https://github.com/gunthercox/ChatterBot/releases) for changes.
69
+ See [release notes](https://github.com/gunthercox/mathparse/releases) for changes.
@@ -0,0 +1,43 @@
1
+ # mathparse
2
+
3
+ The `mathparse` library is a Python module designed to evaluate mathematical equations contained in strings.
4
+
5
+ Here are a few examples:
6
+
7
+ ```python
8
+ from mathparse import mathparse
9
+
10
+ mathparse.parse('50 * (85 / 100)')
11
+ >>> 42.5
12
+
13
+ mathparse.parse('one hundred times fifty four', language='ENG')
14
+ >>> 5400
15
+
16
+ mathparse.parse('(seven * nine) + 8 - (45 plus two)', language='ENG')
17
+ >>> 24
18
+ ```
19
+
20
+ ## Security
21
+
22
+ Mathparse does not employ the use of Python's [`eval` function](https://docs.python.org/3/library/functions.html#eval) when evaluating provided mathematical expressions. This is a measure to prevent arbitrary code execution vulnerabilities. See https://mathparse.chatterbot.us/postfix/ for additional details.
23
+
24
+ Mathparse is a standalone Python package and requires zero dependencies to function.
25
+
26
+ ## Language Support
27
+
28
+ The language parameter must be set in order to evaluate an equation that uses word operators.
29
+ The language code should be a valid [ISO 639-2](https://www.loc.gov/standards/iso639-2/php/code_list.php) language code.
30
+
31
+ ## Installation
32
+
33
+ ```bash
34
+ pip install mathparse
35
+ ```
36
+
37
+ ## Documentation
38
+
39
+ See the full documentation at https://mathparse.chatterbot.us
40
+
41
+ ## Changelog
42
+
43
+ See [release notes](https://github.com/gunthercox/mathparse/releases) for changes.
@@ -2,4 +2,4 @@
2
2
  mathparse is a library for solving mathematical equations contained in strings
3
3
  """
4
4
 
5
- __version__ = '0.2.0'
5
+ __version__ = '0.2.2'
@@ -0,0 +1,513 @@
1
+ """
2
+ Methods for evaluating mathematical equations in strings.
3
+ """
4
+ from decimal import Decimal
5
+ from typing import Union
6
+ from . import mathwords
7
+ import re
8
+
9
+
10
+ class PostfixTokenEvaluationException(Exception):
11
+ """
12
+ Exception to be raised when an expression cannot be evaluated.
13
+ """
14
+ pass
15
+
16
+
17
+ def is_int(string: str) -> bool:
18
+ """
19
+ Return true if string is an integer.
20
+ """
21
+ try:
22
+ int(string)
23
+ return True
24
+ except ValueError:
25
+ return False
26
+
27
+
28
+ def is_float(string: str) -> bool:
29
+ """
30
+ Return true if the string is a float.
31
+ """
32
+ try:
33
+ float(string)
34
+ return '.' in string
35
+ except ValueError:
36
+ return False
37
+
38
+
39
+ def is_constant(string: str) -> bool:
40
+ """
41
+ Return true if the string is a mathematical constant.
42
+ """
43
+ return mathwords.CONSTANTS.get(string, False)
44
+
45
+
46
+ def is_unary(string: str) -> bool:
47
+ """
48
+ Return true if the string is a defined unary mathematical
49
+ operator function.
50
+ """
51
+ return string in mathwords.UNARY_FUNCTIONS
52
+
53
+
54
+ def is_binary(string: str) -> bool:
55
+ """
56
+ Return true if the string is a defined binary operator.
57
+ """
58
+ return string in mathwords.BINARY_OPERATORS
59
+
60
+
61
+ def is_symbol(string: str) -> bool:
62
+ """
63
+ Return true if the string is a mathematical symbol.
64
+ """
65
+ return (
66
+ is_int(string) or is_float(string) or
67
+ is_constant(string) or is_unary(string) or
68
+ is_binary(string) or
69
+ (string == '(') or (string == ')')
70
+ )
71
+
72
+
73
+ def is_word(word: str, language: str) -> bool:
74
+ """
75
+ Return true if the word is a math word for the specified language.
76
+ """
77
+ words = mathwords.words_for_language(language)
78
+
79
+ return word in words
80
+
81
+
82
+ def find_word_groups(string: str, words: list) -> list:
83
+ """
84
+ Find matches for words in the format "3 thousand 6 hundred 2".
85
+ The words parameter should be the list of words to check for
86
+ such as "hundred".
87
+ """
88
+ scale_pattern = '|'.join(words)
89
+ # For example:
90
+ # (?:(?:\d+)\s+(?:hundred|thousand)*\s*)+(?:\d+|hundred|thousand)+
91
+ regex = re.compile(
92
+ r'(?:(?:\d+)\s+(?:' +
93
+ scale_pattern +
94
+ r')*\s*)+(?:\d+|' +
95
+ scale_pattern + r')+'
96
+ )
97
+ result = regex.findall(string)
98
+ return result
99
+
100
+
101
+ def replace_word_tokens(
102
+ string: str, language: str, stopwords: set[str] = None
103
+ ) -> str:
104
+ """
105
+ Replace word-based mathematical terms with their symbolic equivalents.
106
+
107
+ Given a string and an ISO 639-2 language code,
108
+ return the string with the words replaced with
109
+ an operational equivalent.
110
+ """
111
+ words = mathwords.word_groups_for_language(language)
112
+
113
+ # Replace binary operator words with numeric operators
114
+ binary_operators = words['binary_operators']
115
+ for operator in frozenset(binary_operators.keys()):
116
+ if operator in string:
117
+ string = string.replace(operator, binary_operators[operator])
118
+
119
+ # Handle prefix unary operators (like "square root of")
120
+ if 'prefix_unary_operators' in words:
121
+ prefix_unary_operators = words['prefix_unary_operators']
122
+ for operator in frozenset(prefix_unary_operators.keys()):
123
+ if operator in string:
124
+ string = string.replace(
125
+ operator, prefix_unary_operators[operator]
126
+ )
127
+
128
+ # Handle postfix unary operators (like "squared", "cubed")
129
+ if 'postfix_unary_operators' in words:
130
+ postfix_unary_operators = words['postfix_unary_operators']
131
+ for operator in frozenset(postfix_unary_operators.keys()):
132
+ if operator in string:
133
+ # Captures the number/operand before the unary operator
134
+ pattern = r'(\w+)\s+' + re.escape(operator)
135
+ replacement = r'(\1 ' + postfix_unary_operators[operator] + ')'
136
+ string = re.sub(pattern, replacement, string)
137
+
138
+ # Handle compound numbers:
139
+ # (e.g., "twenty one" -> "(20 + 1)", "fifty four" -> "(50 + 4)")
140
+ numbers = words['numbers']
141
+
142
+ # Create regex patterns for compound numbers
143
+ # Pattern matches: (tens_word) (units_word) where tens_word is
144
+ # 20,30,40,...,90 and units_word is 1-9
145
+ tens_words = {word: value for word, value in numbers.items() if value in [
146
+ 20, 30, 40, 50, 60, 70, 80, 90
147
+ ]}
148
+ units_words = {word: value for word, value in numbers.items() if value in [
149
+ 1, 2, 3, 4, 5, 6, 7, 8, 9
150
+ ]}
151
+
152
+ # Preprocess hyphenated compound numbers
153
+ # (e.g., "fifty-four" -> "fifty four")
154
+ for tens_word in tens_words.keys():
155
+ for units_word in units_words.keys():
156
+ hyphenated_pattern = tens_word + r'-' + units_word
157
+ space_separated = tens_word + ' ' + units_word
158
+ if re.search(hyphenated_pattern, string):
159
+ string = re.sub(hyphenated_pattern, space_separated, string)
160
+
161
+ # Replace compound numbers first (before individual number replacement)
162
+ for tens_word, tens_value in tens_words.items():
163
+ for units_word, units_value in units_words.items():
164
+ compound_pattern = tens_word + r'\s+' + units_word
165
+ compound_replacement = f'({tens_value} + {units_value})'
166
+ if re.search(compound_pattern, string):
167
+ string = re.sub(compound_pattern, compound_replacement, string)
168
+
169
+ # Replace number words with numeric values
170
+ for number in frozenset(numbers.keys()):
171
+ # Use word boundaries to prevent partial matches
172
+ # (e.g., "nine" in "nineteen")
173
+ pattern = r'\b' + re.escape(number) + r'\b'
174
+ if re.search(pattern, string):
175
+ string = re.sub(pattern, str(numbers[number]), string)
176
+
177
+ # Remove words specified to be ignored
178
+ if stopwords:
179
+ filtered_words = []
180
+
181
+ for word in string.split():
182
+ if word not in stopwords:
183
+ filtered_words.append(word)
184
+ string = ' '.join(filtered_words)
185
+
186
+ # Replace scaling multipliers with numeric values
187
+ scales = words['scales']
188
+ end_index_characters = mathwords.BINARY_OPERATORS
189
+ end_index_characters.add('(')
190
+
191
+ word_matches = find_word_groups(string, frozenset(scales.keys()))
192
+
193
+ for match in word_matches:
194
+ string = string.replace(match, '(' + match + ')')
195
+
196
+ for scale in frozenset(scales.keys()):
197
+ for _ in range(0, string.count(scale)):
198
+ start_index = string.find(scale) - 1
199
+ end_index = len(string)
200
+
201
+ while is_int(string[start_index - 1]) and start_index > 0:
202
+ start_index -= 1
203
+
204
+ end_index = string.find(' ', start_index) + 1
205
+ end_index = string.find(' ', end_index) + 1
206
+
207
+ add = ' + '
208
+ if string[end_index] in end_index_characters:
209
+ add = ''
210
+
211
+ string = string[:start_index] + '(' + string[start_index:]
212
+ string = string.replace(
213
+ scale, '* ' + str(scales[scale]) + ')' + add,
214
+ 1
215
+ )
216
+
217
+ string = string.replace(') (', ') + (')
218
+
219
+ # Remove extra parentheses around all scale expressions to simplify output
220
+ # Convert ((number * scale)) to (number * scale) for all scales
221
+ string = re.sub(r'\(\((\d+\s*\*\s*\d+)\)\)', r'(\1)', string)
222
+
223
+ return string
224
+
225
+
226
+ def to_postfix(tokens: list) -> list:
227
+ """
228
+ Convert a list of evaluatable tokens to postfix format.
229
+ """
230
+ precedence = {
231
+ '/': 4,
232
+ '*': 4,
233
+ '+': 3,
234
+ '-': 3,
235
+ '^': 2,
236
+ '(': 1
237
+ }
238
+
239
+ # Unary functions have a higher precedence than binary operators
240
+ unary_precedence = max(precedence.values()) + 1
241
+
242
+ postfix = []
243
+ opstack = []
244
+
245
+ for token in tokens:
246
+ if is_int(token):
247
+ postfix.append(int(token))
248
+ elif is_float(token):
249
+ postfix.append(float(token))
250
+ elif token in mathwords.CONSTANTS:
251
+ postfix.append(mathwords.CONSTANTS[token])
252
+ elif is_unary(token):
253
+ opstack.append(token)
254
+ elif token == '(':
255
+ opstack.append(token)
256
+ elif token == ')':
257
+ top_token = opstack.pop()
258
+ while top_token != '(':
259
+ postfix.append(top_token)
260
+ top_token = opstack.pop()
261
+ elif is_binary(token):
262
+ # For binary operators, pop operators with higher or
263
+ # equal precedence
264
+ while (opstack != []) and (
265
+ (
266
+ opstack[-1] in precedence and token in precedence and (
267
+ precedence[opstack[-1]] >= precedence[token]
268
+ )
269
+ ) or
270
+ (
271
+ is_unary(
272
+ opstack[-1]
273
+ ) and unary_precedence >= precedence[token]
274
+ )
275
+ ):
276
+ postfix.append(opstack.pop())
277
+ opstack.append(token)
278
+ else:
279
+ # Raise exception for unsupported mathematical terms
280
+ raise PostfixTokenEvaluationException(
281
+ 'Unsupported mathematical term: "{}"'.format(token)
282
+ )
283
+
284
+ while opstack != []:
285
+ postfix.append(opstack.pop())
286
+
287
+ return postfix
288
+
289
+
290
+ def evaluate_postfix(tokens: list) -> Union[int, float, str, Decimal]:
291
+ """
292
+ Given a list of evaluatable tokens in postfix format,
293
+ calculate a solution.
294
+ """
295
+ stack = []
296
+
297
+ for token in tokens:
298
+ total = None
299
+
300
+ if is_int(token) or is_float(token) or is_constant(token):
301
+ stack.append(token)
302
+ elif is_unary(token):
303
+ a = stack.pop()
304
+ total = mathwords.UNARY_FUNCTIONS[token](a)
305
+ elif len(stack) == 1:
306
+ raise PostfixTokenEvaluationException(
307
+ 'Insufficient values in expression for operator "{}"'.format(
308
+ token
309
+ )
310
+ )
311
+ elif len(stack) > 1:
312
+ b = stack.pop()
313
+ a = stack.pop()
314
+ if token == '+':
315
+ total = a + b
316
+ elif token == '-':
317
+ total = a - b
318
+ elif token == '*':
319
+ total = a * b
320
+ elif token == '^':
321
+ total = a ** b
322
+ elif token == '/':
323
+ if Decimal(str(b)) == 0:
324
+ total = 'undefined'
325
+ else:
326
+ total = Decimal(str(a)) / Decimal(str(b))
327
+ else:
328
+ raise PostfixTokenEvaluationException(
329
+ 'Unknown token "{}"'.format(token)
330
+ )
331
+
332
+ if total is not None:
333
+ stack.append(total)
334
+
335
+ # If the stack is empty the tokens could not be evaluated
336
+ if not stack:
337
+ raise PostfixTokenEvaluationException(
338
+ 'The postfix expression resulted in an empty stack'
339
+ )
340
+
341
+ return stack.pop()
342
+
343
+
344
+ def tokenize(string: str, language: str = None, escape: str = '___') -> list:
345
+ """
346
+ Convert a string into a list of mathematical tokens for processing.
347
+
348
+ Args:
349
+ string (str): The input string containing a mathematical expression.
350
+
351
+ language (str, optional): ISO 639-2 language code for word-based
352
+ parsing. If None, only numeric expressions
353
+ are supported.
354
+
355
+ escape (str, optional): A string used to temporarily replace spaces
356
+ in multi-word phrases during tokenization.
357
+ Default is '___'.
358
+
359
+ Returns:
360
+ list: A list of tokens extracted from the input string.
361
+ """
362
+ # Set all words to lowercase
363
+ string = string.lower()
364
+
365
+ # Ignore punctuation
366
+ if len(string) and not string[-1].isalnum():
367
+ character = string[-1]
368
+ string = string[:-1] + ' ' + character
369
+
370
+ # Parenthesis must have space around them to be tokenized properly
371
+ string = string.replace('(', ' ( ')
372
+ string = string.replace(')', ' ) ')
373
+
374
+ if language:
375
+ words = mathwords.words_for_language(language)
376
+
377
+ for phrase in words:
378
+ escaped_phrase = phrase.replace(' ', escape)
379
+ string = string.replace(phrase, escaped_phrase)
380
+
381
+ tokens = string.split()
382
+
383
+ for index, token in enumerate(tokens):
384
+ tokens[index] = token.replace(escape, ' ')
385
+
386
+ return tokens
387
+
388
+
389
+ def parse(
390
+ string: str, language: str = None, stopwords: set[str] = None
391
+ ) -> Union[int, float, str, Decimal]:
392
+ """
393
+ Parse and evaluate a mathematical expression from a string.
394
+
395
+ This is the main entry point for mathparse. It can handle both numeric
396
+ expressions (like "2 + 3 * 4") and word-based expressions in various
397
+ languages (like "five plus three" in English).
398
+
399
+ Args:
400
+ string (str): The mathematical expression to parse and evaluate.
401
+ Can contain numbers, operators, parentheses, constants,
402
+ and functions. For word-based parsing, must use terms
403
+ from the specified language.
404
+ language (str, optional): ISO 639-2 language code for word-based
405
+ parsing. Supported codes: 'ENG', 'FRE', 'GER',
406
+ 'GRE', 'ITA', 'MAR', 'RUS', 'POR'. If None,
407
+ only numeric expressions are supported.
408
+ stopwords (set[str], optional): A set of words to ignore during
409
+ parsing. This can be used to filter out
410
+ non-mathematical words in expressions.
411
+
412
+ Returns:
413
+ int, float, or str: The result of the mathematical expression.
414
+ Returns 'undefined' for division by zero.
415
+ For division operations, returns a Decimal object
416
+ to maintain precision.
417
+
418
+ Raises:
419
+ InvalidLanguageCodeException:
420
+ An unsupported language code was provided.
421
+ PostfixTokenEvaluationException:
422
+ The expression cannot be evaluated.
423
+
424
+ Examples:
425
+ >>> parse('2 + 3 * 4')
426
+ 14
427
+
428
+ >>> parse('five plus three', language='ENG')
429
+ 8
430
+
431
+ >>> parse('(seven * nine) + 8 - (45 plus two)', language='ENG')
432
+ 24
433
+
434
+ >>> parse('sqrt 16')
435
+ 4.0
436
+
437
+ >>> parse('pi * 2')
438
+ 6.283386
439
+
440
+ >>> parse('10 / 0')
441
+ 'undefined'
442
+
443
+ Note:
444
+ - Follows standard order of operations (PEMDAS)
445
+ - Supports mathematical constants: pi, e
446
+ - Supports unary functions: sqrt, log
447
+ - Each expression must use terms from a single language
448
+ - Division by zero returns 'undefined' instead of raising an exception
449
+ """
450
+ if language:
451
+ string = replace_word_tokens(string, language, stopwords)
452
+
453
+ tokens = tokenize(string)
454
+ postfix = to_postfix(tokens)
455
+
456
+ return evaluate_postfix(postfix)
457
+
458
+
459
+ def extract_expression(dirty_string: str, language: str) -> str:
460
+ """
461
+ Extract a mathematical expression from a sentence containing extra text.
462
+
463
+ This function identifies and extracts the mathematical portion from
464
+ natural language sentences like:
465
+ "What is 4 + 4?" or "Calculate five plus three".
466
+ It works by finding the longest sequence of mathematical symbols and words.
467
+
468
+ Args:
469
+ dirty_string (str): A sentence or phrase containing a mathematical
470
+ expression mixed with other text.
471
+ language (str): ISO 639-2 language code to identify mathematical
472
+ words in the target language.
473
+
474
+ Returns:
475
+ str: The extracted mathematical expression as a string.
476
+
477
+ Examples:
478
+ >>> extract_expression("What is 5 plus 3?", language='ENG')
479
+ '5 plus 3'
480
+
481
+ >>> extract_expression(
482
+ "Please calculate two times seven", language='ENG'
483
+ )
484
+ 'two times seven'
485
+
486
+ >>> extract_expression(
487
+ "The result of 10 / 2 should be 5", language=None
488
+ )
489
+ '10 / 2'
490
+
491
+ Note:
492
+ - The function looks for continuous sequences of mathematical terms
493
+ - Non-mathematical words at the beginning and end are stripped
494
+ - The language parameter is required to identify word-based math terms
495
+ """
496
+ tokens = tokenize(dirty_string, language)
497
+
498
+ start_index = 0
499
+ end_index = len(tokens)
500
+
501
+ for part in tokens:
502
+ if is_symbol(part) or is_word(part, language):
503
+ break
504
+ else:
505
+ start_index += 1
506
+
507
+ for part in reversed(tokens):
508
+ if is_symbol(part) or is_word(part, language):
509
+ break
510
+ else:
511
+ end_index -= 1
512
+
513
+ return ' '.join(tokens[start_index:end_index])