Connection profiles

Most py2neo applications will make use of a class such as Graph or GraphService as the backbone through which Neo4j access is made. On construction, these classes generally accept a profile plus additional individual settings, that together specify how and where to connect.

>>> from py2neo import Graph
>>> g = Graph("neo4j+s://graph.example.com:7687", auth=("alice", "123456"))

The profile can take one of several forms, the simplest of which is a URI. Alternatively, a ConnectionProfile or ServiceProfile object can be supplied instead. These forms are all semantically equivalent, and provide access to the same range of options.

The additional settings allow certain parts of the profile to be overridden individually, and these will therefore be applied after the profile has been parsed.

If no arguments are provided to a Graph constructor, a default ServiceProfile will be assumed. This default describes an unsecured bolt connection to localhost on the default port, and uses neo4j and password as the user name and password respectively.

The routing option is available wherever the profile describes connectivity to a full Neo4j service, i.e. for a ServiceProfile but not for a ConnectionProfile. To ensure backward compatibility with older versions of Neo4j, as well as with standalone deployments, routing is not enabled for the default profile.

Environment variables

Profile defaults can be adjusted through setting environment variables made available to the Python environment. The following variables are available:

NEO4J_URI

NEO4J_AUTH

NEO4J_SECURE

NEO4J_VERIFY

Profile URIs

The general format of a profile URI is <scheme>://[<user>[:<password>]@]<host>[:<port>].

Supported URI schemes are:

• neo4j - Bolt with routing (unsecured)

• neo4j+s - Bolt with routing (secured with full certificate checks)

• neo4j+ssc - Bolt with routing (secured with no certificate checks)

• bolt - Bolt direct (unsecured)

• bolt+s - Bolt direct (secured with full certificate checks)

• bolt+ssc - Bolt direct (secured with no certificate checks)

• http - HTTP direct (unsecured)

• https - HTTP direct (secured with full certificate checks)

• http+s - HTTP direct (secured with full certificate checks)

• http+ssc - HTTP direct (secured with no certificate checks)

Individual settings

Any of the values below can be set as individual overrides. These are applied in an order from broadest to finest resolution; for example, auth would be applied before user and password.

uri

A full profile URI can be passed as a keyword argument. This is parsed identically to a URI passed into the profile argument.

scheme

Use a specific URI scheme.

protocol

The name of the protocol to use for communication. This can be either 'bolt' or 'http' and is not the same as the URI scheme, as it does not include security or verification indicators.

secure

Flag to indicate that a secure connection should be used. Connections are secured with TLS, using Python’s built-in ssl module.

verify

Flag to indicate that the server certificate should be fully verified. This applies only if the connection is secure.

address

Either a tuple (e.g. ('localhost', 7687)), an Address object, or a string (e.g. 'localhost:7687')

host

Database server host name.

port

Database server port.

port_number

Database server port number.

auth

Full authentication details, comprising both user name and password. This can be either a 2-tuple (e.g. ('user', 'password')), or a string (e.g. 'user:password').

user

Name of the user to authenticate as.

password

Password to use for authentication.

routing

Flag to indicate that connections should be routed across multiple servers, whenever available. This keyword is only available with service profiles, not simple connection profiles.

Profile objects

class py2neo.ConnectionProfile(profile=None, **settings)

Connection details for a Neo4j server.

A connection profile holds a set of values that describe how to connect to, and authorise against, a particular Neo4j server. The set of values held within a profile are available as either object attributes (e.g. profile.uri) or sub-items (e.g. profile["uri"]).

Profile instances are immutable, so can be safely hashed for inclusion within a set or as dictionary keys.

Parameters:

• profile – The base connection information, provided as a dictionary of settings, an existing ConnectionProfile object or a string URI. This value can also be None, in which case default base settings are used.

• settings – Optional set of individual overrides.

The full set of attributes and operations are described below.

profile == other

Return True if profile and other are equal.

profile != other

Return True if profile and other are unequal.

hash(profile)

Return a hash of profile based on its contained values.

profile[key]

Return a profile value using a string key. Key names are identical to the corresponding attribute names.

len(profile)

Return the number of values encoded within this profile.

dict(profile)

Coerce the profile into a dictionary of key-value pairs.

property address

The full socket Address of the remote server. If unspecified, and uninfluenced by environment variables, this will default to IPv4Address(('localhost', 7687)).

property auth

A 2-tuple of (user, password) representing the combined auth details. If unspecified, and uninfluenced by environment variables, this will default to ('neo4j', 'password').

classmethod from_file(filenames, section, prefix=None)

Load profile information from a configuration file.

The required file format is described in the standard library configparser module, and is similar to that used in Windows INI files.

Parameters:

• filenames –

• section –

• prefix –

Returns:

ConnectionProfile object created from the loaded configuration

property host

The host name or IP address of the remote server. If unspecified, and uninfluenced by environment variables, this will default to 'localhost'.

property password

The password which with to authorise. If unspecified, and uninfluenced by environment variables, this will default to 'password'.

property port

The port to which to connect on the remote server. This will be the correct port for the given protocol. If unspecified, and uninfluenced by environment variables, this will default to 7687 (for Bolt traffic).

property port_number

A variant of port guaranteed to be returned as a number. In some cases, the regular port value can be a string, this attempts to resolve or convert that value into a number. If unspecified, and uninfluenced by environment variables, this will default to 7687 (for Bolt traffic).

property protocol

The name of the underlying point-to-point protocol, derived from the URI scheme. This will either be 'bolt' or 'http', regardless of security and verification settings. If unspecified, and uninfluenced by environment variables, this will default to 'bolt'.

property scheme

The URI scheme for contacting the remote server. If unspecified, and uninfluenced by environment variables, this will default to 'bolt'.

property secure

A flag for whether or not to apply security to the connection. If unspecified, and uninfluenced by environment variables, this will default to True.

to_dict(include_password=False)

Convert this profile to a dictionary, optionally including password information.

Parameters:

include_password – if True then include the password in the return value, otherwise omit this information (default)

property uri

A full URI for the profile. This generally includes all other information, excluding auth details (for security reasons). If unspecified, and uninfluenced by environment variables, this will default to 'bolt://localhost:7687'.

property user

The user as whom to authorise. If unspecified, and uninfluenced by environment variables, this will default to 'neo4j'.

property verify

A flag for verification of remote server certificates. If unspecified, and uninfluenced by environment variables, this will default to True.

class py2neo.ServiceProfile(profile=None, **settings)

Bases: ConnectionProfile

Connection details for a full Neo4j service, such as a cluster or single instance. This class extends ConnectionProfile so also inherits all of its attributes.

property routing

Routing flag

property scheme

The URI scheme for contacting the remote server. If unspecified, and uninfluenced by environment variables, this will default to 'bolt'.