Skip to content

5.x Changelog

Jump to bottom
Robsdedude edited this page Feb 29, 2024 · 68 revisions

Changelog

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

5.18.0

🔧 Fixes

  • Fix metadata, e.g., __qualname__, of internally forwarded methods of Transaction and AsyncTransaction (#1017).

📚 Docs

5.17.0

🔧 Fixes

  • Fix from neo4j import * statement (#1009).

📚 Docs

  • Improve API documentation of result streams (#1010).

5.16.0

⭐ New Features

  • New driver config option liveness_check_timeout (#992).
  • Enable/fix (deep)copying and pickling support for custom temporal and spatial types (#1002).
    Thanks to @Sopalinge for this contribution.

👏 Improvements

  • Implemented a hierarchical logger structure to improve log source identification and traceability (#997).
    Thanks to @OliverFarren for this contribution.
    Introduced child loggers:
    • neo4j.io: For socket and bolt protocol related logging.
    • neo4j.pool: For logs pertaining to connection pooling and routing.
    • neo4j.auth_management: For logging inside the provided AuthManager implementations.

🔧 Fixes

  • Fix exporting Durations with Result.data resulting in TypeError: unsupported operand type(s) for *: 'int' and 'map' (#1000).
    Also: 1000th PR 🎂
  • Also cover Session.last_bookmarks with the optional concurrency misuse checks introduced in version 5.15.0 (#1004).
  • Harden the driver against unexpected server responses following RESET (#1006).
    Under certain circumstances, can the server respond with FAILURE and even IGNORED when the driver attempts to RESET a failed connection. It's arguable whether it should, but the driver needs to handle to it, let alone to be compatible with older server versions. The driver did not handle this situation gracefully and could even get stuck in an infinite loop. Instead, it will now close such connections and raise the original error the connection failed with.

📚 Docs

  • Fix signature of Driver.execute_query (#998).
  • Fix wrong await in async API docs (#1003).
  • Fix wrong minimum required server version for some notification filters (#1007).

5.15.0

⭐ New Features

  • Driver.execute_query now accepts a Query object to specify transaction config like metadata and transaction timeout (#991).
  • 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. By default, using them concurrently will lead to hard to debug errors. This feature helps to identify such code paths. Note that detection is still inherently racy, hence not guaranteed to always work (#989, 995).

👏 Improvements

  • Materialize experimental Rust extension in bolt-agent and user-agent string (#993).

🔧 Fixes

  • Fix trying to await socket closure on async cancellation during initial connection (#987).

🧹Clean-up

  • ⚠️ Deprecated passing multiple targets to the undocumented method GraphDatabase.neo4j_driver (#986).

5.14.1

🌱 Groundwork

  • Prepare the driver to pick up Rust extensions for a better performing PackStream implementation (#979).
    This change is 100% transparent and doesn't affect the operation of the driver unless the user takes extra steps to install Rust extensions separately.

5.14.0

⭐ New Features

  • Add support for Python 3.12 (#972).
  • Add new notification categories SECURITY and TOPOLOGY (#975).

🔧 Fixes

  • Properly propagate errors across results within a transaction (#973).
    If any record stream fails, the transaction as a whole, including all other results, cannot be recovered. A new error ResultFailedError is introduced to signal this condition.

📚 Docs

  • Migrated API Docs layout to corporate design (#968).

🌳 Maturing

  • Stabilize the re-authentication feature from preview (#977).

5.13.0

⭐ New Features

  • Support for bolt protocol 5.4 (#965).
    Starting with Bolt 5.4, the driver will, by default, send anonymous API usage statistics to the server if requested. Please see the linked pull request for more details like how to opt-out.

🔧 Fixes

  • Fix suppression of warnings inside the driver. This is now concurrency-safe (#961).
  • ⚠️ Using neo4j.Driver/neo4j.AsyncDriver objects after calling .close() on them, except for calling .close() again, is deprecated and will throw an Exception in a future version (#962, #964).

📚 Docs

  • Improve typing information in the API docs (#963).
  • Improve API docs around transaction timeouts (#966, #970).

🌳 Maturing

  • The driver configuration option keep_alive to control the TCP keep alive option on the sockets is no longer marked experimental (#967).

5.12.0

👏 Improvements

  • driver.execute_query is now more efficient by saving a round trip (#956).
  • ⚠️ Changes were made to the re-auth feature in preview (#957, (8b35bd86)):
    • Removed TokenExpiredRetryable exception.
      Even though it wasn't marked preview, it was introduced with and only used for re-auth. It no longer serves any purpose.
    • The AuthManager and AsyncAuthManager abstract classes were changed.
      The method on_auth_expired(self, auth: _TAuth) -> None was removed in favor of handle_security_exception(self, auth: _TAuth, error: Neo4jError) -> bool.
      See the API docs for more details.
    • The factories in AsyncAuthManagers and AuthManagers were changed.
      • expiration_based was renamed to bearer.
      • basic was added to cater for password rotation.

🔧 Fixes

  • Fix potential datarace when handling routing tables (#952).
  • Fix pool closing connections too aggressively. In autonomous clustering scenarios where a given database might not be present on all cluster members, the driver could've closed all connections to such members even if they were still useful for other databases (#955).
  • Fix driver dropping write servers from the routing table too aggressively (#959).

5.11.0

🔧 Fixes

  • Fix handling of sub-ms transaction timeouts (#940).
    • Due to the timeout being float rounding issues were possible (e.g., 256.4 s would be turned into 256399 ms).
    • 0.001 s > timeout > 0 was rounded down to 0 ms which is a special value for no timeout at all. This is very likely not what the user intended.
  • Avoid lazy imports to reduce chances of errors during interpreter shutdown (#942).
  • Avoid swallowing errors coming from asyncio.Lock.acquire (#944).
  • Fix neo4j.debug.watch() not handling logging levels correctly when being called multiple times (#946).

5.10.0

📚 Docs

  • Improve API docs around ExpiringAuth (#934).
  • Remove old migration information, fix and update links, update getting started example to use the new and shorter driver.execute_query API introduced in 5.5.0 and stabilized in 5.8.0 (#929).
  • Small formatting fixed (#938).
  • Fix wrongly documented type of query_ parameter of driver.execute_query (#939).

5.9.0

⭐ New Features

  • Support for bolt protocol 5.3 which adds bolt_agent metadata so that the server knows which driver is connecting (#910).
  • ⚠️ neo4j.auth_management.ExpiringAuth used for auth rotation (re-auth, preview feature) now expects an absolute expiration time. A convenience method to create it with a relative expiration time added (#928).
    The attribute expires_in was replaced by expires_at, which now expects a unix timestamp.
    You can use ExpiringAuth(some_auth).expires_in(123) instead if you rely on relative expiration.

📚 Docs

  • Mention performance impact of notification filtering (#931).

🧹Clean-up

  • Align spacing of log message (#926).

5.8.1

🔧 Fixes

  • Make neo4j.auth_management.ExpiringAuth (in preview) a class instead of a function caused by an incorrect preview decorator (#927).

📚 Docs

  • Fix broken formatting and missing parts caused by an incorrect preview decorator (#927).
  • Fix broken cross references in the API docs that were missed when renaming experimental APIs in #911 (#927).

5.8.0

⭐ New Features

👏 Improvements

  • Implement serialization of temporal types with python's standard datetime.timezone (fixed utc-offset timezones) as tzinfo (#914).
  • The above change enables panadas 2 support (#914).

📚 Docs

  • Multiple small improvements throughout the API docs (cf2c75c0, #919).

🌳 Maturing

  • Bookmark managers (BookmarkManager class, bookmark_manager config options, Driver.bookmark_manager() factory method) (#911).
  • Driver.execute_query API with some minor changes (#911):
    • ⚠️ Rename neo4j.RoutingControl.WRITERS to neo4j.RoutingControl.WRITE and ...READERS to ...READ
    • ⚠️ Rename driver.query_bookmark_manager() to driver.execute_query_bookmark_manager().
    • The query argument is 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 (#923).

5.7.0

⭐ New Features

  • Notification filtering API (#847).
    This introduces two new options notifications_min_severity and notifications_disabled_categories to the driver and session config. Both require neo4j server version 5.7+.

🔧 Fixes

  • Fix application protocol (bolt) handshake not having a timeout (#905).

🧹Clean-up

  • ⚠️ Importing neo4j.work and its submodules has been deprecated. Everything should be imported directly from neo4j instead.

5.6.0

📚 Docs

5.5.0

⭐ New Features

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 hard to debug errors later in the program when accidentally creating the driver while no event loop is (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 deprecated in favor of 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