Skip to content

Commit 487206f

Browse files
technigetechnige
committed
More docs updates
1 parent 3cbece8 commit 487206f

File tree

8 files changed

+90
-55
lines changed

8 files changed

+90
-55
lines changed

‎docs/source/_images/core_type_mappings.png‎

60.3 KB
Loading

‎docs/source/_images/core_type_mappings.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/source/conf.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
'sphinx.ext.coverage',
3939
'sphinx.ext.ifconfig',
4040
'sphinx.ext.viewcode',
41+
'sphinx.ext.intersphinx',
4142
]
4243

4344
# Add any paths that contain templates here, relative to this directory.
@@ -296,3 +297,11 @@
296297

297298
def setup(app):
298299
app.add_stylesheet('custom.css')
300+
301+
302+
# -- Options for Intersphinx
303+
304+
intersphinx_mapping = {
305+
'python': ('https://docs.python.org/3', None),
306+
'neotime': ('http://neotime.readthedocs.io/en/latest/', None),
307+
}

‎docs/source/types/core.rst‎

Lines changed: 36 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,42 @@
22
Core Data Types
33
===============
44

5-
The core types supported by Cypher all map to core types in Python.
6-
Booleans, Integers, Floats and Strings can all be stored as single value or array properties.
7-
Byte Arrays can also be stored but do not have a single value equivalent.
8-
9-
============= ======== ============== =========================== =============
10-
Cypher Type Property Array Property Python 2 Type Python 3 Type
11-
============= ======== ============== =========================== =============
12-
Null *no* *no* :const:`None` :const:`None`
13-
Boolean *yes* *yes* ``bool`` ``bool``
14-
Integer *yes* *yes* ``int``/``long`` :sup:`[1]` ``int``
15-
Float *yes* *yes* ``float`` ``float``
16-
String *yes* *yes* ``unicode`` :sup:`[2]` ``str``
17-
Byte Array *no* *yes* ``bytearray`` ``bytearray``
18-
List *no* *no* ``list`` ``list``
19-
Map *no* *no* ``dict`` ``dict``
20-
============= ======== ============== =========================== =============
5+
.. note::
6+
The Python types mentioned here are based on Python 3.
7+
Differences for Python 2 are highlighted in the `footnotes <#footnotes-for-python-2-users>`_.
8+
9+
Cypher supports a set of core data types that all map to built-in types in Python.
10+
These include the common `Boolean`, `Integer`, `Float` and `String` types as well as `List` and `Map` that can hold heterogenous collections of any other type.
11+
The core types with their general mappings are listed below:
12+
13+
================ =============
14+
Cypher Type Python Type
15+
================ =============
16+
Null :const:`None`
17+
Boolean ``bool``
18+
Integer ``int``
19+
Float ``float``
20+
String ``str``
21+
Bytes :sup:`[1]` ``bytearray``
22+
List ``list``
23+
Map ``dict``
24+
================ =============
2125

2226
.. admonition:: Notes
2327

24-
1. While Cypher uses 64-bit signed integers, `int` can only hold integers up to `sys.maxint` in Python 2; `long` is used for values above this.
25-
2. In Python 2, a ``str`` passed as a parameter will always be implicitly converted to ``unicode`` via UTF-8.
28+
1. `Bytes` is not an actual Cypher type but is transparently passed through when used in parameters or query results.
29+
30+
31+
In reality, the actual conversions and coercions that occur as values are passed through the system are more complex than just a simple mapping.
32+
The diagram below illustrates the actual mappings between the various layers, from driver to data store, for the core types.
33+
34+
.. image:: ../_images/core_type_mappings.svg
35+
:target: ../_images/core_type_mappings.svg
36+
37+
38+
Footnotes for Python 2 users
39+
============================
40+
41+
1. While Cypher uses 64-bit signed integers, ``int`` can only hold integers up to ``sys.maxint`` in Python 2; ``long`` is used for values above this.
42+
2. Python 2 uses ``unicode`` instead of ``str`` for Unicode text.
43+
However, a Python 2 ``str`` passed as a parameter will always be implicitly converted to ``unicode`` via UTF-8.

‎docs/source/types/graph.rst‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,22 @@
22
Graph Data Types
33
================
44

5-
The graph types model graph data returned from a Cypher query.
5+
Cypher queries can return entire graph structures as well as individual property values.
6+
7+
, The graph types model graph data returned from a Cypher query.
68
Graph values cannot be passed in as parameters as it would be unclear whether the entity was intended to be passed by reference or by value.
79
The identity or properties of that entity should be passed explicitly instead.
810

911
All graph values returned within a given :class:`.StatementResult` are contained within a :class:`.Graph` instance, accessible via :meth:`.StatementResult.graph`.
1012
The driver contains a corresponding class for each of the graph types that can be returned.
1113

12-
============= ======== ============== ======================
13-
Cypher Type Property Array Property Python Type
14-
============= ======== ============== ======================
15-
Node *no* *no* :class:`.Node`
16-
Relationship *no* *no* :class:`.Relationship`
17-
Path *no* *no* :class:`.Path`
18-
============= ======== ============== ======================
14+
============= ======================
15+
Cypher Type Python Type
16+
============= ======================
17+
Node :class:`.Node`
18+
Relationship :class:`.Relationship`
19+
Path :class:`.Path`
20+
============= ======================
1921

2022
.. autoclass:: neo4j.v1.types.graph.Graph
2123
:members:

‎docs/source/types/spatial.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22
Spatial Data Types
33
==================
44

5-
============= ======== ============== ======================
6-
Cypher Type Property Array Property Python Type
7-
============= ======== ============== ======================
8-
Point *yes* *yes* :class:`.Point`
9-
============= ======== ============== ======================
5+
============= ======================
6+
Cypher Type Python Type
7+
============= ======================
8+
Point :class:`.Point`
9+
============= ======================
1010

1111
.. autoclass:: neo4j.v1.types.spatial.Point
1212
:members:

‎docs/source/types/temporal.rst‎

Lines changed: 19 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,23 @@
1+
.. py:currentmodule:: neotime
2+
13
===================
24
Temporal Data Types
35
===================
46

5-
.. py:currentmodule:: neotime
6-
7-
============= ======== ============== ======================================
8-
Cypher Property Array Property Python
9-
============= ======== ============== ======================================
10-
Date *yes* *yes* ``neotime.Date``
11-
Time *yes* *yes* ``neotime.Time`` (tzinfo != None)
12-
LocalTime *yes* *yes* ``neotime.Time`` (tzinfo == None)
13-
DateTime *yes* *yes* ``neotime.DateTime`` (tzinfo != None)
14-
LocalDateTime *yes* *yes* ``neotime.DateTime`` (tzinfo == None)
15-
Duration *yes* *yes* ``neotime.Duration`` :sup:`[1]`
16-
============= ======== ============== ======================================
17-
18-
.. admonition:: Notes
19-
20-
1. A ``datetime.timespan`` value passed as a parameter will always be implicitly converted to a :class:`.Duration` value.
21-
22-
.. class:: Duration
23-
24-
.. class:: Date
25-
26-
.. class:: Time
27-
28-
.. class:: DateTime
7+
Temporal data types are implemented by the `neotime <http://neotime.readthedocs.io/en/latest/>`_ package.
8+
These provide a set of types compliant with ISO-8601 and Cypher, which are similar to those found in the built-in ``datetime`` module.
9+
Sub-second values are measured to nanosecond precision and the types are compatible with `pytz <http://pytz.sourceforge.net/>`_.
10+
11+
The table below shows the general mappings between Cypher and the temporal types provided by the driver.
12+
In addition, the built-in temporal types can be passed as parameters and will be mapped appropriately.
13+
14+
============= ========================= ================================== ============
15+
Cypher Python driver type Python built-in type ``tzinfo``
16+
============= ========================= ================================== ============
17+
Date :class:`neotime:Date` :class:`python:datetime.date`
18+
Time :class:`neotime:Time` :class:`python:datetime.time` ``not None``
19+
LocalTime :class:`neotime:Time` :class:`python:datetime.time` ``None``
20+
DateTime :class:`neotime:DateTime` :class:`python:datetime.datetime` ``not None``
21+
LocalDateTime :class:`neotime:DateTime` :class:`python:datetime.datetime` ``None``
22+
Duration :class:`neotime:Duration` :class:`python:datetime.timedelta`
23+
============= ========================= ================================== ============

‎make_docs.sh‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/usr/bin/env bash
2+
3+
HOME=$(dirname $0)
4+
5+
pip install --upgrade sphinx
6+
make -C ${HOME}/docs html
7+
8+
echo ""
9+
INDEX_FILE="${HOME}/docs/build/html/index.html"
10+
echo "Documentation index file can be found at file://$(cd "$(dirname "${INDEX_FILE}")"; pwd)/$(basename "${INDEX_FILE}")"

0 commit comments

Comments
 (0)