pymastring

pymastring is a utility package that globally overrides the runtime behavior of Python's built-in primitive str class via deep C-level monkey-patching. It breaks standard type limitations to allow direct mathematical calculations, matrix equations, bitwise interactions, universal cross-type comparisons, and custom serialization paradigms natively on raw string literals.

Technical Concept

Python's built-in str instances are hardcoded at the C-API level to prevent arbitrary mutation. pymastring bypasses this defense mechanism by temporarily modifying PyTypeObject.tp_flags and overwriting underlying C-slots (tp_as_number, tp_as_sequence, tp_as_mapping, tp_richcompare, tp_iter) via ctypes and garbage collector referent dictionaries.

Every mathematical operation maps the characters of the string to their respective Unicode Code Points (via ord()), runs numerical adjustments, applies an auto-overflow modulo bounds-check (% 1114112), and returns the resulting value shifted back into strings (via chr()).

pymastring features a recursive weight engine (_get_weight) and metaclass-enabled numeric casting (_PatchedInt, _PatchedFloat) ensuring total, crash-free interoperability across all native Python types: numbers (int, float, bool), collections (list, tuple, set, dict, bytes), and custom third-party objects.

Installation

Install pymastring directly from PyPI:

pip install pymastring

Or install the package locally from source in editable development mode:

pip install .

Core Features & Extended API Specification

1. Universal Arithmetic Engine (+, -, *, /, //, %, **)

Standard string literals can be manipulated mathematically with numbers, strings, booleans, collections, and sequences across left-hand and right-hand operations.

• Addition (+ / radd): Integer/float/bool addition shifts character unicode codes forward ("abc" + 1 -> "bcd"). Standard string concatenation ("a" + "b") is retained.
• Subtraction (- / rsub): Subtraction by a number reduces unicode codes ("python" - 5). Subtraction by another string removes target substring bytes ("abcdef" - "bd" -> "acef"). Subtraction from numbers (1000 - "a") computes reverse shifts.
• Multiplication (* / rmul): String-by-integer multiplication performs classic repetition ("a" * 3). String-by-float scales codes. String-by-string evaluates element-wise Hadamard multiplication.
• Division (/, //, %, divmod): Performs exact truediv, floordiv, and modulo on character weights. Supports right-hand division (200 / "a", 200 // "a") and native divmod("abc", 2).
• Exponentiation (** / rpow): Exponentiates internal character weights ("abc" ** 2 or 2 ** "a").

import pymastring

print("abc" + 1)            # Outputs: "bcd"
print(1 + "abc")            # Right-hand addition -> Outputs: "bcd"
print("abc" + True)         # Bool scalar shift -> Outputs: "bcd"
print("python" - 5)         # Left-shifts unicode positions
print("abcdef" - "bd")      # Drops target slices -> Outputs: "acef"
print("abc" ** 2)           # Exponentiates character codes
print(2 ** "a")             # Right-hand exponentiation
print("xyz" / 2)            # Uniform code points scaling
print(200 / "a")            # Right-hand division
print(divmod("a", 10))      # Returns tuple of (floordiv, modulo)

2. Matrix Cross-Multiplication Vector Behavior (@)

Using the @ operator evaluates the structural linear algebra dot product between two string arrays or between strings and numeric vectors (list, tuple).

import pymastring

# String-by-string dot product: (ord('a') * ord('b')) -> 97 * 98
print("a" @ "b")            # Outputs integer: 9506

# String-by-vector dot product: (97*1 + 98*2 + 99*3)
print("abc" @ [1, 2, 3])    # Outputs integer: 590

3. Cross-Type Rich Comparisons (>, <, >=, <=, ==, !=)

Rich comparison algorithms evaluate recursive integrated inner array vector weight sums (_get_weight), allowing seamless comparisons between strings, numbers, nested lists, dicts, and custom objects.

import pymastring

print("aaa" > 1)            # Compares 291 > 1 -> Outputs: True
print(100 < "aaa")          # Compares 100 < 291 -> Outputs: True
print("aaa" == 291)         # Weight equality -> Outputs: True
print("abc" > [1, 2, 3])    # Compares string weight vs list weight -> Outputs: True
print("abc" > None)         # Compares string weight vs object weight -> Outputs: True

4. Dynamic Structural Weight Evaluation & Element Extraction (len(), str[i])

The global len() invocation evaluates context dynamically. Standard raw string literals retain traditional element counts. However, iterated elements, indexed characters (pymastring.MathChar("a")), or MathChar objects compute and report the integrated unicode code point weight (ord()).

import pymastring

# A primitive baseline string keeps its classic character length
print(len("abc"))           # Outputs integer: 3

# MathChar objects report true inner weight sum
char = pymastring.MathChar("a")
print(len(char))            # Outputs Unicode weight: 97

# Intercept loops pull typified MathChar wrappers
for char in "a":
    print(len(char))        # Outputs Unicode weight: 97

5. Unary Operators & Transparent Casting (-str, ~str, abs(), int(), float(), round())

• Unary Negation (-): Reverses the string (-"abc" -> "cba").
• Bitwise NOT (~): Inverts character bit positions (~"abc").
• Vector Norm (abs()): Calculates Euclidean vector magnitude ($\sqrt{\sum \text{ord}(c)^2}$).
• Transparent Casting (int(), float(), round()): Safely parses valid numeric text or falls back to total character weight sums for non-numeric strings via metaclass-enabled numeric types.

import pymastring

print(-"abc")               # Reverses string -> Outputs: "cba"
print(abs("abc"))           # Calculates Euclidean vector length -> ~169.75
print(int("123"))           # Parses valid integer -> 123
print(int("abc"))           # Fallback sum of weights -> 97 + 98 + 99 = 294
print(float("123.45"))      # Parses float -> 123.45
print(float("abc"))         # Fallback sum of weights -> 294.0

6. Bitwise Vector Conversions (<<, >>, &, |, ^)

Direct byte-level array transformations across registers supporting left-hand and right-hand operations.

import pymastring

print("abc" << 2)           # Left shift bit positions
print("secret" ^ 42)        # XOR encryption mask mapping
print("hello" & "world")     # Matrix intersection overlay
print(15 & "a")             # Right-hand bitwise AND

7. Typified Generator Array Extraction & Reversal

Loops and reversed iterators parsing raw string sequences yield operational wrappers (MathChar) inheriting full mathematical capabilities.

import pymastring

for char in reversed("xyz"):
    print(char ** 1.5)

8. Custom JSON Serialization Engine (MathJSONEncoder)

To prevent internal character objects from breaking standard data transfers, use our targeted serialization mapping profile.

import json
import pymastring

data = {"payload": "abc" ** 2}
json_string = json.dumps(data, cls=pymastring.MathJSONEncoder)

License

MIT License - Copyright (c) 2026 ProgVM