omarlib 1.0.0__tar.gz

omarlib-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OmarYauh
+
+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.

omarlib-1.0.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.2
+Name: omarlib
+Version: 1.0.0
+Summary: Extended Python features: xor, pointers, references, nameof, private methods, and function overloading
+Author-email: OmarYauh <omaryauh@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/SlackPen/omarlib
+Project-URL: Documentation, https://github.com/SlackPen/omarlib#readme
+Project-URL: Repository, https://github.com/SlackPen/omarlib
+Project-URL: Issues, https://github.com/SlackPen/omarlib/issues
+Keywords: xor,pointer,reference,nameof,private,overload,utilities,extensions,metaprogramming
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+
+# omarlib
+
+Extended Python features inspired by other programming languages.
+
+## Installation
+
+```bash
+pip install omarlib
+```
+
+## Features
+
+### 1. `xor(a, b)` - Logical XOR
+
+```python
+from omarlib import xor
+
+xor(True, False)   # True
+xor(True, True)    # False
+xor(False, False)  # False
+xor(1, 0)          # True (truthy/falsy)
+```
+
+### 2. `ptr(obj)` - Pointers
+
+C-style pointers for Python objects.
+
+```python
+from omarlib import ptr
+
+x = [1, 2, 3]
+p = ptr(x)
+
+print(p.value)     # [1, 2, 3] - dereference
+print(p.addr)      # memory address (id)
+print(~p)          # [1, 2, 3] - dereference with ~
+
+# Pointer arithmetic with sequences
+arr = [10, 20, 30, 40, 50]
+p = ptr(arr)
+print((p + 2).value)  # 30
+
+# Null pointer
+p.set_null()
+print(p.is_null())    # True
+print(bool(p))        # False
+```
+
+### 3. `ref(name)` - Real References
+
+Create references that can modify the original variable.
+
+```python
+from omarlib import ref
+
+x = 42
+r = ref('x')
+print(r.value)    # 42
+
+r.value = 100
+print(x)          # 100 - x was modified!
+
+# Swap example
+a, b = 1, 2
+ref('a').value, ref('b').value = ref('b').value, ref('a').value
+print(a, b)       # 2, 1
+```
+
+### 4. `nameof(var)` - Get Variable Name
+
+```python
+from omarlib import nameof
+
+my_variable = 42
+print(nameof(my_variable))  # 'my_variable'
+
+user_name = "Omar"
+print(nameof(user_name))    # 'user_name'
+```
+
+### 5. `nameof_all(*vars)` - Get Multiple Variable Names
+
+```python
+from omarlib import nameof_all
+
+a = 1
+b = 2
+c = 3
+
+names = nameof_all(a, b, c)
+print(names)  # ['a', 'b', 'c']
+
+# Useful for iteration
+for name, value in zip(nameof_all(a, b, c), [a, b, c]):
+    print(f"{name} = {value}")
+```
+
+### 6. `@private` - Real Private Methods
+
+```python
+from omarlib import private
+
+class BankAccount:
+    def __init__(self, balance):
+        self._balance = balance
+
+    @private
+    def _calculate_interest(self):
+        return self._balance * 0.05
+
+    def apply_interest(self):
+        # OK - called from inside the class
+        interest = self._calculate_interest()
+        self._balance += interest
+        return interest
+
+account = BankAccount(1000)
+account.apply_interest()      # OK
+account._calculate_interest() # PermissionError!
+```
+
+### 7. `@overload` - Function Overloading
+
+```python
+from omarlib import overload
+
+@overload
+def process(x: int):
+    return x * 2
+
+@process.register
+def process(x: str):
+    return x.upper()
+
+@process.register
+def process(x: int, y: int):
+    return x + y
+
+print(process(5))        # 10
+print(process("hello"))  # HELLO
+print(process(3, 4))     # 7
+```
+
+## Import Everything
+
+```python
+from omarlib import *
+
+# Now you have: xor, ptr, ref, nameof, nameof_all, private, overload
+```
+
+## Requirements
+
+- Python 3.8+
+- No external dependencies
+
+## License
+
+MIT License - see LICENSE file.
+
+## Author
+
+OmarYauh
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.

omarlib-1.0.0/README.md

@@ -0,0 +1,167 @@
+# omarlib
+
+Extended Python features inspired by other programming languages.
+
+## Installation
+
+```bash
+pip install omarlib
+```
+
+## Features
+
+### 1. `xor(a, b)` - Logical XOR
+
+```python
+from omarlib import xor
+
+xor(True, False)   # True
+xor(True, True)    # False
+xor(False, False)  # False
+xor(1, 0)          # True (truthy/falsy)
+```
+
+### 2. `ptr(obj)` - Pointers
+
+C-style pointers for Python objects.
+
+```python
+from omarlib import ptr
+
+x = [1, 2, 3]
+p = ptr(x)
+
+print(p.value)     # [1, 2, 3] - dereference
+print(p.addr)      # memory address (id)
+print(~p)          # [1, 2, 3] - dereference with ~
+
+# Pointer arithmetic with sequences
+arr = [10, 20, 30, 40, 50]
+p = ptr(arr)
+print((p + 2).value)  # 30
+
+# Null pointer
+p.set_null()
+print(p.is_null())    # True
+print(bool(p))        # False
+```
+
+### 3. `ref(name)` - Real References
+
+Create references that can modify the original variable.
+
+```python
+from omarlib import ref
+
+x = 42
+r = ref('x')
+print(r.value)    # 42
+
+r.value = 100
+print(x)          # 100 - x was modified!
+
+# Swap example
+a, b = 1, 2
+ref('a').value, ref('b').value = ref('b').value, ref('a').value
+print(a, b)       # 2, 1
+```
+
+### 4. `nameof(var)` - Get Variable Name
+
+```python
+from omarlib import nameof
+
+my_variable = 42
+print(nameof(my_variable))  # 'my_variable'
+
+user_name = "Omar"
+print(nameof(user_name))    # 'user_name'
+```
+
+### 5. `nameof_all(*vars)` - Get Multiple Variable Names
+
+```python
+from omarlib import nameof_all
+
+a = 1
+b = 2
+c = 3
+
+names = nameof_all(a, b, c)
+print(names)  # ['a', 'b', 'c']
+
+# Useful for iteration
+for name, value in zip(nameof_all(a, b, c), [a, b, c]):
+    print(f"{name} = {value}")
+```
+
+### 6. `@private` - Real Private Methods
+
+```python
+from omarlib import private
+
+class BankAccount:
+    def __init__(self, balance):
+        self._balance = balance
+
+    @private
+    def _calculate_interest(self):
+        return self._balance * 0.05
+
+    def apply_interest(self):
+        # OK - called from inside the class
+        interest = self._calculate_interest()
+        self._balance += interest
+        return interest
+
+account = BankAccount(1000)
+account.apply_interest()      # OK
+account._calculate_interest() # PermissionError!
+```
+
+### 7. `@overload` - Function Overloading
+
+```python
+from omarlib import overload
+
+@overload
+def process(x: int):
+    return x * 2
+
+@process.register
+def process(x: str):
+    return x.upper()
+
+@process.register
+def process(x: int, y: int):
+    return x + y
+
+print(process(5))        # 10
+print(process("hello"))  # HELLO
+print(process(3, 4))     # 7
+```
+
+## Import Everything
+
+```python
+from omarlib import *
+
+# Now you have: xor, ptr, ref, nameof, nameof_all, private, overload
+```
+
+## Requirements
+
+- Python 3.8+
+- No external dependencies
+
+## License
+
+MIT License - see LICENSE file.
+
+## Author
+
+OmarYauh
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.

omarlib-1.0.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "omarlib"
+version = "1.0.0"
+description = "Extended Python features: xor, pointers, references, nameof, private methods, and function overloading"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [
+    {name = "OmarYauh", email = "omaryauh@gmail.com"}
+]
+keywords = [
+    "xor", "pointer", "reference", "nameof", "private", "overload",
+    "utilities", "extensions", "metaprogramming"
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/SlackPen/omarlib"
+Documentation = "https://github.com/SlackPen/omarlib#readme"
+Repository = "https://github.com/SlackPen/omarlib"
+Issues = "https://github.com/SlackPen/omarlib/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "black>=23.0",
+    "mypy>=1.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+omarlib = ["py.typed"]
+
+[tool.black]
+line-length = 100
+target-version = ["py38", "py39", "py310", "py311", "py312"]
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

omarlib-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

omarlib-1.0.0/src/omarlib/__init__.py

@@ -0,0 +1,46 @@
+"""
+omarlib - Extended Python features.
+
+A library providing additional language features inspired by other
+programming languages:
+
+- xor(a, b): Logical XOR operation
+- ptr(obj): C-style pointers
+- ref(name): Real references that modify original variables
+- nameof(var): Get variable name as string
+- nameof_all(*vars): Get multiple variable names
+- @private: Make methods truly private
+- @overload: Function overloading
+
+Basic usage:
+    from omarlib import xor, ptr, ref, nameof, nameof_all, private, overload
+
+Import everything:
+    from omarlib import *
+"""
+
+__version__ = "1.0.0"
+__author__ = "OmarYauh"
+
+# Import all features
+from omarlib.xor import xor
+from omarlib.ptr import ptr
+from omarlib.ref import ref
+from omarlib.nameof import nameof, nameof_all
+from omarlib.private import private
+from omarlib.overload import overload
+
+# Define what gets exported with "from omarlib import *"
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__",
+    # Features
+    "xor",
+    "ptr",
+    "ref",
+    "nameof",
+    "nameof_all",
+    "private",
+    "overload",
+]

omarlib-1.0.0/src/omarlib/nameof.py

@@ -0,0 +1,164 @@
+"""
+nameof - Get variable names as strings.
+
+Provides functions to retrieve the name of a variable as a string,
+useful for debugging, logging, and metaprogramming.
+"""
+
+import inspect
+from typing import Any, List, Set
+
+__all__ = ["nameof", "nameof_all"]
+
+
+def nameof(var: Any) -> str:
+    """
+    Return the name of a variable as a string.
+
+    This function inspects the caller's namespace to find the name
+    of the variable that was passed as an argument.
+
+    Args:
+        var: The variable whose name you want to get
+
+    Returns:
+        str: The name of the variable
+
+    Raises:
+        ValueError: If the variable name cannot be determined
+
+    Examples:
+        >>> my_variable = 42
+        >>> nameof(my_variable)
+        'my_variable'
+
+        >>> user_name = "Omar"
+        >>> nameof(user_name)
+        'user_name'
+
+        >>> # Useful for debugging
+        >>> x = [1, 2, 3]
+        >>> print(f"{nameof(x)} = {x}")
+        'x = [1, 2, 3]'
+
+    Note:
+        This function works by comparing object identity (using `is`).
+        In loops like `for i in x: nameof(i)`, it will return 'i',
+        not the original variable name. Use nameof_all() before the loop
+        to capture original names.
+    """
+    frame = inspect.currentframe()
+    if frame is None:
+        raise RuntimeError("nameof() cannot determine caller frame")
+
+    try:
+        caller_frame = frame.f_back
+        if caller_frame is None:
+            raise RuntimeError("nameof() cannot determine caller frame")
+
+        # Search in locals first
+        for name, value in caller_frame.f_locals.items():
+            if value is var and name not in ("nameof", "nameof_all"):
+                return name
+
+        # Search in globals
+        for name, value in caller_frame.f_globals.items():
+            if value is var and name not in ("nameof", "nameof_all"):
+                return name
+
+        raise ValueError(
+            "nameof() could not determine variable name. "
+            "Only simple variable names are supported, not expressions."
+        )
+    finally:
+        del frame
+
+
+def nameof_all(*args: Any) -> List[str]:
+    """
+    Return a list with the names of all variables passed as arguments.
+
+    This function inspects the caller's namespace to find the names
+    of all variables passed as arguments.
+
+    Args:
+        *args: The variables whose names you want to get
+
+    Returns:
+        List[str]: A list of variable names in the order they were passed
+
+    Raises:
+        TypeError: If no arguments are provided
+
+    Examples:
+        >>> a = 1
+        >>> b = 2
+        >>> c = 3
+        >>> nameof_all(a, b, c)
+        ['a', 'b', 'c']
+
+        >>> # Useful for iteration - capture names BEFORE the loop
+        >>> x = 10
+        >>> y = 20
+        >>> z = 30
+        >>> names = nameof_all(x, y, z)
+        >>> values = [x, y, z]
+        >>> for name, value in zip(names, values):
+        ...     print(f"{name} = {value}")
+        x = 10
+        y = 20
+        z = 30
+
+    Note:
+        Each variable's name is found by comparing object identity.
+        Variables with the same value will return the first matching name found
+        that hasn't been used yet in the result list.
+    """
+    if not args:
+        raise TypeError("nameof_all() requires at least 1 argument")
+
+    frame = inspect.currentframe()
+    if frame is None:
+        raise RuntimeError("nameof_all() cannot determine caller frame")
+
+    try:
+        caller_frame = frame.f_back
+        if caller_frame is None:
+            raise RuntimeError("nameof_all() cannot determine caller frame")
+
+        result: List[str] = []
+        used_names: Set[str] = set()
+
+        locals_dict = caller_frame.f_locals
+        globals_dict = caller_frame.f_globals
+
+        for var in args:
+            found_name = None
+
+            # Search in locals first
+            for name, value in locals_dict.items():
+                if (value is var and
+                    name not in ("nameof", "nameof_all") and
+                    name not in used_names):
+                    found_name = name
+                    used_names.add(name)
+                    break
+
+            # Search in globals if not found in locals
+            if found_name is None:
+                for name, value in globals_dict.items():
+                    if (value is var and
+                        name not in ("nameof", "nameof_all") and
+                        name not in used_names):
+                        found_name = name
+                        used_names.add(name)
+                        break
+
+            if found_name is None:
+                found_name = "<unknown>"
+
+            result.append(found_name)
+
+        return result
+    finally:
+        del frame