docstr: Create a form that batches elements together with a "Submit" button.
  
  A form is a container that visually groups other elements and
  widgets together, and contains a Submit button. When the form's
  Submit button is pressed, all widget values inside the form will be
  sent to Streamlit in a batch.
  
  To add elements to a form object, you can use "with" notation
  (preferred) or just call methods directly on the form. See
  examples below.
  
  Forms have a few constraints:
  
  * Every form must contain a ``st.form_submit_button``.
  * ``st.button`` and ``st.download_button`` cannot be added to a form.
  * Forms can appear anywhere in your app (sidebar, columns, etc),
    but they cannot be embedded inside other forms.
  * Within a form, the only widget that can have a callback function is
    ``st.form_submit_button``.
  
  Parameters
  ----------
  key : str
      A string that identifies the form. Each form must have its own
      key. (This key is not displayed to the user in the interface.)
  clear_on_submit : bool
      If True, all widgets inside the form will be reset to their default
      values after the user presses the Submit button. Defaults to False.
      (Note that Custom Components are unaffected by this flag, and
      will not be reset to their defaults on form submission.)
  border : bool
      Whether to show a border around the form. Defaults to True.
  
      .. note::
          Not showing a border can be confusing to viewers since interacting with a
          widget in the form will do nothing. You should only remove the border if
          there's another border (e.g. because of an expander) or the form is small
          (e.g. just a text input and a submit button).
  
  Examples
  --------
  Inserting elements using "with" notation:
  
  >>> import streamlit as st
  >>>
  >>> with st.form("my_form"):
  ...    st.write("Inside the form")
  ...    slider_val = st.slider("Form slider")
  ...    checkbox_val = st.checkbox("Form checkbox")
  ...
  ...    # Every form must have a submit button.
  ...    submitted = st.form_submit_button("Submit")
  ...    if submitted:
  ...        st.write("slider", slider_val, "checkbox", checkbox_val)
  ...
  >>> st.write("Outside the form")
  
  .. output::
     https://doc-form1.streamlit.app/
     height: 425px
  
  Inserting elements out of order:
  
  >>> import streamlit as st
  >>>
  >>> form = st.form("my_form")
  >>> form.slider("Inside the form")
  >>> st.slider("Outside the form")
  >>>
  >>> # Now add a submit button to the form:
  >>> form.form_submit_button("Submit")
  
  .. output::
     https://doc-form2.streamlit.app/
     height: 375px
docstr_tok: ["Create","a","form","that","batches","elements","together","with","a","``","Submit","''","button",".","A","form","is","a","container","that","visually","groups","other","elements","and","widgets","together",",","and","contains","a","Submit","button",".","When","the","form's","Submit","button","is","pressed",",","all","widget","values","inside","the","form","will","be","sent","to","Streamlit","in","a","batch",".","To","add","elements","to","a","form","object",",","you","can","use","``","with","''","notation","(","preferred",")","or","just","call","methods","directly","on","the","form",".","See","examples","below",".","Forms","have","a","few","constraints",":","*","Every","form","must","contain","a","``","st.form_submit_button","``",".","*","``","st.button","``","and","``","st.download_button","``","can","not","be","added","to","a","form",".","*","Forms","can","appear","anywhere","in","your","app","(","sidebar",",","columns",",","etc",")",",","but","they","can","not","be","embedded","inside","other","forms",".","*","Within","a","form",",","the","only","widget","that","can","have","a","callback","function","is","``","st.form_submit_button","``",".","Parameters","--","--","--","--","--","key",":","str","A","string","that","identifies","the","form",".","Each","form","must","have","its","own","key",".","(","This","key","is","not","displayed","to","the","user","in","the","interface",".",")","clear_on_submit",":","bool","If","True",",","all","widgets","inside","the","form","will","be","reset","to","their","default","values","after","the","user","presses","the","Submit","button",".","Defaults","to","False",".","(","Note","that","Custom","Components","are","unaffected","by","this","flag",",","and","will","not","be","reset","to","their","defaults","on","form","submission",".",")","border",":","bool","Whether","to","show","a","border","around","the","form",".","Defaults","to","True",".","..","note",":",":","Not","showing","a","border","can","be","confusing","to","viewers","since","interacting","with","a","widget","in","the","form","will","do","nothing",".","You","should","only","remove","the","border","if","there","'s","another","border","(","e.g",".","because","of","an","expander",")","or","the","form","is","small","(","e.g",".","just","a","text","input","and","a","submit","button",")",".","Examples","--","--","--","--","Inserting","elements","using","``","with","''","notation",":",">",">",">","import","streamlit","as","st",">",">",">",">",">",">","with","st.form","(","``","my_form","''",")",":","...","st.write","(","``","Inside","the","form","''",")","...","slider_val","=","st.slider","(","``","Form","slider","''",")","...","checkbox_val","=","st.checkbox","(","``","Form","checkbox","''",")","...","...","#","Every","form","must","have","a","submit","button",".","...","submitted","=","st.form_submit_button","(","``","Submit","''",")","...","if","submitted",":","...","st.write","(","``","slider","''",",","slider_val",",","``","checkbox","''",",","checkbox_val",")","...",">",">",">","st.write","(","``","Outside","the","form","''",")","..","output",":",":","https",":","\/\/doc-form1.streamlit.app\/","height",":","425px","Inserting","elements","out","of","order",":",">",">",">","import","streamlit","as","st",">",">",">",">",">",">","form","=","st.form","(","``","my_form","''",")",">",">",">","form.slider","(","``","Inside","the","form","''",")",">",">",">","st.slider","(","``","Outside","the","form","''",")",">",">",">",">",">",">","#","Now","add","a","submit","button","to","the","form",":",">",">",">","form.form_submit_button","(","``","Submit","''",")","..","output",":",":","https",":","\/\/doc-form2.streamlit.app\/","height",":","375px"]
code: def form(
      self,
      key: str,
      clear_on_submit: bool = False,
      *,
      border: bool = True,
  ) -> DeltaGenerator:
      """Create a form that batches elements together with a "Submit" button.
  
      A form is a container that visually groups other elements and
      widgets together, and contains a Submit button. When the form's
      Submit button is pressed, all widget values inside the form will be
      sent to Streamlit in a batch.
  
      To add elements to a form object, you can use "with" notation
      (preferred) or just call methods directly on the form. See
      examples below.
  
      Forms have a few constraints:
  
      * Every form must contain a ``st.form_submit_button``.
      * ``st.button`` and ``st.download_button`` cannot be added to a form.
      * Forms can appear anywhere in your app (sidebar, columns, etc),
        but they cannot be embedded inside other forms.
      * Within a form, the only widget that can have a callback function is
        ``st.form_submit_button``.
  
      Parameters
      ----------
      key : str
          A string that identifies the form. Each form must have its own
          key. (This key is not displayed to the user in the interface.)
      clear_on_submit : bool
          If True, all widgets inside the form will be reset to their default
          values after the user presses the Submit button. Defaults to False.
          (Note that Custom Components are unaffected by this flag, and
          will not be reset to their defaults on form submission.)
      border : bool
          Whether to show a border around the form. Defaults to True.
  
          .. note::
              Not showing a border can be confusing to viewers since interacting with a
              widget in the form will do nothing. You should only remove the border if
              there's another border (e.g. because of an expander) or the form is small
              (e.g. just a text input and a submit button).
  
      Examples
      --------
      Inserting elements using "with" notation:
  
      >>> import streamlit as st
      >>>
      >>> with st.form("my_form"):
      ...    st.write("Inside the form")
      ...    slider_val = st.slider("Form slider")
      ...    checkbox_val = st.checkbox("Form checkbox")
      ...
      ...    # Every form must have a submit button.
      ...    submitted = st.form_submit_button("Submit")
      ...    if submitted:
      ...        st.write("slider", slider_val, "checkbox", checkbox_val)
      ...
      >>> st.write("Outside the form")
  
      .. output::
         https://doc-form1.streamlit.app/
         height: 425px
  
      Inserting elements out of order:
  
      >>> import streamlit as st
      >>>
      >>> form = st.form("my_form")
      >>> form.slider("Inside the form")
      >>> st.slider("Outside the form")
      >>>
      >>> # Now add a submit button to the form:
      >>> form.form_submit_button("Submit")
  
      .. output::
         https://doc-form2.streamlit.app/
         height: 375px
  
      """
      # Import this here to avoid circular imports.
      from streamlit.elements.utils import check_session_state_rules
  
      if is_in_form(self.dg):
          raise StreamlitAPIException(
              "Forms cannot be nested in other forms."
          )
  
      check_session_state_rules(
          default_value=None, key=key, writes_allowed=False
      )
  
      # A form is uniquely identified by its key.
      form_id = key
  
      ctx = get_script_run_ctx()
      if ctx is not None:
          new_form_id = form_id not in ctx.form_ids_this_run
          if new_form_id:
              ctx.form_ids_this_run.add(form_id)
          else:
              raise StreamlitAPIException(
                  _build_duplicate_form_message(key)
              )
  
      block_proto = Block_pb2.Block()
      block_proto.form.form_id = form_id
      block_proto.form.clear_on_submit = clear_on_submit
      block_proto.form.border = border
      block_dg = self.dg._block(block_proto)
  
      # Attach the form's button info to the newly-created block's
      # DeltaGenerator.
      block_dg._form_data = FormData(form_id)
      return block_dg
  
imports: from __future__ import annotations
  import textwrap
  from typing import TYPE_CHECKING, NamedTuple, cast
  from typing_extensions import Literal
  from streamlit import runtime
  from streamlit.errors import StreamlitAPIException
  from streamlit.proto import Block_pb2
  from streamlit.runtime.metrics_util import gather_metrics
  from streamlit.runtime.scriptrunner import ScriptRunContext, get_script_run_ctx
  from streamlit.runtime.scriptrunner.script_run_context import dg_stack
  from streamlit.runtime.state import WidgetArgs, WidgetCallback, WidgetKwargs
label_desc: Use image node_id 1 for calling the FormMixin obj's underlying member method code with example usage: obj.form(key, clear_on_submit) and returns: block_dg