code: def revision(
      config: Config,
      message: Optional[str] = None,
      autogenerate: bool = False,
      sql: bool = False,
      head: str = "head",
      splice: bool = False,
      branch_label: Optional[_RevIdType] = None,
      version_path: Optional[str] = None,
      rev_id: Optional[str] = None,
      depends_on: Optional[str] = None,
      process_revision_directives: Optional[
          ProcessRevisionDirectiveFn
      ] = None,
  ) -> Union[Optional[Script], List[Optional[Script]]]:
      """Create a new revision file.
  
      :param config: a :class:`.Config` object.
  
      :param message: string message to apply to the revision; this is the
       ``-m`` option to ``alembic revision``.
  
      :param autogenerate: whether or not to autogenerate the script from
       the database; this is the ``--autogenerate`` option to
       ``alembic revision``.
  
      :param sql: whether to dump the script out as a SQL string; when specified,
       the script is dumped to stdout.  This is the ``--sql`` option to
       ``alembic revision``.
  
      :param head: head revision to build the new revision upon as a parent;
       this is the ``--head`` option to ``alembic revision``.
  
      :param splice: whether or not the new revision should be made into a
       new head of its own; is required when the given ``head`` is not itself
       a head.  This is the ``--splice`` option to ``alembic revision``.
  
      :param branch_label: string label to apply to the branch; this is the
       ``--branch-label`` option to ``alembic revision``.
  
      :param version_path: string symbol identifying a specific version path
       from the configuration; this is the ``--version-path`` option to
       ``alembic revision``.
  
      :param rev_id: optional revision identifier to use instead of having
       one generated; this is the ``--rev-id`` option to ``alembic revision``.
  
      :param depends_on: optional list of "depends on" identifiers; this is the
       ``--depends-on`` option to ``alembic revision``.
  
      :param process_revision_directives: this is a callable that takes the
       same form as the callable described at
       :paramref:`.EnvironmentContext.configure.process_revision_directives`;
       will be applied to the structure generated by the revision process
       where it can be altered programmatically.   Note that unlike all
       the other parameters, this option is only available via programmatic
       use of :func:`.command.revision`
  
      """
  
      script_directory = ScriptDirectory.from_config(config)
  
      command_args = dict(
          message=message,
          autogenerate=autogenerate,
          sql=sql,
          head=head,
          splice=splice,
          branch_label=branch_label,
          version_path=version_path,
          rev_id=rev_id,
          depends_on=depends_on,
      )
      revision_context = autogen.RevisionContext(
          config,
          script_directory,
          command_args,
          process_revision_directives=process_revision_directives,
      )
  
      environment = util.asbool(
          config.get_main_option("revision_environment")
      )
  
      if autogenerate:
          environment = True
  
          if sql:
              raise util.CommandError(
                  "Using --sql with --autogenerate does not make any sense"
              )
  
          def retrieve_migrations(rev, context):
              revision_context.run_autogenerate(rev, context)
              return []
  
      elif environment:
  
          def retrieve_migrations(rev, context):
              revision_context.run_no_autogenerate(rev, context)
              return []
  
      elif sql:
          raise util.CommandError(
              "Using --sql with the revision command when "
              "revision_environment is not configured does not make any sense"
          )
  
      if environment:
          with EnvironmentContext(
              config,
              script_directory,
              fn=retrieve_migrations,
              as_sql=sql,
              template_args=revision_context.template_args,
              revision_context=revision_context,
          ):
              script_directory.run_env()
  
          # the revision_context now has MigrationScript structure(s) present.
          # these could theoretically be further processed / rewritten *here*,
          # in addition to the hooks present within each run_migrations() call,
          # or at the end of env.py run_migrations_online().
  
      scripts = [
          script for script in revision_context.generate_scripts()
      ]
      if len(scripts) == 1:
          return scripts[0]
      else:
          return scripts
  
imports: from __future__ import annotations
  import os
  from typing import List
  from typing import Optional
  from typing import TYPE_CHECKING
  from typing import Union
  from .None import autogenerate
  from .None import util
  from .runtime.environment import EnvironmentContext
  from .script import ScriptDirectory
label_desc: Use image node_id 3 for calling a global function with example usage: revision(config, message, autogenerate, sql, head, splice, branch_label, version_path, rev_id, depends_on, process_revision_directives) and returns: scripts, scripts, list, list