U aYf @sdZddlZddlmZddlmZddlmZddlmZdd lm Z dd lm Z dd lm Z Gd d d e d dddddddgZ ddZddZddZddZddZdS)aProvides the :class:`~sqlalchemy.engine.url.URL` class which encapsulates information about a database connection specification. The URL object is created automatically when :func:`~sqlalchemy.engine.create_engine` is called with a string argument; alternatively, the URL is a public-facing construct which can be used directly and is also accepted directly by ``create_engine()``. N)Dialect)exc)util)plugins)registry)collections_abc)compatcs2eZdZdZfddZedddddejfddZeddZ ed d Z ed d Z ed dZ d;ddZ fddZdddZddZejddZeddd?d!d"Zd@d#d$Zd%d&Zd'd(Zd)d*Zd+d,Zd-d.Zd/d0Zd1d2Zd3d4Zd5d6Z d7d8Z!gfd9d:Z"Z#S)AURLa Represent the components of a URL used to connect to a database. This object is suitable to be passed directly to a :func:`_sa.create_engine` call. The fields of the URL are parsed from a string by the :func:`.make_url` function. The string format of the URL is an RFC-1738-style string. To create a new :class:`_engine.URL` object, use the :func:`_engine.url.make_url` function. To construct a :class:`_engine.URL` programmatically, use the :meth:`_engine.URL.create` constructor. .. versionchanged:: 1.4 The :class:`_engine.URL` object is now an immutable object. To create a URL, use the :func:`_engine.make_url` or :meth:`_engine.URL.create` function / method. To modify a :class:`_engine.URL`, use methods like :meth:`_engine.URL.set` and :meth:`_engine.URL.update_query_dict` to return a new :class:`_engine.URL` object with modifications. See notes for this change at :ref:`change_5526`. :class:`_engine.URL` contains the following attributes: * :attr:`_engine.URL.drivername`: database backend and driver name, such as ``postgresql+psycopg2`` * :attr:`_engine.URL.username`: username string * :attr:`_engine.URL.password`: password, which is normally a string but may also be any object that has a ``__str__()`` method. * :attr:`_engine.URL.host`: string hostname * :attr:`_engine.URL.port`: integer port number * :attr:`_engine.URL.database`: string database name * :attr:`_engine.URL.query`: an immutable mapping representing the query string. contains strings for keys and either strings or tuples of strings for values. csD|s(t|dkr(tt|j|f||Stddtj||SdS)NzCalling URL() directly is deprecated and will be disabled in a future release. The public constructor for URL is now the URL.create() method.1.4)lensuperr __new__rZwarn_deprecatedcreate)selfargkw __class__VC:\Users\vtejo\AppData\Local\Temp\pip-unpacked-wheel-nyjtotrf\sqlalchemy\engine\url.pyrRsz URL.__new__Nc Cs@|||d||d|||d||||d||S)aCreate a new :class:`_engine.URL` object. :param drivername: the name of the database backend. This name will correspond to a module in sqlalchemy/databases or a third party plug-in. :param username: The user name. :param password: database password. May be a string or an object that can be stringified with ``str()``. :param host: The name of the host. :param port: The port number. :param database: The database name. :param 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 :func:`_sa.create_engine`. See also :attr:`_engine.URL.normalized_query` for a dictionary that is consistently string->list of string. :return: new :class:`_engine.URL` object. .. versionadded:: 1.4 The :class:`_engine.URL` object is now an **immutable named tuple**. In addition, the ``query`` dictionary is also immutable. To create a URL, use the :func:`_engine.url.make_url` or :meth:`_engine.URL.create` function/ method. To modify a :class:`_engine.URL`, use the :meth:`_engine.URL.set` and :meth:`_engine.URL.update_query` methods. drivernameusernamehostdatabase) _assert_str_assert_none_str _assert_port _str_dict)clsrrpasswordrportrqueryrrrr^s*    z URL.createcCs8|dkr dSz t|WStk r2tdYnXdS)Nz(Port argument must be an integer or None)int TypeError)r!r#rrrrs  zURL._assert_portcCs(|dkr |St|tjs$td||S)Nz%s must be a string isinstancer string_typesr&r!vZ paramnamerrrrs   zURL._assert_strcCs|dkr |S|||SN)rr*rrrrszURL._assert_none_strcsV|dkrtjSfddddt|tjr4|}n|}tfdd|DS)Ncs<t|tr|St|tjr0tfdd|DStddS)Nc3s|]}|VqdSr,r).0elem _assert_valuerr sz7URL._str_dict.._assert_value..z?Query dictionary values must be strings or sequences of strings)r(strr Sequencetupler&)valr/rrr0s  z$URL._str_dict.._assert_valuecSst|tjstd|S)Nz%Query dictionary keys must be stringsr')r+rrrrs z"URL._str_dict.._assert_strcsi|]\}}||qSrr)r-keyvaluerr0rr s z!URL._str_dict..)r EMPTY_DICTr(r r3items immutabledict)r!Zdict_ dict_itemsrr8rr s   z URL._str_dictc Csi}|dk r||d<|dk r$||d<|dk r4||d<|dk rD||d<|dk rT||d<|dk rd||d<|dk rt||d<|jf|S) areturn a new :class:`_engine.URL` object with modifications. Values are used if they are non-None. To set a value to ``None`` explicitly, use the :meth:`_engine.URL._replace` method adapted from ``namedtuple``. :param drivername: new drivername :param username: new username :param password: new password :param host: new hostname :param port: new port :param 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. :return: new :class:`_engine.URL` object. .. versionadded:: 1.4 .. seealso:: :meth:`_engine.URL.update_query_dict` Nrrr"rr#rr$)_replace) rrrr"rr#rr$rrrrsets #zURL.setc s|d|kr||dddD]}||kr||||qd|krP||dd|krj||d|d<tt|jf|S)z@Override ``namedtuple._replace()`` to provide argument checking.r)rrrr#r$)rrrr rr r>)rrnamerrrr>sz URL._replaceFcCs|jt||dS)a3Return a new :class:`_engine.URL` object with the :attr:`_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' :param query_string: a URL escaped query string, not including the question mark. :param 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. .. versionadded:: 1.4 .. seealso:: :attr:`_engine.URL.query` :meth:`_engine.URL.update_query_dict` append)update_query_pairsr parse_qsl)rZ query_stringrBrrrupdate_query_stringszURL.update_query_stringcs|ji}|D]:\}}||kr@t||||<|||q|||<q|ri}|D]:}|krt|t||||<qV||||<qV|fddt|Dn |j|}|j|dS)a|Return a new :class:`_engine.URL` object with the :attr:`_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' :param key_value_pairs: A sequence of tuples containing two strings each. :param 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. .. versionadded:: 1.4 .. seealso:: :attr:`_engine.URL.query` :meth:`_engine.URL.difference_update_query` :meth:`_engine.URL.set` csi|]}||qSrr)r-kZexisting_queryrrr9jsz*URL.update_query_pairs..r$)r$rto_listrBupdater? differenceunion)rZkey_value_pairsrBZnew_keysr6r7Z new_queryrFrrGrrC3s0!      zURL.update_query_pairscCs|j||dS)aReturn a new :class:`_engine.URL` object with the :attr:`_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' :param query_parameters: A dictionary with string keys and values that are either strings, or sequences of strings. :param 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. .. versionadded:: 1.4 .. seealso:: :attr:`_engine.URL.query` :meth:`_engine.URL.update_query_string` :meth:`_engine.URL.update_query_pairs` :meth:`_engine.URL.difference_update_query` :meth:`_engine.URL.set` rA)rCr;)rZquery_parametersrBrrrupdate_query_dictss+zURL.update_query_dictc sTt|jsStjjjjjj t fddtj |DS)a Remove the given names from the :attr:`_engine.URL.query` dictionary, returning the new :class:`_engine.URL`. E.g.:: url = url.difference_update_query(['foo', 'bar']) Equivalent to using :meth:`_engine.URL.set` as follows:: url = url.set( query={ key: url.query[key] for key in set(url.query).difference(['foo', 'bar']) } ) .. versionadded:: 1.4 .. seealso:: :attr:`_engine.URL.query` :meth:`_engine.URL.update_query_dict` :meth:`_engine.URL.set` csi|]}|j|qSrrH)r-r6rrrr9sz/URL.difference_update_query..) r? intersectionr$r rrr"rr#rrr<rK)rnamesrrNrdifference_update_querys zURL.difference_update_querycCstdd|jDS)aReturn the :attr:`_engine.URL.query` dictionary with values normalized into sequences. As the :attr:`_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',)}) cSs&i|]\}}|t|ts|fn|qSr)r(r4)r-rFr+rrrr9sz(URL.normalized_query..)rr<r$r;rNrrrnormalized_querys zURL.normalized_queryr zThe :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.TcCs |j|dS)zRender this :class:`_engine.URL` object as a string. :param hide_password: Defaults to True. The password is not shown in the string unless this is set to False.  hide_passwordrender_as_string)rrTrrr __to_string__s zURL.__to_string__csjd}jdk rR|tj7}jdk rJ|d|r8dn ttj7}|d7}jdk rdjkrv|dj7}n |j7}jdk r|dtj7}jdk r|dj7}jrt j}| |dd fd d |D7}|S) aRRender this :class:`_engine.URL` object as a string. This method is used when the ``__str__()`` or ``__repr__()`` methods are used. The method directly includes additional options. :param hide_password: Defaults to True. The password is not shown in the string unless this is set to False. z://N:z***@z[%s]/?&c3s<|]4}tj|D]}dt|t|fVqqdS)z%s=%sN)rrIr$ quote_plus)r-rFelementrNrrr1sz'URL.render_as_string..) rr_rfc_1738_quoter"r2rr#rr$listsortjoin)rrTskeysrrNrrVs2           zURL.render_as_stringcCs |jddS)NFrSrUrNrrr__str__$sz URL.__str__cCs|Sr,rUrNrrr__repr__'sz URL.__repr__cCs tt|Sr,)hashr2rNrrr__hash__*sz URL.__hash__cCs^t|to\|j|jko\|j|jko\|j|jko\|j|jko\|j|jko\|j|jko\|j|jkSr,) r(r rrr"rrr$r#rotherrrr__eq__-s        z URL.__eq__cCs ||k Sr,rrirrr__ne__9sz URL.__ne__cCs$d|jkr|jS|jddSdS)zReturn the backend name. This is the name that corresponds to the database backend in use, and is the portion of the :attr:`_engine.URL.drivername` that is to the left of the plus sign. +rN)rsplitrNrrrget_backend_name<s zURL.get_backend_namecCs(d|jkr|jS|jddSdS)aReturn the backend name. This is the name that corresponds to the DBAPI driver in use, and is the portion of the :attr:`_engine.URL.drivername` that is to the right of the plus sign. If the :attr:`_engine.URL.drivername` does not include a plus sign, then the default :class:`_engine.Dialect` for this :class:`_engine.URL` is imported in order to get the driver name. rmrN)r get_dialectZdriverrnrNrrrget_driver_nameIs  zURL.get_driver_namecstjdd}|dg7}tfdd|D}ddg}|D]}||}|dk rR|}qRdd||fS)Npluginrrcsg|]}t|qSr)rload)r-Z plugin_namekwargsrrr asz,URL._instantiate_plugins..)rrIr$getdictrQZ update_urlpop)rruZ plugin_namesZloaded_pluginsurrZnew_urrtr_instantiate_plugins[s   zURL._instantiate_pluginscCsZd|jkr|j}n|jdd}t|}t|drRt|jtrRt|jt rR|jS|SdS)zReturn 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. rm.dialectN) rreplacerrshasattrr(r}type issubclassr)rr@r!rrr_get_entrypointqs    zURL._get_entrypointcCs|}||}|S)zoReturn the SQLAlchemy :class:`_engine.Dialect` class corresponding to this URL's driver name. )rZget_dialect_cls)rZ entrypointZ dialect_clsrrrrps zURL.get_dialectcKshi}dddddg}|D]L}|r*|d}n||kr<||}n|}|dk rt||drt||||<q|S) a2Translate 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. :param \**kw: Optional, alternate key names for url attributes. :param names: Deprecated. Same purpose as the keyword-based alternate names, but correlates the name to the original positionally. rrrr"r#rNF)rygetattr)rrPrZ translatedZattribute_namesZsnamer@rrrtranslate_connect_argss  zURL.translate_connect_args)NNNNNNN)F)F)F)T)T)$__name__ __module__ __qualname____doc__r classmethodrr:rrrrr r?r>rErCrMrQZmemoized_propertyrR deprecatedrWrVrerfrhrkrlrorqr{rrpr __classcell__rrrrr sd(  3    $ 5  ! @ -0  '   r rrr"rr#rr$cCst|tjrt|S|SdS)zGiven a string or unicode instance, produce a new URL instance. The given string is parsed according to the RFC 1738 spec. If an existing URL object is passed, just returns the object. N)r(rr)_parse_rfc1738_args)Z name_or_urlrrrmake_urls rc Cs>tdtj}||}|dk r,|}|ddk ri}t|dD]J\}}tjr`|d}||krt ||||<|| |qH|||<qHnd}||d<|ddk rt |d|d<|ddk rt |d|d<| d}| d}|p||d<| d }|d rt |d |d <tj|f|Std |dS) Na (?P[\w\+]+):// (?: (?P[^:/]*) (?::(?P[^@]*))? @)? (?: (?: \[(?P[^/\?]+)\] | (?P[^/:\?]+) )? (?::(?P[^/\?]*))? )? (?:/(?P[^\?]*))? (?:\?(?P.*))? r$asciirr"ipv4hostipv6hostrr@r#z,Could not parse rfc1738 URL from string '%s')recompileXmatch groupdictrrDZpy2kencoderIrB_rfc_1738_unquoteryr%r rr ArgumentError) r@patternm componentsr$r6r7rrrrrrs@            rcCstddd|S)Nz[:@/]cSsdt|dS)Nz%%%Xr)ordgroup)rrrrz!_rfc_1738_quote..)rsubtextrrrr_sr_cCs t|Sr,)runquoterrrrrsrcCsHtd|}|dk r@|dd\}}tt|}t|f|SdSdS)Nz (\w+)://(.*)rr)rrrrxrrDr )r@rargsoptsrrr_parse_keyvalue_argss  r)rrZ interfacesrrrZdialectsrrr r namedtupler rrr_rrrrrrs>          =