text & links

python-manual/modules/ROOT/pages/migration.adoc

@@ -1,16 +1,46 @@
 = Upgrade & Migration
 
-Steps:
-
-- Run the migration assistent tool with its default config, address the issues.
-- Re-run the assistent with the regex parser, check if any more legit issues are raised.
-- Audit your codebase for the changes and deprecations not surfaces by the tool, indicated by {cross-mark} in the table below.
-- At this point you are ready to upgrade the driver package to the new version, knowing that it will also be backwards compatible with the previous LTS (i.e. if you upgrade from 4.4 to 5, you can upgrade the driver before you upgrade the server).
-- Review your queries for cypher changes in the new server target version.
-
-https://github.com/stefano-ottolenghi/neo4j-drivers-migration-assistent
-
-https://github.com/neo4j/neo4j-python-driver/wiki/5.x-changelog
+This page contains the list of new features and breaking changes that happened in the driver from version 4.4 to 5.LTS.
+For a full list of changes, see the link:https://github.com/neo4j/neo4j-python-driver/wiki/5.x-changelog[Driver -> Changelog].
+
+The link:https://github.com/stefano-ottolenghi/neo4j-drivers-migration-assistent[Neo4j Drivers Migration Assistent] simplifies the upgrade process, by contextualizing the changelog to your codebase.
+It scans your codebase for usage of deprecations and removals, and brings them up to you.
+The tool doesn't automatically rewrite your code; it only points at where action is needed, providing in-context information on how each hit should be addressed.
+
+Any of the 5.x versions of the driver is compatible both with Neo4j server 4.4 and 5.x, so you can upgrade the driver before you upgrade the server.
+
+[TIP]
+When upgrading the Neo4j server to a newer version, the Cypher queries in your application may also need updating. +
+See link:https://neo4j.com/docs/cypher-manual/current/deprecations-additions-removals-compatibility/[Cypher -> Deprecations, additions, and compatibility].
+
+
+== Recommended steps
+
+Using the migration assistent, the recommended upgrade steps are:
+
+1. Run the migration assistent with its default configuration and address all the issues that it surfaces. The `path` argument supports globbing and can be repeated as many times as needed. +
++
+[source, bash]
+----
+python main.py -l python <path...>
+----
++
+2. Re-run the assistent with the regex parser and check if any more legit issues are raised. +
++
+[source, bash]
+----
+python main.py -l python --regex-parser <path...>
+----
++
+The regex parser is able to parse implicit function calls and other hard-to-parse expressions, but is likely surface more false positive (for more information, see link:https://github.com/stefano-ottolenghi/neo4j-drivers-migration-assistent?tab=readme-ov-file#accuracy[Neo4j Drivers Migration Assistent -> Accuracy]).
+You can add any spurious entry to the ignored list, so that the assistent won't bring them up in future runs.
+3. Although the assistent can detect most of the locations where action is needed, a few changelog entries can't be surfaced in this form, so you should still revise the xref:breaking-changes[breaking changes] section and audit your codebase for the changes marked with {cross-mark}.
+4. You are ready to upgrade the driver package to the new version. +
++
+[source, bash]
+----
+pip install -U neo4j
+----
 
 
 == New features
@@ -28,7 +58,7 @@ The driver is compatible with any Python version starting from 3.6 up to 3.12.
 .`asyncio` support
 [%collapsible]
 ====
-For using the driver's features in parallel.
+For using the driver's features in parallel via the link:https://docs.python.org/3/library/asyncio.html[asyncio] package.
 
 See xref:concurrency.adoc[].
 ====
@@ -54,15 +84,15 @@ Usage-wise, the drivers are identical.
 .Export to Pandas Dataframe
 [%collapsible]
 ====
-`Result.to_df()` allows to export a `Result` object into a Pandas DataFrame.
+`Result.to_df()` allows for exporting a `Result` object into a Pandas DataFrame.
 
 See xref:transformers.adoc#_transform_to_pandas_dataframe[Manipulate query results -> Transform to Pandas Dataframe].
 ====
 |
 .Type hints for all public APIs
 [%collapsible]
 ====
-For (optional) use with type checkers and linters.
+All public objects have type annotations via the link:https://docs.python.org/3/library/typing.html[typing] package. For (optional) use with type checkers and linters.
 ====
 
 |
@@ -128,13 +158,14 @@ Use the driver configuration `telemetry_disabled=True` to opt out.
 [%collapsible]
 ====
 For local development, run your application with `python -X dev ...` or set the environment variable `PYTHONNEO4JDEBUG` to anything non-empty to get additional concurrency misuse checks.
-Some driver primitives (e.g. sessions) are not safe to be used concurrently, and using them concurrently will lead to hard-to-debug errors.
-This feature helps identifying such code paths. Note that detection is still inherently racy, hence not guaranteed to always work.
+Some driver primitives (e.g. sessions) are not safe to be used concurrently, and using them so will lead to hard-to-debug errors.
+This feature helps identifying such code paths (detection is still inherently racy, hence not guaranteed to always work).
 ====
 
 |===
 
 
+[[breaking-changes]]
 == Breaking changes and deprecations
 
 The column `Assistent` denotes whether the Neo4j Drivers Migration Assistent can detect issues related to the given changelog entry.
@@ -152,7 +183,7 @@ Deprecated features get removed in the next LTS version.
 |{cross-mark}
 
 |5.0
-|Driver options `update_routing_table_timeout` and `session_connection_timeout` have been removed. Regular keep-alives are sufficient to avoid the driver getting stuck. Further liveness check config options are available but normally not needed (`keep_alive`, `liveness_check_timeout`).
+|Driver options `update_routing_table_timeout` and `session_connection_timeout` have been removed. Regular keep-alives are sufficient to avoid the driver getting stuck. Further liveness check config options are available but normally not needed (link:https://neo4j.com/docs/api/python-driver/current/api.html#keep-alive-ref[`keep_alive`], link:https://neo4j.com/docs/api/python-driver/current/api.html#liveness-check-timeout[`liveness_check_timeout`]).
 |label:removed[]
 |{check-mark}
 
@@ -162,33 +193,33 @@ Deprecated features get removed in the next LTS version.
 |{check-mark}
 
 |5.0
-|Removed `ResultSummary.server.version_info`.
+|In link:https://neo4j.com/docs/api/python-driver/current/api.html#neo4j.ServerInfo[`neo4j.ServerInfo`], removed `ResultSummary.server.version_info`.
 Use `ResultSummary.server.agent`, `ResultSummary.server.protocol_version`, or call the `dbms.components` Cypher procedure instead.
 |label:removed[]
 |{cross-mark}
 
 |5.0
-|`Duration` -- The constructor does not accept `subseconds` anymore. Use `milliseconds`, `microseconds`, or `nanoseconds` instead.
+|link:https://neo4j.com/docs/api/python-driver/current/types/temporal.html#neo4j.time.Duration[`Duration`] -- The constructor does not accept `subseconds` anymore. Use `milliseconds`, `microseconds`, or `nanoseconds` instead.
 |label:removed[]
 |{check-mark}
 
 |5.0
-|`Duration` -- The property `subseconds` has been removed. Use `nanoseconds` instead.
+|link:https://neo4j.com/docs/api/python-driver/current/types/temporal.html#neo4j.time.Duration[`Duration`] -- The property `subseconds` has been removed. Use `nanoseconds` instead.
 |label:removed[]
 |{check-mark}
 
 |5.0
-|`Duration` -- The property `hours_minutes_seconds` has been removed. Use `hours_minutes_seconds_nanoseconds` instead.
+|link:https://neo4j.com/docs/api/python-driver/current/types/temporal.html#neo4j.time.Duration[`Duration`] -- The property `hours_minutes_seconds` has been removed. Use `hours_minutes_seconds_nanoseconds` instead.
 |label:removed[]
 |{check-mark}
 
 |5.0
-|`DateTime` -- The property `hour_minute_second` has been removed. Use `hour_minute_second_nanosecond` instead.
+|link:https://neo4j.com/docs/api/python-driver/current/types/temporal.html#neo4j.time.DateTime[`DateTime`] -- The property `hour_minute_second` has been removed. Use `hour_minute_second_nanosecond` instead.
 |label:removed[]
 |{check-mark}
 
 |5.0
-|`DateTime` -- The property `second` returns an int instead of a float. Use `nanosecond` to get the sub-second information.
+|link:https://neo4j.com/docs/api/python-driver/current/types/temporal.html#neo4j.time.DateTime[`DateTime`] -- The property `second` returns an int instead of a float. Use `nanosecond` to get the sub-second information.
 |label:removed[Changed]
 |{cross-mark}
 
@@ -201,32 +232,32 @@ Multiplication and division allow for floats but will always result in integer v
 |{cross-mark}
 
 |5.0
-|`Time` -- The constructor does not accept floats for `second` anymore. Use `nanosecond` instead.
+|link:https://neo4j.com/docs/api/python-driver/current/types/temporal.html#neo4j.time.Time[`Time`] -- The constructor does not accept floats for `second` anymore. Use `nanosecond` instead.
 |label:removed[]
 |{check-mark}
 
 |5.0
-|`Time` -- The `ticks` property's type changed from float to int. It's now nanoseconds since midnight instead of seconds.
+|link:https://neo4j.com/docs/api/python-driver/current/types/temporal.html#neo4j.time.Time[`Time`] -- The `ticks` property's type changed from float to int. It's now nanoseconds since midnight instead of seconds.
 |label:removed[Changed]
 |{cross-mark}
 
 |5.0
-|`Time` -- The property `ticks_ns` has been renamed to `ticks`.
+|link:https://neo4j.com/docs/api/python-driver/current/types/temporal.html#neo4j.time.Time[`Time`] -- The property `ticks_ns` has been renamed to `ticks`.
 |label:removed[]
 |{check-mark}
 
 |5.0
-|`Time` -- The property `second` returns an int instead of a float. Use `nanosecond` to get the sub-second information.
+|link:https://neo4j.com/docs/api/python-driver/current/types/temporal.html#neo4j.time.Time[`Time`] -- The property `second` returns an int instead of a float. Use `nanosecond` to get the sub-second information.
 |label:removed[Changed]
 |{cross-mark}
 
 |5.0
-|`Time` -- The property `hour_minute_second` has been removed. Use `hour_minute_second_nanosecond` instead.
+|link:https://neo4j.com/docs/api/python-driver/current/types/temporal.html#neo4j.time.Time[`Time`] -- The property `hour_minute_second` has been removed. Use `hour_minute_second_nanosecond` instead.
 |label:removed[]
 |{check-mark}
 
 |5.0
-|Session methods `.read_transaction()` and `.write_transaction()` are deprecated in favor of `.execute_read()` and `.execute_write()`.
+|Session methods `.read_transaction()` and `.write_transaction()` are deprecated in favor of link:https://neo4j.com/docs/api/python-driver/current/api.html#neo4j.Session.execute_read[`.execute_read()`] and link:https://neo4j.com/docs/api/python-driver/current/api.html#neo4j.Session.execute_write[`.execute_write()`].
 Through the new methods, the first argument of transaction functions is a `ManagedTransaction` object. It behaves exactly like a regular `Transaction` object, except it does not offer the `.commit()`, `.rollback()`, `.close()`, and `.closed()` methods.
 |label:deprecated[]
 |{check-mark}
@@ -237,8 +268,8 @@ Through the new methods, the first argument of transaction functions is a `Manag
 |{cross-mark}
 
 |5.0
-|Property `id` (int) for `Node` and `Relationship` objects is deprecated in favor of `element_id` (str).
-This also affects `Graph` objects, as indexing `graph.nodes[...]` and `graph.relationships[...]` with integers is deprecated in favor of indexing them with strings.
+|Property `id` (int) for link:https://neo4j.com/docs/api/python-driver/current/api.html#neo4j.graph.Node[`Node`] and link:https://neo4j.com/docs/api/python-driver/current/api.html#neo4j.graph.Relationship[`Relationship`] objects is deprecated in favor of `element_id` (str).
+This also affects link:https://neo4j.com/docs/api/python-driver/current/api.html#neo4j.graph.Graph[`Graph`] objects, as indexing `graph.nodes[...]` and `graph.relationships[...]` with integers is deprecated in favor of indexing them with strings.
 |label:deprecated[]
 |{check-mark} property +
 {cross-mark} indexing
@@ -254,23 +285,23 @@ Call `driver.close()` explicitly or create the driver via a `with` statement.
 |5.0
 |Import of the following modules is deprecated without replacement: they are internal and should not be used by client code: `neo4j.packstream`, `neo4j.routing`, `neo4j.config`, `neo4j.meta`, `neo4j.data`.
 
-ExperimentalWarning (previously in `meta`) should be imported directly from neo4j. +
+`ExperimentalWarning` (previously in `meta`) should be imported directly from neo4j. +
 `neo4j.meta.version` is exposed through `+++neo4j.__version__+++`.
 |label:deprecated[]
 |{check-mark}
 
 |5.0
-|The `trust` driver option is deprecated. New options `trusted_certificates` and `ssl_context` are available.
+|The `trust` driver option is deprecated. New options link:https://neo4j.com/docs/api/python-driver/current/api.html#trusted-certificates-ref[`trusted_certificates`] and link:https://neo4j.com/docs/api/python-driver/current/api.html#ssl-context-ref[`ssl_context`] are available.
 |label:deprecated[]
 |{check-mark}
 
 |5.0
-|`Session.last_bookmark()` is deprecated (its behaviour is partially incorrect and cannot be fixed without breaking its signature). Use `Session.last_bookmarks()` instead.
+|`Session.last_bookmark()` is deprecated (its behaviour is partially incorrect and cannot be fixed without breaking its signature). Use link:https://neo4j.com/docs/api/python-driver/current/api.html#neo4j.Session.last_bookmarks[`Session.last_bookmarks()`] instead.
 |label:deprecated[]
 |{check-mark}
 
 |5.0
-|`neo4j.Bookmark` is deprecated in favor of `neo4j.Bookmarks`.
+|`neo4j.Bookmark` is deprecated in favor of link:https://neo4j.com/docs/api/python-driver/current/api.html#neo4j.Bookmarks[`neo4j.Bookmarks`].
 |label:deprecated[]
 |{check-mark}
 
@@ -290,7 +321,7 @@ ExperimentalWarning (previously in `meta`) should be imported directly from neo4
 |{check-mark}
 
 |5.22
-|Type `SummaryNotificationPosition` is deprecated in favor of `SummaryInputPosition`.
+|Class link:https://neo4j.com/docs/api/python-driver/current/api.html#neo4j.SummaryInputPosition[`SummaryNotificationPosition`] is deprecated in favor of `SummaryInputPosition`.
 |label:deprecated[]
 |{check-mark}