Merge pull request #2 from immmdreza/master-entity

Master entity

Author: immmdreza

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = json-entity
-version = 0.1.1.5
+version = 0.1.2.5
 author = immmdreza
 author_email = ir310022@gmail.com
 description = A simple and async json database.

src/examples/general_1.py

@@ -0,0 +1,76 @@
+# pylint: skip-file
+
+import asyncio
+from datetime import datetime
+
+from sjd import TEntity, Engine, properties as props, make_property, PropertyOptions
+
+
+@props.auto_collect()
+class Order(TEntity):
+
+    # A reference to order's owner ( a Customer instance )
+    customer_id = props.reference()
+
+    # Description will be automatically collected from __init__ parameters.
+    def __init__(self, description: str) -> None:
+        self.description = description
+        self._created_at_iso_fmt = datetime.now().isoformat()  # private field
+
+    # Here our private property _created_at_iso_fmt will be covered by created_at
+    # property, which is a python property as well as sjd property
+    @make_property(
+        str,
+        options=PropertyOptions(init=False, required=True),
+        binder="_created_at_iso_fmt",  # Get or set from this, but save in created_at
+    )
+    def created_at(self):
+        # _created_at_iso_fmt is an str field which stores an iso format of datetime
+        return datetime.fromisoformat(self._created_at_iso_fmt)
+
+
+@props.auto_collect()
+class Customer(TEntity):
+
+    # A virtual list of orders, saved in a separate collection Order.
+    orders = props.from_entities(Order, "customer_id")
+
+    def __init__(self, username: str, *orders: Order) -> None:
+        self.username = username
+        if orders:
+            self.orders = list(orders)
+
+
+class AppEngine(Engine):
+    __db_path__ = "__test_db__"
+    customers = Engine.set(Customer)
+
+    # A custom method to create orders
+    async def create_order(self, customer_username: str, order_description: str):
+        customer = await self.customers.get_first_async("username", customer_username)
+        if customer:
+            # Iter over virtually saved orders
+            async for order in self.customers.iter_referenced_by_async(
+                customer, lambda c: c.orders
+            ):
+                if order.description == order_description:
+                    return False
+
+            customer.orders.append(Order(order_description))
+        else:
+            customer = Customer(customer_username, Order(order_description))
+            self.customers.add(customer)
+        await self.customers.save_changes_async()
+        return True
+
+
+async def main():
+
+    engine = AppEngine()
+
+    await engine.create_order("immmdreza", "Gimme some faith ...")
+    await engine.create_order("immmdreza", "Gimme some hope ...")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/examples/query_builders.py

@@ -0,0 +1,51 @@
+# pylint: skip-file
+
+import asyncio
+import datetime
+from typing import Optional
+
+from sjd import TEntity, Engine, properties as props
+
+
+@props.auto_collect()
+class Student(TEntity):
+    def __init__(
+        self,
+        first_name: str,
+        registered_date: datetime.datetime,
+        last_name: Optional[str] = None,
+    ):
+        self.first_name = first_name
+        self.registered_date = registered_date
+        self.last_name = last_name
+
+
+class AppEngine(Engine):
+    __db_path__ = "__test_db__"
+    students = Engine.set(Student)
+
+
+async def main():
+
+    engine = AppEngine()
+    students_col = engine.students
+
+    students_col.add_range(
+        Student("Johnny", datetime.datetime(2001, 7, 20), "Deep"),
+        Student("Jececa", datetime.datetime(2000, 6, 10), "Doe"),
+        Student("Jack", datetime.datetime(2001, 6, 5), "Makron"),
+    )
+
+    await engine.save_changes_async()
+
+    target_date = datetime.datetime(2001, 1, 1)
+    async for new_student in students_col.find_all_async(
+        students_col.qa.gt(lambda s: s.registered_date, target_date)
+    ):
+        print(new_student.first_name, new_student.last_name)
+        # Johnny Deep
+        # Jack Makron
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/examples/real_properties.py

@@ -0,0 +1,60 @@
+# pylint: skip-file
+
+import asyncio
+from typing import Optional
+from uuid import uuid4
+
+from sjd import TEntity, Engine, properties as props, make_property, PropertyOptions
+
+
+@props.auto_collect()
+class Student(TEntity):
+    def __init__(self, first_name: str, last_name: Optional[str] = None):
+        self.first_name = first_name
+        self.last_name = last_name
+        self._private_key = str(uuid4())
+
+    @make_property(
+        str,
+        options=PropertyOptions(init=False, required=True),
+        binder="_private_key",  # The serializations use this for getting or setting.
+    )
+    def private_key(self):
+        # private_key is an actual property
+        # Unless you dont define a setter, it's impossible to set value for it.
+        return self._private_key
+
+    @private_key.setter  # You can optionally define a setter or even deleter ...
+    def private_key(self, _):
+        raise AttributeError(
+            "Attribute private_key can't be set after it's initialized"
+        )
+
+
+class AppEngine(Engine):
+    __db_path__ = "__test_db__"
+    students = Engine.set(Student)
+
+
+async def main():
+
+    engine = AppEngine()
+    students_col = engine.students
+
+    students_col.add_range(
+        Student("Johhny", "Deep"),
+        Student("Jececa", "Doe"),
+        Student("Jack", "Makron"),
+    )
+
+    await engine.save_changes_async()
+
+    async for student in students_col:
+        print(student.private_key)
+        # a77d0534-f09f-4977-81d7-55a0373155bc
+        student.private_key = "My new blah"
+        # AttributeError: Attribute private_key can't be set after it's initialized
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/examples/shifting_syntax.py

@@ -0,0 +1,57 @@
+import asyncio
+
+from sjd import TEntity, Engine, properties as props
+
+
+@props.auto_collect()
+class Customer(TEntity):
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+
+class AppEngine(Engine):
+    __db_path__ = "__test_db__"
+    customers = Engine.set(Customer)
+
+
+async def main():
+
+    engine = AppEngine()
+    customers_collection = engine.customers
+
+    customers_collection <<= Customer("Arash"), Customer("Sara")
+    tracked = Customer("Kiarash") >> customers_collection
+    # Both of above ways will call add() method of customers_collection
+    # using second way, you can only add one! but you receive a free tracking instance
+    # which contains information about changes in entity, and entity id.
+    print("A new entity will be added with id:", tracked.key)
+
+    await customers_collection.save_changes_async()
+
+    async for customer in customers_collection:
+        customers_collection >>= customer
+        # Using above syntax is same as calling: customers_collection.delete(customer)
+        break
+
+    # Again, using below syntax, you can get tracking instance as well.
+    async for customer in customers_collection:
+        tracked = customer << customers_collection
+        print(f"An entity with id {tracked.key}, is going to be deleted!")
+
+    await customers_collection.save_changes_async()
+
+    # NOTE: no other kind of shifting are allowed only these four!
+    # ---------------------------------------------
+    # To add:
+    #   one - Entity >> Collection of Entities
+    #   two - Collection of Entities <<= Entity, Entities
+    # ---------------------------------------------
+    # To delete:
+    #   three - Entity << Collection of Entities
+    #   four  - Collection of Entities >>= Entity, Entities
+
+    # You see? Only four!
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/sjd/__init__.py

@@ -1,5 +1,7 @@
 from .database import Engine, Collection
 from .entity import TEntity, EmbeddedEntity, properties
+from .entity._adv_property import make_property
+from .entity._property_options import PropertyOptions, PropertyBinder
 
 
 __all__ = [
@@ -8,4 +10,7 @@
     "TEntity",
     "EmbeddedEntity",
     "properties",
+    "make_property",
+    "PropertyOptions",
+    "PropertyBinder"
 ]