I'm in a similar position to original poster, new to Flask, Python, and Neo4j.
After some pondering I think I prefer the py2neo driver, but have the same documentation issues, the documentation tells me precisely how to do something, but not why and when I would want to do it.
The starter app you've done there looks great, although I've just written much the same as part of learning it all. The biggest problem today was older documentation out there, like Nicole's, call methods line "find_one" that are gone now in py2neo.
I've understood that to avoid the duplicate nodes, I have to merge (hopefully OP has got that now). But then when I work on a "Node" in py2neo, I find that existing properties are updated in the database immediately, but I have to "push" for new properties.
For example if "pw_hash" is present and "pw_changed" isn't....
matcher = NodeMatcher(graph)
thisUser = matcher.match("Person", name=name).first()
if not thisUser:
user = Node('Person', name=name, pw_hash=pw_hash)
graph.create(user)
else:
thisUser["pw_hash"] = pw_hash
thisUser["pw_changed"] = neotime.DateTime.now()
graph.push(thisUser)
The "push" is required for the update to include pw_changed. But I'm not even sure this is the right, or optimal approach. Should I have done "thisUser.update" or "thisUser.properties" ? Without some meta description of these options it is hard to know.
Part of the issue is that it is deliberately unrestrictive. I can do anything by pushing the Cypher, or playing with nodes and relationships directly, or matching and updating parts of the graph locally, and pushing them back, or use the OGM.
I'm expecting my model to evolve fairly rapidly. So that as I add features to the application, each new feature will need additional properties on existing nodes. I was planning to use the Node and Relationship objects from py2neo, and have the code update the models, but not sure if an OGM approach makes more sense. Or how hard it would be to maintain those classes, it feels that if the additional features require properties and relationships, they should add them. But it was only reading the py2neo documentation I (re-)discovered nodes could have more than one label (I think I missed something in the earlier training and doocumentation somewhere, as the docs are clear "zero" to "many" labels). When to use multiple labels, and temporary labels is something I clearly need to learn. If I extend a base object, say I have a "User" who is also an "Employee" does it make sense to have that as a label as well perhaps as a relationship?
Another concern is that a lot of the example "Movie" apps looks fine and understandable, but I wondered what "operational" code looks like in this space. e.g. I see a lot of database updates with no explicit error handling, no logging etc. I'm assuming "real" code in this space often has more checking?
That said I'm still prototyping things, and switching between drivers and trying out little scripts, whatever I settle on I'll abstract away as much as I can so changing things shouldn't be too hard.