class_docstr: A space consisting of finitely many elements.
  
  This class represents a finite subset of integers, more specifically a set of the form :math:`\{ a, a+1, \dots, a+n-1 \}`.
  
  Example::
  
      >>> Discrete(2)            # {0, 1}
      >>> Discrete(3, start=-1)  # {-1, 0, 1}
class_docstr_tok: ["A","space","consisting","of","finitely","many","elements",".","This","class","represents","a","finite","subset","of","integers",",","more","specifically","a","set","of","the","form",":","math",":","`","\\","{","a",",","a+1",",","\\dots",",","a+n-1","\\","}","`",".","Example",":",":",">",">",">","Discrete","(","2",")","#","{","0",",","1","}",">",">",">","Discrete","(","3",",","start=-1",")","#","{","-1",",","0",",","1","}"]
docstr: Generates a single random sample from this space.
  
  A sample will be chosen uniformly at random with the mask if provided
  
  Args:
      mask: An optional mask for if an action can be selected.
          Expected `np.ndarray` of shape `(n,)` and dtype `np.int8` where `1` represents valid actions and `0` invalid / infeasible actions.
          If there are no possible actions (i.e. `np.all(mask == 0)`) then `space.start` will be returned.
  
  Returns:
      A sampled integer from the space
docstr_tok: ["Generates","a","single","random","sample","from","this","space",".","A","sample","will","be","chosen","uniformly","at","random","with","the","mask","if","provided","Args",":","mask",":","An","optional","mask","for","if","an","action","can","be","selected",".","Expected","`","np.ndarray","`","of","shape","`","(","n",",",")","`","and","dtype","`","np.int8","`","where","`","1","`","represents","valid","actions","and","`","0","`","invalid","\/","infeasible","actions",".","If","there","are","no","possible","actions","(","i.e",".","`","np.all","(","mask","==","0",")","`",")","then","`","space.start","`","will","be","returned",".","Returns",":","A","sampled","integer","from","the","space"]
code: def sample(self, mask: Optional[np.ndarray] = None) -> int:
      """Generates a single random sample from this space.
  
      A sample will be chosen uniformly at random with the mask if provided
  
      Args:
          mask: An optional mask for if an action can be selected.
              Expected `np.ndarray` of shape `(n,)` and dtype `np.int8` where `1` represents valid actions and `0` invalid / infeasible actions.
              If there are no possible actions (i.e. `np.all(mask == 0)`) then `space.start` will be returned.
  
      Returns:
          A sampled integer from the space
      """
      if mask is not None:
          assert isinstance(
              mask, np.ndarray
          ), f"The expected type of the mask is np.ndarray, actual type: {type(mask)}"
          assert (
              mask.dtype == np.int8
          ), f"The expected dtype of the mask is np.int8, actual dtype: {mask.dtype}"
          assert mask.shape == (
              self.n,
          ), f"The expected shape of the mask is {(self.n,)}, actual shape: {mask.shape}"
          valid_action_mask = mask == 1
          assert np.all(
              np.logical_or(mask == 0, valid_action_mask)
          ), f"All values of a mask should be 0 or 1, actual values: {mask}"
          if np.any(valid_action_mask):
              return int(
                  self.start
                  + self.np_random.choice(
                      np.where(valid_action_mask)[0]
                  )
              )
          else:
              return self.start
  
      return int(self.start + self.np_random.integers(self.n))
  
file_path: gym/gym/spaces/discrete.py
imports: from typing import Optional, Union
  import numpy
  from gym.spaces.space import Space
label_desc: Use image node_id 3 for calling the Discrete obj's underlying member method code with example usage: obj.sample(mask) and returns: int, int, self