class_docstr: Export the content of a dataset as a ZIP archive to figshare
  
  Very quick and dirty approach.  Ideally figshare should be supported as
  a proper git annex special remote.  Unfortunately, figshare does not support
  having directories, and can store only a flat list of files.  That makes
  it impossible for any sensible publishing of complete datasets.
  
  The only workaround is to publish dataset as a zip-ball, where the entire
  content is wrapped into a .zip archive for which figshare would provide a
  navigator.
class_docstr_tok: ["Export","the","content","of","a","dataset","as","a","ZIP","archive","to","figshare","Very","quick","and","dirty","approach",".","Ideally","figshare","should","be","supported","as","a","proper","git","annex","special","remote",".","Unfortunately",",","figshare","does","not","support","having","directories",",","and","can","store","only","a","flat","list","of","files",".","That","makes","it","impossible","for","any","sensible","publishing","of","complete","datasets",".","The","only","workaround","is","to","publish","dataset","as","a","zip-ball",",","where","the","entire","content","is","wrapped","into","a",".zip","archive","for","which","figshare","would","provide","a","navigator","."]
code: def __call__(
      filename=None,
      *,
      dataset=None,
      missing_content="error",
      no_annex=False,
      # TODO: support working with projects and articles within them
      # project_id=None,
      article_id=None,
  ):
      import logging
  
      lgr = logging.getLogger("datalad.plugin.export_to_figshare")
  
      from datalad.ui import ui
      from datalad.api import add_archive_content
      from datalad.api import export_archive
      from datalad.distribution.dataset import require_dataset
      from datalad.support.annexrepo import AnnexRepo
  
      dataset = require_dataset(
          dataset, check_installed=True, purpose="export to figshare"
      )
  
      if not isinstance(dataset.repo, AnnexRepo):
          raise ValueError(
              "%s is not an annex repo, so annexification could be done"
              % dataset
          )
  
      if dataset.repo.dirty:
          yield get_status_dict(
              "export_to_figshare",
              ds=dataset,
              status="impossible",
              message=(
                  "clean dataset required to export; "
                  "use `datalad status` to inspect unsaved changes"
              ),
          )
          return
      if filename is None:
          filename = dataset.path
      lgr.info(
          "Exporting current tree as an archive under %s since figshare "
          "does not support directories",
          filename,
      )
      archive_out = next(
          export_archive(
              dataset=dataset,
              filename=filename,
              archivetype="zip",
              missing_content=missing_content,
              return_type="generator",
          )
      )
      assert archive_out["status"] == "ok"
      fname = str(archive_out["path"])
  
      lgr.info("Uploading %s to figshare", fname)
      figshare = FigshareRESTLaison()
  
      if not article_id:
          # TODO: ask if it should be an article within a project
          if ui.is_interactive:
              # or should we just upload to a new article?
              if ui.yesno(
                  "Would you like to create a new article to upload to?  "
                  "If not - we will list existing articles",
                  title="Article",
              ):
                  article = figshare.create_article(
                      title=_enter_title(ui, dataset)
                  )
                  lgr.info(
                      "Created a new (private) article %(id)s at %(url_private_html)s. "
                      "Please visit it, enter additional meta-data and make public",
                      article,
                  )
                  article_id = article["id"]
              else:
                  article_id = int(
                      ui.question(
                          "Which of the articles should we upload to.",
                          choices=list(
                              map(str, figshare.get_article_ids())
                          ),
                      )
                  )
          if not article_id:
              raise ValueError("We need an article to upload to.")
  
      file_info = figshare.upload_file(
          fname, files_url="account/articles/%s/files" % article_id
      )
  
      if no_annex:
          lgr.info("Removing generated tarball")
          unlink(fname)
      else:
          # I will leave all the complaining etc to the dataset add if path
          # is outside etc
          lgr.info("'Registering' %s within annex", fname)
          repo = dataset.repo
          repo.add(fname, git=False)
          key = repo.get_file_annexinfo(fname)["key"]
          lgr.info("Adding URL %(download_url)s for it", file_info)
          repo.call_annex(
              [
                  "registerurl",
                  "-c",
                  "annex.alwayscommit=false",
                  key,
                  file_info["download_url"],
              ]
          )
  
          lgr.info(
              "Registering links back for the content of the archive"
          )
          add_archive_content(
              fname,
              dataset=dataset,
              delete_after=True,  # just remove extracted into a temp dir
              allow_dirty=True,  # since we have a tarball
              commit=False,  # we do not want to commit anything we have done here
          )
  
          lgr.info(
              "Removing generated and now registered in annex archive"
          )
          repo.drop(key, key=True, options=["--force"])
          repo.remove(fname, force=True)  # remove the tarball
  
          # if annex in {'delete'}:
          #     dataset.repo.remove(fname)
          # else:
          #     # kinda makes little sense I guess.
          #     # Made more sense if export_archive could export an arbitrary treeish
          #     # so we could create a branch where to dump and export to figshare
          #     # (kinda closer to my idea)
          #     dataset.save(fname, message="Added the entire dataset into a zip file")
  
      # TODO: add to downloader knowledge about figshare token so it could download-url
      # those zipballs before they go public
      yield dict(
          status="ok",
          # TODO: add article url (which needs to be queried if only ID is known
          message="Published archive {}".format(
              file_info["download_url"]
          ),
          file_info=file_info,
          path=dataset,
          action="export_to_figshare",
          logger=lgr,
      )
  
imports: from datalad.utils import unlink
  from datalad.interface.base import Interface
  from datalad.interface.base import build_doc
  from datalad.interface.results import get_status_dict
  import logging
label_desc: Use image node_id 1 for calling the ExportToFigshare obj's underlying member method code with example usage: obj.__call__(filename) without return types