class_docstr: Simple position embedder that maps position indexes into embeddings
  via lookup.
  
  Either :attr:`init_value` or :attr:`position_size` is required. If both are
  given, there must be ``init_value.shape[0]==position_size``.
  
  Args:
      init_value (optional): A Tensor or numpy array that contains the
          initial value of embeddings. It is typically of shape
          ``[position_size, embedding dim]``
  
          If `None`, embedding is initialized as specified in
          ``hparams["initializer"]``. Otherwise, the
          ``"initializer"`` and ``"dim"``
          hyperparameters in :attr:`hparams` are ignored.
      position_size (int, optional): The number of possible positions, e.g.,
          the maximum sequence length. Required if :attr:`init_value` is
          not given.
      hparams (dict, optional): Embedder hyperparameters. If it is not
          specified, the default hyperparameter setting is used. See
          :attr:`default_hparams` for the structure and default values.
  
  
  .. document private functions
  .. automethod:: _build
class_docstr_tok: ["Simple","position","embedder","that","maps","position","indexes","into","embeddings","via","lookup",".","Either",":","attr",":","`","init_value","`","or",":","attr",":","`","position_size","`","is","required",".","If","both","are","given",",","there","must","be","``","init_value.shape","[","0","]","==position_size","``",".","Args",":","init_value","(","optional",")",":","A","Tensor","or","numpy","array","that","contains","the","initial","value","of","embeddings",".","It","is","typically","of","shape","``","[","position_size",",","embedding","dim","]","``","If","`","None","`",",","embedding","is","initialized","as","specified","in","``","hparams","[","``","initializer","''","]","``",".","Otherwise",",","the","``","``","initializer","''","``","and","``","``","dim","''","``","hyperparameters","in",":","attr",":","`","hparams","`","are","ignored",".","position_size","(","int",",","optional",")",":","The","number","of","possible","positions",",","e.g.",",","the","maximum","sequence","length",".","Required","if",":","attr",":","`","init_value","`","is","not","given",".","hparams","(","dict",",","optional",")",":","Embedder","hyperparameters",".","If","it","is","not","specified",",","the","default","hyperparameter","setting","is","used",".","See",":","attr",":","`","default_hparams","`","for","the","structure","and","default","values",".","..","document","private","functions","..","automethod",":",":","_build"]
docstr: Embeds the positions.
  
  Either :attr:`positions` or :attr:`sequence_length` is required:
  
      - If both are given, :attr:`sequence_length` is used to mask out
        embeddings of those time steps beyond the respective sequence
        lengths.
      - If only :attr:`sequence_length` is given, then positions
        from 0 to ``sequence_length-1`` are embedded.
  
  Args:
      positions (optional): An integer tensor containing the position
          ids to embed.
      sequence_length (optional): An integer tensor of shape
          ``[batch_size]``. Time steps beyond the respective sequence
          lengths will have zero-valued embeddings.
      mode (optional): A tensor taking value in
          :tf_main:`tf.estimator.ModeKeys <estimator/ModeKeys>`, including
          `TRAIN`, `EVAL`, and `PREDICT`. If `None`, dropout will be
          controlled by :func:`texar.tf.global_mode`.
      kwargs: Additional keyword arguments for
          :tf_main:`tf.nn.embedding_lookup <nn/embedding_lookup>` besides
          :attr:`params` and :attr:`ids`.
  
  Returns:
      A `Tensor` of shape `shape(inputs) + embedding dimension`.
docstr_tok: ["Embeds","the","positions",".","Either",":","attr",":","`","positions","`","or",":","attr",":","`","sequence_length","`","is","required",":","-","If","both","are","given",",",":","attr",":","`","sequence_length","`","is","used","to","mask","out","embeddings","of","those","time","steps","beyond","the","respective","sequence","lengths",".","-","If","only",":","attr",":","`","sequence_length","`","is","given",",","then","positions","from","0","to","``","sequence_length-1","``","are","embedded",".","Args",":","positions","(","optional",")",":","An","integer","tensor","containing","the","position","ids","to","embed",".","sequence_length","(","optional",")",":","An","integer","tensor","of","shape","``","[","batch_size","]","``",".","Time","steps","beyond","the","respective","sequence","lengths","will","have","zero-valued","embeddings",".","mode","(","optional",")",":","A","tensor","taking","value","in",":","tf_main",":","`","tf.estimator.ModeKeys","<","estimator\/ModeKeys",">","`",",","including","`","TRAIN","`",",","`","EVAL","`",",","and","`","PREDICT","`",".","If","`","None","`",",","dropout","will","be","controlled","by",":","func",":","`","texar.tf.global_mode","`",".","kwargs",":","Additional","keyword","arguments","for",":","tf_main",":","`","tf.nn.embedding_lookup","<","nn\/embedding_lookup",">","`","besides",":","attr",":","`","params","`","and",":","attr",":","`","ids","`",".","Returns",":","A","`","Tensor","`","of","shape","`","shape","(","inputs",")","+","embedding","dimension","`","."]
code: def _build(
      self, positions=None, sequence_length=None, mode=None, **kwargs
  ):
      r"""Embeds the positions.
  
      Either :attr:`positions` or :attr:`sequence_length` is required:
  
          - If both are given, :attr:`sequence_length` is used to mask out
            embeddings of those time steps beyond the respective sequence
            lengths.
          - If only :attr:`sequence_length` is given, then positions
            from 0 to ``sequence_length-1`` are embedded.
  
      Args:
          positions (optional): An integer tensor containing the position
              ids to embed.
          sequence_length (optional): An integer tensor of shape
              ``[batch_size]``. Time steps beyond the respective sequence
              lengths will have zero-valued embeddings.
          mode (optional): A tensor taking value in
              :tf_main:`tf.estimator.ModeKeys <estimator/ModeKeys>`, including
              `TRAIN`, `EVAL`, and `PREDICT`. If `None`, dropout will be
              controlled by :func:`texar.tf.global_mode`.
          kwargs: Additional keyword arguments for
              :tf_main:`tf.nn.embedding_lookup <nn/embedding_lookup>` besides
              :attr:`params` and :attr:`ids`.
  
      Returns:
          A `Tensor` of shape `shape(inputs) + embedding dimension`.
      """
      # Gets embedder inputs
      # pylint:disable=too-many-locals
      inputs = positions
      if positions is None:
          if sequence_length is None:
              raise ValueError(
                  "Either `positions` or `sequence_length` is required."
              )
          max_length = tf.reduce_max(sequence_length)
          single_inputs = tf.range(
              start=0, limit=max_length, dtype=tf.int32
          )
          # Expands `single_inputs` to have shape [batch_size, max_length]
          expander = tf.expand_dims(tf.ones_like(sequence_length), -1)
          inputs = expander * tf.expand_dims(single_inputs, 0)
      ids_rank = len(inputs.shape.dims)
  
      embedding = self._embedding
  
      is_training = is_train_mode(mode)
  
      # Gets dropout strategy
      st = self._hparams.dropout_strategy
      if positions is None and st == "item":
          # If `inputs` is based on `sequence_length`, then dropout
          # strategies 'item' and 'item_type' have the same effect, we
          # use 'item_type' to avoid unknown noise_shape in the 'item'
          # strategy
          st = "item_type"
  
      # Dropouts as 'item_type' before embedding
      if st == "item_type":
          dropout_layer = self._get_dropout_layer(
              self._hparams, dropout_strategy=st
          )
          if dropout_layer:
              embedding = dropout_layer.apply(
                  inputs=embedding, training=is_training
              )
  
      # Embeds
      outputs = tf.nn.embedding_lookup(embedding, inputs, **kwargs)
  
      # Dropouts as 'item' or 'elements' after embedding
      if st != "item_type":
          dropout_layer = self._get_dropout_layer(
              self._hparams,
              ids_rank=ids_rank,
              dropout_input=outputs,
              dropout_strategy=st,
          )
          if dropout_layer:
              outputs = dropout_layer.apply(
                  inputs=outputs, training=is_training
              )
  
      # Optionally masks
      if sequence_length is not None:
          outputs = mask_sequences(
              outputs,
              sequence_length,
              tensor_rank=len(inputs.shape.dims) + self._dim_rank,
          )
  
      return outputs
  
imports: import math
  import tensorflow
  from texar.tf.modules.embedders.embedder_base import EmbedderBase
  from texar.tf.modules.embedders import embedder_utils
  from texar.tf.utils.mode import is_train_mode
  from texar.tf.utils.shapes import mask_sequences
  from texar.tf.utils.shapes import shape_list
label_desc: Use image node_id 3 for calling the PositionEmbedder obj's underlying member method code with example usage: obj._build(positions, sequence_length, mode) and returns: outputs