Permalink
Browse files

Update documentation

  • Loading branch information...
1 parent 3648234 commit 46b20cf7b38882fa8dc18c2c74d6766765db9f4a @versae committed Dec 9, 2012
Showing with 269 additions and 60 deletions.
  1. +22 −19 README.rst
  2. +22 −19 README.txt
  3. +2 −2 docs/conf.py
  4. +150 −0 docs/filters.rst
  5. +3 −1 docs/index.rst
  6. +7 −6 docs/indices.rst
  7. +25 −13 docs/info.rst
  8. +38 −0 docs/queries.rst
View
@@ -4,14 +4,14 @@ Neo4j Python REST Client
:synopsis: Object-oriented Python library to interact with Neo4j standalone REST server.
The first objective of Neo4j Python REST Client is to make transparent for
-Python programmers the use of a local database through neo4j.py_ or a remote
-database thanks to Neo4j REST Server. So, the syntax of this API is fully
-compatible with neo4j.py. However, a new syntax is introduced in order to
-reach a more pythonic style.
+Python programmers the use of a local database through python-embedded_ or a
+remote database thanks to Neo4j REST Server. So, the syntax of this API is
+fully compatible with python-embedded. However, a new syntax is introduced in
+order to reach a more pythonic style.
-Installation
-------------
+Installation_
+-------------
Available throught Python Package Index::
@@ -22,22 +22,22 @@ Or::
$ easy_install neo4jrestclient
-Getting started
----------------
+`Getting started`_
+------------------
-The main class is *GraphDatabase*, exactly how in neo4j.py_::
+The main class is *GraphDatabase*, exactly how in python-embedded_::
>>> from neo4jrestclient.client import GraphDatabase
-
+
>>> gdb = GraphDatabase("http://localhost:7474/db/data/")
-Due to the syntax is fully compatible with neo4j.py_, the next lines only show
+Due to the syntax is fully compatible with python-embedded_, the next lines only show
the commands added and its differences.
Creating a node::
>>> n = gdb.nodes.create()
-
+
# Equivalent to
>>> n = gdb.node()
@@ -48,7 +48,7 @@ Specify properties for new node::
Accessing properties::
>>> value = n['key'] # Get property value
-
+
>>> n['key'] = value # Set property value
Create relationship::
@@ -61,14 +61,17 @@ Specify properties for new relationships::
>>> n1.Knows(n2, since=123456789, introduced_at="Christmas party")
-Documentation
--------------
+Documentation_
+--------------
-For an extended and lates version of the documentation, please, visit the
-docs_ site:: http://readthedocs.org/docs/neo4j-rest-client/en/latest/
+For the extended and latest version of the documentation, please, visit the
+`read the docs`_ site
-.. _neo4j.py: http://components.neo4j.org/neo4j.py/
+.. _python-embedded: http://docs.neo4j.org/chunked/snapshot/python-embedded.html
.. _lucene-querybuilder: http://github.com/scholrly/lucene-querybuilder
-.. _docs: http://readthedocs.org/docs/neo4j-rest-client/en/latest/
+.. _`read the docs`: http://readthedocs.org/docs/neo4j-rest-client/en/latest/
+.. _Documentation: http://readthedocs.org/docs/neo4j-rest-client/en/latest/
+.. _Installation: https://neo4j-rest-client.readthedocs.org/en/latest/info.html#installation
+.. _`Getting started`: https://neo4j-rest-client.readthedocs.org/en/latest/info.html#getting-started
View
@@ -4,14 +4,14 @@ Neo4j Python REST Client
:synopsis: Object-oriented Python library to interact with Neo4j standalone REST server.
The first objective of Neo4j Python REST Client is to make transparent for
-Python programmers the use of a local database through neo4j.py_ or a remote
-database thanks to Neo4j REST Server. So, the syntax of this API is fully
-compatible with neo4j.py. However, a new syntax is introduced in order to
-reach a more pythonic style.
+Python programmers the use of a local database through python-embedded_ or a
+remote database thanks to Neo4j REST Server. So, the syntax of this API is
+fully compatible with python-embedded. However, a new syntax is introduced in
+order to reach a more pythonic style.
-Installation
-------------
+Installation_
+-------------
Available throught Python Package Index::
@@ -22,22 +22,22 @@ Or::
$ easy_install neo4jrestclient
-Getting started
----------------
+`Getting started`_
+------------------
-The main class is *GraphDatabase*, exactly how in neo4j.py_::
+The main class is *GraphDatabase*, exactly how in python-embedded_::
>>> from neo4jrestclient.client import GraphDatabase
-
+
>>> gdb = GraphDatabase("http://localhost:7474/db/data/")
-Due to the syntax is fully compatible with neo4j.py_, the next lines only show
+Due to the syntax is fully compatible with python-embedded_, the next lines only show
the commands added and its differences.
Creating a node::
>>> n = gdb.nodes.create()
-
+
# Equivalent to
>>> n = gdb.node()
@@ -48,7 +48,7 @@ Specify properties for new node::
Accessing properties::
>>> value = n['key'] # Get property value
-
+
>>> n['key'] = value # Set property value
Create relationship::
@@ -61,14 +61,17 @@ Specify properties for new relationships::
>>> n1.Knows(n2, since=123456789, introduced_at="Christmas party")
-Documentation
--------------
+Documentation_
+--------------
-For an extended and lates version of the documentation, please, visit the
-docs_ site:: http://readthedocs.org/docs/neo4j-rest-client/en/latest/
+For the extended and latest version of the documentation, please, visit the
+`read the docs`_ site
-.. _neo4j.py: http://components.neo4j.org/neo4j.py/
+.. _python-embedded: http://docs.neo4j.org/chunked/snapshot/python-embedded.html
.. _lucene-querybuilder: http://github.com/scholrly/lucene-querybuilder
-.. _docs: http://readthedocs.org/docs/neo4j-rest-client/en/latest/
+.. _`read the docs`: http://readthedocs.org/docs/neo4j-rest-client/en/latest/
+.. _Documentation: http://readthedocs.org/docs/neo4j-rest-client/en/latest/
+.. _Installation: https://neo4j-rest-client.readthedocs.org/en/latest/info.html#installation
+.. _`Getting started`: https://neo4j-rest-client.readthedocs.org/en/latest/info.html#getting-started
View
@@ -48,9 +48,9 @@
# built documents.
#
# The short X.Y version.
-version = '1.6.0'
+version = '1.8.0'
# The full version, including alpha/beta/rc tags.
-release = '1.6.0'
+release = '1.8.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
View
@@ -0,0 +1,150 @@
+Filters
+=======
+
+On top of Queries feature, there are some filtering helpers for nodes,
+relationships and both indices. First thing you need is to define `Q` objects:
+
+ >>> from neo4jrestclient.query import Q
+
+ >>> Q("name", istartswith="william")
+
+Once a lookup is defined, you may call the `filter` method over all
+the nodes or the relationships:
+
+ >>> gdb.nodes.filter(lookup)
+ [<Neo4j Node: http://localhost:7474/db/data/node/14>]
+
+Or just a list of elements identifiers, `Node`'s or `Relationship`'s:
+
+ >>> nodes = []
+
+ >>> for i in range(2):
+ ...: nodes.append(gdb.nodes.create(name="William %s" % i))
+
+ >>> lookup = Q("name", istartswith="william")
+
+ >>> williams = gdb.nodes.filter(lookup, start=nodes)
+
+
+Lookups
+-------
+
+The syntax for lookups is very similar to the one used in Django_, but does
+include other options:
+
+ Q(property_name, lookup=match)
+
+The next list shows all the current lookups supported:
+
+* `exact`, performs exact string comparation.
+* `iexact`, performs exact string comparation, case insesitive.
+* `contains`, checks if the property is contained in the string passed.
+* `icontains`, as `contains` but case insesitive.
+* `startswith`, checks if the property starts with the string passed.
+* `istartswith`, as `startswith` but case insesitive.
+* `endswith`, checks if the property ends with the string passed.
+* `iendswith`, as `endswith` but case insesitive.
+* `regex`, performs regular expression matching agains the string passed.
+* `iregex`, as `regex` but case insesitive.
+* `gt`, check if the property is greater than the value passed.
+* `gte`, check if the property is greater than or equal to the value passed.
+* `lt`, check if the property is lower than the value passed.
+* `lte`, check if the property is lower than or equal to the value passed.
+* `in`, , check if the property is in a list of elements passed.
+* `inrange`,`an alias for `in`.
+* `isnull`, checks if the property is null, passing `True`, or not, passing `False`.
+* `eq`, performs equal comparations.
+* `equals`, an alias `eq`.
+* `neq`, performs not equal comparations.
+* `notequals`, an alias `neq`.
+
+Also, in order to be compliant with Cypher syntax, you can add a `nullable`
+parameter to set if the lookup must be don using `!` or `?`. By default, all
+lookups are nullable.
+
+ >>> lookup = Q("name", istartswith="william", nullable=True)
+
+ >>> lookup
+ n.`name`! =~ (?i)william.*
+
+ >>> lookup = Q("name", istartswith="william", nullable=False)
+
+ >>> lookup
+ n.`name`? =~ (?i)william.*
+
+ >>> lookup = Q("name", istartswith="william", nullable=None)
+
+ >>> lookup
+ n.`name` =~ (?i)william.*
+
+
+There is support for complex lookups as well:
+
+ >>> lookups = (Q("name", exact="James")
+ ...: & (Q("surname", startswith="Smith") & ~Q("surname", endswith="e")))
+ ( n.`name`! = James AND ( n.`surname`! =~ Smith.* AND NOT ( n.`surname`! =~ .*1 ) ) )
+
+
+
+Ordering
+--------
+
+There is an feature to set the order by which the elements will be returned,
+using the Cypher option `order by`. The syntax is a tuple: the first element is
+the property name to order by, the second one the type of ordering, `constants.ASC`
+for ascending, and `constants.DESC` for descending. A set of orderings can be used:
+
+ >>> gdb.nodes.filter(lookup).order_by("code", constants.DESC)
+
+
+Indices
+-------
+
+Indices also implement the `filter` method, so you can use an index as a start,
+or just invoke the method to filter the elements:
+
+ >>> old_loves = gdb.relationships.filter(lookup, start=index)
+
+ >>> old_loves = gdb.relationships.filter(lookup, start=index["since"])
+
+So, the next would be the same:
+
+ >>> old_loves = index.filter(lookup)
+
+ >>> old_loves = index.filter(lookup, key="since")
+
+ >>> old_loves = index["since"].filter(lookup)
+
+However, it is not possible yet to pass a value for the index using the common
+dictionary syntax. Instead, you may use the `value` parameter:
+
+ >>> old_loves = index.filter(lookup, key="since", value=1990)
+
+
+Slicing
+-------
+
+In addition, all filters implement lazy slicing, so the query is not run until
+the results are going to be retrieved. However, there is not still support for
+transactions:
+
+ >>> lookup = Q("name", istartswith="william")
+
+ >>> results = gdb.nodes.filter(lookup) # Not query executed yet
+
+ >>> len(restuls) # Here the query is executed
+ 12
+
+If the elements of the filter have been already retrieved from the server, the
+slicing is then run against the local version. If not, the `slice` is transformed
+into `limit` and `skip` options before doing the request.
+
+ >>> results = gdb.nodes.filter(lookup) # Not query executed yet
+
+ >>> restuls[1:2] # The Cypher query is limited using limit and skip
+ [<Neo4j Node: http://localhost:7474/db/data/node/14>]
+
+ >>> len(results) # The Cypher query is sent again to the server
+ 12
+
+.. _Django: https://docs.djangoproject.com/en/dev/topics/db/queries/#complex-lookups-with-q-objects
View
@@ -10,11 +10,13 @@ Contents:
.. toctree::
:maxdepth: 2
-
+
info
elements
traversals
indices
+ queries
+ filters
extensions
transactions
changes
View
@@ -1,9 +1,9 @@
Indices
=======
-Due to the original neo4j.py_ currently doesn't provide support for the new
-index component, for nodes and for relationships, the syntax for indexing is
-not compliant, quite different and, hopefully, more intuitive::
+The original neo4j.py_ currently did not provide support for the new
+index component. However, the current syntax for indexing is now compliant
+with the python-embedded_ API, and hopefully more intuitive::
>>> i1 = gdb.nodes.indexes.create("index1")
@@ -37,7 +37,7 @@ using the convenience methods::
<Neo4j Node: http://localhost:7474/db/data/node/2>]
Advanced queries are also supported if the index is created with the type
-'fulltext' ('lucene' is the default provider) by entering a Lucene query::
+`fulltext` (`lucene` is the default provider) by entering a Lucene query::
>>> n1 = gdb.nodes.create(name="John Doe", place="Texas")
@@ -46,11 +46,11 @@ Advanced queries are also supported if the index is created with the type
>>> i1 = gdb.nodes.indexes.create(name="do", type="fulltext")
>>> i1["surnames"]["doe"] = n1
-
+
>>> i1["places"]["Texas"] = n1
>>> i1["surnames"]["donald"] = n2
-
+
>>> i1["places"]["Tijuana"] = n2
>>> i1.query("surnames", "do*")[:]
@@ -81,3 +81,4 @@ For deleting an index just call 'delete' with no arguments::
.. _neo4j.py: http://components.neo4j.org/neo4j.py/
.. _lucene-querybuilder: http://github.com/scholrly/lucene-querybuilder
+.. _python-embedded: http://docs.neo4j.org/chunked/snapshot/python-embedded.html
Oops, something went wrong.

0 comments on commit 46b20cf

Please sign in to comment.