pyneo4j-ogm 0.6.0

Description:

pyneo4jogm 0.6.0

pyneo4j-ogm




pyneo4j-ogm is a asynchronous Object-Graph-Mapper for Neo4j 5+ and Python 3.10+. It is inspired by beanie and build on top of proven technologies like Pydantic 1.10+ and 2+ and the Neo4j Python Driver. It saves you from writing ever-repeating boilerplate queries and allows you to focus on the stuff that actually matters. It is designed to be simple and easy to use, but also flexible and powerful.
🎯 Features
pyneo4j-ogm has a lot to offer, including:

Fully typed: pyneo4j-ogm is fully typed out of the box.
Powerful validation: Since we use Pydantic under the hood, you can use it's powerful validation and serialization features without any issues.
Focus on developer experience: Designed to be simple to use, pyneo4j-ogm provides features for both simple queries and more advanced use-cases while keeping it's API as simple as possible.
Build-in migration tooling: Shipped with simple, yet flexible migration tooling.
Fully asynchronous: Completely asynchronous code, thanks to the Neo4j Python Driver.
Supports Neo4j 5+: pyneo4j-ogm supports Neo4j 5+ and is tested against the latest version of Neo4j.
Multi-version Pydantic support: Both Pydantic 1.10+ and 2+ fully supported.

📣 Announcements
Things to come in the future. Truly exiting stuff! If you have feature requests which you think might improve pyneo4j-ogm, feel free to open up a feature request.

MemGraph support.

📦 Installation
Using pip:
pip install pyneo4j-ogm

or when using Poetry:
poetry add pyneo4j-ogm

🚀 Quickstart
Before we can get going, we have to take care of some things:

We need to define our models, which will represent the nodes and relationships inside our database.
We need a database client, which will do the actual work for us.

Defining our data structures
Since every developer has a coffee addiction one way or another, we are going to use Coffee and Developers for this guide. So let's start by defining what our data should look like:
from pyneo4j_ogm import (
NodeModel,
RelationshipModel,
RelationshipProperty,
RelationshipPropertyCardinality,
RelationshipPropertyDirection,
WithOptions,
)
from pydantic import Field
from uuid import UUID, uuid4


class Developer(NodeModel):
"""
This class represents a `Developer` node inside the graph. All interactions
with nodes of this type will be handled by this class.
"""
uid: WithOptions(UUID, unique=True) = Field(default_factory=uuid4)
name: str
age: int

coffee: RelationshipProperty["Coffee", "Consumed"] = RelationshipProperty(
target_model="Coffee",
relationship_model="Consumed",
direction=RelationshipPropertyDirection.OUTGOING,
cardinality=RelationshipPropertyCardinality.ZERO_OR_MORE,
allow_multiple=True,
)

class Settings:
# Hooks are available for all methods that interact with the database.
post_hooks = {
"coffee.connect": lambda self, *args, **kwargs: print(f"{self.name} chugged another one!")
}


class Coffee(NodeModel):
"""
This class represents a node with the labels `Beverage` and `Hot`. Notice
that the labels of this model are explicitly defined in the `Settings` class.
"""
flavor: str
sugar: bool
milk: bool

developers: RelationshipProperty["Developer", "Consumed"] = RelationshipProperty(
target_model=Developer,
relationship_model="Consumed",
direction=RelationshipPropertyDirection.INCOMING,
cardinality=RelationshipPropertyCardinality.ZERO_OR_MORE,
allow_multiple=True,
)

class Settings:
labels = {"Beverage", "Hot"}

class Consumed(RelationshipModel):
"""
Unlike the models above, this class represents a relationship between two
nodes. In this case, it represents the relationship between the `Developer`
and `Coffee` models. Like with node-models, the `Settings` class allows us to
define some configuration for this relationship.

Note that the relationship itself does not define it's start- and end-nodes,
making it reusable for other models as well.
"""
liked: bool

class Settings:
type = "CHUGGED"

Until now everything seems pretty standard if you have worked with other ORM's before. But if you haven't, we are going to go over what happened above:

We defined 2 node models Developer and Coffee, and a relationship Consumed.
Some models define a special inner Settings class. This is used to customize the behavior of our models inside the graph. More on these settings can be found here.
The WithOptions function has been used to define constraints and indexes (more about them here) on model properties.

Creating a database client
In pyneo4j-ogm, the real work is done by a database client. One of these bad-boys can be created by initializing a Pyneo4jClient instance. But for models to work as expected, we have to let our client know that we want to use them like so:
from pyneo4j_ogm import Pyneo4jClient

async def main():
# We initialize a new `Pyneo4jClient` instance and connect to the database.
client = Pyneo4jClient()

# Replace `<connection-uri-to-database>`, `<username>` and `<password>` with the
# actual values.
await client.connect(uri="<connection-uri-to-database>", auth=("<username>", "<password>"))

# To use our models for running queries later on, we have to register
# them with the client.
# **Note**: You only have to register the models that you want to use
# for queries and you can even skip this step if you want to use the
# `Pyneo4jClient` instance for running raw queries.
await client.register_models([Developer, Coffee, Consumed])

Interacting with the database
Now the fun stuff begins! We are ready to interact with our database. For the sake of this quickstart guide we are going to keep it nice and simple, but this is just the surface of what pyneo4j-ogm has to offer.
We are going to create a new Developer and some Coffee and give him something to drink:
# Imagine your models have been defined above...

async def main():
# And your client has been initialized and connected to the database...

# We create a new `Developer` node and the `Coffee` he is going to drink.
john = Developer(name="John", age=25)
await john.create()

cappuccino = Coffee(flavor="Cappuccino", milk=True, sugar=False)
await cappuccino.create()

# Here we create a new relationship between `john` and his `cappuccino`.
# Additionally, we set the `liked` property of the relationship to `True`.
await john.coffee.connect(cappuccino, {"liked": True}) # Will print `John chugged another one!`

Full example
import asyncio
from pyneo4j_ogm import (
NodeModel,
Pyneo4jClient,
RelationshipModel,
RelationshipProperty,
RelationshipPropertyCardinality,
RelationshipPropertyDirection,
WithOptions,
)
from pydantic import Field
from uuid import UUID, uuid4

class Developer(NodeModel):
"""
This class represents a `Developer` node inside the graph. All interaction
with nodes of this type will be handled by this class.
"""
uid: WithOptions(UUID, unique=True) = Field(default_factory=uuid4)
name: str
age: int

coffee: RelationshipProperty["Coffee", "Consumed"] = RelationshipProperty(
target_model="Coffee",
relationship_model="Consumed",
direction=RelationshipPropertyDirection.OUTGOING,
cardinality=RelationshipPropertyCardinality.ZERO_OR_MORE,
allow_multiple=True,
)

class Settings:
# Hooks are available for all methods that interact with the database.
post_hooks = {
"coffee.connect": lambda self, *args, **kwargs: print(f"{self.name} chugged another one!")
}


class Coffee(NodeModel):
"""
This class represents a node with the labels `Beverage` and `Hot`. Notice
that the labels of this model are explicitly defined in the `Settings` class.
"""
flavor: str
sugar: bool
milk: bool

developers: RelationshipProperty["Developer", "Consumed"] = RelationshipProperty(
target_model=Developer,
relationship_model="Consumed",
direction=RelationshipPropertyDirection.INCOMING,
cardinality=RelationshipPropertyCardinality.ZERO_OR_MORE,
allow_multiple=True,
)

class Settings:
labels = {"Beverage", "Hot"}

class Consumed(RelationshipModel):
"""
Unlike the models above, this class represents a relationship between two
nodes. In this case, it represents the relationship between the `Developer`
and `Coffee` models. Like with node-models, the `Settings` class allows us to
define some settings for this relationship.

Note that the relationship itself does not define it's start- and end-nodes,
making it reusable for other models as well.
"""
liked: bool

class Settings:
type = "CHUGGED"


async def main():
# We initialize a new `Pyneo4jClient` instance and connect to the database.
client = Pyneo4jClient()
await client.connect(uri="<connection-uri-to-database>", auth=("<username>", "<password>"))

# To use our models for running queries later on, we have to register
# them with the client.
# **Note**: You only have to register the models that you want to use
# for queries and you can even skip this step if you want to use the
# `Pyneo4jClient` instance for running raw queries.
await client.register_models([Developer, Coffee, Consumed])

# We create a new `Developer` node and the `Coffee` he is going to drink.
john = Developer(name="John", age=25)
await john.create()

cappuccino = Coffee(flavor="Cappuccino", milk=True, sugar=False)
await cappuccino.create()

# Here we create a new relationship between `john` and his `cappuccino`.
# Additionally, we set the `liked` property of the relationship to `True`.
await john.coffee.connect(cappuccino, {"liked": True}) # Will print `John chugged another one!`

# Be a good boy and close your connections after you are done.
await client.close()

asyncio.run(main())

And that's it! You should now see a Developer and a Hot/Beverage node, connected by a CONSUMED relationship. If you want to learn more about the library, you can check out the full Documentation.
📚 Documentation
In the following we are going to take a closer look at the different parts of pyneo4j-ogm and how to use them. We will cover everything pyneo4j-ogm has to offer, from the Pyneo4jClient to the NodeModel and RelationshipModel classes all the way to the Query filters and Auto-fetching relationship-properties.
Table of contents

pyneo4j-ogm

🎯 Features
📣 Announcements
📦 Installation
🚀 Quickstart

Defining our data structures
Creating a database client
Interacting with the database
Full example


Running the test suite
📚 Documentation

Basic concepts

A note on Pydantic version support


Database client

Connecting to the database
Closing an existing connection
Registering models
Executing Cypher queries
Batching cypher queries
Using bookmarks (Enterprise Edition only)
Manual indexing and constraints
Client utilities


Models

Indexes, constraints and properties
Reserved properties
Configuration settings

NodeModel configuration
RelationshipModel configuration


Available methods

Instance.update()
Instance.delete()
Instance.refresh()
Model.find_one()
Model.find_many()
Model.update_one()
Model.update_many()
Model.delete_one()
Model.delete_many()
Model.count()
NodeModelInstance.create()
NodeModelInstance.find_connected_nodes()
RelationshipModelInstance.start_node()
RelationshipModelInstance.end_node()


Serializing models
Hooks

Pre-hooks
Post-hooks


Model settings


Relationship-properties

Available methods

RelationshipProperty.relationships()
RelationshipProperty.connect()
RelationshipProperty.disconnect()
RelationshipProperty.disconnect_all()
RelationshipProperty.replace()
RelationshipProperty.find_connected_nodes()


Hooks with relationship properties


Queries

Filtering queries

Comparison operators
String operators
List operators
Logical operators
Element operators
Pattern matching
Multi-hop filters


Projections
Query options
Auto-fetching relationship-properties


Migrations

Initializing migrations for your project
Creating a new migration
Running migrations
Listing migrations
Programmatic usage


Logging





Running the test suite
To run the test suite, you have to install the development dependencies and run the tests using pytest. The tests are located in the tests directory. Some tests will require you to have a Neo4j instance running on localhost:7687 with the credentials (neo4j:password). This can easily be done using the provided docker-compose.yml file.
poetry run pytest tests --asyncio-mode=auto -W ignore::DeprecationWarning


Note: The -W ignore::DeprecationWarning can be omitted but will result in a lot of deprication warnings by Neo4j itself about the usage of the now deprecated ID.

As for running the tests with a different pydantic version, you can just install a different pydantic version with the following command:
poetry add pydantic@<version>