code: def swap_words(
      aug_toks: list[types.AugTok],
      *,
      num: int | float = 1,
      pos: Optional[str | set[str]] = None,
  ) -> list[types.AugTok]:
      """
      Randomly swap the positions of two *adjacent* words,
      up to ``num`` times or with a probability of ``num``.
  
      Args:
          aug_toks: Sequence of tokens to augment through position swapping.
          num: If int, maximum number of adjacent word pairs to swap;
              if float, probability that a given word pair will be swapped.
          pos: Part of speech tag(s) of words to be considered for augmentation.
              If None, all words are considered.
  
      Returns:
          New, augmented sequence of tokens.
      """
      _validate_aug_toks(aug_toks)
      pos = utils.to_collection(pos, str, set)
      # if we don't require _adjacent_ words, this does the trick
      # if not pos:
      #     pos = set(aug_tok.pos for aug_tok in aug_toks if aug_tok.is_word)
      # cand_idx_pairs = list(
      #     itertools.chain.from_iterable(
      #         itertools.combinations(
      #             (idx for idx, aug_tok in enumerate(aug_toks) if aug_tok.pos == pos_),
      #             2,
      #         )
      #         for pos_ in pos
      #     )
      # )
      cand_idxs = (
          idx
          for idx, aug_tok in enumerate(aug_toks)
          if aug_tok.is_word and (pos is None or aug_tok.pos in pos)
      )
      cand_idx_pairs = [
          (idx1, idx2)
          for idx1, idx2 in itertoolz.sliding_window(2, cand_idxs)
          if idx2 - idx1 == 1
      ]
      rand_idx_pairs = _select_random_candidates(cand_idx_pairs, num)
      if not rand_idx_pairs:
          return aug_toks[:]
  
      new_aug_toks = aug_toks[:]
      for idx1, idx2 in rand_idx_pairs:
          tok1 = new_aug_toks[idx1]
          tok2 = new_aug_toks[idx2]
          new_aug_toks[idx1] = types.AugTok(
              text=tok2.text,
              ws=tok1.ws,
              pos=tok2.pos,
              is_word=tok2.is_word,
              syns=tok2.syns,
          )
          new_aug_toks[idx2] = types.AugTok(
              text=tok1.text,
              ws=tok2.ws,
              pos=tok1.pos,
              is_word=tok1.is_word,
              syns=tok1.syns,
          )
      return new_aug_toks
  
file_path: textacy/src/textacy/augmentation/transforms.py
imports: from __future__ import annotations
  import random
  from typing import Optional
  from cytoolz import itertoolz
  from ..None import errors, types, utils
  from .None import utils
label_desc: Use image node_id 3 for calling a global function with example usage: swap_words(aug_toks) and returns: new_aug_toks, aug_toks