ic-python-db 0.7.1__py3-none-any.whl

ic_python_db/system_time.py

@@ -0,0 +1,88 @@
+"""System time management for the database."""
+
+import time
+from datetime import datetime
+from typing import Optional
+
+
+class SystemTime:
+    """Manages system time for the database.
+
+    This class allows setting a fixed time for testing or synchronizing
+    time across different systems. If no time is set, it uses the real
+    system time.
+    """
+
+    _instance = None
+    _current_time_ms: Optional[int] = None
+
+    def __init__(self):
+        if SystemTime._instance is not None:
+            raise RuntimeError("Use SystemTime.get_instance() instead")
+        SystemTime._instance = self
+
+    @classmethod
+    def get_instance(cls) -> "SystemTime":
+        """Get the singleton instance."""
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    def get_time(self) -> int:
+        """Get the current time.
+
+        If a fixed time is set, returns the fixed time,
+        otherwise returns the real system time.
+
+        Returns:
+            int: Current time in milliseconds
+        """
+        if self._current_time_ms is not None:
+            return self._current_time_ms
+        return int(time.time() * 1000)  # Convert to milliseconds
+
+    def set_time(self, timestamp: int) -> None:
+        """Set a fixed time.
+
+        Args:
+            timestamp: Time in milliseconds since epoch
+        """
+        self._current_time_ms = timestamp
+
+    def clear_time(self) -> None:
+        """Clear the fixed time and revert to using real system time."""
+        self._current_time_ms = None
+
+    def advance_time(self, milliseconds: int) -> None:
+        """Advance the current time by the specified number of milliseconds.
+
+        If no fixed time is set, this will set the time to current time + milliseconds.
+
+        Args:
+            milliseconds: Number of milliseconds to advance
+        """
+        current = self.get_time()
+        print(
+            f"Advancing time by {milliseconds} ms (current: {current}) = {current + milliseconds}"
+        )
+        self.set_time(current + milliseconds)
+
+    @staticmethod
+    def format_timestamp(timestamp: int) -> str:
+        """Format a timestamp as a human-readable string.
+
+        Args:
+            timestamp: Time in milliseconds since epoch
+
+        Returns:
+            Formatted string like "2025-02-09 15:26:27.123"
+        """
+        if not timestamp:
+            return "None"
+        dt = datetime.fromtimestamp(timestamp / 1000).strftime("%Y-%m-%d %H:%M:%S.%f")[
+            :-3
+        ]
+        return f"{dt}"
+
+    def print(self) -> str:
+        return self.format_timestamp(self.get_time())

ic_python_db-0.7.1.dist-info/METADATA

@@ -0,0 +1,356 @@
+Metadata-Version: 2.4
+Name: ic_python_db
+Version: 0.7.1
+Summary: A lightweight key-value database written in Python, intended for use on the Internet Computer (IC)
+Home-page: https://github.com/smart-social-contracts/ic-python-db
+Author: Smart Social Contracts
+Author-email: Smart Social Contracts <contact@smartsocialcontracts.org>
+License: MIT License
+        
+        Copyright (c) 2025 Smart Social Contracts
+        
+        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/smart-social-contracts/ic-python-db
+Project-URL: Repository, https://github.com/smart-social-contracts/ic-python-db.git
+Project-URL: Issues, https://github.com/smart-social-contracts/ic-python-db/issues
+Keywords: database,key-value,entity,relationship,audit
+Classifier: Development Status :: 3 - Alpha
+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.10
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# IC Python DB
+
+A lightweight key-value database with entity relationships and audit logging capabilities, intended for small to medium-sized applications running on the Internet Computer. Forked from [kybra-simple-db](https://github.com/smart-social-contracts/kybra-simple-db).
+
+[![Test on IC](https://github.com/smart-social-contracts/ic-python-db/actions/workflows/test_ic.yml/badge.svg)](https://github.com/smart-social-contracts/ic-python-db/actions)
+[![Test](https://github.com/smart-social-contracts/ic-python-db/actions/workflows/test.yml/badge.svg)](https://github.com/smart-social-contracts/ic-python-db/actions)
+[![PyPI version](https://badge.fury.io/py/ic-python-db.svg)](https://badge.fury.io/py/ic-python-db)
+[![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3107/)
+[![License](https://img.shields.io/github/license/smart-social-contracts/ic-python-db.svg)](https://github.com/smart-social-contracts/ic-python-db/blob/main/LICENSE)
+
+## Features
+
+- **Persistent Storage**: Works with StableBTreeMap stable structure for persistent storage on your canister's stable memory so your data persists automatically across canister upgrades.
+- **Entity-Relational Database**: Create, read and write entities with OneToOne, OneToMany, ManyToOne, and ManyToMany relationships.
+- **Entity Hooks**: Intercept and control entity lifecycle events (create, modify, delete) with `on_event` hooks.
+- **Access Control**: Thread-safe context management for user identity tracking and ownership-based permissions.
+- **Namespaces**: Organize entities into namespaces to avoid type conflicts when you have multiple entities with the same class name.
+- **Audit Logging**: Track all changes to your data with created/updated timestamps and who created and updated each entity.
+
+
+## Installation
+
+```bash
+pip install ic-python-db
+```
+
+## Quick Start
+
+The database storage must be initialized before using IC Python DB. Here's an example of how to do it:
+
+```python
+from basilisk import StableBTreeMap
+from ic_python_db import Database
+
+# Initialize storage and database
+storage = StableBTreeMap[str, str](memory_id=1, max_key_size=100, max_value_size=1000)  # Use a unique memory ID for each storage instance
+Database.init(db_storage=storage)
+```
+
+Read [Basilisk's documentation](https://github.com/smart-social-contracts/basilisk) for more information regarding StableBTreeMap and memory IDs.
+
+Next, define your entities:
+
+```python
+from ic_python_db import (
+    Database, Entity, String, Integer,
+    OneToOne, OneToMany, ManyToOne, ManyToMany, TimestampedMixin
+)
+
+class Person(Entity, TimestampedMixin):
+    __alias__ = "name"  # Use `name` as the alias field for lookup
+    name = String(min_length=2, max_length=50)
+    age = Integer(min_value=0, max_value=120)
+    friends = ManyToMany("Person", "friends")
+    mother = ManyToOne("Person", "children")
+    children = OneToMany("Person", "mother")
+    spouse = OneToOne("Person", "spouse")
+```
+
+### Entity Lookup
+
+Entities can be retrieved using `Entity[key]` syntax with three different lookup modes:
+
+```python
+# Create an entity
+john = Person(name="John", age=30)
+
+# Lookup by ID
+Person[1]                  # Returns john (by _id)
+Person["1"]                # Also works with string ID
+
+# Lookup by alias (defined via __alias__)
+Person["John"]             # Tries ID first, then alias field "name"
+
+# Lookup by specific field (tuple syntax)
+Person["name", "John"]     # Lookup by field "name" only
+```
+
+| Syntax | Behavior |
+|--------|----------|
+| `Person[1]` | Lookup by `_id` |
+| `Person["John"]` | Try `_id` first, then `__alias__` field |
+| `Person["name", "John"]` | Lookup by specific field `name` only |
+
+Then use the defined entities to store objects:
+
+```python
+    # Create and save an object
+    john = Person(name="John", age=30)
+
+    # Update an object's property
+    john.age = 33  # Type checking and validation happens automatically
+
+    # use the `_id` property to load an entity with the [] operator
+    Person(name="Peter")
+    peter = Person["Peter"]
+
+    # Delete an object
+    peter.delete()
+
+    # Create relationships
+    alice = Person(name="Alice")
+    eva = Person(name="Eva")
+    john.mother = alice
+    assert john in alice.children
+    eva.friends = [alice]
+    assert alice in eva.friends
+    assert eva in alice.friends
+
+    print(alice.serialize())  # Prints the dictionary representation of an object
+    # Prints: {'timestamp_created': '2025-09-12 22:15:35.882', 'timestamp_updated': '2025-09-12 22:15:35.883', 'creator': 'system', 'updater': 'system', 'owner': 'system', '_type': 'Person', '_id': '3', 'name': 'Alice', 'age': None, 'children': '1', 'friends': '4'}
+
+    assert Person.count() == 3
+    assert Person.max_id() == 4
+    assert Person.instances() == [john, alice, eva]
+
+    # Cursor-based pagination
+    assert Person.load_some(0, 2) == [john, alice]
+    assert Person.load_some(2, 2) == [eva]
+
+    # Retrieve database contents in JSON format
+    print(Database.get_instance().dump_json(pretty=True))
+
+    # Audit log
+    audit_records = Database.get_instance().get_audit(id_from=0, id_to=5)
+    pprint(audit_records['0'])
+    ''' Prints:
+
+    ['save',
+    1744138342934,
+    'Person@1',
+    {'_id': '1',
+    '_type': 'Person',
+    'age': 30,
+    'creator': 'system',
+    'name': 'John',
+    'owner': 'system',
+    'timestamp_created': '2025-04-08 20:52:22.934',
+    'timestamp_updated': '2025-04-08 20:52:22.934',
+    'updater': 'system'}]
+
+    '''
+```
+
+For more usage examples, see the [tests](tests/src/tests).
+
+## Namespaces
+
+Organize entities with the `__namespace__` attribute to avoid type conflicts when you have the same class name in different modules:
+
+```python
+# In app/models.py
+class User(Entity):
+    __namespace__ = "app"
+    name = String()
+    role = String()
+```
+
+```python
+# In admin/models.py  
+class User(Entity):
+    __namespace__ = "admin"
+    name = String()
+    permissions = String()
+```
+
+```python
+from app.models import User as AppUser
+from admin.models import User as AdminUser
+
+app_user = AppUser(name="Alice", role="developer")      # Stored as "app::User"
+admin_user = AdminUser(name="Bob", permissions="all")     # Stored as "admin::User"
+
+# Each namespace has isolated ID sequences and storage
+assert app_user._id == "1"
+assert admin_user._id == "1"
+```
+
+## Entity Hooks
+
+Intercept and control entity changes with the `on_event` hook:
+
+```python
+from ic_python_db import Entity, String, ACTION_MODIFY
+
+class User(Entity):
+    name = String()
+    email = String()
+    
+    @staticmethod
+    def on_event(entity, field_name, old_value, new_value, action):
+        # Validate email format
+        if field_name == "email" and "@" not in new_value:
+            return False, None  # Reject invalid email
+        
+        # Auto-capitalize names
+        if field_name == "name":
+            return True, new_value.upper()
+        
+        return True, new_value
+
+user = User(name="alice", email="alice@example.com")
+assert user.name == "ALICE"  # Auto-capitalized
+```
+
+See [docs/HOOKS.md](docs/HOOKS.md) for more patterns.
+
+## Access Control
+
+Thread-safe user context management with `as_user()`:
+
+```python
+from ic_python_db import Database, Entity, String, ACTION_MODIFY, ACTION_DELETE
+from ic_python_db.mixins import TimestampedMixin
+from ic_python_db.context import get_caller_id
+
+class Document(Entity, TimestampedMixin):
+    title = String()
+    
+    @staticmethod
+    def on_event(entity, field_name, old_value, new_value, action):
+        caller = get_caller_id()
+        
+        # Only owner can modify or delete
+        if action in (ACTION_MODIFY, ACTION_DELETE):
+            if entity._owner != caller:
+                return False, None
+        
+        return True, new_value
+
+db = Database.get_instance()
+
+# Alice creates a document
+with db.as_user("alice"):
+    doc = Document(title="My Doc")  # Owner: alice
+
+# Bob cannot modify Alice's document
+with db.as_user("bob"):
+    doc.title = "Hacked"  # Raises ValueError
+```
+
+See [docs/ACCESS_CONTROL.md](docs/ACCESS_CONTROL.md) and [examples/simple_access_control.py](examples/simple_access_control.py).
+
+## Type Hints
+
+The library is fully typed (PEP 561 compliant). Type checkers and IDEs automatically infer property types:
+
+```python
+class User(Entity):
+    name = String()      # Inferred as str
+    age = Integer()      # Inferred as int
+    active = Boolean()   # Inferred as bool
+
+user = User(name="Alice", age=30, active=True)
+user.name   # IDE knows this is str
+user.age    # IDE knows this is int
+```
+
+For stricter typing, you can add explicit annotations:
+
+```python
+from typing import Optional
+
+class User(Entity):
+    name: str = String()
+    age: int = Integer()
+    profile: Optional["Profile"] = OneToOne("Profile", "user")
+```
+
+## API Reference
+
+- **Core**: `Database`, `Entity`
+- **Properties**: `String`, `Integer`, `Float`, `Boolean`
+- **Relationships**: `OneToOne`, `OneToMany`, `ManyToOne`, `ManyToMany`
+- **Mixins**: `TimestampedMixin` (timestamps and ownership tracking)
+- **Hooks**: `ACTION_CREATE`, `ACTION_MODIFY`, `ACTION_DELETE`
+- **Context**: `get_caller_id()`, `set_caller_id()`, `Database.as_user()`
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/smart-social-contracts/ic-python-db.git
+cd ic-python-db
+
+# Recommended setup
+pyenv install 3.10.7
+pyenv local 3.10.7
+python -m venv venv
+source venv/bin/activate
+
+# Install development dependencies
+pip install -r requirements-dev.txt
+
+# Running tests
+./run_linters.sh && (cd tests && ./run_test.sh && ./run_test_ic.sh)
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+[MIT](LICENSE).

ic_python_db-0.7.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+ic_python_db/__init__.py,sha256=7tiDQ0kSkzWyCnpk5zbBOIgJsrEkcsIhn30MD1yBoIw,814
+ic_python_db/_cdk.py,sha256=zTj8HzXUcPz8R73nh5bo6JMkCorp-KSW1hDutzi5LZs,387
+ic_python_db/constants.py,sha256=oLvKJev-65gXFd284DdYutWBX95sTF5Xkikc6IC4mhM,118
+ic_python_db/context.py,sha256=97F4_EAJm3adOnUfh0SaDisX3nc7F2vFIZwZUsUAy58,1080
+ic_python_db/db_engine.py,sha256=LOwFWvXw_BPMmJsRGe86GAKm1zzXP4gyG6U8toUGYEw,11624
+ic_python_db/entity.py,sha256=p31QTI2TyaxKpse06f-P6pAow30wEr_zt9uxXkfcvkE,35863
+ic_python_db/hooks.py,sha256=B1wV18dAMH-PootSripmMpG9Cr9M3W3lcNEF7QvPrL4,1620
+ic_python_db/mixins.py,sha256=qZmb3ssXYf2NSjHJtgmdsOlkIJdouDjPHdQ9tZmrZi8,1937
+ic_python_db/properties.py,sha256=NbDKKH7TBrV3lPP1zwdhMrWKVPDq2N3EViv1rL8gcjk,22433
+ic_python_db/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ic_python_db/storage.py,sha256=2F6m_01g2jwoF40s4BrdO2SffJNSO3gPf0QU3Co7T5Y,1873
+ic_python_db/system_time.py,sha256=xrx8NfjLXCGsac3hUpuvsNwCH91tQ9jfH4N-XFo8iJk,2614
+ic_python_db-0.7.1.dist-info/licenses/LICENSE,sha256=6q6XYNOGnJcVSus2bAezFn7bU_2Y5T6W4aGQHBb8X-c,1079
+ic_python_db-0.7.1.dist-info/METADATA,sha256=pXPo2r6dtGWMru3EY5cBj6724SEan83xLtXcY97eHwA,12188
+ic_python_db-0.7.1.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+ic_python_db-0.7.1.dist-info/top_level.txt,sha256=ZaOTqhWKtJQEuXmqR920AqbDBAqv1mvsKj3TClWimDk,13
+ic_python_db-0.7.1.dist-info/RECORD,,

ic_python_db-0.7.1.dist-info/WHEEL

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

ic_python_db-0.7.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Smart Social Contracts
+
+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.

ic_python_db-0.7.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+ic_python_db