diff --git a/python-manual/modules/ROOT/content-nav.adoc b/python-manual/modules/ROOT/content-nav.adoc index 1d20864a..184f26d4 100644 --- a/python-manual/modules/ROOT/content-nav.adoc +++ b/python-manual/modules/ROOT/content-nav.adoc @@ -20,7 +20,7 @@ * xref:connect-advanced.adoc[Advanced connection information] * xref:data-types.adoc[Data types and mapping to Cypher types] -* xref:migration.adoc[Upgrade & Migration] +* xref:upgrade.adoc[Upgrade & Migration] * link:https://neo4j.com/docs/api/python-driver/current/[API documentation, window=_blank] * *GraphAcademy courses* diff --git a/python-manual/modules/ROOT/pages/migration.adoc b/python-manual/modules/ROOT/pages/upgrade.adoc similarity index 90% rename from python-manual/modules/ROOT/pages/migration.adoc rename to python-manual/modules/ROOT/pages/upgrade.adoc index 6ccd5e8e..c9e3fdcc 100644 --- a/python-manual/modules/ROOT/pages/migration.adoc +++ b/python-manual/modules/ROOT/pages/upgrade.adoc @@ -6,12 +6,12 @@ For a full list of changes, see the link:https://github.com/neo4j/neo4j-python-d [NOTE] This page may be revised with new changes up until the time when the latest 5.x version is released. -The link:https://github.com/neo4j/drivers-migration-assistant[Neo4j Drivers Migration Assistant] simplifies the upgrade process, by contextualizing the changelog to your codebase. +The link:https://github.com/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. -The driver version 4.4 is forward compatible with Neo4j server 5.x as well, so you could also upgrade the server before the driver; however, given that it's easier to rollback an application upgrade than a server upgrade, it's recommended to start with the driver. +The driver version 4.4 is forward compatible with Neo4j server 5.x as well, so you could also upgrade the server before the driver; however, given that it's easier to roll back an application upgrade than a server upgrade, it's recommended to start with the driver. [TIP] When upgrading the Neo4j server to a newer version, the Cypher queries in your application may also need updating. + @@ -21,25 +21,25 @@ See link:https://neo4j.com/docs/cypher-manual/current/deprecations-additions-rem [[recommended-steps]] == Recommended steps -Using the migration assistant, the recommended upgrade steps are: +Using the migration assistent, the recommended upgrade steps are: -1. Run the migration assistant with its default configuration and address all the issues that it surfaces. The `path` argument supports link:https://www.man7.org/linux/man-pages/man7/glob.7.html[globbing] and can be repeated as many times as needed. + +1. Run the migration assistent with its default configuration and address all the issues that it surfaces. The `path` argument supports link:https://www.man7.org/linux/man-pages/man7/glob.7.html[globbing] and can be repeated as many times as needed. + + [source, bash] ---- python3 main.py -l python /path/*.py /path-recursive/**/*.py ---- + -2. Re-run the assistant with the regex parser and check if any more legit issues are raised. + +2. Re-run the assistent with the regex parser and check if any more legit issues are raised. + + [source, bash] ---- python3 main.py -l python --regex-parser /path/*.py /path-recursive/**/*.py ---- + -The regex parser can detect implicit function calls and other hard-to-parse expressions, but is likely to surface more false positives (for more information, see link:https://github.com/stefano-ottolenghi/neo4j-drivers-migration-assistant?tab=readme-ov-file#accuracy[Neo4j Drivers Migration Assistant -> Accuracy]). -You can add any spurious entry to the ignored list, so that the assistant won't bring them up in future runs. -3. Although the assistant 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}. +The regex parser can detect implicit function calls and other hard-to-parse expressions, but is likely to surface more false positives (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. For example, using `pip`: + + [source, bash] @@ -181,20 +181,25 @@ This feature helps identifying such code paths (detection is still inherently ra [[breaking-changes]] == Breaking changes and deprecations -The column `Assistant` denotes whether the Neo4j Drivers Migration Assistant can detect issues related to the given changelog entry. +The column `Assistent` denotes whether the Neo4j Drivers Migration Assistent can detect issues related to the given changelog entry. Entries with a cross mark {cross-mark} require manual inspection. Deprecated features are likely to be removed in version 6. [cols="1,5a,1,1"] |=== -|Version |Message |Status |Assistant +|Version |Message |Status |Assistent |5.0 |Dropped support for Python 3.6. |label:removed[] |{cross-mark} +|5.3 +|Package-alias `neo4j-driver` is deprecated. It will stop receiving updates starting with 6.0.0. Install `neo4j` instead. +|label:deprecated[] +|{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 (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[] @@ -206,10 +211,10 @@ Deprecated features are likely to be removed in version 6. |{check-mark} |5.0 -|In link:https://neo4j.com/docs/api/python-driver/current/api.html#neo4j.ServerInfo[`neo4j.ServerInfo`], removed `ResultSummary.server.version_info`. +|link:https://neo4j.com/docs/api/python-driver/current/api.html#neo4j.ServerInfo[`neo4j.ServerInfo`] -- `ResultSummary.server.version_info` has been removed. Use `ResultSummary.server.agent`, `ResultSummary.server.protocol_version`, or call the `dbms.components` Cypher procedure instead. |label:removed[] -|{cross-mark} +|{check-mark} |5.0 |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. @@ -275,11 +280,6 @@ Through the new methods, the first argument of transaction functions is a `Manag |label:deprecated[] |{check-mark} -|5.3 -|Package-alias `neo4j-driver` is deprecated. It will stop receiving updates starting with 6.0.0. Install `neo4j` instead. -|label:deprecated[] -|{cross-mark} - |5.0 |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. @@ -296,7 +296,7 @@ Call `driver.close()` explicitly or create the driver via a `with` statement. |{check-mark} |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`. +|Import of the following modules is deprecated without replacement, as 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. + `neo4j.meta.version` is exposed through `+++neo4j.__version__+++`. @@ -329,7 +329,7 @@ Call `driver.close()` explicitly or create the driver via a `with` statement. |{check-mark} |5.0 -|The following objects are deprecated without replacement: they are internal and should not be used by client code: `neo4j.spatial.hydrate_point`, `neo4j.spatial.dehydrate_point`, `neoj4.Config`, `neoj4.PoolConfig`, `neoj4.SessionConfig`, `neoj4.WorkspaceConfig`, `neo4j.data.DataDehydrator`, `neo4j.data.DataHydrator`. +|The following objects are deprecated without replacement, as they are internal and should not be used by client code: `neo4j.spatial.hydrate_point`, `neo4j.spatial.dehydrate_point`, `neoj4.Config`, `neoj4.PoolConfig`, `neoj4.SessionConfig`, `neoj4.WorkspaceConfig`, `neo4j.data.DataDehydrator`, `neo4j.data.DataHydrator`. |label:deprecated[] |{check-mark}