Merge pull request #11 from Roboy/devel

Devel to Master

Author: josephbirkner

.gitignore

@@ -0,0 +1,11 @@
+.idea
+venv
+*.key
+*.default
+.coverage
+.pytest_cache
+__pycache__
+dist/*
+build/*
+*.egg-info
+*.log

README.md

@@ -1,2 +1,141 @@
 # Roboy ScientIO
+
+## About
+
 Roboy ScientIO (from Lat. scientia - knowledge and Input/Output) - a Knowledge Graph Engine to organise and query complex data.
+
+## Dependencies
+
+To use ScientIO, you will need to have one of it's supported back-ends installed. Currently, the only supported back-end is Neo4j, which may be run in a number of ways
+(if you don't have a remote instance available). We recommend simply running it through docker - like this:
+
+```bash
+docker run \
+    --publish=7474:7474 --publish=7687:7687 \
+    --volume=$HOME/neo4j/data:/data \
+    --volume=$HOME/neo4j/logs:/logs \
+    neo4j:3.0
+```
+
+## Installation
+
+### Via PIP
+
+The easiest way to install ScientIO is through pip:
+
+``
+pip install scientio
+``
+
+### For developers
+
+First, install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+Then, you may open the repository in any IDE, and mark the
+`src` folder as a sources root.
+
+## Basic ScientIO use-cases
+
+### Supplying an ontology description
+
+The ontology description is a collection of named entity types, where each type may declare a specific set of properties and relationships like this:
+
+```yaml
+# my_ontology.yml
+
+!OType
+entity: Alien    # The name of the ontology type
+---
+!OType
+entity: Vulcan   # Declare a more specific Alien type
+meta: [Alien]
+properties:      # Allowed properties for every Vulcan
+ - name
+ - homeworld
+ - ear_pointiness
+---
+!OType
+entity: Human    # Declare a more specific Alien type
+meta: [Alien]
+properties:      # Allowed properties for every Human
+ - name
+ - homeworld
+relationships: [captain_of]  # Allowed relationships for every Human
+```
+
+### Creating some nodes
+
+```python
+from scientio.ontology.ontology import Ontology
+from scientio.session import Session
+from scientio.ontology.node import Node
+
+# Load the ontology from a yaml file
+onto = Ontology(path_to_yaml="my_ontology.yml")
+
+# Create a session (with default Neo4j backend)
+sess = Session(
+    ontology=onto,
+    neo4j_address="bolt://localhost:7687",
+    neo4j_username="neo4j",
+    neo4j_password="test")
+
+# Get human/vulcan types from ontology
+human_type = onto.get_type("Human")
+vulcan_type = onto.get_type("Vulcan")
+
+# Create a transient human named "Kirk"
+kirk = Node(metatype=human_type)
+kirk.set_name("Kirk")
+
+# Create a transient vulcan named "Spock"
+spock = Node(metatype=vulcan_type)
+spock.set_name("Spock")
+
+# Persist kirk and spock
+sess.create(kirk)
+sess.create(spock)
+```
+
+### Add a relationship between your nodes
+
+```python
+from scientio.ontology.ontology import Ontology
+from scientio.session import Session
+from scientio.ontology.node import Node
+
+# Load the ontology from a yaml file
+onto = Ontology(path_to_yaml="my_ontology.yml")
+
+# Create a session (with default Neo4j backend)
+sess = Session(
+    ontology=onto,
+    neo4j_address="bolt://localhost:7687",
+    neo4j_username="neo4j",
+    neo4j_password="test")
+
+# Get human/vulcan types from ontology
+human_type = onto.get_type("Human")
+vulcan_type = onto.get_type("Vulcan")
+
+# Create query templates to get the actual kirk/spock
+kirk = Node(metatype=human_type)
+spock = Node(metatype=vulcan_type)
+
+# Query Kirk and Spock from the database, using
+# the query nodes we created previously. We're just
+# gonna assume that the first human is Kirk, and the first
+# vulcan is Spock.
+kirk = sess.retrieve(request=kirk)[0]
+spock = sess.retrieve(request=spock)[0]
+
+# Add a relationship between Kirk and Spock
+kirk.add_relationships({"captain_of": {spock.get_id()}})
+
+# Make sure that the new relationship is persisted
+sess.update(kirk)
+```

deploy.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+export setupfile=${1}
+
+if [[ ! $setupfile ]]; then
+    export setupfile=setup.py
+fi
+
+rm -rf dist
+python3 $setupfile sdist bdist_wheel
+twine upload dist/*

requirements.txt

@@ -0,0 +1,4 @@
+pytz
+neo4j
+pyyaml
+reggol

setup.py

@@ -0,0 +1,39 @@
+import setuptools
+
+with open("README.md", "r") as fh:
+    long_description = fh.read()
+
+required_url = []
+required = []
+with open("requirements.txt", "r") as freq:
+    for line in freq.read().split():
+        if "://" in line:
+            required_url.append(line)
+        else:
+            required.append(line)
+
+packages = setuptools.find_packages("src")
+
+setuptools.setup(
+    name="scientio",
+    version="0.9.0",
+    url="https://github.com/roboy/scientio",
+    author="Roboy",
+    author_email="[email protected]",
+
+    description="ScientIO is a Knowledge Graph Engine to organise and query complex data.",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+
+    package_dir={'': 'src'},
+    packages=packages,
+
+    install_requires=required,
+    dependency_links=required_url,
+    python_requires='>=3.7',
+
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Operating System :: OS Independent",
+    ],
+)