Merge pull request #5 from neo4j-labs/merge/merge_unrelated_dev_and_m…

…aster

Merging unrelated develop to master

.gitignore

@@ -127,3 +127,5 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+.DS_Store
+.idea/

README.md

@@ -73,7 +73,8 @@ for band in g.subjects(rdflib.RDF.type, rdflib.URIRef("neo4j://graph.schema#Band
     for bandName in g.objects(band, rdflib.URIRef("neo4j://graph.schema#name")):
         print(bandName)
 ```
-This fragment retunrs a listing with the names of the bands in the dataset and at the same time, has populated your Neo4j DB with a graph like this one:
+
+This fragment returns a listing with the names of the bands in the dataset and at the same time, has populated your Neo4j DB with a graph like this one:
 
 <img src="https://raw.githubusercontent.com/neo4j-labs/rdflib-neo4j/master/img/graph-view.png" height="400">
 
@@ -83,7 +84,7 @@ You can also write to the graph triple by triple like this:
 MUSIC = rdflib.Namespace("neo4j://graph.schema#")
 fm = rdflib.URIRef("http://neo4j.com/indiv#Fleetwood_Mac")
 
-g.add((fm, rdflib.RDF.type, MUSIC.Band))
+g.add((fm, rdflib.RDF.rel_type, MUSIC.Band))
 g.add((fm, MUSIC.name, rdflib.Literal("Fleetwood Mac")))
 ```
 Where `rdflib.RDFS` is the RDFS Namespace, `MUSIC` is a custom namespace for the vocabulary used in our dataset, and `rdflib.URIRef` and `rdflib.Literal` are used to construct URI objects and Literal objects from their string representations. 

docs/README.md

@@ -0,0 +1 @@
+to start from here

docs/documentation/Neo4jStore-0.1.adoc

@@ -0,0 +1,77 @@
+== Neo4j Store
+[.procedures, opts=header]
+
+This class is an implementation of the rdflib link:https://rdflib.readthedocs.io/en/stable/_modules/rdflib/store.html[Store class] that uses Neo4j as a backend. In this way it is possible to persist you RDF data directly in Neo4j, with the power of rdflib to process your data.
+
+=== Object Initialization
+|===
+| Name | Type | Required | Default | Description
+|config|Neo4jStoreConfig|True||Neo4jStoreConfig object that contains all the useful informations to initialize the store.
+|===
+
+== Functions
+
+=== open
+
+Opens a connection to the Neo4j database.
+
+==== Arguments
+
+|===
+| Name | Type | Description
+| configuration | | The configuration for the Neo4j database. (Not used, just kept for the method declaration in the Store class)
+| create | bool | Flag indicating whether to create the uniqueness constraint if not found.
+|===
+
+=== is_open
+
+Checks if the store is open.
+
+==== Arguments
+No arguments.
+
+==== Output
+
+|===
+| Type | Description
+| bool | True if the store is open, False otherwise.
+|===
+
+=== add
+
+Adds a triple to the Neo4j store. It requires an opened store to work.
+
+==== Arguments
+
+|===
+| Name | Type | Default | Description
+| triple | Tuple |N/A| The triple to add.
+| context | |N/A| The context of the triple (default: None). Kept to respect the signature but currently not used.
+| quoted | bool |N/A| Flag indicating whether the triple is quoted (default: False). Kept to respect the signature but currently not used.
+|===
+
+=== commit
+
+Commits the currently stored nodes/relationships to the Neo4j database.
+
+==== Arguments
+
+|===
+| Name | Type |Default| Description
+| commit_nodes | bool | False | Flag indicating whether to commit the nodes in the buffer.
+| commit_rels | bool | False | Flag indicating whether to commit the relationships in the buffer.
+|===
+
+=== close
+
+Closes the store. If the field _batching_ is set to True in the Neo4jStoreConfig, remember to close the store to prevent the loss of any uncommitted records.
+
+==== Arguments
+
+|===
+| Name | Type | Default | Description
+| commit_pending_transaction | bool | True | Flag indicating whether to commit any pending transaction before closing.
+|===
+
+
+

docs/documentation/Neo4jStoreConfig-0.1.adoc

@@ -0,0 +1,252 @@
+== Neo4j Store Config
+[.procedures, opts=header]
+
+This object is used to configure the Neo4j Store to connect to your Neo4j Instance and to manage the parsing of a Triple Store.
+
+=== Object Initialization
+|===
+| Name | Type | Required | Values(Default) | Description
+| auth_data | Dictionary | True | ("uri", "database", "user", "pwd") | A dictionary containing authentication data. The required keys are: ["uri", "database", "user", "pwd"].
+| batching | Boolean | False | boolean (True) | A boolean indicating whether batching is enabled.
+| batch_size | Integer | False | (5000) | An integer representing the batch size (The batch size is intended as number of entities to store inside the database (nodes/relationships) and not triples.
+| custom_mappings | List[Tuple[Str,Str,Str]] | False | Empty list | A list of tuples containing custom mappings for prefixes in the form (prefix, object_to_replace, new_object).
+| custom_prefixes | Dictionary | True if handle_vocab_uri_strategy ==  HANDLE_VOCAB_URI_STRATEGY.SHORTEN | ({}) | A dictionary containing custom prefixes.
+| handle_vocab_uri_strategy | HANDLE_VOCAB_URI_STRATEGY | False |HANDLE_VOCAB_URI_STRATEGY.IGNORE, HANDLE_VOCAB_URI_STRATEGY.KEEP, HANDLE_VOCAB_URI_STRATEGY.MAP(HANDLE_VOCAB_URI_STRATEGY.SHORTEN) |
+
+* 'SHORTEN',  full uris are shortened using prefixes for property names, relationship names and labels. Fails if a prefix is not predefined for a namespace in the imported RDF.
+
+* 'IGNORE' uris are ignored and only local names are kept
+
+* 'MAP' vocabulary element mappings are applied on import
+
+* 'KEEP' uris are kept unchanged
+
+| handle_multival_strategy | HANDLE_MULTIVAL_STRATEGY | False | HANDLE_MULTIVAL_STRATEGY.ARRAY (HANDLE_MULTIVAL_STRATEGY.OVERWRITE)|
+* 'OVERWRITE' property values are kept single valued. Multiple values in the imported RDF are overwriten (only the last one is kept)
+
+* 'ARRAY' properties are stored in an array enabling storage of multiple values. All of them unless multivalPropList is set.
+| multival_props_names | List[Tuple[Str,Str]] | False | ([]) | A list of tuples containing the prefix and property names to be treated as multivalued in the form (prefix, property_name).
+|===
+
+== Functions
+
+=== set_handle_vocab_uri_strategy
+
+Set the strategy to handle vocabulary URIs.
+
+==== Arguments
+
+|===
+| Name | Type | Description
+| val | HANDLE_VOCAB_URI_STRATEGY | The handle_vocab_uri_strategy value to be set.
+|===
+
+
+
+=== set_handle_multival_strategy
+
+Set the strategy to handle multiple values.
+
+==== Arguments
+
+|===
+| Name | Type | Description
+| val | HANDLE_MULTIVAL_STRATEGY | The handle_multival_strategy value to be set.
+|===
+
+
+=== set_default_prefix
+
+Set a default prefix.
+
+==== Arguments
+
+|===
+| Name | Type | Description
+| name | str | The name of the prefix.
+| value | str | The value of the prefix (namespace URI).
+|===
+
+=== set_multival_prop_name
+
+Set a property name to be treated as multivalued.
+
+==== Arguments
+
+|===
+| Name | Type | Description
+| prefix_name | str | The name of the prefix.
+| prop_name | str | The name of the property to be treated as multivalued.
+|===
+
+=== set_custom_prefix
+
+Add a custom prefix to the configuration.
+
+==== Arguments
+
+|===
+| Name | Type | Description
+| name | str | The name of the prefix.
+| value | str | The value of the prefix (namespace URI).
+|===
+
+=== delete_custom_prefix
+
+Delete a custom prefix from the 'custom_prefixes' dictionary.
+
+==== Arguments
+
+|===
+| Name | Type | Description
+| name | str | The name of the custom prefix to be deleted.
+|===
+
+=== set_custom_mapping
+
+Add a custom mapping for a certain prefix.
+
+==== Arguments
+
+|===
+| Name | Type | Description
+| prefix_name | str | The name of the prefix to be mapped.
+| to_replace | str | The value to be replaced in the namespace URI.
+| new_value | str | The new value for the mapping (namespace URI).
+|===
+
+=== delete_custom_mapping
+
+Deletes a custom mapping from the custom_mappings dictionary. It will raise PrefixNotFoundException if the prefix is not found in the available prefixes.
+
+==== Arguments
+
+|===
+| Name | Type | Description
+| prefix_name | str | The name of the prefix to which 'to_replace' is associated.
+| to_replace | str | The value to be replaced within the prefix's namespace.
+|===
+
+=== set_auth_data
+
+Set authentication data.
+
+==== Arguments
+
+|===
+| Name | Type | Description
+| auth | Dictionary | A dictionary containing authentication data. The required keys are ["uri", "database", "user", "pwd"].
+|===
+
+=== set_batching
+
+Set batching.
+
+==== Arguments
+
+|===
+| Name | Type | Description
+| val | bool | A boolean indicating whether batching is enabled.
+|===
+
+=== set_batch_size
+
+Set the batch size.
+
+==== Arguments
+
+|===
+| Name | Type | Description
+| val | int | An integer representing the batch size.
+|===
+
+=== get_config_dict
+
+Get the configuration dictionary. Raises WrongAuthenticationException if any of the required authentication fields is missing.
+
+==== Arguments
+No arguments.
+
+==== Output
+
+|===
+| Type | Description
+| Dictionary | A dictionary containing the configuration parameters.
+|===
+
+=== get_prefixes
+
+Get a dictionary containing all prefixes (default and custom).
+
+==== Arguments
+No arguments
+
+==== Output
+
+|===
+| Type | Description
+| Dictionary | A dictionary containing all prefixes.
+|===
+
+== Enumerators
+
+=== HANDLE_VOCAB_URI_STRATEGY
+
+Enum class defining different strategies for handling vocabulary URIs.
+
+==== Possible Values
+
+|===
+| Name | Description
+| SHORTEN | Strategy to shorten the URIs (Every prefix that you will use must be defined in the config, otherwise Neo4jStore will throw a ShortenStrictException)
+| MAP | Strategy to map the URIs using provided mappings
+| KEEP | Strategy to keep the URIs
+| IGNORE | Strategy to ignore the Namespace and get only the local part
+|===
+
+=== Examples
+
+Here a series of examples of the application of a strategy on a certain triplet.
+
+#TODO: Fill the examples#
+
+=== Shorten
+
+This strategy will shorten the URIs, replacing the prefix with its shorted version. If the Store find a prefix not defined inside its Neo4jStoreConfig object, the parsing will stop, raising a ShortenStrictException error.
+
+=== Map
+vocabulary element mappings are applied on import.
+
+=== Keep
+
+This strategy will keep the predicate as it is by preserving its prefix
+
+=== Ignore
+
+This strategy will remove the entire prefix from the predicate.
+
+=== HANDLE_MULTIVAL_STRATEGY
+
+Enum class defining different strategies for handling multiple values.
+
+TO NOTICE: If the strategy is ARRAY and the Neo4jStoreConfig doesn't contain any predicate marked as multivalued, EVERY field will be treated as multivalued.
+
+==== Possible Values
+
+|===
+| Name | Description
+| OVERWRITE | Strategy to overwrite multiple values
+| ARRAY | Strategy to treat multiple values as an array
+|===
+
+=== Examples
+
+Here a series of examples of the application of a strategy on a certain triplet.
+
+=== Overwrite
+
+This strategy will overwrite the current value of a node.
+
+=== Map
+
+This strategy will concat all the values encountered during the ingestion for the same subject inside an array.

docs/getting_started.adoc

@@ -0,0 +1,3 @@
+== Using the Neo4j store and examples
+
+== Migrating an existing implementation to the Neo4j Store

docs/introduction.adoc

@@ -0,0 +1,16 @@
+= RDFLIB + Neo4j User Guide
+:doctype: book
+:icons: font
+:source-highlighter: coderay
+:toc: left
+:toclevels: 2
+
+toc::[]
+
+= Chapter 1: Introduction
+
+== Section 1.1: Purpose
+This section provides an overview of the purpose of this documentation.
+
+
+