# CastNet
*** This package is in the very early stages of testing. Do not use for production. ***
`pip install castnet`
CastNet is a schema based low level Neo4j connection interaction library your Python back end, enabling easy type conversions and generalized CRUD endpoints (including GraphQL).
CastNet does not want to take over your backend, it just wants to help out. You still control routing, auth, and deployment.
Each node by default has an automatically generated ID, a user-specified name which should be unique to that label, and a description. Incoming URL requests are transformed to their labels by a route-label table and types/relationships are automatically cast from the incoming JSON based on a schema.
CastNet managed databases support:
* Automatic conversion of Route -> node_label/node_id
* Automatic conversion of Json->PythonTypes->Neo4jTypes
* Managed (Optional) Hierarchy
* Ordered Relationships
* Label-level `name` unique constraints (for hierarchy)
* Simple GraphQL Read-only endpoint
* Immutable URI path compatible node IDs for filesystem/cloud integration
And Coming soon:
* Logging function to record changes
* Callbacks for custom behavior
## How to Use
1. Define a schema
2. Define a URL/Label table
3. Plug in to your REST backend (Tested with Flask)
## Minimal Example
`{'id': str, 'name': str, and 'description': str}` are automatically created in the schema.
```Python
import json
from flask import Flask, request
from castnet import CastNetConn
def make_response(response, status=200):
return (json.dumps(response), status, {"Access-Control-Allow-Origin": "*"})
SCHEMA = {"Person" :{}}
URL_KEY = {"people": "person"}
CONN = CastNetConn("database_uri", "username", "password", SCHEMA, URL_KEY)
app = Flask(__name__)
@app.route("/<path:path>", methods=["POST", "PATCH", "OPTIONS", "DELETE"])
def main(**_):
path_params = CONN.get_path(request.path)
if path_params[0] == "graphql":
return make_response(*CONN.generic_graphql(request))
if request.method == "POST":
return make_response(*CONN.generic_post(request))
if request.method == "PATCH":
return make_response(*CONN.generic_patch(request))
if request.method == "DELETE":
return make_response(*CONN.generic_delete(request))
app.run(debug=True)
```
Create a Person:
```
curl -X POST localhost:5000/people -H 'Content-Type: application/json'
-d '{"name":"Alice", "description":"Pretty nice."}'
```
Retrieve People (Post to the GraphQL endpoint)
```
curl -X POST localhost:5000/graphql -H 'Content-Type: application/json'
-d '{"query":"Person{id name description}"}'
```
Update a Person (IDs and Names are immutable):
```
curl -X POST localhost:5000/people/<Alice's ID> -H 'Content-Type: application/json'
-d '{"description":"Actually really nice."}'
```
Delete a Person:
```
curl -X DELETE localhost:5000/people/<Alice's ID>
```
And from the back end, there are manual endpoints, such as
```
results = CONN.read_cypher(cypher, **params)
results = CONN.write_cypher(cypher, **params)
results = CONN.read_graphql(graphql, **params)
```
## More Complicated Example
Let's say we want to create a database to handle easy updates to a Bird tracker at various birdfeeders, at multiple houses, each with multiple feeders. One possible way to have a database is by making a hierarchical database, starting with Houses. And, we may want a running list of birds and know when/where they were seen. Most importantly, we want to build a snazzy web based front end, and don't want to make a dedicated endpoint for each update.
The database entries, with their hierarchies might look something like this:
* My House (House)
* GardenFeeder (Feeder)
* Day1 (FeederScan)
* Day2 (FeederScan)
* SideYardFeeder (Feeder)
* Day1 (FeederScan)
* Day2 (FeederScan)
* Bob's House (House)
* BackyardFeeder (Feeder)
* Day1 (FeederScan)
* Day2 (FeederScan)
* BlueJay (Bird)
* Eastern BlueBird (Bird)
* Ruby-Throated Hummingbird (Bird)
* Ivory-Billed Woodpecker (Bird)
We have two Houses, 3 Feeders, and 6 observations (FeederScan) and 2 birds in the database. In this design, we could build a schema like so:
```python
from datetime import datetime
# NOTE: {'id': str, 'name': str, and 'description': str} is automatically added to attributes
# If there is the "IS_IN" rel, then an automatic "isIn" GraphQL endpoint is created.
SCHEMA = {
"House": {},
"Feeder": {
"attributes": {"feederType": str, "feederHeight": float, "seedType": str, "dateInstalled": datetime},
"IS_IN": "House"
},
"Scan": {
"attributes": {"scanTime": datetime, "feederHeight": float, "seedType": str, "dateInstalled": datetime},
"relationships": {"BIRDS_OBSERVED": ["Bird"]},
"IS_IN": "Feeder",
"graphql":{
"birdsObserved": {"rel": "BIRDS_OBSERVED", "dir": "OUT", "lab": "Bird"}
}
},
"Bird": {
"attributes": {"favoriteFood": str},
"graphql":{
"seenAt": {"rel": "BIRDS_OBSERVED", "dir": "IN", "lab": "Scan"}
}
},
}
```
and tie it in to our url schema
```python
URL_KEY = {
"birds": "Bird",
"houses": "House",
"birdfeeders": "Feeder",
"feederscans": "Scan",
}
```
And now we can begin making requests!
### Create a House:
```
POST: /birdserver/houses
JSON: "{'name': 'My House', 'description': 'This is my house.'}"
```
which automatically generates an id (e.g. `House_20220429_myhouse_abcd`), parses and casts the name and submits the following Cypher:
```
CREATE
(source:House {id: $source_id, name:$name, description:$description})
RETURN
source
```
### Now add a feeder, which is that the house
```
Method: POST
URL: /birdserver/birdfeeders
JSON: "{'name': 'GardenFeeder', 'dateInstalled': "2022-04-22': 'IS_IN': 'House_20220429_myhouse_abcd'}"
```
which becomes:
```Cypher
MATCH
(target_0:House {id: $target_0_id})
CREATE
(source:Feeder {id: $source_id, dateInstalled:$dateInstalled})
CREATE
(source)-[:IS_IN {order_num: 0}]->(target_0)
RETURN
source
```
And assuming the birds are added, add a scan
```
Method: POST
URL: /birdserver/feederscans
JSON: "{'name': 'Day1', 'timeStamp': "2022-04-22': 'IS_IN': 'Feeder_20220429_gardenfeeder_abcd',
'BIRDS_OBSERVED': ['Bird_20220429_ivorybilledwoodpecker_abcd', Bird_20220429_bluejay_abcd]}"
```
```Cypher
MATCH
(target_0:Feeder {id: $target_0_id})
(target_0:Bird {id: $target_1_id})
(target_0:Bird {id: $target_2_id})
CREATE
(source:Scan {id: $source_id, timeStamp:timeStamp})
CREATE
(source)-[:IS_IN {order_num: 0}]->(target_0),
(source)-[:BIRDS_OBSERVED {order_num: 1}]->(target_1),
(source)-[:BIRDS_OBSERVED {order_num: 2}]->(target_2)
RETURN
source
```
Or remove the Ivory-Billed Woodpecker by updating with just a bluejay...
```
Method: PATCH
URL: /birdserver/scans/Scan_20220429_day1_abcd
JSON: "{'BIRDS_OBSERVED': ['Bird_20220429_bluejay_abcd']}"
```
## Current known issues/updates
* Some operations are not atomic and must be
* Node ID's might have better format
* Is a "request" object the best item to pass into the generic endpoints?
* GraphQL not secure
Raw data
{
"_id": null,
"home_page": "https://github.com/broadinstitute/castnet",
"name": "castnet",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Neo4j,REST,graphdb,CRUD,graphql",
"author": "Daniel S. Hitchcock",
"author_email": "daniel.s.hitchcock@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9a/d5/a110127ce4eefd772092da6db5dd2853ae47b30adcd9e320865eba8e592c/castnet-0.0.15.tar.gz",
"platform": null,
"description": "# CastNet\r\n*** This package is in the very early stages of testing. Do not use for production. ***\r\n\r\n`pip install castnet`\r\n\r\nCastNet is a schema based low level Neo4j connection interaction library your Python back end, enabling easy type conversions and generalized CRUD endpoints (including GraphQL).\r\n\r\nCastNet does not want to take over your backend, it just wants to help out. You still control routing, auth, and deployment.\r\n\r\nEach node by default has an automatically generated ID, a user-specified name which should be unique to that label, and a description. Incoming URL requests are transformed to their labels by a route-label table and types/relationships are automatically cast from the incoming JSON based on a schema. \r\n\r\nCastNet managed databases support:\r\n* Automatic conversion of Route -> node_label/node_id\r\n* Automatic conversion of Json->PythonTypes->Neo4jTypes \r\n* Managed (Optional) Hierarchy\r\n* Ordered Relationships\r\n* Label-level `name` unique constraints (for hierarchy)\r\n* Simple GraphQL Read-only endpoint\r\n* Immutable URI path compatible node IDs for filesystem/cloud integration\r\n\r\nAnd Coming soon:\r\n* Logging function to record changes\r\n* Callbacks for custom behavior\r\n\r\n## How to Use\r\n1. Define a schema\r\n2. Define a URL/Label table\r\n3. Plug in to your REST backend (Tested with Flask)\r\n\r\n## Minimal Example\r\n`{'id': str, 'name': str, and 'description': str}` are automatically created in the schema.\r\n```Python\r\nimport json\r\nfrom flask import Flask, request\r\nfrom castnet import CastNetConn\r\n\r\ndef make_response(response, status=200):\r\n return (json.dumps(response), status, {\"Access-Control-Allow-Origin\": \"*\"})\r\n\r\nSCHEMA = {\"Person\" :{}}\r\nURL_KEY = {\"people\": \"person\"}\r\nCONN = CastNetConn(\"database_uri\", \"username\", \"password\", SCHEMA, URL_KEY)\r\napp = Flask(__name__)\r\n\r\n@app.route(\"/<path:path>\", methods=[\"POST\", \"PATCH\", \"OPTIONS\", \"DELETE\"])\r\ndef main(**_):\r\n path_params = CONN.get_path(request.path)\r\n if path_params[0] == \"graphql\":\r\n return make_response(*CONN.generic_graphql(request))\r\n if request.method == \"POST\":\r\n return make_response(*CONN.generic_post(request))\r\n if request.method == \"PATCH\":\r\n return make_response(*CONN.generic_patch(request))\r\n if request.method == \"DELETE\":\r\n return make_response(*CONN.generic_delete(request))\r\n \r\napp.run(debug=True)\r\n```\r\nCreate a Person:\r\n```\r\ncurl -X POST localhost:5000/people -H 'Content-Type: application/json' \r\n -d '{\"name\":\"Alice\", \"description\":\"Pretty nice.\"}'\r\n```\r\nRetrieve People (Post to the GraphQL endpoint)\r\n```\r\ncurl -X POST localhost:5000/graphql -H 'Content-Type: application/json' \r\n -d '{\"query\":\"Person{id name description}\"}'\r\n```\r\nUpdate a Person (IDs and Names are immutable):\r\n```\r\ncurl -X POST localhost:5000/people/<Alice's ID> -H 'Content-Type: application/json' \r\n -d '{\"description\":\"Actually really nice.\"}'\r\n```\r\nDelete a Person:\r\n```\r\ncurl -X DELETE localhost:5000/people/<Alice's ID>\r\n```\r\nAnd from the back end, there are manual endpoints, such as \r\n```\r\nresults = CONN.read_cypher(cypher, **params)\r\nresults = CONN.write_cypher(cypher, **params)\r\nresults = CONN.read_graphql(graphql, **params)\r\n```\r\n\r\n## More Complicated Example\r\nLet's say we want to create a database to handle easy updates to a Bird tracker at various birdfeeders, at multiple houses, each with multiple feeders. One possible way to have a database is by making a hierarchical database, starting with Houses. And, we may want a running list of birds and know when/where they were seen. Most importantly, we want to build a snazzy web based front end, and don't want to make a dedicated endpoint for each update.\r\n\r\nThe database entries, with their hierarchies might look something like this:\r\n\r\n* My House (House)\r\n * GardenFeeder (Feeder)\r\n * Day1 (FeederScan)\r\n * Day2 (FeederScan)\r\n * SideYardFeeder (Feeder)\r\n * Day1 (FeederScan)\r\n * Day2 (FeederScan)\r\n* Bob's House (House)\r\n * BackyardFeeder (Feeder)\r\n * Day1 (FeederScan)\r\n * Day2 (FeederScan)\r\n* BlueJay (Bird)\r\n* Eastern BlueBird (Bird)\r\n* Ruby-Throated Hummingbird (Bird)\r\n* Ivory-Billed Woodpecker (Bird)\r\n\r\nWe have two Houses, 3 Feeders, and 6 observations (FeederScan) and 2 birds in the database. In this design, we could build a schema like so:\r\n\r\n```python\r\nfrom datetime import datetime\r\n# NOTE: {'id': str, 'name': str, and 'description': str} is automatically added to attributes\r\n# If there is the \"IS_IN\" rel, then an automatic \"isIn\" GraphQL endpoint is created.\r\nSCHEMA = {\r\n \"House\": {},\r\n \"Feeder\": {\r\n \"attributes\": {\"feederType\": str, \"feederHeight\": float, \"seedType\": str, \"dateInstalled\": datetime},\r\n \"IS_IN\": \"House\"\r\n },\r\n \"Scan\": {\r\n \"attributes\": {\"scanTime\": datetime, \"feederHeight\": float, \"seedType\": str, \"dateInstalled\": datetime},\r\n \"relationships\": {\"BIRDS_OBSERVED\": [\"Bird\"]},\r\n \"IS_IN\": \"Feeder\",\r\n \"graphql\":{\r\n \"birdsObserved\": {\"rel\": \"BIRDS_OBSERVED\", \"dir\": \"OUT\", \"lab\": \"Bird\"}\r\n }\r\n },\r\n \"Bird\": {\r\n \"attributes\": {\"favoriteFood\": str},\r\n \"graphql\":{\r\n \"seenAt\": {\"rel\": \"BIRDS_OBSERVED\", \"dir\": \"IN\", \"lab\": \"Scan\"}\r\n }\r\n },\r\n}\r\n```\r\nand tie it in to our url schema\r\n```python\r\nURL_KEY = {\r\n \"birds\": \"Bird\",\r\n \"houses\": \"House\",\r\n \"birdfeeders\": \"Feeder\",\r\n \"feederscans\": \"Scan\",\r\n}\r\n```\r\n\r\nAnd now we can begin making requests!\r\n\r\n### Create a House:\r\n```\r\nPOST: /birdserver/houses\r\nJSON: \"{'name': 'My House', 'description': 'This is my house.'}\"\r\n``` \r\nwhich automatically generates an id (e.g. `House_20220429_myhouse_abcd`), parses and casts the name and submits the following Cypher:\r\n```\r\nCREATE\r\n(source:House {id: $source_id, name:$name, description:$description})\r\nRETURN\r\nsource\r\n```\r\n### Now add a feeder, which is that the house\r\n```\r\nMethod: POST\r\nURL: /birdserver/birdfeeders\r\nJSON: \"{'name': 'GardenFeeder', 'dateInstalled': \"2022-04-22': 'IS_IN': 'House_20220429_myhouse_abcd'}\"\r\n```\r\nwhich becomes:\r\n```Cypher\r\nMATCH\r\n(target_0:House {id: $target_0_id})\r\nCREATE\r\n(source:Feeder {id: $source_id, dateInstalled:$dateInstalled})\r\nCREATE\r\n(source)-[:IS_IN {order_num: 0}]->(target_0)\r\nRETURN\r\nsource\r\n```\r\nAnd assuming the birds are added, add a scan\r\n```\r\nMethod: POST\r\nURL: /birdserver/feederscans\r\nJSON: \"{'name': 'Day1', 'timeStamp': \"2022-04-22': 'IS_IN': 'Feeder_20220429_gardenfeeder_abcd',\r\n 'BIRDS_OBSERVED': ['Bird_20220429_ivorybilledwoodpecker_abcd', Bird_20220429_bluejay_abcd]}\"\r\n```\r\n```Cypher\r\nMATCH\r\n(target_0:Feeder {id: $target_0_id})\r\n(target_0:Bird {id: $target_1_id})\r\n(target_0:Bird {id: $target_2_id})\r\nCREATE\r\n(source:Scan {id: $source_id, timeStamp:timeStamp})\r\nCREATE\r\n(source)-[:IS_IN {order_num: 0}]->(target_0),\r\n(source)-[:BIRDS_OBSERVED {order_num: 1}]->(target_1),\r\n(source)-[:BIRDS_OBSERVED {order_num: 2}]->(target_2)\r\nRETURN\r\nsource\r\n```\r\nOr remove the Ivory-Billed Woodpecker by updating with just a bluejay...\r\n```\r\nMethod: PATCH\r\nURL: /birdserver/scans/Scan_20220429_day1_abcd\r\nJSON: \"{'BIRDS_OBSERVED': ['Bird_20220429_bluejay_abcd']}\"\r\n```\r\n\r\n## Current known issues/updates\r\n* Some operations are not atomic and must be\r\n* Node ID's might have better format\r\n* Is a \"request\" object the best item to pass into the generic endpoints?\r\n* GraphQL not secure\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CastNet is a schema based low level Neo4j connection interaction library your Python back end, enabling easy type conversions and generalized CRUD endpoints (including GraphQL).",
"version": "0.0.15",
"project_urls": {
"Homepage": "https://github.com/broadinstitute/castnet"
},
"split_keywords": [
"neo4j",
"rest",
"graphdb",
"crud",
"graphql"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9ad5a110127ce4eefd772092da6db5dd2853ae47b30adcd9e320865eba8e592c",
"md5": "7adf39dff8da108a8e883cf9be433e9d",
"sha256": "3df518af0cfd30a2b092f103c182a5bd729d52d0e285bd7643a904e453a5533b"
},
"downloads": -1,
"filename": "castnet-0.0.15.tar.gz",
"has_sig": false,
"md5_digest": "7adf39dff8da108a8e883cf9be433e9d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17896,
"upload_time": "2024-02-26T15:53:43",
"upload_time_iso_8601": "2024-02-26T15:53:43.694692Z",
"url": "https://files.pythonhosted.org/packages/9a/d5/a110127ce4eefd772092da6db5dd2853ae47b30adcd9e320865eba8e592c/castnet-0.0.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-26 15:53:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "broadinstitute",
"github_project": "castnet",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "neo4j",
"specs": []
},
{
"name": "shortuuid",
"specs": []
}
],
"lcname": "castnet"
}
JSON
