Skip to content

5.x Changelog

Jump to bottom
Robsdedude edited this page Jan 27, 2023 · 67 revisions

Changelog

⚠️ marks breaking changes or pending breaking changes (deprecations)

5.5.0

⭐ New Features

  • Experimental Driver.execute_query API (#833).

5.4.0

⭐ New Features

  • Supporting more types as query parameters (e.g., tuple, some pandas and numpy types, see also API docs) (#881).

🔧 Fixes

  • Fix not handling async cancellation during Driver.close properly (#881).

👏 Improvements

  • Update custom async synchronization primitives to be based on Python 3.11's implementation. This will among other things avoid accidentally creating the driver while not event loop is running which can lead to hard to debug errors later in the program (see #868) (#879).
  • More server errors will be surfaced directly on failed routing discovery. Those used to be masked as ServiceUnavailable errors hiding driver misconfiguration as the real cause (#870). Specifically:
    • Neo.ClientError.Statement.TypeError, e.g., when trying to impersonate an integer or any type other than None or str.
    • Neo.ClientError.Statement.ArgumentError, e.g., when trying to impersonate without the required permissions.
    • Neo.ClientError.Request.Invalid, e.g., when trying to select an integer database or any type other than None or str.

📚 Docs

  • Multiple small improvements throughout the API docs (#887, #874).

🧹Clean-up

  • ⚠️ Undocumented helper methods Neo4jError.is_fatal_during_discovery and Neo4jError.invalidates_all_connections have been deprecated and will be removed without replacement in version 6.0 (#870).

5.3.0

⭐ New Features

  • Add Support for Python 3.11 (#861).

🔧 Fixes

  • ⚠️ The experimental BookmarkManager API received a necessary change that simplifies it and makes it work correctly (#859).
    It will no longer track bookmarks per database. This effectively changes the signature of almost all bookmark manager related methods:
    • neo4j.BookmarkManger and neo4j.AsyncBookmarkManger abstract base classes:
      • update_bookmarks has no longer a database argument.
      • get_bookmarks has no longer a database argument.
      • The get_all_bookmarks method was removed.
      • The forget method was removed.
    • neo4j.GraphDatabase.bookmark_manager and neo4j.AsyncGraphDatabase.bookmark_manager factory methods:
      • initial_bookmarks is no longer a mapping from database name to bookmarks but plain bookmarks.
      • bookmarks_supplier no longer receives the database name as an argument.
      • bookmarks_consumer no longer receives the database name as an argument.

👏 Improvements

  • Modernize packaging to use pyproject.toml, fixing deprecation warning DEPRECATION: neo4j is being installed using the legacy 'setup.py install' method[...] when installed with pip (#867).
  • Improve exception context for some exceptions (#860).
  • Query strings are now typed LiteralString instead of str to help mitigate accidental Cypher injections. There are rare use-cases where a computed string is necessary. Please use # type: ignore, or typing.cast to suppress the type checking in those cases (#861).

🧹Clean-up

  • ⚠️ Deprecated package-alias neo4j-driver. It will stop receiving updates starting with 6.0.0. Please install neo4j instead (#867).
  • Removed testing code (testkitbackend) from distributed package (#855 thanks to @thesamesam, #867).

📚 Docs

  • Expand API docs to fully state the implications of not specifying a database parameters when creating a session(#865).
  • Multiple small improvements throughout the API docs (#858).

5.2.1

🔧 Fixes

  • Data race in the routing driver that could lead to a KeyError (#852).
  • Package py.typed marker file so that mypy and other type checkers consider the type annotations that were added to the driver in 5.0 (#856).

👏 Improvements

  • Major improvements of the driver's debug logging (#849).
  • Implemented __format__ for temporal types enabling expressions like f"{neo4j.time.Time(12, 34, 56, 789123001):%H:%M:%S.%f}" (#853).
  • Made the driver compatible with mypy version 0.990 (#854).

📚 Docs

  • Several small improvements to the API docs (#848, #850, #851)

5.2.0

🔧 Fixes

  • Fix missing rewrite of driver internal error neo4j._exceptions.SocketDeadlineExceeded: timed out (#842).

👏 Improvements

  • Keyword parameters of Session.run and Transaction.run are no longer restricted by parameters used in driver internal functions further down the stack (#835).

📚 Docs

  • Editorial changes (#844 and 839).
  • Remove documentation of driver configuration options (session_connection_timeout and update_routing_table_timeout) that were already removed in 5.0.0 (#838).
  • Clarification of the timeout parameter to unit_of_work (#827).
  • Clarify precedence of parameters and keyword parameters of Session.run and Transaction.run (#835).

5.1.0

🔧 Fixes

  • Fix optional dependencies (pandas) in packaging (#808).
  • [Python 3.10+] Fix deprecation warnings from using deprecated SSL options (#809).

📚 Docs

5.0.1

🔧 Fixes

  • Fix connection pool clogging up when checking if new connections can be created while the pool is full (#804; fixes #796).
    The bug was introduced in 5.0.0 with #745.
  • Fix string representation of neo4j.exceptions.ClientError and neo4j.exceptions.Neo4jError when raised from the driver code (806).

👏 Improvements

  • Properly close sockets on async cancellation during HELLO handshakes. This resolves a ResourceWarning that otherwise would be emitted when the garbage collection cleans up the socket (#801).

5.0.0

🔧 Fixes

  • Fix relying on garbage collector to close sockets under certain failure conditions (#795).

🧹Clean-up

  • ⚠️ Removed ignore_bookmark_manager session config option. It's a leftover from a previous design of the bookmark manager and was introduced in 5.0.0a2 (#792).

5.0.0a2

This release contains all fixes up until version 4.4.6 plus:

⭐ New Features

  • Support for Bolt protocol version 5.0 (#672, #737).
    • ⚠️ Deprecated Nodes' and Relationships' id property (int) in favor of element_id (str).
      This also affects Graph objects as indexing graph.nodes[...] and graph.relationships[...] with integers has been deprecated in favor of indexing them with strings.
    • Fixed encoding of DateTimes with zone id (#748).
  • Added type hints for all public APIs (#767).
  • Added BookmarkManager support (#771).
    This feature makes it easier to achieve causal chaining of sessions. See the API documentation for more details.
  • New SSL config options (#639, #656, #666)
    • ⚠️ The trust option has been deprecated.
      Use trusted_certificates instead. See the API documentation for more details.
    • New options trusted_certificates and ssl_context have been added (see API docs for more details).
  • Result API
    • Result.single has a new optional argument strict (#646, #673).
      If strict is True and the result set contains not exactly one record, an exception will be raised.
    • Added Result.fetch(n) to fetch up to n records as a list (#673).
    • Result objects are now iterators (i.e. next(result)/result.__next__() is supported) (#647).
      result.__anext__() for AsyncResult respectively.
  • Added Driver.get_server_info() (#654).
  • Added .is_retryable() to Neo4jError and DriverError (#682, #742).
    ⚠️ Deprecated neo4j.exceptions.Neo4jError.is_retriable() in favor of neo4j.exceptions.Neo4jError.is_retryable().
    This change helps users to implement custom retry policies together with explicit transactions.
  • Added expand and parse_dates parameters to Result.to_df() (Pandas DataFrame export) (#663, #716).

🔧 Fixes

  • Allow sending a transaction timeout of 0 (#642).
    Previously, 0 was interpreted as None and thus the server-side default timeout was used. Now, 0 denotes an infinite timeout.
  • Bookmarks (#649)
    • ⚠️ Session.last_bookmark was deprecated. Its behaviour is partially incorrect and cannot be fixed without breaking its signature.
      Use Session.last_bookmarks instead.
    • neo4j.Bookmark was deprecated.
      Use neo4j.Bookmarks instead.
  • Many async fixes:
    • Fix custom implementation of AsyncCondition (#638).
    • asyncio.iscoroutinefunction was None in destructor (#643).
    • Add missing await in Session.being_transaction (423e1e5).
    • Await and fix async socket closure (#701, #705).
    • Handle asyncio.CancelledError gracefully (#761).
    • Patch asyncio.wait_for to no swallow cancellations (#761).
  • Fix sync socket close helper method (#777).
  • ⚠️ Removed deprecated parts in the neo4j.time module (#635).
    • Duration
      • The constructor does not accept subseconds anymore.
        Use milliseconds, microseconds, or nanoseconds instead.
      • The property subseconds has been removed.
        Use nanoseconds instead.
      • The property hours_minutes_seconds has been removed.
        Use hours_minutes_seconds_nanoseconds instead.
      • For all math operations holds: they are element-wise on (months, days, nanoseconds). This affects (i.e., changes) the working of //, %, /, and *.
        • Years are equal to 12 months.
        • Weeks are equal to 7 days.
        • seconds, milliseconds, microseconds, and nanoseconds are implicitly converted to nanoseconds or seconds as fit.
      • Multiplication and division allow for floats but will always result in integer values (round to nearest even).
    • Time
      • The constructor does not accept floats for second anymore.
        Use nanosecond instead.
      • Ticks are now nanoseconds since midnight (int).
        • The property ticks_ns has been renamed to ticks.
          The old ticks is no longer supported.
        • The propertyfrom_ticks_ns has been renamed to from_ticks.
          The old from_ticks is no longer supported.
      • The property second returns an int instead of a float.
        Use nanosecond to get the sub-second information.
      • The property hour_minute_second has been removed.
        Use hour_minute_second_nanosecond instead.
    • DateTime
      • The property hour_minute_second has been removed.
        Use hour_minute_second_nanosecond instead.
      • The property second returns an int instead of a float.
        Use nanosecond to get the sub-second information.

👏 Improvements

  • Speed up by caching the local port number of connections (#724).
  • Raise ResultConsumedError when result is out of scope (#652):
    • Records of Results cannot be accessed (peek, single, iter, ...) after their owning transaction has been closed, committed, or rolled back.
      Previously, this would yield undefined behavior. It now raises a ResultConsumedError.
    • Records of Results cannot be accessed (peek, single, iter, ...) after the Result has been consumed (Result.consume()).
      Previously, this would always yield no records. It now raises a ResultConsumedError.
    • New method Result.closed() can be used to check for this condition if necessary.
  • Improved output of logging helper neo4j.debug.watch (#728, #755).
    • ANSI colour codes for log output are now opt-in.
    • Prepend log format with log-level (if colours are disabled).
    • Prepend log format with thread name and id.
  • Change the transaction class passed to transaction functions (a.k.a. managed transactions) (#658):
    The first argument of transaction functions is now a ManagedTransaction object. It behaves exactly like a regular Transaction object, except it does not offer the commit, rollback, close, and closed methods.
    Those methods would have caused a hard to interpreted error previously. Hence, they have been removed.
    • To reflect this change in signature, Session.read_transaction and Session.write_transaction have been renamed to Session.execute_read and Session.execute_write respectively (#784, #786).
  • ⚠️ Certain deserialization errors (e.g., receiving a DateTime with an unsupported time zone) will no longer raise when receiving them but when trying to access them through the Record (#759). neo4j.exceptions.BrokenRecordError has been introduced to indicate this.

🧹Clean-up

  • ⚠️ Removed deprecated ResultSummary.server.version_info (#636).
    Use ResultSummary.server.agent, ResultSummary.server.protocol_version, or call the dbms.components procedure instead.
  • ⚠️ Deprecate implicit closing of drivers and sessions in __del__ (destructor) (#653). This behaviour is non-deterministic as there is no guarantee that the destructor will ever be called. A ResourceWarning is emitted instead.
    Make sure to configure Python to output those warnings when developing your application locally (it does not by default).
  • ⚠️ Removed deprecated (since 4.4.6) timeout config options introduced in 4.4.5 (#769).
    Server-side keep-alives communicated through configuration hints together with connection_acquisition_timeout are sufficient to avoid the driver getting stuck.
  • Creation of a driver with bolt[+s[sc]]:// scheme and a routing context has been deprecated and will raise an error in the Future. (#645, 655).
    Previously, the routing context was silently ignored.
  • ⚠️ Removed undocumented return value of Driver.verify_connectivity() (#654, #743).
    Use Driver.get_server_info() instead.
  • ⚠️ Package structure/imports (#748)
    • Importing submodules from neo4j.time (neo4j.time.xyz) has been deprecated. Everything needed should be imported from neo4j.time directly.
    • neo4j.spatial.hydrate_point and neo4j.spatial.dehydrate_point have been deprecated without replacement. They are internal functions.
    • Importing neo4j.packstream has been deprecated. It's internal and should not be used by client code.
    • Importing neo4j.routing has been deprecated. It's internal and should not be used by client code.
    • Importing neo4j.config has been deprecated. It's internal and should not be used by client code.
    • neoj4.Config, neoj4.PoolConfig, neoj4.SessionConfig, and neoj4.WorkspaceConfig have been deprecated without replacement. They are internal classes.
    • Importing neo4j.meta has been deprecated. It's internal and should not be used by client code. ExperimantalWarning should be imported directly from neo4j. neo4j.meta.version is exposed through neo4j.__vesrion__
    • Importing neo4j.data has been deprecated. It's internal and should not be used by client code. Record should be imported directly from neo4j instead. neo4j.data.DataHydrator and neo4j.data.DataDeydrator have been removed without replacement.

🌳 Maturing

  • The async driver (neo4j.AsyncGraphDatabase) is no longer experimental (#783).
  • Result.to_df() (Pandas DataFrame export) is no longer experimental (#787).

5.0.0a1

IMPORTANT: this pre-release does not contain any 5.0 features and future pre-releases might have to be API-breaking. This release' sole purpose it to give early access to the async driver.

📚 Note on Documentation
You can find the preliminary API documentation here https://neo4j.com/docs/api/python-driver/5.0/
Note, that the compatible server versions are listed for the stable 5.0.x driver. The 5.0.0a1 driver supports the same server versions as 4.4.x drivers.

⭐ New Features

  • Added experimental asyncio support (#629).
  • Added support for Python 3.10 (#627).

🧹Clean-up

  • ⚠️ Drop support for Python 3.6 (end of life 2021-12-23) (#627).
  • ⚠️ Experimental pipeline feature has been dropped (#629).
  • ⚠️ Result, Session, and Transaction can no longer be imported from neo4j.work. Import them from neo4j instead.
Clone this wiki locally