Metadata-Version: 2.4
Name: rubberize
Version: 0.3.0
Summary: Turn Python calculations into well-formatted, math-rich documents.
Author-email: Chito Peralta <chitoangeloperalta@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Chito Peralta
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/chitoperalta/rubberize
Project-URL: Repository, https://github.com/chitoperalta/rubberize
Project-URL: Documentation, https://github.com/chitoperalta/rubberize/blob/main/docs/index.md
Keywords: latex,markdown,jupyter,notebook,math,engineering
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: IPython
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Education :: Computer Aided Instruction (CAI)
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown<4.0,>=3.7
Requires-Dist: titlecase<3.0.0,>=2.4.1
Provides-Extra: notebook
Requires-Dist: ipython<10.0.0,>=9.0.2; extra == "notebook"
Requires-Dist: playwright<2.0.0,>=1.51.0; extra == "notebook"
Requires-Dist: nbconvert<8.0.0,>=7.16.6; extra == "notebook"
Provides-Extra: dev
Requires-Dist: ipython<10.0.0,>=9.0.2; extra == "dev"
Requires-Dist: playwright<2.0.0,>=1.51.0; extra == "dev"
Requires-Dist: nbconvert<8.0.0,>=7.16.6; extra == "dev"
Requires-Dist: jupyterlab<5.0.0,>=4.3.6; extra == "dev"
Requires-Dist: pint<0.25.0,>=0.24.4; extra == "dev"
Requires-Dist: sympy<2.0.0,>=1.13.3; extra == "dev"
Requires-Dist: numpy<3.0.0,>=2.2.4; extra == "dev"
Dynamic: license-file

<picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/chitoperalta/rubberize/main/docs/assets/banner_dark.png">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/chitoperalta/rubberize/main/docs/assets/banner.png">
    <img alt="Rubberize Banner" title="Turn Python calculations into well-formatted, math-rich documents." src="https://raw.githubusercontent.com/chitoperalta/rubberize/main/docs/assets/banner.png">
</picture>

# Rubberize

Rubberize is a Python library designed to enhance the presentation of
calculations in Jupyter notebooks and Python scripts.

**In Jupyter Notebooks:** Rubberize transforms code cells containing calculations
into beautifully typeset mathematical expressions using LaTeX, making engineering
and scientific computations easier to read and review. Simply use the `%%tap`
magic command to render your code as math-rich output.

<picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/chitoperalta/rubberize/main/docs/assets/notebook_example_dark.png">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/chitoperalta/rubberize/main/docs/assets/notebook_example.png">
    <img alt="Screenshot of a Jupyter Notebook using Rubberize" src="https://raw.githubusercontent.com/chitoperalta/rubberize/main/docs/assets/notebook_example.png">
</picture>

**As an API:** Developers can use Rubberize's API to generate LaTeX representations
of Python code. These LaTeX outputs can then be integrated into custom typesetting
workflows, providing flexibility for professional-grade documents.

Rubberize bridges the gap between raw code and polished, math-rich documentation.

## Who is Rubberize For?

Rubberize is designed for:

- **Scientists and Engineers**: Simplify the presentation of complex calculations
in Jupyter notebooks by rendering them as clear, typeset math.
- **Educators and Students**: Create visually appealing and easy-to-understand
mathematical explanations directly from Python code.
- **Technical Writers**: Generate LaTeX representations of Python calculations for
seamless integration into professional-grade documents.
- **Developers**: Use Rubberize's API to build custom workflows for typesetting
and documentation.

If you work with Python code that involves mathematical computations and want to
bridge the gap between raw code and polished documentation, Rubberize is for you!

## Installation

Install Rubberize with `pip`:

```bash
pip install rubberize
```

Rubberize is primarily built for Jupyter. To enable notebook magics:

```bash
pip install rubberize[notebook]
# The headless chromium dependency of `playwright` also needs to be installed:
playwright install chromium
```

## Basic Usage

> [!WARNING]
> **Use of `eval()`**: This project uses Python's built-in `eval()` to evaluate some expressions. Since it executes code already present in the input source (e.g., a Jupyter cell or script), it poses no additional risk in such environments. However, be cautious when handling untrusted inputs outside controlled settings.

### In Jupyter Notebooks

Rubberize must be installed with `pip install rubberize[notebooks]`. Load the
extension after importing:

```python
import rubberize
%load_ext rubberize
```

Then, on the next code cell, use the `%%tap` magic command. Your code within the
cell will be rendered in math notation, along with substitutions, results, and
comments:

```python
%%tap
import math
a = 3
b = 4
c = math.sqrt(a**2 + b**2)
```
&emsp; $\displaystyle a = 3$

&emsp; $\displaystyle b = 4$
 
&emsp; $\displaystyle c = \sqrt{a^{2} + b^{2}} = \sqrt{3^{2} + 4^{2}} = 5.00$

There are a lot of customization options available, such as controlling the display
of substitutions and results, formatting the output, and integrating Rubberize with
other libraries such as [Pint](https://github.com/hgrecco/pint).

For more detailed examples and advanced usage, please refer to the
[Rubberize Documentation](https://github.com/chitoperalta/rubberize/blob/main/docs/index.md).

### As an API

You can use `latexer()` to generate LaTeX for your Python statements, and use the
output in your own typesetting code.

```python
import rubberize

source = """\
 import math
 a = 3
 b = 4
 c = math.sqrt(a**2 + b**2)
"""
namespace = {"a": 3, "b": 4, "c": 5.0}

stmts_latex = rubberize.latexer(source, namespace)
```

Please refer to the [API reference](https://github.com/chitoperalta/rubberize/blob/main/docs/api_reference.md) (TODO) section of the Rubberize
Documentation for more information.

## Why Those Names?

The name *Rubberize* is inspired by the process of tapping rubber trees for latex.
In the same way, this library **taps** into the **abstract syntax tree (AST)** of a
Python code to extract **LaTeX**. The `%%tap` magic command acts as the tap, drawing
out structured mathematical representations—just like latex flowing from a tree!

## Contributing

This is my first full project, and as a facade structural engineer by profession,
I’m still learning the ropes of software development. I would greatly appreciate
help from experienced developers in areas such as:

- Setting up a robust development environment
- Writing and organizing tests
- Improving and expanding the documentation

If you’re interested in contributing or mentoring, please feel free to contact me. I’m eager to learn and collaborate to make Rubberize even better!

Thank you for your support!

### Setting Up for Development

To set up Rubberize for development, install the development dependencies:

```bash
pip install rubberize[dev]
```

This will also install other libraries supported by Rubberize.

## License

[MIT License](LICENSE) © 2025 Chito Peralta

