0
# Mathparse
1

2
Mathparse is a Python library for solving mathematical equations contained in strings, supporting both numeric expressions and natural language mathematical phrases in multiple languages. It provides a simple, unified API for evaluating mathematical expressions from user input, text processing systems, and NLP applications.
3

4
## Package Information
5

6
- **Package Name**: mathparse
7
- **Language**: Python
8
- **Installation**: `pip install mathparse`
9

10
## Core Imports
11

12
```python
13
from mathparse import mathparse
14
```
15

16
For accessing constants and language utilities:
17

18
```python
19
from mathparse import mathwords
20
```
21

22
## Module Organization
23

24
The mathparse package provides access to functionality through two main modules:
25

26
- **`mathparse.mathparse`**: Core parsing and evaluation functions (imported as `mathparse`)
27
- **`mathparse.mathwords`**: Language dictionaries, constants, and utility functions (imported as `mathwords`)
28

29
## Basic Usage
30

31
```python
32
from mathparse import mathparse
33

34
# Basic numeric expressions
35
result = mathparse.parse('50 * (85 / 100)')
36
# Returns: 42.5
37

38
# Natural language expressions (requires language parameter)
39
result = mathparse.parse('nine times nine', language='ENG')
40
# Returns: 81
41

42
# Mixed numeric and word expressions
43
result = mathparse.parse('(seven * nine) + 8 - (45 plus two)', language='ENG')
44
# Returns: 24
45

46
# Extracting expressions from noisy text
47
expression = mathparse.extract_expression('What is 4 + 4?', language='ENG')
48
# Returns: '4 + 4'
49
result = mathparse.parse(expression)
50
# Returns: 8
51
```
52

53
## Capabilities
54

55
### Mathematical Expression Parsing
56

57
Evaluates mathematical expressions from strings, supporting standard arithmetic operations and natural language mathematical phrases.
58

59
```python { .api }
60
def parse(string, language=None):
61
    """
62
    Return a solution to the equation in the input string.
63

64
    Args:
65
        string (str): Mathematical expression as string (e.g., "4 + 4" or "four plus four")
66
        language (str, optional): ISO 639-2 language code for natural language support
67

68
    Returns:
69
        number: Computed result (int, float, or Decimal for division)
70
    """
71
```
72

73
### Expression Extraction
74

75
Extracts mathematical expressions from noisy text, filtering out non-mathematical content.
76

77
```python { .api }
78
def extract_expression(dirty_string, language):
79
    """
80
    Extract mathematical expression from text containing non-mathematical content.
81

82
    Args:
83
        dirty_string (str): Text containing mathematical expression
84
        language (str): ISO 639-2 language code for word recognition
85

86
    Returns:
87
        str: Cleaned mathematical expression
88
    """
89
```
90

91
### String Tokenization
92

93
Converts string expressions into lists of mathematical tokens for processing.
94

95
```python { .api }
96
def tokenize(string, language=None, escape='___'):
97
    """
98
    Convert string into list of mathematical symbol tokens.
99

100
    Args:
101
        string (str): Input mathematical expression
102
        language (str, optional): ISO 639-2 language code for word recognition
103
        escape (str): Character sequence for escaping spaces in multi-word phrases
104

105
    Returns:
106
        list: List of mathematical tokens
107
    """
108
```
109

110
### Validation Functions
111

112
Utility functions for checking whether strings represent specific mathematical elements.
113

114
```python { .api }
115
def is_int(string):
116
    """
117
    Check if string represents an integer.
118

119
    Args:
120
        string (str): String to check
121

122
    Returns:
123
        bool: True if string is an integer
124
    """
125

126
def is_float(string):
127
    """
128
    Check if string represents a float.
129

130
    Args:
131
        string (str): String to check
132

133
    Returns:
134
        bool: True if string is a float
135
    """
136

137
def is_constant(string):
138
    """
139
    Check if string is a mathematical constant.
140

141
    Args:
142
        string (str): String to check
143

144
    Returns:
145
        bool: True if string is a mathematical constant (pi, e)
146
    """
147

148
def is_unary(string):
149
    """
150
    Check if string is a unary mathematical operator.
151

152
    Args:
153
        string (str): String to check
154

155
    Returns:
156
        bool: True if string is a unary operator (sqrt, log)
157
    """
158

159
def is_binary(string):
160
    """
161
    Check if string is a binary mathematical operator.
162

163
    Args:
164
        string (str): String to check
165

166
    Returns:
167
        bool: True if string is a binary operator (+, -, *, /, ^)
168
    """
169

170
def is_symbol(string):
171
    """
172
    Check if string is any mathematical symbol.
173

174
    Args:
175
        string (str): String to check
176

177
    Returns:
178
        bool: True if string is a mathematical symbol
179
    """
180

181
def is_word(word, language):
182
    """
183
    Check if word is a mathematical word in the specified language.
184

185
    Args:
186
        word (str): Word to check
187
        language (str): ISO 639-2 language code
188

189
    Returns:
190
        bool: True if word is a math word in the language
191
    """
192
```
193

194
### Language Support
195

196
Access to language-specific mathematical vocabularies and word-to-symbol mappings.
197

198
```python { .api }
199
# Available through mathparse.mathwords module
200
def word_groups_for_language(language_code):
201
    """
202
    Get complete word groups for a language code.
203

204
    Args:
205
        language_code (str): ISO 639-2 language code
206

207
    Returns:
208
        dict: Dictionary containing numbers, operators, and scales for the language
209

210
    Raises:
211
        InvalidLanguageCodeException: If language code is not supported
212
    """
213

214
def words_for_language(language_code):
215
    """
216
    Get all mathematical words for a language code.
217

218
    Args:
219
        language_code (str): ISO 639-2 language code
220

221
    Returns:
222
        list: List of all mathematical words in the language
223

224
    Raises:
225
        InvalidLanguageCodeException: If language code is not supported
226
    """
227
```
228

229
### Advanced Processing
230

231
Internal processing functions for postfix notation and expression evaluation.
232

233
```python { .api }
234
def replace_word_tokens(string, language):
235
    """
236
    Replace word tokens with numeric equivalents.
237

238
    Args:
239
        string (str): String containing word tokens
240
        language (str): ISO 639-2 language code
241

242
    Returns:
243
        str: String with words replaced by numeric operators
244
    """
245

246
def to_postfix(tokens):
247
    """
248
    Convert list of tokens to postfix notation.
249

250
    Args:
251
        tokens (list): List of mathematical tokens
252

253
    Returns:
254
        list: Tokens in postfix notation
255
    """
256

257
def evaluate_postfix(tokens):
258
    """
259
    Evaluate tokens in postfix notation.
260

261
    Args:
262
        tokens (list): Tokens in postfix notation
263

264
    Returns:
265
        number: Computed result
266

267
    Raises:
268
        PostfixTokenEvaluationException: If evaluation fails
269
    """
270

271
def find_word_groups(string, words):
272
    """
273
    Find word group patterns for scaling (e.g., "3 thousand 6 hundred").
274

275
    Args:
276
        string (str): Input string
277
        words (list): List of scaling words to match
278

279
    Returns:
280
        list: List of matched word group patterns
281
    """
282
```
283

284
## Language Support
285

286
The library supports mathematical expressions in the following languages (ISO 639-2 codes):
287

288
- **ENG** (English): "four plus four", "twenty times three"
289
- **FRE** (French): "quatre plus quatre", "vingt fois trois"  
290
- **GER** (German): "vier plus vier", "zwanzig mal drei"
291
- **GRE** (Greek): "τέσσερα συν τέσσερα"
292
- **ITA** (Italian): "quattro più quattro"
293
- **MAR** (Marathi): "चार बेरीज चार"
294
- **RUS** (Russian): "четыре плюс четыре"
295
- **POR** (Portuguese): "quatro mais quatro"
296

297
Each language includes:
298
- Number words (zero through ninety, plus scales)
299
- Binary operators (plus, minus, times, divided by, power)
300
- Unary operators (squared, cubed, square root)
301
- Scaling words (hundred, thousand, million, billion, trillion)
302

303
## Constants and Functions
304

305
### Mathematical Constants
306

307
```python { .api }
308
# Access mathematical constants
309
from mathparse import mathwords
310

311
CONSTANTS = mathwords.CONSTANTS
312
# Returns: {'pi': 3.141693, 'e': 2.718281}
313
```
314

315
### Mathematical Functions
316

317
```python { .api }
318
# Access unary mathematical functions
319
from mathparse import mathwords
320

321
UNARY_FUNCTIONS = mathwords.UNARY_FUNCTIONS
322
# Returns: {'sqrt': math.sqrt, 'log': math.log10}
323
```
324

325
### Language Codes
326

327
```python { .api }
328
# Access available language codes
329
from mathparse import mathwords
330

331
LANGUAGE_CODES = mathwords.LANGUAGE_CODES
332
# Returns: ['ENG', 'FRE', 'GER', 'GRE', 'ITA', 'MAR', 'RUS', 'POR']
333
```
334

335
## Numeric Types
336

337
### Decimal Class
338

339
High-precision decimal arithmetic class used for division operations to maintain precision.
340

341
```python { .api }
342
# Decimal type used by mathparse (from Python's decimal module)
343
from decimal import Decimal
344

345
class Decimal:
346
    """
347
    High-precision decimal arithmetic class used for division operations.
348
    
349
    Used internally by mathparse to avoid floating-point precision issues.
350
    Results from division operations return Decimal objects.
351
    """
352
    def __init__(self, value):
353
        """Create Decimal from string or number."""
354
    
355
    def __str__(self):
356
        """Return string representation."""
357
    
358
    # Supports standard arithmetic operations: +, -, *, /, ==, etc.
359
```
360

361
## Exception Classes
362

363
```python { .api }
364
# Available through mathparse import
365
from mathparse import mathparse
366

367
class PostfixTokenEvaluationException(Exception):
368
    """
369
    Exception raised when postfix token evaluation fails.
370
    Common causes: unknown tokens, empty expression stack, malformed expressions.
371
    """
372

373
# Available through mathwords import  
374
from mathparse import mathwords
375

376
class InvalidLanguageCodeException(Exception):
377
    """
378
    Exception raised when an unsupported ISO 639-2 language code is provided.
379
    """
380
```
381

382
## Error Handling
383

384
```python
385
from mathparse import mathparse, mathwords
386

387
try:
388
    result = mathparse.parse('invalid expression')
389
except mathparse.PostfixTokenEvaluationException as e:
390
    print(f"Expression evaluation failed: {e}")
391

392
try:
393
    words = mathwords.words_for_language('XXX')
394
except mathwords.InvalidLanguageCodeException as e:
395
    print(f"Invalid language code: {e}")
396

397
# Division by zero returns 'undefined' string rather than raising exception
398
result = mathparse.parse('5 / 0')
399
# Returns: 'undefined'
400
```
401

402
## Usage Examples
403

404
### Complex Natural Language Expressions
405

406
```python
407
from mathparse import mathparse
408

409
# Large number expressions with scales
410
result = mathparse.parse('four thousand two hundred one plus five hundred', language='ENG')
411
# Returns: 4701
412

413
# Mixed operations with parentheses
414
result = mathparse.parse('(seven * nine) + 8 - (45 plus two)', language='ENG')
415
# Returns: 24
416

417
# Power operations
418
result = mathparse.parse('two to the power of three', language='ENG')
419
# Returns: 8
420

421
# Constants and functions
422
result = mathparse.parse('sqrt 25')
423
# Returns: 5.0
424

425
result = mathparse.parse('pi * 2')
426
# Returns: 6.283386
427
```
428

429
### Text Processing Integration
430

431
```python
432
from mathparse import mathparse
433

434
# Extract and evaluate from natural text
435
user_input = "Can you tell me what is 15 plus 27?"
436
expression = mathparse.extract_expression(user_input, language='ENG')
437
# Returns: '15 plus 27'
438

439
result = mathparse.parse(expression, language='ENG')
440
# Returns: 42
441

442
# Multi-language support
443
result = mathparse.parse('vingt plus trente', language='FRE') 
444
# Returns: 50
445

446
result = mathparse.parse('zwanzig plus dreißig', language='GER')
447
# Returns: 50
448
```