docs: def _assemble_attachment(self, file, metadata):
          ''' store file and return a dict containing assembled metadata
  
              param `file` must be a path or a File Object
              param `metadata` must be a dict:
                  {
                    "name"  : "nome_buffo.ext"         # name of the file (extension included) [optional if a path was given]
                    "mime"  : "application/json"       # mime type of the file [optional]
                    "notes" : "this file is awesome"   # notes about this file [optional]
                  }
          '''
          res = dict()
  
          if isinstance(file, basestring) and os.path.isfile(file):
              res['name'] = metadata['name'] if 'name' in metadata else os.path.basename(file)
              res['size'] = os.path.getsize(file)
              res['sha1'] = calc_file_digest(file, algorithm="sha1")
  
          elif hasattr(file, 'read') and hasattr(file, 'seek'):
              if 'name' in metadata and metadata['name']:
                  res['name'] = metadata['name']
              elif hasattr(file, 'name'):
                  file['name'] = file.name
              else:
                  raise ValueError("Could not assign a name to the file")
  
              old_position = file.tell()
  
              file.seek(0, os.SEEK_END)
              res['size'] = file.tell() - old_position
              file.seek(old_position, os.SEEK_SET)
  
              res['sha1'] = calc_digest(file, algorithm="sha1")
              file.seek(old_position, os.SEEK_SET)
  
          else:
              raise ValueError("Unsupported file value type: {}".format(type(file)))
  
          res['id'] = uuid4().hex
          res['mime'] = metadata['mime'] if 'mime' in metadata else None
          res['notes'] = metadata['notes'] if 'notes' in metadata else ""
          res['download_count'] = 0
          fsdb_id = self._fsdb.add(file)
          res['url'] = "fsdb:///" + fsdb_id
          return res