# kabaret.flow_entities
A `kabaret.flow` extension providing searchable large collections of entities, stored in a mongodb.
Create your Entities
====================
Entities are a queryable collection of objects.
In order to define an entity, you must inherit
the `Entity` class and add some `Property` in it:
```python
from kabaret.flow_entities.entities import Entity, Property
class Asset(Entity):
asset_type = Property()
asset_family = Property()
status = Property()
```
You can also add classic relations like `Param` and `Child` and build a whole branch
inside your entity. But keep in mind that the `Propery` relations will be the only ones
usable in your queries.
Once you have an Entity defined, you must use it in an `EntityCollection`:
```python
from kabaret.flow_entities.entities import EntityCollection, CreateEntitiesAction, DeleteEntitiesAction
class Assets(EntityCollection):
# Those actions are provided for convenience,
# you will probably want to define your owns:
create_assets = flow.Child(CreateEntitiesAction)
delete_assets = flow.Child(DeleteEntitiesAction)
@classmethod
def mapped_type(cls):
# This tells which entity is show in
# this collection:
return Asset
```
When using the `Assets` collection in your flow, the users will see a
table with "Asset Type", "Asset Family" and "Status" columns.
This table is more efficient than a `kabaret.flow.Map` and can retrieve thousands of items
in a fraction of seconds.
Still, the `EntityCollection` class inherits `kabaret.flow.DynamicMap` so you can use all the classic
customization points (`columns()`, `_fill_row_style()`, etc...).
Filter your Entities
====================
The `EntityCollection.query_filter()` method can be overidden to return a mongodb filter and
restrict the list of displayed entities. You can for example decide to show only the Assets
with a "WIP" status:
```python
class Assets(EntityCollection):
create_assets = flow.Child(CreateEntitiesAction)
delete_assets = flow.Child(DeleteEntitiesAction)
@classmethod
def mapped_type(cls):
return Asset
def query_filter(self):
"""
Listing only assets with a WIP status
"""
return {"status": "WIP"}
```
Now you can add some `Action` and `Param` on your collection to control
the returned value of `query_filter()`.
Note that only the `Property` relations of your entity can be used
in the filter !
The query filter must be a valid argument for a mongodb `collection.find()` call. Here is some documentation about it: https://docs.mongodb.com/manual/tutorial/query-documents/
Multiple Entity Views
=====================
The `EntityCollection.collection_name()` method can be overidden to point
to another entity collection. This is usefull if you want to display some
entities with a different query filter in different place of your flow.
Here is an example of showing only unfinished tasks assigned to the
current user from a collection of tasks managed in an `admin` section of the
project:
```python
class MyTodo(EntityCollection):
@classmethod
def mapped_type(cls):
# be sure to match the source
# collection here:
return AwesomeTask
def collection_name(self):
return self.root().project().admin.all_tasks.collection_name()
def query_filter(self):
return {
"assignee": getpass.getuser(),
"status": {"$in": ["NYS", "WIP"]},
}
```
MongoDB Connection
==================
The entities are stored as documents in collections of a `mongodb`.
In order for your `EntityCollection` to connect to the database, you
must add an `EntityStore` somewhere in your project and implement a `get_entity_store()` method on your project's root.
A classic aproach is to use an `admin` group in your project:
```python
from kabaret.flow_entities.store import EntityStore
class Admin(flow.Object):
entity_store = flow.Child(EntityStore)
class AwesomePipeline(flow.Object):
admin = flow.Child(Admin)
def get_entity_store(self):
return self.admin.entity_store
```
The `EntityStore` has an `uri` param that you will need to
set before showing or creating entity. The default value connects to a local mongodb database using the default port and options. Contact your beloved IT support team and ask them the value to use for production.
Here is a detailed documentation of the URI syntaxe: https://docs.mongodb.com/manual/reference/connection-string/
Demo
====
See `kabaret.flow_entities.demo` for more demo code.
Create a project with the type `kabaret.flow_entities.demo.EntitiesDemo` to see it in action.
# Changelog
## [1.0.0] - 2024-04-26
After 3 years of beta testing of version 0.0.1, this is the long awaited release of version 1.0.0 stable for production.
### Changed
issue #4: Verbose property print : removed annoying print and change it to logger
## [0.0.1] - 2021-03-30
Initial release by Damien Dee Coureau allowing to expand flow entities to Mongo
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/kabaretstudio/kabaret.flow_entities",
"name": "kabaret.flow-entities",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "kabaret pipeline dataflow workflow mongodb",
"author": "Damien \"dee\" Coureau",
"author_email": "kabaret-dev@googlegroups.com",
"download_url": "https://files.pythonhosted.org/packages/50/bb/6caa35f72f95fb44672694ba5b7855f4dcd66cbca44e9d4388c0411f1708/kabaret_flow_entities-1.0.0.tar.gz",
"platform": null,
"description": "# kabaret.flow_entities\n\nA `kabaret.flow` extension providing searchable large collections of entities, stored in a mongodb.\n\nCreate your Entities\n====================\n\nEntities are a queryable collection of objects. \n\nIn order to define an entity, you must inherit\nthe `Entity` class and add some `Property` in it:\n\n```python\nfrom kabaret.flow_entities.entities import Entity, Property\n\nclass Asset(Entity):\n\n asset_type = Property()\n asset_family = Property()\n \n status = Property()\n\n```\n\nYou can also add classic relations like `Param` and `Child` and build a whole branch\ninside your entity. But keep in mind that the `Propery` relations will be the only ones\nusable in your queries.\n\nOnce you have an Entity defined, you must use it in an `EntityCollection`:\n\n```python\nfrom kabaret.flow_entities.entities import EntityCollection, CreateEntitiesAction, DeleteEntitiesAction\n\nclass Assets(EntityCollection):\n\n # Those actions are provided for convenience,\n # you will probably want to define your owns:\n create_assets = flow.Child(CreateEntitiesAction)\n delete_assets = flow.Child(DeleteEntitiesAction)\n\n @classmethod\n def mapped_type(cls):\n # This tells which entity is show in \n # this collection:\n return Asset\n```\n\nWhen using the `Assets` collection in your flow, the users will see a\ntable with \"Asset Type\", \"Asset Family\" and \"Status\" columns.\n\nThis table is more efficient than a `kabaret.flow.Map` and can retrieve thousands of items\nin a fraction of seconds.\n\nStill, the `EntityCollection` class inherits `kabaret.flow.DynamicMap` so you can use all the classic\ncustomization points (`columns()`, `_fill_row_style()`, etc...).\n\n\nFilter your Entities\n====================\n\nThe `EntityCollection.query_filter()` method can be overidden to return a mongodb filter and\nrestrict the list of displayed entities. You can for example decide to show only the Assets\nwith a \"WIP\" status:\n\n```python\nclass Assets(EntityCollection):\n\n create_assets = flow.Child(CreateEntitiesAction)\n delete_assets = flow.Child(DeleteEntitiesAction)\n\n @classmethod\n def mapped_type(cls):\n return Asset\n\n def query_filter(self):\n \"\"\"\n Listing only assets with a WIP status\n \"\"\" \n return {\"status\": \"WIP\"}\n```\n\nNow you can add some `Action` and `Param` on your collection to control \nthe returned value of `query_filter()`.\n\nNote that only the `Property` relations of your entity can be used \nin the filter !\n\nThe query filter must be a valid argument for a mongodb `collection.find()` call. Here is some documentation about it: https://docs.mongodb.com/manual/tutorial/query-documents/\n\n\nMultiple Entity Views\n=====================\n\nThe `EntityCollection.collection_name()` method can be overidden to point\nto another entity collection. This is usefull if you want to display some\nentities with a different query filter in different place of your flow.\n\nHere is an example of showing only unfinished tasks assigned to the\ncurrent user from a collection of tasks managed in an `admin` section of the\nproject:\n\n```python\n\nclass MyTodo(EntityCollection):\n\n @classmethod\n def mapped_type(cls):\n # be sure to match the source\n # collection here:\n return AwesomeTask\n\n def collection_name(self):\n return self.root().project().admin.all_tasks.collection_name()\n \n def query_filter(self):\n return {\n \"assignee\": getpass.getuser(), \n \"status\": {\"$in\": [\"NYS\", \"WIP\"]},\n }\n```\n\nMongoDB Connection\n==================\n\nThe entities are stored as documents in collections of a `mongodb`.\n\nIn order for your `EntityCollection` to connect to the database, you\nmust add an `EntityStore` somewhere in your project and implement a `get_entity_store()` method on your project's root.\n\nA classic aproach is to use an `admin` group in your project:\n```python\n\nfrom kabaret.flow_entities.store import EntityStore\n\nclass Admin(flow.Object):\n\n entity_store = flow.Child(EntityStore)\n \nclass AwesomePipeline(flow.Object):\n\n admin = flow.Child(Admin)\n\n def get_entity_store(self):\n return self.admin.entity_store\n\n\n```\n\nThe `EntityStore` has an `uri` param that you will need to \nset before showing or creating entity. The default value connects to a local mongodb database using the default port and options. Contact your beloved IT support team and ask them the value to use for production.\n\nHere is a detailed documentation of the URI syntaxe: https://docs.mongodb.com/manual/reference/connection-string/\n\nDemo\n====\n\nSee `kabaret.flow_entities.demo` for more demo code.\n\nCreate a project with the type `kabaret.flow_entities.demo.EntitiesDemo` to see it in action.\n\n\n\n# Changelog\n\n## [1.0.0] - 2024-04-26\n\nAfter 3 years of beta testing of version 0.0.1, this is the long awaited release of version 1.0.0 stable for production.\n\n### Changed\n\nissue #4: Verbose property print : removed annoying print and change it to logger\n\n## [0.0.1] - 2021-03-30\n\nInitial release by Damien Dee Coureau allowing to expand flow entities to Mongo\n\n",
"bugtrack_url": null,
"license": "LGPLv3+",
"summary": "A kabaret.flow extension providing searchable large collections of entities.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://gitlab.com/kabaretstudio/kabaret.flow_entities"
},
"split_keywords": [
"kabaret",
"pipeline",
"dataflow",
"workflow",
"mongodb"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "50bb6caa35f72f95fb44672694ba5b7855f4dcd66cbca44e9d4388c0411f1708",
"md5": "375155b97b5867c3d1b8f04ba9cae874",
"sha256": "9cd51e5ce248f402274bf17a57e8ee039d3c5c32ae6b59b6f816c4e230b320f8"
},
"downloads": -1,
"filename": "kabaret_flow_entities-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "375155b97b5867c3d1b8f04ba9cae874",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27014,
"upload_time": "2024-04-26T09:16:33",
"upload_time_iso_8601": "2024-04-26T09:16:33.220329Z",
"url": "https://files.pythonhosted.org/packages/50/bb/6caa35f72f95fb44672694ba5b7855f4dcd66cbca44e9d4388c0411f1708/kabaret_flow_entities-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-26 09:16:33",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "kabaretstudio",
"gitlab_project": "kabaret.flow_entities",
"lcname": "kabaret.flow-entities"
}
JSON