parameters: (self,
                       file_name: str,
                       *,
                       export_as: Optional[str] = None)
return_statement: return alloced_path
docstring: Allocates an optional temporary file.
  
  
      When in non-retained mode, the return value is 'export_as', meaning that the
      file is just some user specified output file.
  
      When in retained mode, the output file will be an index-mangled variant
      of 'file_name' under the temp_path. In addition, a mapping will be added
      so that upon finalization, the file is also exported to 'export_as' if
      specified.
  
      Returns None if neither a user-specified 'export_as' is specified nor in
      retained mode.
  
      The distinction between retained temporaries and exports is to help in
      cases for when the caller has requested that an artifact be written to
      a specific place (i.e. an output file) but for debuggability, we also
      want to save it as a temporary. In this case, we save it to the temporary
      location and then conclude by moving artifacts to their final location
      once the saver goes out of scope.
docstring_summary: Allocates an optional temporary file.
docstring_tokens: Allocates an optional temporary file .
function: def alloc_optional(self,
                       file_name: str,
                       *,
                       export_as: Optional[str] = None) -> Optional[str]:
      """Allocates an optional temporary file.
  
  
      When in non-retained mode, the return value is 'export_as', meaning that the
      file is just some user specified output file.
  
      When in retained mode, the output file will be an index-mangled variant
      of 'file_name' under the temp_path. In addition, a mapping will be added
      so that upon finalization, the file is also exported to 'export_as' if
      specified.
  
      Returns None if neither a user-specified 'export_as' is specified nor in
      retained mode.
  
      The distinction between retained temporaries and exports is to help in
      cases for when the caller has requested that an artifact be written to
      a specific place (i.e. an output file) but for debuggability, we also
      want to save it as a temporary. In this case, we save it to the temporary
      location and then conclude by moving artifacts to their final location
      once the saver goes out of scope.
      """
      if not self.retained:
        return export_as
      alloced_path = self._alloc_retained_path(file_name)
      if export_as:
        self._copy_on_finalize.append((alloced_path, export_as))
      return alloced_path
function_tokens: def alloc_optional ( self , file_name : str , * , export_as : Optional [ str ] = None ) -> Optional [ str ] : if not self . retained : return export_as alloced_path = self . _alloc_retained_path ( file_name ) if export_as : self . _copy_on_finalize . append ( ( alloced_path , export_as ) ) return alloced_path