Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Update documentation

  • Loading branch information...
commit 46b20cf7b38882fa8dc18c2c74d6766765db9f4a 1 parent 3648234
@versae authored
View
41 README.rst
@@ -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
41 README.txt
@@ -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 docs/conf.py
@@ -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
150 docs/filters.rst
@@ -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
4 docs/index.rst
@@ -10,11 +10,13 @@ Contents:
.. toctree::
:maxdepth: 2
-
+
info
elements
traversals
indices
+ queries
+ filters
extensions
transactions
changes
View
13 docs/indices.rst
@@ -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
View
38 docs/info.rst
@@ -4,10 +4,10 @@ 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
@@ -29,44 +29,56 @@ Or even if you want to use the development branch::
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/")
For providing authentication like is needed in services like Heroku_, you
-should add the proper parameters::
+should add the proper parameters:
>>> url = "http://<instance>.hosted.neo4j.org:7000/db/data/"
>>> gdb = GraphDatabase(url, username="username", password="password")
+Or even using certificates:
+
+ >>> gdb = GraphDatabase(url, username="username", password="password",
+ ...: cert_file='path/to/file.cert', key_file='path/to/file.key')
+
+Due to a limitation of `httplib2`, both files must be in PEM_ format.
+
Options
-------
There some global options available::
-If CACHE is 'True', a '.cache' directory is created and the future request to
+If CACHE is `True`, a `.cache` directory is created and the future request to
the same URL will be taken from cache::
neo4jrestclient.options.CACHE = False # Default
You can also use your own custom cache, (e.g LocMemCache from django)::
- neo4jrestclient.options.CACHE_STORE = LocMemCache()
+ neo4jrestclient.options.CACHE_STORE = LocMemCache()
-If DEBUG is 'True', 'httplib2' is set to debuglevel = 1::
+If DEBUG is `True`, `httplib2` is set to debuglevel = 1::
neo4jrestclient.options.DEBUG = False # Default
-And SMART_ERRORS, set to 'False' by default. In case of 'True', the standard
-HTTP errors will be replaced by more pythonic errors (i.e. 'KeyError' instead
-of 'NotFoundError' in some cases)::
+And `SMART_ERRORS`, set to 'False' by default. In case of `True`, the standard
+HTTP errors will be replaced by more pythonic errors (i.e. `KeyError` instead
+of `NotFoundError` in some cases)::
neo4jrestclient.options.SMART_ERRORS = False # Default
-.. _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
+.. _`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
.. _Heroku: http://devcenter.heroku.com/articles/neo4j
+.. _PEM: http://en.wikipedia.org/wiki/X.509#Certificate_filename_extensions
View
38 docs/queries.rst
@@ -0,0 +1,38 @@
+Queries
+=======
+
+Since the Cypher plugin is not a plugin anymore, neo4j-rest-client_ is able to
+run queries and returns the results properly formatted:
+
+ >>> q = """start n=node(*) return n"""
+
+ >>> result = gdb.query(q=q)
+
+This way to run a query will return the results as RAW, i.e., in the same way
+the REST interface get them. However, you can always use a `returns` parameter
+in order to perform custom castings:
+
+ >>> q = """start n=node(*) match n-[r]-() return n, n.name, r"""
+
+ >>> results = gdb.query(q, returns=(client.Node, unicode, client.Relationship))
+
+ >>> results[0]
+ [<Neo4j Node: http://localhost:7474/db/data/node/14>,
+ u'John Doe',
+ <Neo4j Relationship: http://localhost:7474/db/data/relationship/47>]
+
+Or pass a custom function:
+
+ >>> is_john_doe = lambda x: x == "John Doe"
+
+ >>> results = gdb.query(q, returns=(client.Node, is_john_doe, client.Relationship))
+ >>> results[0]
+ [<Neo4j Node: http://localhost:7474/db/data/node/14>,
+ True,
+ <Neo4j Relationship: http://localhost:7474/db/data/relationship/47>]
+
+If the lenght of the elements is greater than the casting functions pass through
+the `returns` parameter, the `RAW` will be used instead of raising an exception.
+
+
+.. _neo4j-rest-client: http://pypi.python.org/pypi/neo4jrestclient/
Please sign in to comment.
Something went wrong with that request. Please try again.