Skip to content

Commit ef828d4

Browse files
gunthercoxgunthercox
committed
Update documentation
1 parent dc5dd14 commit ef828d4

File tree

6 files changed

+472
-13
lines changed

6 files changed

+472
-13
lines changed

‎README.md‎

Lines changed: 61 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,83 @@
11
# mathparse
22

3-
The `mathparse` library is a Python module designed to evaluate mathematical equations contained in strings.
3+
**A secure, multilingual mathematical expression evaluator for Python**
44

5-
Here are a few examples:
5+
`mathparse` is a Python library that safely parses and evaluates mathematical expressions from strings, supporting both numeric operators and natural language words across 13+ languages. Unlike Python's dangerous `eval()` function, mathparse provides a secure, zero-dependency solution for evaluating user-provided mathematical expressions.
6+
7+
## Why mathparse?
8+
9+
✅ **Security First** - Never uses `eval()`, protecting against arbitrary code execution
10+
✅ **Multilingual Support** - Parse math in English, Spanish, French, German, Chinese, and 8+ more languages
11+
✅ **Zero Dependencies** - Pure Python implementation with no external requirements
12+
✅ **Natural Language** - Understands "fifty times twenty plus ten" alongside standard notation
13+
✅ **Production Ready** - Used in chatbots, calculators, voice assistants, and educational applications
14+
✅ **Well Tested** - Comprehensive test suite ensuring reliability
15+
16+
## Quick Examples
617

718
```python
819
from mathparse import mathparse
920

21+
# Standard numeric expressions
1022
mathparse.parse('50 * (85 / 100)')
1123
>>> 42.5
1224

25+
# Natural language in English
1326
mathparse.parse('one hundred times fifty four', language='ENG')
1427
>>> 5400
1528

29+
# Mixed notation
1630
mathparse.parse('(seven * nine) + 8 - (45 plus two)', language='ENG')
1731
>>> 24
32+
33+
# Other languages (French, Spanish, German, Chinese, etc.)
34+
mathparse.parse('cinq plus trois', language='FRE')
35+
>>> 8
36+
37+
mathparse.parse('cinco más tres', language='ESP')
38+
>>> 8
39+
```
40+
41+
## Use Cases
42+
43+
- 🤖 **Chatbots & Voice Assistants** - Parse natural language math queries
44+
- 🧮 **Calculator Applications** - Build safe calculators that accept text input
45+
- 📚 **Educational Software** - Evaluate student-provided math expressions
46+
- 🌐 **Multilingual Apps** - Support math parsing in users' native languages
47+
- 🔐 **Secure Code Evaluation** - Replace dangerous `eval()` calls with safe parsing
48+
- 📊 **Data Processing** - Extract and calculate values from natural language text
49+
50+
## Security: Why Not eval()?
51+
52+
Python's `eval()` function executes arbitrary code, creating severe security vulnerabilities:
53+
54+
```python
55+
# DANGEROUS - Never do this with user input!
56+
eval("__import__('os').system('rm -rf /')") # Deletes files
57+
eval("__import__('requests').get('evil.com')") # Network access
1858
```
1959

20-
## Security
60+
**mathparse is the safe alternative:**
61+
62+
| Feature | eval() | mathparse |
63+
|---------|--------|-----------|
64+
| Mathematical expressions | ✅ | ✅ |
65+
| Arbitrary code execution | ⚠️ **YES - DANGEROUS** | ❌ No |
66+
| File system access | ⚠️ **YES - DANGEROUS** | ❌ No |
67+
| Network access | ⚠️ **YES - DANGEROUS** | ❌ No |
68+
| Import statements | ⚠️ **YES - DANGEROUS** | ❌ No |
69+
| Security risk | 🔴 **CRITICAL** | 🟢 Safe |
70+
| Dependencies | 0 | 0 |
71+
| Natural language support | ❌ No | ✅ Yes |
72+
| Multilingual | ❌ No | ✅ 13+ languages |
73+
74+
mathparse uses [postfix (Reverse Polish) notation](https://mathparse.chatterbot.us/postfix/) internally, ensuring only valid mathematical operations are performed. See our [security documentation](https://mathparse.chatterbot.us/postfix/) for technical details.
2175

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.
76+
## Performance
2377

24-
Mathparse is a standalone Python package and requires zero dependencies to function.
78+
- **Fast**: Simple numeric expressions parse in microseconds
79+
- **Efficient**: Minimal memory footprint, suitable for high-volume applications
80+
- **Scalable**: Linear time complexity for expression evaluation
2581

2682
## Language Support
2783

‎docs/_templates/layout.html‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,54 @@
1111
{{ super() }}
1212
{%- endblock %}
1313

14+
{%- block extrahead %}
15+
{{ super() }}
16+
17+
{# SEO Meta Tags #}
18+
<meta name="description" content="{{ meta.get('description', 'mathparse: Secure Python library for parsing and evaluating mathematical expressions. Supports 13+ languages, natural language input, and safe eval() alternative with zero dependencies.') if meta else 'mathparse: Secure Python library for parsing and evaluating mathematical expressions. Supports 13+ languages, natural language input, and safe eval() alternative with zero dependencies.' }}">
19+
<meta name="keywords" content="python, math parser, eval alternative, mathematical expressions, natural language processing, multilingual, calculator, secure evaluation, postfix notation, RPN, safe eval">
20+
<meta name="author" content="Gunther Cox">
21+
22+
{# Open Graph Meta Tags for Social Sharing #}
23+
<meta property="og:title" content="{{ title|striptags|e }}{% if title %} - {% endif %}mathparse">
24+
<meta property="og:description" content="{{ meta.get('description', 'Secure Python library for parsing mathematical expressions. Safe alternative to eval() with multilingual support.') if meta else 'Secure Python library for parsing mathematical expressions. Safe alternative to eval() with multilingual support.' }}">
25+
<meta property="og:type" content="website">
26+
<meta property="og:url" content="{{ pageurl|e }}">
27+
<meta property="og:site_name" content="mathparse Documentation">
28+
<meta property="og:image" content="https://mathparse.chatterbot.us/_static/mathparse.png">
29+
30+
{# Additional SEO Tags #}
31+
<meta name="robots" content="index, follow">
32+
<meta name="language" content="English">
33+
<meta name="revisit-after" content="7 days">
34+
35+
{# Structured Data for Search Engines #}
36+
<script type="application/ld+json">
37+
{
38+
"@context": "https://schema.org",
39+
"@type": "SoftwareApplication",
40+
"name": "mathparse",
41+
"description": "Secure Python library for parsing and evaluating mathematical expressions with multilingual support",
42+
"url": "https://mathparse.chatterbot.us",
43+
"applicationCategory": "DeveloperApplication",
44+
"operatingSystem": "Cross-platform",
45+
"programmingLanguage": "Python",
46+
"offers": {
47+
"@type": "Offer",
48+
"price": "0",
49+
"priceCurrency": "USD"
50+
},
51+
"author": {
52+
"@type": "Person",
53+
"name": "Gunther Cox"
54+
},
55+
"codeRepository": "https://github.com/gunthercox/mathparse",
56+
"softwareVersion": "{{ version|e }}",
57+
"license": "https://opensource.org/licenses/MIT"
58+
}
59+
</script>
60+
{%- endblock %}
61+
1462
{%- block relbaritems %}
1563
<li class="right"><a href="{{github_page_link()}}">Edit on GitHub</a> |</li>
1664
{% endblock %}

‎docs/conf.py‎

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,13 @@
5757
author
5858
)
5959

60+
# Project description
61+
project_description = (
62+
'Secure Python library for parsing and evaluating mathematical '
63+
'expressions. Safe alternative to eval() with multilingual support '
64+
'for natural language math in 13+ languages.'
65+
)
66+
6067
# The version info for the project you're documenting, acts as replacement for
6168
# |version| and |release|, also used in various other places throughout the
6269
# built documents.
@@ -117,6 +124,22 @@
117124

118125
html_baseurl = 'https://mathparse.chatterbot.us/'
119126

127+
html_context = {
128+
'extra_css_files': [
129+
'_static/style.css'
130+
],
131+
'meta': {
132+
'description': project_description,
133+
'keywords': (
134+
'python, math parser, eval alternative, mathematical expressions, '
135+
'natural language processing, multilingual, calculator, '
136+
'secure evaluation, postfix notation, RPN, safe eval, '
137+
'reverse polish notation, expression parser'
138+
),
139+
'author': author,
140+
}
141+
}
142+
120143
# Add any paths that contain custom static files (such as style sheets) here,
121144
# relative to this directory. They are copied after the builtin static files,
122145
# so a file named "default.css" will overwrite the builtin "default.css".
@@ -140,12 +163,6 @@
140163
# Output file base name for HTML help builder.
141164
htmlhelp_basename = 'mathparsedoc'
142165

143-
html_context = {
144-
'extra_css_files': [
145-
'_static/style.css'
146-
]
147-
}
148-
149166
# -- Options for LaTeX output ---------------------------------------------
150167

151168
latex_elements = {
@@ -192,8 +209,8 @@
192209
# dir menu entry, description, category)
193210
texinfo_documents = [
194211
(master_doc, 'mathparse', 'mathparse Documentation',
195-
author, 'mathparse', 'One line description of project.',
196-
'Miscellaneous'),
212+
author, 'mathparse', project_description,
213+
'Development/Libraries/Python'),
197214
]
198215

199216

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Mathparse Documentation
1717
:maxdepth: 1
1818

1919
setup
20+
quickstart
2021
examples
2122
languages
2223
utils

0 commit comments

Comments
 (0)