class_docstr: Represent the components of a URL used to connect to a database.
  
  URLs are typically constructed from a fully formatted URL string, where the
  :func:`.make_url` function is used internally by the
  :func:`_sa.create_engine` function in order to parse the URL string into
  its individual components, which are then used to construct a new
  :class:`.URL` object. When parsing from a formatted URL string, the parsing
  format generally follows
  `RFC-1738 <https://www.ietf.org/rfc/rfc1738.txt>`_, with some exceptions.
  
  A :class:`_engine.URL` object may also be produced directly, either by
  using the :func:`.make_url` function with a fully formed URL string, or
  by using the :meth:`_engine.URL.create` constructor in order
  to construct a :class:`_engine.URL` programmatically given individual
  fields. The resulting :class:`.URL` object may be passed directly to
  :func:`_sa.create_engine` in place of a string argument, which will bypass
  the usage of :func:`.make_url` within the engine's creation process.
  
  .. 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`.
  
  .. seealso::
  
      :ref:`database_urls`
  
  :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 string
  * :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.
class_docstr_tok: ["Represent","the","components","of","a","URL","used","to","connect","to","a","database",".","URLs","are","typically","constructed","from","a","fully","formatted","URL","string",",","where","the",":","func",":","`",".make_url","`","function","is","used","internally","by","the",":","func",":","`","_sa.create_engine","`","function","in","order","to","parse","the","URL","string","into","its","individual","components",",","which","are","then","used","to","construct","a","new",":","class",":","`",".URL","`","object",".","When","parsing","from","a","formatted","URL","string",",","the","parsing","format","generally","follows","`","RFC-1738","<","https",":","\/\/www.ietf.org\/rfc\/rfc1738.txt",">","`","_",",","with","some","exceptions",".","A",":","class",":","`","_engine.URL","`","object","may","also","be","produced","directly",",","either","by","using","the",":","func",":","`",".make_url","`","function","with","a","fully","formed","URL","string",",","or","by","using","the",":","meth",":","`","_engine.URL.create","`","constructor","in","order","to","construct","a",":","class",":","`","_engine.URL","`","programmatically","given","individual","fields",".","The","resulting",":","class",":","`",".URL","`","object","may","be","passed","directly","to",":","func",":","`","_sa.create_engine","`","in","place","of","a","string","argument",",","which","will","bypass","the","usage","of",":","func",":","`",".make_url","`","within","the","engine","'s","creation","process",".","..","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","`",".","..","seealso",":",":",":","ref",":","`","database_urls","`",":","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","string","*",":","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","."]
docstr: Create a new :class:`_engine.URL` object.
  
  .. seealso::
  
      :ref:`database_urls`
  
  :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.  Is typically a string, but may
    also be an object that can be stringified with ``str()``.
  
    .. note:: The password string should **not** be URL encoded when
       passed as an argument to :meth:`_engine.URL.create`; the string
       should contain the password characters exactly as they would be
       typed.
  
    .. note::  A password-producing object will be stringified only
       **once** per :class:`_engine.Engine` object.  For dynamic password
       generation per connect, see :ref:`engines_dynamic_tokens`.
  
  :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.
code: def create(
      cls,
      drivername: str,
      username: Optional[str] = None,
      password: Optional[str] = None,
      host: Optional[str] = None,
      port: Optional[int] = None,
      database: Optional[str] = None,
      query: Mapping[str, Union[Sequence[str], str]] = util.EMPTY_DICT,
  ) -> URL:
      """Create a new :class:`_engine.URL` object.
  
      .. seealso::
  
          :ref:`database_urls`
  
      :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.  Is typically a string, but may
        also be an object that can be stringified with ``str()``.
  
        .. note:: The password string should **not** be URL encoded when
           passed as an argument to :meth:`_engine.URL.create`; the string
           should contain the password characters exactly as they would be
           typed.
  
        .. note::  A password-producing object will be stringified only
           **once** per :class:`_engine.Engine` object.  For dynamic password
           generation per connect, see :ref:`engines_dynamic_tokens`.
  
      :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.
  
      """
  
      return cls(
          cls._assert_str(drivername, "drivername"),
          cls._assert_none_str(username, "username"),
          password,
          cls._assert_none_str(host, "host"),
          cls._assert_port(port),
          cls._assert_none_str(database, "database"),
          cls._str_dict(query),
      )
  
imports: from __future__ import annotations
  import collections.abc
  import re
  from typing import Any
  from typing import cast
  from typing import Dict
  from typing import Iterable
  from typing import List
  from typing import Mapping
  from typing import NamedTuple
  from typing import Optional
  from typing import overload
  from typing import Sequence
  from typing import Tuple
  from typing import Type
  from typing import Union
  from urllib.parse import parse_qsl
  from urllib.parse import quote
  from urllib.parse import quote_plus
  from urllib.parse import unquote
  from .interfaces import Dialect
  from ..None import exc
  from ..None import util
  from ..dialects import plugins
  from ..dialects import registry
label_desc: Use image node_id 1 for calling the URL obj's underlying member method code with example usage: obj.create(cls, drivername, username, password, host, port, database, query) and returns: cls