# Connection Parameters

To maintain flexibility in how you specify the connection information required for your applications to properly connect to RabbitMQ, pika implements two classes for encapsulating the information, `ConnectionParameters` and `URLParameters`.

## ConnectionParameters

The classic object for specifying all of the connection parameters required to connect to RabbitMQ, `ConnectionParameters` provides attributes for tweaking every possible connection option.

Example:

    import pika

    # Set the connection parameters to connect to rabbit-server1 on port 5672
    # on the / virtual host using the username "guest" and password "guest"
    credentials = pika.PlainCredentials('guest', 'guest')
    parameters = pika.ConnectionParameters('rabbit-server1',
                                           5672,
                                           '/',
                                           credentials)

class pika.connection.ConnectionParameters(host: DefaultT[str] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, port: DefaultT[int] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, virtual_host: DefaultT[str] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, credentials: DefaultT[Union[pika.credentials.PlainCredentials, pika.credentials.ExternalCredentials]] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, channel_max: DefaultT[int] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, frame_max: DefaultT[int] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, heartbeat: DefaultT[Optional[Union[int, Callable[[Connection, float], int]]]] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, ssl_options: DefaultT[Optional[SSLOptions]] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, connection_attempts: DefaultT[int] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, retry_delay: DefaultT[float] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, socket_timeout: DefaultT[Optional[float]] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, stack_timeout: DefaultT[Optional[float]] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, locale: DefaultT[str] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, blocked_connection_timeout: DefaultT[Optional[float]] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, client_properties: DefaultT[Optional[Dict[str, Any]]] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, tcp_options: DefaultT[Optional[Dict[str, Any]]] = <class 'pika.connection.ConnectionParameters._DEFAULT'>, **kwargs: Any)

  Connection parameters object that is passed into the connection adapter upon construction.

  property blocked_connection_timeout: float | None
    Returns:

      blocked connection timeout. Defaults to DEFAULT_BLOCKED_CONNECTION_TIMEOUT.

    Return type:

      float|None

  property channel_max: int
    Returns:

      max preferred number of channels. Defaults to DEFAULT_CHANNEL_MAX.

    Return type:

      int

  property client_properties: Dict[str, Any] | None
    Returns:

      client properties used to override the fields in the default client properties reported to RabbitMQ via Connection.StartOk method. Defaults to DEFAULT_CLIENT_PROPERTIES.

    Return type:

      dict|None

  property connection_attempts: int
    Returns:

      number of socket connection attempts. Defaults to DEFAULT_CONNECTION_ATTEMPTS. See also retry_delay.

    Return type:

      int

  property credentials: PlainCredentials | ExternalCredentials
    Return type:

      one of the classes from pika.credentials.VALID_TYPES. Defaults to DEFAULT_CREDENTIALS.

  property frame_max: int
    Returns:

      desired maximum AMQP frame size to use. Defaults to DEFAULT_FRAME_MAX.

    Return type:

      int

  property heartbeat: int | Callable[[Connection, float], int] | None
    Returns:

      AMQP connection heartbeat timeout value for negotiation during connection tuning or callable which is invoked during connection tuning. None to accept broker’s value. 0 turns heartbeat off. Defaults to DEFAULT_HEARTBEAT_TIMEOUT.

    Return type:

      int|callable|None

  property host: str
    Returns:

      hostname or ip address of broker. Defaults to DEFAULT_HOST.

    Return type:

      str

  property locale: str
    Returns:

      locale value to pass to broker; e.g., ‘en_US’. Defaults to DEFAULT_LOCALE.

    Return type:

      str

  property retry_delay: float
    Returns:

      interval between socket connection attempts; see also connection_attempts. Defaults to DEFAULT_RETRY_DELAY.

    Return type:

      float

  property socket_timeout: float | None
    Returns:

      socket connect timeout in seconds. Defaults to DEFAULT_SOCKET_TIMEOUT. The value None disables this timeout.

    Return type:

      float|None

  property stack_timeout: float | None
    Returns:

      full protocol stack TCP/[SSL]/AMQP bring-up timeout in seconds. Defaults to DEFAULT_STACK_TIMEOUT. The value None disables this timeout.

    Return type:

      float

  property ssl_options: SSLOptions | None
    Returns:

      None for plaintext or pika.SSLOptions instance for SSL/TLS.

    Return type:

      `pika.SSLOptions`|None

  property port: int
    Returns:

      port number of broker’s listening socket. Defaults to DEFAULT_PORT.

    Return type:

      int

  property virtual_host: str
    Returns:

      rabbitmq virtual host name. Defaults to DEFAULT_VIRTUAL_HOST.

    Return type:

      str

  property tcp_options: Dict[str, int] | None
    Returns:

      None or a dict of options to pass to the underlying socket

    Return type:

      dict|None

## URLParameters

The `URLParameters` class allows you to pass in an AMQP URL when creating the object and supports the host, port, virtual host, ssl, username and password in the base URL and other options are passed in via query parameters.

Example:

    import pika

    # Set the connection parameters to connect to rabbit-server1 on port 5672
    # on the / virtual host using the username "guest" and password "guest"
    parameters = pika.URLParameters('amqp://guest:guest@rabbit-server1:5672/%2F')

class pika.connection.URLParameters(url: str)

  Connect to RabbitMQ via an AMQP URL in the format:

      amqp://username:password@host:port/<virtual_host>[?query-string]

  Ensure that the virtual host is URI encoded when specified. For example if you are using the default “/” virtual host, the value should be %2f.

  See Parameters for default values.

  Valid query string values are:

  > - channel_max:

  >     Override the default maximum channel count value

  > - client_properties:

  >     dict of client properties used to override the fields in the default client properties reported to RabbitMQ via Connection.StartOk method

  > - connection_attempts:

  >     Specify how many times pika should try and reconnect before it gives up

  > - frame_max:

  >     Override the default maximum frame size for communication

  > - heartbeat:

  >     Desired connection heartbeat timeout for negotiation. If not present the broker’s value is accepted. 0 turns heartbeat off.

  > - locale:

  >     Override the default en_US locale value

  > - ssl_options:

  >     None for plaintext; for SSL: dict of public ssl context-related arguments that may be passed to `ssl.SSLSocket()` as kwargs, except sock, server_side,`do_handshake_on_connect`, family, type, proto, fileno.

  > - retry_delay:

  >     The number of seconds to sleep before attempting to connect on connection failure.

  > - socket_timeout:

  >     Socket connect timeout value in seconds (float or int)

  > - stack_timeout:

  >     Positive full protocol stack (TCP/[SSL]/AMQP) bring-up timeout in seconds. It’s recommended to set this value higher than socket_timeout.

  > - blocked_connection_timeout:

  >     Set the timeout, in seconds, that the connection may remain blocked (triggered by Connection.Blocked from broker); if the timeout expires before connection becomes unblocked, the connection will be torn down, triggering the connection’s on_close_callback

  > - tcp_options:

  >     Set the tcp options for the underlying socket.

  Parameters:

    url (str) – The AMQP URL to connect to

  property ssl_options: SSLOptions | None
    Returns:

      None for plaintext or pika.SSLOptions instance for SSL/TLS.

    Return type:

      `pika.SSLOptions`|None

  property host: str
    Returns:

      hostname or ip address of broker. Defaults to DEFAULT_HOST.

    Return type:

      str

  property port: int
    Returns:

      port number of broker’s listening socket. Defaults to DEFAULT_PORT.

    Return type:

      int

  property credentials: PlainCredentials | ExternalCredentials
    Return type:

      one of the classes from pika.credentials.VALID_TYPES. Defaults to DEFAULT_CREDENTIALS.

  property virtual_host: str
    Returns:

      rabbitmq virtual host name. Defaults to DEFAULT_VIRTUAL_HOST.

    Return type:

      str

  property blocked_connection_timeout: float | None
    Returns:

      blocked connection timeout. Defaults to DEFAULT_BLOCKED_CONNECTION_TIMEOUT.

    Return type:

      float|None

  property channel_max: int
    Returns:

      max preferred number of channels. Defaults to DEFAULT_CHANNEL_MAX.

    Return type:

      int

  property client_properties: Dict[str, Any] | None
    Returns:

      client properties used to override the fields in the default client properties reported to RabbitMQ via Connection.StartOk method. Defaults to DEFAULT_CLIENT_PROPERTIES.

    Return type:

      dict|None

  property connection_attempts: int
    Returns:

      number of socket connection attempts. Defaults to DEFAULT_CONNECTION_ATTEMPTS. See also retry_delay.

    Return type:

      int

  property frame_max: int
    Returns:

      desired maximum AMQP frame size to use. Defaults to DEFAULT_FRAME_MAX.

    Return type:

      int

  property heartbeat: int | Callable[[Connection, float], int] | None
    Returns:

      AMQP connection heartbeat timeout value for negotiation during connection tuning or callable which is invoked during connection tuning. None to accept broker’s value. 0 turns heartbeat off. Defaults to DEFAULT_HEARTBEAT_TIMEOUT.

    Return type:

      int|callable|None

  property locale: str
    Returns:

      locale value to pass to broker; e.g., ‘en_US’. Defaults to DEFAULT_LOCALE.

    Return type:

      str

  property retry_delay: float
    Returns:

      interval between socket connection attempts; see also connection_attempts. Defaults to DEFAULT_RETRY_DELAY.

    Return type:

      float

  property socket_timeout: float | None
    Returns:

      socket connect timeout in seconds. Defaults to DEFAULT_SOCKET_TIMEOUT. The value None disables this timeout.

    Return type:

      float|None

  property stack_timeout: float | None
    Returns:

      full protocol stack TCP/[SSL]/AMQP bring-up timeout in seconds. Defaults to DEFAULT_STACK_TIMEOUT. The value None disables this timeout.

    Return type:

      float

  property tcp_options: Dict[str, int] | None
    Returns:

      None or a dict of options to pass to the underlying socket

    Return type:

      dict|None