cobra-oop 0.1.0__py3-none-any.whl

cobra/__init__.py

@@ -0,0 +1,58 @@
+"""
+COBRA
+=====
+
+Comprehensive Object-Based Runtime Architecture
+
+Optional runtime-enforced OOP features for Python.
+
+Author: Vishnu Swaroop
+Version: 0.1.0
+"""
+
+from .base import CobraObject
+from .decorators import (
+    private,
+    protected,
+    public,
+    final,
+    override,
+)
+from .exceptions import (
+    CobraError,
+    PrivateAccessError,
+    ProtectedAccessError,
+    FinalMethodError,
+    OverrideError,
+    CobraConfigurationError,
+)
+from .fields import (
+    PrivateField,
+    ProtectedField,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Base
+    "CobraObject",
+
+    # Decorators
+    "private",
+    "protected",
+    "public",
+    "final",
+    "override",
+
+    # Fields
+    "PrivateField",
+    "ProtectedField",
+
+    # Exceptions
+    "CobraError",
+    "PrivateAccessError",
+    "ProtectedAccessError",
+    "FinalMethodError",
+    "OverrideError",
+    "CobraConfigurationError",
+]

cobra/base.py

@@ -0,0 +1,52 @@
+"""
+cobra.object
+
+Base object for all COBRA-enabled classes.
+
+Version: 0.1.0
+"""
+
+
+class CobraObject:
+    """
+    Base class for all COBRA objects.
+
+    Future versions will provide:
+
+    - Runtime access control
+    - Field interception
+    - Contract validation
+    - Reflection utilities
+    - Metadata support
+    """
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} at {hex(id(self))}>"
+
+    def __str__(self):
+        return self.__repr__()
+
+    # ------------------------------------------------------------------
+    # Reserved for COBRA v0.2+
+    # ------------------------------------------------------------------
+
+    def __getattribute__(self, name):
+        """
+        Reserved for future runtime access interception.
+
+        In v0.2 this will become the central point for
+        field-level encapsulation.
+        """
+        return super().__getattribute__(name)
+
+    def __setattr__(self, name, value):
+        """
+        Reserved for future runtime write interception.
+        """
+        super().__setattr__(name, value)
+
+    def __delattr__(self, name):
+        """
+        Reserved for future runtime delete interception.
+        """
+        super().__delattr__(name)

cobra/decorators.py

@@ -0,0 +1,61 @@
+"""
+cobra.decorators
+
+Decorators for enforcing optional OOP access modifiers.
+
+Version: 0.1.0
+"""
+
+from functools import wraps
+
+from .exceptions import PrivateAccessError
+from .utils import is_private_access_allowed
+
+
+def private(func):
+    """
+    Marks a method as private.
+
+    A private method may only be called from within
+    the declaring class.
+
+    Example:
+        class Person:
+
+            @private
+            def secret(self):
+                ...
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        if not is_private_access_allowed(func, args):
+            raise PrivateAccessError(
+                f"Private method '{func.__qualname__}' cannot be accessed from outside its class."
+            )
+
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def protected(func):
+    raise NotImplementedError(
+        "@protected will be implemented in COBRA v0.2"
+    )
+
+
+def public(func):
+    return func
+
+
+def final(func):
+    raise NotImplementedError(
+        "@final will be implemented in COBRA v0.2"
+    )
+
+
+def override(func):
+    raise NotImplementedError(
+        "@override will be implemented in COBRA v0.2"
+    )

cobra/exceptions.py

@@ -0,0 +1,65 @@
+"""
+cobra.exceptions
+
+Custom exceptions used throughout the COBRA framework.
+"""
+
+
+class CobraError(Exception):
+    """
+    Base exception for all COBRA-related errors.
+    """
+
+    pass
+
+
+class PrivateAccessError(CobraError):
+    """
+    Raised when a private method is accessed
+    from outside its declaring class.
+    """
+
+    pass
+
+
+class ProtectedAccessError(CobraError):
+    """
+    Raised when a protected member is accessed
+    from an unauthorized context.
+
+    (Reserved for COBRA v0.2)
+    """
+
+    pass
+
+
+class FinalMethodError(CobraError):
+    """
+    Raised when attempting to override
+    a final method.
+
+    (Reserved for COBRA v0.2)
+    """
+
+    pass
+
+
+class OverrideError(CobraError):
+    """
+    Raised when an @override method does not
+    override any method in the parent class.
+
+    (Reserved for COBRA v0.2)
+    """
+
+    pass
+
+
+class CobraConfigurationError(CobraError):
+    """
+    Raised when COBRA is used incorrectly,
+    such as applying decorators to unsupported
+    objects.
+    """
+
+    pass

cobra/fields.py

@@ -0,0 +1,69 @@
+"""
+cobra.fields
+
+Descriptor implementations for COBRA.
+
+Version: 0.1.0
+
+NOTE:
+Field-level encapsulation is planned for COBRA v0.2.
+This file provides the initial structure only.
+"""
+
+from .exceptions import PrivateAccessError, ProtectedAccessError
+
+
+class PrivateField:
+    """
+    Descriptor representing a private field.
+
+    Access control will be enforced in COBRA v0.2.
+    """
+
+    def __init__(self, default=None):
+        self.default = default
+        self.storage_name = None
+
+    def __set_name__(self, owner, name):
+        self.storage_name = f"__cobra_private_{name}"
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+
+        # TODO:
+        # Enforce private access using caller inspection.
+        return getattr(instance, self.storage_name, self.default)
+
+    def __set__(self, instance, value):
+        # TODO:
+        # Enforce private write access.
+        setattr(instance, self.storage_name, value)
+
+
+class ProtectedField:
+    """
+    Descriptor representing a protected field.
+
+    Access control will be enforced in COBRA v0.2.
+    """
+
+    def __init__(self, default=None):
+        self.default = default
+        self.storage_name = None
+
+    def __set_name__(self, owner, name):
+        self.storage_name = f"__cobra_protected_{name}"
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+
+        # TODO:
+        # Enforce protected access.
+        return getattr(instance, self.storage_name, self.default)
+
+    def __set__(self, instance, value):
+        # TODO:
+        # Enforce protected write access.
+        setattr(instance, self.storage_name, value)

cobra/utils.py

@@ -0,0 +1,53 @@
+"""
+cobra.utils
+
+Utility functions used by COBRA decorators.
+"""
+
+import inspect
+
+
+def is_private_access_allowed(func, args):
+    """
+    Returns True if a private method is being called
+    from within its declaring class.
+
+    NOTE:
+    This is a Proof-of-Concept implementation for COBRA v0.1.
+    It is not intended to be security hardened.
+    """
+
+    # Private methods should always be instance methods.
+    if not args:
+        return False
+
+    instance = args[0]
+    owner_class = instance.__class__
+
+    # The caller is two frames above:
+    #
+    # user_code()
+    #   -> wrapper()
+    #       -> is_private_access_allowed()
+    #
+    frame = inspect.currentframe()
+
+    try:
+        wrapper_frame = frame.f_back
+        caller_frame = wrapper_frame.f_back
+
+        if caller_frame is None:
+            return False
+
+        caller_self = caller_frame.f_locals.get("self")
+
+        # No 'self' means the caller is outside any instance method.
+        if caller_self is None:
+            return False
+
+        # Allow calls only from the same instance type.
+        return isinstance(caller_self, owner_class)
+
+    finally:
+        # Prevent reference cycles.
+        del frame

cobra_oop-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: cobra-oop
+Version: 0.1.0
+Summary: Comprehensive Object-Based Runtime Architecture
+Author: Vishnu Swaroop
+License-Expression: MIT
+Keywords: python,oop,decorators,encapsulation,runtime
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# COBRA 🐍
+
+> **Comprehensive Object-Based Runtime Architecture**
+
+**COBRA** is an experimental Python library that introduces **optional runtime-enforced object-oriented programming concepts** while remaining fully compatible with standard Python.
+
+Python follows the philosophy of *"We're all consenting adults here."* COBRA embraces that philosophy while providing developers with the option to enforce stronger object-oriented constraints when building large or enterprise-grade applications.
+
+---
+
+## Why COBRA?
+
+Python intentionally relies on conventions instead of strict access modifiers.
+
+For example:
+
+```python
+class BankAccount:
+    def __reset_pin(self):
+        ...
+```
+
+Although name mangling discourages accidental access, private members are still accessible when explicitly referenced.
+
+COBRA explores an alternative approach by introducing optional runtime validation for concepts such as:
+
+* Private methods
+* Protected methods
+* Private fields
+* Final methods
+* Runtime contracts
+* Interface validation
+
+The goal is **not to replace Python**, but to provide an optional layer of additional runtime guarantees.
+
+---
+
+## Features
+
+### Current (v0.1)
+
+* ✅ `@private`
+* ✅ Runtime access validation
+* ✅ Custom exception hierarchy
+* ✅ Unit tests
+* ✅ Extensible architecture
+
+### Planned
+
+* `@protected`
+* `PrivateField`
+* `ProtectedField`
+* `@final`
+* `@override`
+* Runtime contracts
+* Interface support
+* Performance optimisations
+
+---
+
+## Installation
+
+```bash
+pip install cobra-oop
+```
+
+For development:
+
+```bash
+pip install -e .
+```
+
+---
+
+## Quick Example
+
+```python
+from cobra import CobraObject, private
+
+
+class BankAccount(CobraObject):
+
+    @private
+    def reset_pin(self):
+        print("PIN reset")
+
+    def change_pin(self):
+        self.reset_pin()
+
+
+account = BankAccount()
+
+account.change_pin()      # ✅ Allowed
+account.reset_pin()       # ❌ Raises PrivateAccessError
+```
+
+---
+
+## Project Structure
+
+```text
+cobra/
+├── decorators.py
+├── fields.py
+├── base.py
+├── exceptions.py
+├── utils.py
+└── __init__.py
+```
+
+---
+
+## Roadmap
+
+The development roadmap can be found in:
+
+```
+docs/roadmap.md
+```
+
+Architecture decisions are documented under:
+
+```
+docs/adr/
+```
+
+---
+
+## Philosophy
+
+COBRA is designed around a few simple principles:
+
+* Keep Pythonic syntax.
+* Make strictness optional.
+* Prefer explicit behaviour over hidden magic.
+* Build small, testable components.
+* Learn by exploring Python internals.
+
+---
+
+## Contributing
+
+Contributions, suggestions, and discussions are always welcome.
+
+If you discover an issue or have an idea for improving COBRA, feel free to open an issue or submit a pull request.
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+---
+
+> *"Python trusts developers. COBRA helps developers trust each other."* 🐍

cobra_oop-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+cobra/__init__.py,sha256=rM21gZXUBtIg6lFoNzAsCDmBQwOSN13TK5uRJMGE5W0,892
+cobra/base.py,sha256=-zGZxktvwOtOS6p5Jt74BImFCDKXgTrTJzXF0z-nACI,1212
+cobra/decorators.py,sha256=vkQgXPjwx4o2GEkFPGaFUnHipYVoA5i3-9BafpTKL_g,1155
+cobra/exceptions.py,sha256=ntgxcsOwDgXJ5CBX3GsUj_dJt0z1yl9ajSp0Wp0Tb74,1025
+cobra/fields.py,sha256=nmOLNSczfal3TLbA-VU1LDaDnM1czuaDcOKMIRyUJgQ,1670
+cobra/utils.py,sha256=ExAat3dPXLozEj6z82TUQLXoBj0OD7yP31kCTFmj4po,1188
+cobra_oop-0.1.0.dist-info/licenses/LICENSE,sha256=VTR0d33ThYBTk2TpAuM7koboaTaHt0wu7aGMLOOUe5w,1070
+cobra_oop-0.1.0.dist-info/METADATA,sha256=4CrPC2KcnYJd0aBznAJNKGeuDRSIpGEwOHiXbjk52ic,3255
+cobra_oop-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cobra_oop-0.1.0.dist-info/top_level.txt,sha256=LeT4BKKqEqFNqc-EGNWRSpdtIvqG4eLt-Qn3Rf1EmG8,6
+cobra_oop-0.1.0.dist-info/RECORD,,

cobra_oop-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cobra_oop-0.1.0.dist-info/licenses/LICENSE

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

cobra_oop-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cobra