docs: def purge(self, session, checksum):
          '''
          Deletes calc entry by checksum entirely from the database
          NB source files on disk are not deleted
          NB: this is the PUBLIC method
          @returns error
          '''
          C = session.query(model.Calculation).get(checksum)
  
          if not C:
              return 'Calculation does not exist!'
  
          # dataset deletion includes editing the whole dataset hierarchical tree (if any)
          if C.siblings_count:
              C_meta = session.query(model.Metadata).get(checksum)
              higher_lookup = {}
              more = C.parent
              distance = 0
              while True:
                  distance += 1
                  higher, more = more, []
                  if not higher:
                      break
                  for item in higher:
                      try:
                          higher_lookup[distance].add(item)
                      except KeyError:
                          higher_lookup[distance] = set([item])
                      if item.parent:
                          more += item.parent
              for distance, members in higher_lookup.items():
                  for member in members:
                      if distance == 1:
                          member.siblings_count -= 1
  
                      if not member.siblings_count:
                          return 'The parent dataset contains only one (current) item, please, delete parent dataset first!'
  
                      member.meta_data.download_size -= C_meta.download_size
                      session.add(member)
          # low-level entry deletion deals with additional tables
          else:
              session.execute( model.delete( model.Spectra ).where( model.Spectra.checksum == checksum) )
              session.execute( model.delete( model.Electrons ).where( model.Electrons.checksum == checksum ) )
              session.execute( model.delete( model.Phonons ).where( model.Phonons.checksum == checksum ) )
              session.execute( model.delete( model.Recipinteg ).where( model.Recipinteg.checksum == checksum ) )
              session.execute( model.delete( model.Basis ).where( model.Basis.checksum == checksum ) )
              session.execute( model.delete( model.Energy ).where( model.Energy.checksum == checksum ) )
              session.execute( model.delete( model.Spacegroup ).where( model.Spacegroup.checksum == checksum ) )
              session.execute( model.delete( model.Struct_ratios ).where( model.Struct_ratios.checksum == checksum ) )
              session.execute( model.delete( model.Struct_optimisation ).where( model.Struct_optimisation.checksum == checksum ) )
  
              struct_ids = [ int(i[0]) for i in session.query(model.Structure.struct_id).filter(model.Structure.checksum == checksum).all() ]
              for struct_id in struct_ids:
                  session.execute( model.delete( model.Atom ).where( model.Atom.struct_id == struct_id ) )
                  session.execute( model.delete( model.Lattice ).where( model.Lattice.struct_id == struct_id ) )
              session.execute( model.delete( model.Structure ).where( model.Structure.checksum == checksum ) )
  
          # for all types of entries
          if len(C.references):
              left_references = [ int(i[0]) for i in session.query(model.Reference.reference_id).join(model.metadata_references, model.Reference.reference_id == model.metadata_references.c.reference_id).filter(model.metadata_references.c.checksum == checksum).all() ]
              session.execute( model.delete( model.metadata_references ).where( model.metadata_references.c.checksum == checksum ) )
  
              # remove the whole citation?
              for lc in left_references:
                  if not (session.query(model.metadata_references.c.checksum).filter(model.metadata_references.c.reference_id == lc).count()):
                      session.execute( model.delete( model.Reference ).where(model.Reference.reference_id == lc) )
  
          # TODO rewrite with cascading
          session.execute( model.delete( model.Metadata ).where( model.Metadata.checksum == checksum ) )
  
          session.execute( model.delete( model.Grid ).where( model.Grid.checksum == checksum ) )
          session.execute( model.delete( model.tags ).where( model.tags.c.checksum == checksum ) )
  
          session.execute( model.delete( model.calcsets ).where( model.calcsets.c.children_checksum == checksum ) )
          session.execute( model.delete( model.calcsets ).where( model.calcsets.c.parent_checksum == checksum ) )
          session.execute( model.delete( model.Calculation ).where( model.Calculation.checksum == checksum ) )
          session.commit()
          # NB tables topics, codefamily, codeversion, pottype are mostly irrelevant and, if needed, should be cleaned manually
          return False