sqlalchemy.engine.url.URL

class documentation

class URL(util.namedtuple('URL', ['drivername', 'username', 'password', 'host', 'port', 'database', 'query'])):

Represent the components of a URL used to connect to a database.

This object is suitable to be passed directly to a _sa.create_engine call. The fields of the URL are parsed from a string by the .make_url function. The string format of the URL is an RFC-1738-style string.

To create a new _engine.URL object, use the _engine.url.make_url function. To construct a _engine.URL programmatically, use the _engine.URL.create constructor.

Changed in version 1.4: The _engine.URL object is now an immutable object. To create a URL, use the _engine.make_url or _engine.URL.create function / method. To modify a _engine.URL, use methods like _engine.URL.set and _engine.URL.update_query_dict to return a new _engine.URL object with modifications. See notes for this change at :ref:`change_5526`.

_engine.URL contains the following attributes:

_engine.URL.drivername: database backend and driver name, such as postgresql+psycopg2
_engine.URL.username: username string
_engine.URL.password: password string, or object that includes a __str__() method that produces a password.

Note

A password-producing object will be stringified only once per _engine.Engine object. For dynamic password generation per connect, see :ref:`engines_dynamic_tokens`.
_engine.URL.host: string hostname
_engine.URL.port: integer port number
_engine.URL.database: string database name
_engine.URL.query: an immutable mapping representing the query string. contains strings for keys and either strings or tuples of strings for values.

Class Method	`create`	Create a new `_engine.URL` object.
Class Method	`_assert_none_str`	Undocumented
Class Method	`_assert_port`	Undocumented
Class Method	`_assert_str`	Undocumented
Class Method	`_str_dict`	Undocumented
Method	`__copy__`	Undocumented
Method	`__deepcopy__`	Undocumented
Method	`__eq__`	Undocumented
Method	`__hash__`	Undocumented
Method	`__ne__`	Undocumented
Method	`__new__`	Undocumented
Method	`__repr__`	Undocumented
Method	`__str__`	Undocumented
Method	`__to_string__`	Render this `_engine.URL` object as a string.
Method	`_get_entrypoint`	Return the "entry point" dialect class.
Method	`_instantiate_plugins`	Undocumented
Method	`_replace`	Override `namedtuple._replace()` to provide argument checking.
Method	`difference_update_query`	Remove the given names from the `_engine.URL.query` dictionary, returning the new `_engine.URL`.
Method	`get_backend_name`	Return the backend name.
Method	`get_dialect`	Return the SQLAlchemy `_engine.Dialect` class corresponding to this URL's driver name.
Method	`get_driver_name`	Return the backend name.
Method	`render_as_string`	Render this `_engine.URL` object as a string.
Method	`set`	return a new `_engine.URL` object with modifications.
Method	`translate_connect_args`	Translate url attributes into a dictionary of connection arguments.
Method	`update_query_dict`	Return a new `_engine.URL` object with the `_engine.URL.query` parameter dictionary updated by the given dictionary.
Method	`update_query_pairs`	Return a new `_engine.URL` object with the `_engine.URL.query` parameter dictionary updated by the given sequence of key/value pairs
Method	`update_query_string`	Return a new `_engine.URL` object with the `_engine.URL.query` parameter dictionary updated by the given query string.
Property	`normalized_query`	Return the `_engine.URL.query` dictionary with values normalized into sequences.

@classmethod
def create(cls, drivername, username=None, password=None, host=None, port=None, database=None, query=util.EMPTY_DICT):

Create a new _engine.URL object.

New in version 1.4: The _engine.URL object is now an immutable named tuple. In addition, the query dictionary is also immutable. To create a URL, use the _engine.url.make_url or _engine.URL.create function/ method. To modify a _engine.URL, use the _engine.URL.set and _engine.URL.update_query methods.

Parameters
drivername	the name of the database backend. This name will correspond to a module in sqlalchemy/databases or a third party plug-in.
username	The user name.
password	database password. Is typically a string, but may also be an object that can be stringified with `str()`. Note A password-producing object will be stringified only once per `_engine.Engine` object. For dynamic password generation per connect, see :ref:`engines_dynamic_tokens`.
host	The name of the host.
port	The port number.
database	The database name.
query	A dictionary of string keys to string values to be passed to the dialect and/or the DBAPI upon connect. To specify non-string parameters to a Python DBAPI directly, use the :paramref:`_sa.create_engine.connect_args` parameter to `_sa.create_engine`. See also `_engine.URL.normalized_query` for a dictionary that is consistently string->list of string.
Returns
new `_engine.URL` object.

@classmethod
def _assert_none_str(cls, v, paramname):

Undocumented

@classmethod
def _assert_port(cls, port):

Undocumented

@classmethod
def _assert_str(cls, v, paramname):

Undocumented

@classmethod
def _str_dict(cls, dict_):

Undocumented

def __copy__(self):

Undocumented

def __deepcopy__(self, memo):

Undocumented

def __eq__(self, other):

Undocumented

def __hash__(self):

Undocumented

def __ne__(self, other):

Undocumented

def __new__(self, *arg, **kw):

Undocumented

def __repr__(self):

Undocumented

def __str__(self):

Undocumented

@util.deprecated('1.4', 'The :meth:`_engine.URL.__to_string__ method is deprecated and will be removed in a future release. Please use the :meth:`_engine.URL.render_as_string` method.')
def __to_string__(self, hide_password=True):

Render this _engine.URL object as a string.

Parameters
hide_password	Defaults to True. The password is not shown in the string unless this is set to False.

def _get_entrypoint(self):

Return the "entry point" dialect class.

This is normally the dialect itself except in the case when the returned class implements the get_dialect_cls() method.

def _instantiate_plugins(self, kwargs):

Undocumented

def _replace(self, **kw):

Override namedtuple._replace() to provide argument checking.

def difference_update_query(self, names):

Remove the given names from the _engine.URL.query dictionary, returning the new _engine.URL.

E.g.:

url = url.difference_update_query(['foo', 'bar'])

Equivalent to using _engine.URL.set as follows:

url = url.set(
    query={
        key: url.query[key]
        for key in set(url.query).difference(['foo', 'bar'])
    }
)

New in version 1.4.

See Also

_engine.URL.query

_engine.URL.update_query_dict

_engine.URL.set

def get_backend_name(self):

Return the backend name.

This is the name that corresponds to the database backend in use, and is the portion of the _engine.URL.drivername that is to the left of the plus sign.

def get_dialect(self):

Return the SQLAlchemy _engine.Dialect class corresponding to this URL's driver name.

def get_driver_name(self):

Return the backend name.

This is the name that corresponds to the DBAPI driver in use, and is the portion of the _engine.URL.drivername that is to the right of the plus sign.

If the _engine.URL.drivername does not include a plus sign, then the default _engine.Dialect for this _engine.URL is imported in order to get the driver name.

def render_as_string(self, hide_password=True):

Render this _engine.URL object as a string.

This method is used when the __str__() or __repr__() methods are used. The method directly includes additional options.

Parameters
hide_password	Defaults to True. The password is not shown in the string unless this is set to False.

def set(self, drivername=None, username=None, password=None, host=None, port=None, database=None, query=None):

return a new _engine.URL object with modifications.

Values are used if they are non-None. To set a value to None explicitly, use the _engine.URL._replace method adapted from namedtuple.

New in version 1.4.

See Also

_engine.URL.update_query_dict

Parameters
drivername	new drivername
username	new username
password	new password
host	new hostname
port	new port
database	Undocumented
query	new query parameters, passed a dict of string keys referring to string or sequence of string values. Fully replaces the previous list of arguments.
Returns
new `_engine.URL` object.

def translate_connect_args(self, names=None, **kw):

Translate url attributes into a dictionary of connection arguments.

Returns attributes of this url (host, database, username, password, port) as a plain dictionary. The attribute names are used as the keys by default. Unset or false attributes are omitted from the final dictionary.

Parameters
names	Deprecated. Same purpose as the keyword-based alternate names, but correlates the name to the original positionally.
**kw	Optional, alternate key names for url attributes.

def update_query_dict(self, query_parameters, append=False):

Return a new _engine.URL object with the _engine.URL.query parameter dictionary updated by the given dictionary.

The dictionary typically contains string keys and string values. In order to represent a query parameter that is expressed multiple times, pass a sequence of string values.

E.g.:

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql://user:pass@host/dbname")
>>> url = url.update_query_dict({"alt_host": ["host1", "host2"], "ssl_cipher": "/path/to/crt"})
>>> str(url)
'postgresql://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'

New in version 1.4.

See Also

_engine.URL.query

_engine.URL.update_query_string

_engine.URL.update_query_pairs

_engine.URL.difference_update_query

_engine.URL.set

Parameters
query_parameters	A dictionary with string keys and values that are either strings, or sequences of strings.
append	if True, parameters in the existing query string will not be removed; new parameters will be in addition to those present. If left at its default of False, keys present in the given query parameters will replace those of the existing query string.

def update_query_pairs(self, key_value_pairs, append=False):

Return a new _engine.URL object with the _engine.URL.query parameter dictionary updated by the given sequence of key/value pairs

E.g.:

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql://user:pass@host/dbname")
>>> url = url.update_query_pairs([("alt_host", "host1"), ("alt_host", "host2"), ("ssl_cipher", "/path/to/crt")])
>>> str(url)
'postgresql://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'

New in version 1.4.

See Also

_engine.URL.query

_engine.URL.difference_update_query

_engine.URL.set

Parameters
key_value_pairs	A sequence of tuples containing two strings each.
append	if True, parameters in the existing query string will not be removed; new parameters will be in addition to those present. If left at its default of False, keys present in the given query parameters will replace those of the existing query string.

def update_query_string(self, query_string, append=False):

Return a new _engine.URL object with the _engine.URL.query parameter dictionary updated by the given query string.

E.g.:

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql://user:pass@host/dbname")
>>> url = url.update_query_string("alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt")
>>> str(url)
'postgresql://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'

New in version 1.4.

See Also

_engine.URL.query

_engine.URL.update_query_dict

Parameters
query_string	a URL escaped query string, not including the question mark.
append	if True, parameters in the existing query string will not be removed; new parameters will be in addition to those present. If left at its default of False, keys present in the given query parameters will replace those of the existing query string.

@util.memoized_property
normalized_query =

Return the _engine.URL.query dictionary with values normalized into sequences.

As the _engine.URL.query dictionary may contain either string values or sequences of string values to differentiate between parameters that are specified multiple times in the query string, code that needs to handle multiple parameters generically will wish to use this attribute so that all parameters present are presented as sequences. Inspiration is from Python's urllib.parse.parse_qs function. E.g.:

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt")
>>> url.query
immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': '/path/to/crt'})
>>> url.normalized_query
immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': ('/path/to/crt',)})