class_docstr: A `Composable` representing a snippet of SQL statement.
  
  `!SQL` exposes `join()` and `format()` methods useful to create a template
  where to merge variable parts of a query (for instance field or table
  names).
  
  The *string* doesn't undergo any form of escaping, so it is not suitable to
  represent variable identifiers or values: you should only use it to pass
  constant strings representing templates or snippets of SQL statements; use
  other objects such as `Identifier` or `Literal` to represent variable
  parts.
  
  Example::
  
      >>> query = sql.SQL("select {0} from {1}").format(
      ...    sql.SQL(', ').join([sql.Identifier('foo'), sql.Identifier('bar')]),
      ...    sql.Identifier('table'))
      >>> print(query.as_string(conn))
      select "foo", "bar" from "table"
docstr: Merge `Composable` objects into a template.
  
  :param `Composable` args: parameters to replace to numbered
      (``{0}``, ``{1}``) or auto-numbered (``{}``) placeholders
  :param `Composable` kwargs: parameters to replace to named (``{name}``)
      placeholders
  :return: the union of the `!SQL` string with placeholders replaced
  :rtype: `Composed`
  
  The method is similar to the Python `str.format()` method: the string
  template supports auto-numbered (``{}``), numbered (``{0}``,
  ``{1}``...), and named placeholders (``{name}``), with positional
  arguments replacing the numbered placeholders and keywords replacing
  the named ones. However placeholder modifiers (``{0!r}``, ``{0:<10}``)
  are not supported. Only `!Composable` objects can be passed to the
  template.
  
  Example::
  
      >>> print(sql.SQL("select * from {} where {} = %s")
      ...     .format(sql.Identifier('people'), sql.Identifier('id'))
      ...     .as_string(conn))
      select * from "people" where "id" = %s
  
      >>> print(sql.SQL("select * from {tbl} where {pkey} = %s")
      ...     .format(tbl=sql.Identifier('people'), pkey=sql.Identifier('id'))
      ...     .as_string(conn))
      select * from "people" where "id" = %s
docstr_tok: ["Merge","`","Composable","`","objects","into","a","template",".",":","param","`","Composable","`","args",":","parameters","to","replace","to","numbered","(","``","{","0","}","``",",","``","{","1","}","``",")","or","auto-numbered","(","``","{","}","``",")","placeholders",":","param","`","Composable","`","kwargs",":","parameters","to","replace","to","named","(","``","{","name","}","``",")","placeholders",":","return",":","the","union","of","the","`","!","SQL","`","string","with","placeholders","replaced",":","rtype",":","`","Composed","`","The","method","is","similar","to","the","Python","`","str.format","(",")","`","method",":","the","string","template","supports","auto-numbered","(","``","{","}","``",")",",","numbered","(","``","{","0","}","``",",","``","{","1","}","``","...",")",",","and","named","placeholders","(","``","{","name","}","``",")",",","with","positional","arguments","replacing","the","numbered","placeholders","and","keywords","replacing","the","named","ones",".","However","placeholder","modifiers","(","``","{","0","!","r","}","``",",","``","{","0",":","<","10","}","``",")","are","not","supported",".","Only","`","!","Composable","`","objects","can","be","passed","to","the","template",".","Example",":",":",">",">",">","print","(","sql.SQL","(","``","select","*","from","{","}","where","{","}","=","%","s","''",")","...",".format","(","sql.Identifier","(","'people","'",")",",","sql.Identifier","(","'id","'",")",")","...",".as_string","(","conn",")",")","select","*","from","``","people","''","where","``","id","''","=","%","s",">",">",">","print","(","sql.SQL","(","``","select","*","from","{","tbl","}","where","{","pkey","}","=","%","s","''",")","...",".format","(","tbl=sql.Identifier","(","'people","'",")",",","pkey=sql.Identifier","(","'id","'",")",")","...",".as_string","(","conn",")",")","select","*","from","``","people","''","where","``","id","''","=","%","s"]
code: def format(self, *args, **kwargs):
      """
      Merge `Composable` objects into a template.
  
      :param `Composable` args: parameters to replace to numbered
          (``{0}``, ``{1}``) or auto-numbered (``{}``) placeholders
      :param `Composable` kwargs: parameters to replace to named (``{name}``)
          placeholders
      :return: the union of the `!SQL` string with placeholders replaced
      :rtype: `Composed`
  
      The method is similar to the Python `str.format()` method: the string
      template supports auto-numbered (``{}``), numbered (``{0}``,
      ``{1}``...), and named placeholders (``{name}``), with positional
      arguments replacing the numbered placeholders and keywords replacing
      the named ones. However placeholder modifiers (``{0!r}``, ``{0:<10}``)
      are not supported. Only `!Composable` objects can be passed to the
      template.
  
      Example::
  
          >>> print(sql.SQL("select * from {} where {} = %s")
          ...     .format(sql.Identifier('people'), sql.Identifier('id'))
          ...     .as_string(conn))
          select * from "people" where "id" = %s
  
          >>> print(sql.SQL("select * from {tbl} where {pkey} = %s")
          ...     .format(tbl=sql.Identifier('people'), pkey=sql.Identifier('id'))
          ...     .as_string(conn))
          select * from "people" where "id" = %s
  
      """
      rv = []
      autonum = 0
      for pre, name, spec, conv in _formatter.parse(self._wrapped):
          if spec:
              raise ValueError(
                  "no format specification supported by SQL"
              )
          if conv:
              raise ValueError("no format conversion supported by SQL")
          if pre:
              rv.append(SQL(pre))
  
          if name is None:
              continue
  
          if name.isdigit():
              if autonum:
                  raise ValueError(
                      "cannot switch from automatic field numbering to manual"
                  )
              rv.append(args[int(name)])
              autonum = None
  
          elif not name:
              if autonum is None:
                  raise ValueError(
                      "cannot switch from manual field numbering to automatic"
                  )
              rv.append(args[autonum])
              autonum += 1
  
          else:
              rv.append(kwargs[name])
  
      return Composed(rv)
  
imports: import string
  from psycopg2 import extensions
label_desc: Use image node_id 4 for calling the SQL obj's underlying member method code with example usage: obj.format() and returns: Composed