class_docstr: A space representing a string comprised of characters from a given charset.
  
  Example::
      >>> # {"", "B5", "hello", ...}
      >>> Text(5)
      >>> # {"0", "42", "0123456789", ...}
      >>> import string
      >>> Text(min_length = 1,
      ...      max_length = 10,
      ...      charset = string.digits)
class_docstr_tok: ["A","space","representing","a","string","comprised","of","characters","from","a","given","charset",".","Example",":",":",">",">",">","#","{","``","''",",","``","B5","''",",","``","hello","''",",","...","}",">",">",">","Text","(","5",")",">",">",">","#","{","``","0","''",",","``","42","''",",","``","0123456789","''",",","...","}",">",">",">","import","string",">",">",">","Text","(","min_length","=","1",",","...","max_length","=","10",",","...","charset","=","string.digits",")"]
docstr: Generates a single random sample from this space with by default a random length between `min_length` and `max_length` and sampled from the `charset`.
  
  Args:
      mask: An optional tuples of length and mask for the text.
          The length is expected to be between the `min_length` and `max_length` otherwise a random integer between `min_length` and `max_length` is selected.
          For the mask, we expect a numpy array of length of the charset passed with `dtype == np.int8`.
          If the charlist mask is all zero then an empty string is returned no matter the `min_length`
  
  Returns:
      A sampled string from the space
docstr_tok: ["Generates","a","single","random","sample","from","this","space","with","by","default","a","random","length","between","`","min_length","`","and","`","max_length","`","and","sampled","from","the","`","charset","`",".","Args",":","mask",":","An","optional","tuples","of","length","and","mask","for","the","text",".","The","length","is","expected","to","be","between","the","`","min_length","`","and","`","max_length","`","otherwise","a","random","integer","between","`","min_length","`","and","`","max_length","`","is","selected",".","For","the","mask",",","we","expect","a","numpy","array","of","length","of","the","charset","passed","with","`","dtype","==","np.int8","`",".","If","the","charlist","mask","is","all","zero","then","an","empty","string","is","returned","no","matter","the","`","min_length","`","Returns",":","A","sampled","string","from","the","space"]
code: def sample(
      self,
      mask: Optional[Tuple[Optional[int], Optional[np.ndarray]]] = None,
  ) -> str:
      """Generates a single random sample from this space with by default a random length between `min_length` and `max_length` and sampled from the `charset`.
  
      Args:
          mask: An optional tuples of length and mask for the text.
              The length is expected to be between the `min_length` and `max_length` otherwise a random integer between `min_length` and `max_length` is selected.
              For the mask, we expect a numpy array of length of the charset passed with `dtype == np.int8`.
              If the charlist mask is all zero then an empty string is returned no matter the `min_length`
  
      Returns:
          A sampled string from the space
      """
      if mask is not None:
          assert isinstance(
              mask, tuple
          ), f"Expects the mask type to be a tuple, actual type: {type(mask)}"
          assert (
              len(mask) == 2
          ), f"Expects the mask length to be two, actual length: {len(mask)}"
          length, charlist_mask = mask
  
          if length is not None:
              assert np.issubdtype(
                  type(length), np.integer
              ), f"Expects the Text sample length to be an integer, actual type: {type(length)}"
              assert (
                  self.min_length <= length <= self.max_length
              ), f"Expects the Text sample length be between {self.min_length} and {self.max_length}, actual length: {length}"
  
          if charlist_mask is not None:
              assert isinstance(
                  charlist_mask, np.ndarray
              ), f"Expects the Text sample mask to be an np.ndarray, actual type: {type(charlist_mask)}"
              assert (
                  charlist_mask.dtype == np.int8
              ), f"Expects the Text sample mask to be an np.ndarray, actual dtype: {charlist_mask.dtype}"
              assert charlist_mask.shape == (
                  len(self.character_set),
              ), f"expects the Text sample mask to be {(len(self.character_set),)}, actual shape: {charlist_mask.shape}"
              assert np.all(
                  np.logical_or(charlist_mask == 0, charlist_mask == 1)
              ), f"Expects all masks values to 0 or 1, actual values: {charlist_mask}"
      else:
          length, charlist_mask = None, None
  
      if length is None:
          length = self.np_random.integers(
              self.min_length, self.max_length + 1
          )
  
      if charlist_mask is None:
          string = self.np_random.choice(
              self.character_list, size=length
          )
      else:
          valid_mask = charlist_mask == 1
          valid_indexes = np.where(valid_mask)[0]
          if len(valid_indexes) == 0:
              if self.min_length == 0:
                  string = ""
              else:
                  # Otherwise the string will not be contained in the space
                  raise ValueError(
                      f"Trying to sample with a minimum length > 0 ({self.min_length}) but the character mask is all zero meaning that no character could be sampled."
                  )
          else:
              string = "".join(
                  self.character_list[index]
                  for index in self.np_random.choice(
                      valid_indexes, size=length
                  )
              )
  
      return "".join(string)
  
file_path: gym/gym/spaces/text.py
imports: from typing import Any, Dict, FrozenSet, Optional, Set, Tuple, Union
  import numpy
  from gym.spaces.space import Space
label_desc: Use image node_id 2 for calling the Text obj's underlying member method code with example usage: obj.sample(mask) and returns: str