# `uri_parser` – Tools to parse and validate a MongoDB URI

Tools to parse and validate a MongoDB URI.

pymongo.uri_parser.parse_host(entity, default_port=27017)

  Validates a host string

  Returns a 2-tuple of host followed by port where port is default_port if it wasn’t specified in the string.

  Parameters:

    - entity (str) – A host or host:port string where host could be a hostname or IP address.

    - default_port (int | None) – The port number to use when one wasn’t specified in entity.

  Return type:

    Tuple[str, int | None]

pymongo.uri_parser.parse_ipv6_literal_host(entity, default_port)

  Validates an IPv6 literal host:port string.

  Returns a 2-tuple of IPv6 literal followed by port where port is default_port if it wasn’t specified in entity.

  Parameters:

    - entity (str) – A string that represents an IPv6 literal enclosed in braces (e.g. ‘[::1]’ or ‘[::1]:27017’).

    - default_port (int | None) – The port number to use when one wasn’t specified in entity.

  Return type:

    tuple[str, int | str | None]

pymongo.uri_parser.parse_uri(uri, default_port=27017, validate=True, warn=False, normalize=True, connect_timeout=None, srv_service_name=None, srv_max_hosts=None)

  Parse and validate a MongoDB URI.

  Returns a dict of the form:

      {
          'nodelist': <list of (host, port) tuples>,
          'username': <username> or None,
          'password': <password> or None,
          'database': <database name> or None,
          'collection': <collection name> or None,
          'options': <dict of MongoDB URI options>,
          'fqdn': <fqdn of the MongoDB+SRV URI> or None
      }

  If the URI scheme is “mongodb+srv://” DNS SRV and TXT lookups will be done to build nodelist and options.

  Parameters:

    - uri (str) – The MongoDB URI to parse.

    - default_port (int | None) – The port number to use when one wasn’t specified for a host in the URI.

    - validate (bool) – If `True` (the default), validate and normalize all options. Default: `True`.

    - warn (bool) – When validating, if `True` then will warn the user then ignore any invalid options or values. If `False`, validation will error when options are unsupported or values are invalid. Default: `False`.

    - normalize (bool) – If `True`, convert names of URI options to their internally-used names. Default: `True`.

    - connect_timeout (float | None) – The maximum time in milliseconds to wait for a response from the DNS server.

    - srv_service_name (str | None) – A custom SRV service name

    - srv_max_hosts (int | None)

  Return type:

    dict[str, Any]

  Changed in version 4.14: `options` is now type `dict` as opposed to a `_CaseInsensitiveDictionary`.

  Changed in version 4.6: The delimiting slash (`/`) between hosts and connection options is now optional. For example, “mongodb://example.com?tls=true” is now a valid URI.

  Changed in version 4.0: To better follow RFC 3986, unquoted percent signs (“%”) are no longer supported.

  Changed in version 3.9: Added the `normalize` parameter.

  Changed in version 3.6: Added support for mongodb+srv:// URIs.

  Changed in version 3.5: Return the original value of the `readPreference` MongoDB URI option instead of the validated read preference mode.

  Changed in version 3.1: `warn` added so invalid options can be ignored.

pymongo.uri_parser.parse_userinfo(userinfo)

  Validates the format of user information in a MongoDB URI. Reserved characters that are gen-delimiters (“:”, “/”, “?”, “#”, “[“, “]”, “@”) as per RFC 3986 must be escaped.

  Returns a 2-tuple containing the unescaped username followed by the unescaped password.

  Parameters:

    userinfo (str) – A string of the form <username>:<password>

  Return type:

    tuple[str, str]

pymongo.uri_parser.split_hosts(hosts, default_port=27017)

  Takes a string of the form host1[:port],host2[:port]… and splits it into (host, port) tuples. If [:port] isn’t present the default_port is used.

  Returns a set of 2-tuples containing the host name (or IP) followed by port number.

  Parameters:

    - hosts (str) – A string of the form host1[:port],host2[:port],…

    - default_port (int | None) – The port number to use when one wasn’t specified for a host.

  Return type:

    list[Tuple[str, int | None]]

pymongo.uri_parser.split_options(opts, validate=True, warn=False, normalize=True)

  Takes the options portion of a MongoDB URI, validates each option and returns the options in a dictionary.

  Parameters:

    - opt – A string representing MongoDB URI options.

    - validate (bool) – If `True` (the default), validate and normalize all options.

    - warn (bool) – If `False` (the default), suppress all warnings raised during validation of options.

    - normalize (bool) – If `True` (the default), renames all options to their internally-used names.

    - opts (str)

  Return type:

    MutableMapping[str, Any]

pymongo.uri_parser.validate_options(opts, warn=False)

  Validates and normalizes options passed in a MongoDB URI.

  Returns a new dictionary of validated and normalized options. If warn is False then errors will be thrown for invalid options, otherwise they will be ignored and a warning will be issued.

  Parameters:

    - opts (Mapping[str, Any]) – A dict of MongoDB URI options.

    - warn (bool) – If `True` then warnings will be logged and invalid options will be ignored. Otherwise invalid options will cause errors.

  Return type:

    MutableMapping[str, Any]