class_docstr: A more featureful embedding module than the default in Pytorch.  Adds the ability to:
  
      1. embed higher-order inputs
      2. pre-specify the weight matrix
      3. use a non-trainable embedding
      4. project the resultant embeddings to some other dimension (which only makes sense with
         non-trainable embeddings).
  
  Note that if you are using our data API and are trying to embed a
  [`TextField`](../../data/fields/text_field.md), you should use a
  [`TextFieldEmbedder`](../text_field_embedders/text_field_embedder.md) instead of using this directly.
  
  Registered as a `TokenEmbedder` with name "embedding".
  
  # Parameters
  
  num_embeddings : `int`
      Size of the dictionary of embeddings (vocabulary size).
  embedding_dim : `int`
      The size of each embedding vector.
  projection_dim : `int`, optional (default=`None`)
      If given, we add a projection layer after the embedding layer.  This really only makes
      sense if `trainable` is `False`.
  weight : `torch.FloatTensor`, optional (default=`None`)
      A pre-initialised weight matrix for the embedding lookup, allowing the use of
      pretrained vectors.
  padding_index : `int`, optional (default=`None`)
      If given, pads the output with zeros whenever it encounters the index.
  trainable : `bool`, optional (default=`True`)
      Whether or not to optimize the embedding parameters.
  max_norm : `float`, optional (default=`None`)
      If given, will renormalize the embeddings to always have a norm lesser than this
  norm_type : `float`, optional (default=`2`)
      The p of the p-norm to compute for the max_norm option
  scale_grad_by_freq : `bool`, optional (default=`False`)
      If given, this will scale gradients by the frequency of the words in the mini-batch.
  sparse : `bool`, optional (default=`False`)
      Whether or not the Pytorch backend should use a sparse representation of the embedding weight.
  vocab_namespace : `str`, optional (default=`None`)
      In case of fine-tuning/transfer learning, the model's embedding matrix needs to be
      extended according to the size of extended-vocabulary. To be able to know how much to
      extend the embedding-matrix, it's necessary to know which vocab_namspace was used to
      construct it in the original training. We store vocab_namespace used during the original
      training as an attribute, so that it can be retrieved during fine-tuning.
  pretrained_file : `str`, optional (default=`None`)
      Path to a file of word vectors to initialize the embedding matrix. It can be the
      path to a local file or a URL of a (cached) remote file. Two formats are supported:
          * hdf5 file - containing an embedding matrix in the form of a torch.Tensor;
          * text file - an utf-8 encoded text file with space separated fields.
  vocab : `Vocabulary`, optional (default = `None`)
      Used to construct an embedding from a pretrained file.
  
      In a typical AllenNLP configuration file, this parameter does not get an entry under the
      "embedding", it gets specified as a top-level parameter, then is passed in to this module
      separately.
  
  # Returns
  
  An Embedding module.
class_docstr_tok: ["A","more","featureful","embedding","module","than","the","default","in","Pytorch",".","Adds","the","ability","to",":","1.","embed","higher-order","inputs","2.","pre-specify","the","weight","matrix","3.","use","a","non-trainable","embedding","4.","project","the","resultant","embeddings","to","some","other","dimension","(","which","only","makes","sense","with","non-trainable","embeddings",")",".","Note","that","if","you","are","using","our","data","API","and","are","trying","to","embed","a","[","`","TextField","`","]","(","..","\/","..","\/data\/fields\/text_field.md",")",",","you","should","use","a","[","`","TextFieldEmbedder","`","]","(","..","\/text_field_embedders\/text_field_embedder.md",")","instead","of","using","this","directly",".","Registered","as","a","`","TokenEmbedder","`","with","name","``","embedding","''",".","#","Parameters","num_embeddings",":","`","int","`","Size","of","the","dictionary","of","embeddings","(","vocabulary","size",")",".","embedding_dim",":","`","int","`","The","size","of","each","embedding","vector",".","projection_dim",":","`","int","`",",","optional","(","default=","`","None","`",")","If","given",",","we","add","a","projection","layer","after","the","embedding","layer",".","This","really","only","makes","sense","if","`","trainable","`","is","`","False","`",".","weight",":","`","torch.FloatTensor","`",",","optional","(","default=","`","None","`",")","A","pre-initialised","weight","matrix","for","the","embedding","lookup",",","allowing","the","use","of","pretrained","vectors",".","padding_index",":","`","int","`",",","optional","(","default=","`","None","`",")","If","given",",","pads","the","output","with","zeros","whenever","it","encounters","the","index",".","trainable",":","`","bool","`",",","optional","(","default=","`","True","`",")","Whether","or","not","to","optimize","the","embedding","parameters",".","max_norm",":","`","float","`",",","optional","(","default=","`","None","`",")","If","given",",","will","renormalize","the","embeddings","to","always","have","a","norm","lesser","than","this","norm_type",":","`","float","`",",","optional","(","default=","`","2","`",")","The","p","of","the","p-norm","to","compute","for","the","max_norm","option","scale_grad_by_freq",":","`","bool","`",",","optional","(","default=","`","False","`",")","If","given",",","this","will","scale","gradients","by","the","frequency","of","the","words","in","the","mini-batch",".","sparse",":","`","bool","`",",","optional","(","default=","`","False","`",")","Whether","or","not","the","Pytorch","backend","should","use","a","sparse","representation","of","the","embedding","weight",".","vocab_namespace",":","`","str","`",",","optional","(","default=","`","None","`",")","In","case","of","fine-tuning\/transfer","learning",",","the","model","'s","embedding","matrix","needs","to","be","extended","according","to","the","size","of","extended-vocabulary",".","To","be","able","to","know","how","much","to","extend","the","embedding-matrix",",","it","'s","necessary","to","know","which","vocab_namspace","was","used","to","construct","it","in","the","original","training",".","We","store","vocab_namespace","used","during","the","original","training","as","an","attribute",",","so","that","it","can","be","retrieved","during","fine-tuning",".","pretrained_file",":","`","str","`",",","optional","(","default=","`","None","`",")","Path","to","a","file","of","word","vectors","to","initialize","the","embedding","matrix",".","It","can","be","the","path","to","a","local","file","or","a","URL","of","a","(","cached",")","remote","file",".","Two","formats","are","supported",":","*","hdf5","file","-","containing","an","embedding","matrix","in","the","form","of","a","torch.Tensor",";","*","text","file","-","an","utf-8","encoded","text","file","with","space","separated","fields",".","vocab",":","`","Vocabulary","`",",","optional","(","default","=","`","None","`",")","Used","to","construct","an","embedding","from","a","pretrained","file",".","In","a","typical","AllenNLP","configuration","file",",","this","parameter","does","not","get","an","entry","under","the","``","embedding","''",",","it","gets","specified","as","a","top-level","parameter",",","then","is","passed","in","to","this","module","separately",".","#","Returns","An","Embedding","module","."]
code: def __init__(
      self,
      embedding_dim: int,
      num_embeddings: int = None,
      projection_dim: int = None,
      weight: torch.FloatTensor = None,
      padding_index: int = None,
      trainable: bool = True,
      max_norm: float = None,
      norm_type: float = 2.0,
      scale_grad_by_freq: bool = False,
      sparse: bool = False,
      vocab_namespace: str = "tokens",
      pretrained_file: str = None,
      vocab: Vocabulary = None,
  ) -> None:
      super().__init__()
  
      if num_embeddings is None and vocab is None:
          raise ConfigurationError(
              "Embedding must be constructed with either num_embeddings or a vocabulary."
          )
  
      _vocab_namespace: Optional[str] = vocab_namespace
      if num_embeddings is None:
          num_embeddings = vocab.get_vocab_size(_vocab_namespace)  # type: ignore
      else:
          # If num_embeddings is present, set default namespace to None so that extend_vocab
          # call doesn't misinterpret that some namespace was originally used.
          _vocab_namespace = None  # type: ignore
  
      self.num_embeddings = num_embeddings
      self.padding_index = padding_index
      self.max_norm = max_norm
      self.norm_type = norm_type
      self.scale_grad_by_freq = scale_grad_by_freq
      self.sparse = sparse
      self._vocab_namespace = _vocab_namespace
      self._pretrained_file = pretrained_file
  
      self.output_dim = projection_dim or embedding_dim
  
      if weight is not None and pretrained_file:
          raise ConfigurationError(
              "Embedding was constructed with both a weight and a pretrained file."
          )
  
      elif pretrained_file is not None:
          if vocab is None:
              raise ConfigurationError(
                  "To construct an Embedding from a pretrained file, you must also pass a vocabulary."
              )
  
          # If we're loading a saved model, we don't want to actually read a pre-trained
          # embedding file - the embeddings will just be in our saved weights, and we might not
          # have the original embedding file anymore, anyway.
  
          # TODO: having to pass tokens here is SUPER gross, but otherwise this breaks the
          # extend_vocab method, which relies on the value of vocab_namespace being None
          # to infer at what stage the embedding has been constructed. Phew.
          weight = _read_pretrained_embeddings_file(
              pretrained_file, embedding_dim, vocab, vocab_namespace
          )
          self.weight = torch.nn.Parameter(
              weight, requires_grad=trainable
          )
  
      elif weight is not None:
          self.weight = torch.nn.Parameter(
              weight, requires_grad=trainable
          )
  
      else:
          weight = torch.FloatTensor(num_embeddings, embedding_dim)
          self.weight = torch.nn.Parameter(
              weight, requires_grad=trainable
          )
          torch.nn.init.xavier_uniform_(self.weight)
  
      # Whatever way we have constructed the embedding, it should be consistent with
      # num_embeddings and embedding_dim.
      if self.weight.size() != (num_embeddings, embedding_dim):
          raise ConfigurationError(
              "A weight matrix was passed with contradictory embedding shapes."
          )
  
      if self.padding_index is not None:
          self.weight.data[self.padding_index].fill_(0)
  
      if projection_dim:
          self._projection = torch.nn.Linear(
              embedding_dim, projection_dim
          )
      else:
          self._projection = None
  
imports: import io
  import itertools
  import logging
  import re
  import tarfile
  import warnings
  import zipfile
  from typing import Any, cast, Iterator, NamedTuple, Optional, Sequence, Tuple, BinaryIO
  import numpy
  import torch
  from torch.nn.functional import embedding
  from allennlp.common import Tqdm
  from allennlp.common.checks import ConfigurationError
  from allennlp.common.file_utils import cached_path, get_file_extension, is_url_or_existing_file
  from allennlp.data.vocabulary import Vocabulary
  from allennlp.modules.time_distributed import TimeDistributed
  from allennlp.modules.token_embedders.token_embedder import TokenEmbedder
  from allennlp.nn import util
label_desc: Use image node_id 1 to create a new Embedding object from inherited base classes: TokenEmbedder with example: obj = Embedding(embedding_dim, num_embeddings, projection_dim, weight, padding_index, trainable, max_norm, norm_type, scale_grad_by_freq, sparse, vocab_namespace, pretrained_file, vocab)