Package: paperoni
PaperoniSearchfor scientific papers on the command lineDownload PDFsGenerateBibTeXentriesGenerateHTMLfor your publications!Buildcollectionsof papersPaperoni uses the Microsoft Academic Knowledge API, which requires an API key:Get a Microsoft Academic Knowledge API key(free tier: 10,000 queries per month)Installpipinstallpaperoni# This will prompt for the API keypaperoniconfigOverviewThis is a curated set of examples of things you can do with Paperoni. Most of the flags shown below can be combined.# Search for papers from an authorpaperonisearch-aalanturing# Search for papers with a certain titlepaperonisearch-tthechemicalbasisofmorphogenesis# Search for the most cited AI papers of 2017paperonisearch-kartificialintelligence-y2017--cited# Collect papers into a filepaperonicollect-cmy-papers.json-aolivierbreuleux-y2018# Dump BibTeX for all papers in a collectionpaperonibibtex-cmy-papers.json>>papers.bib# Output a webpagepaperonihtml-cmy-papers.json# Collect info about a researcher into a file (interactive)paperoniresearcher-rresearchers.json-aolivierbreuleux# Search for papers from researchers with status "phd"paperonisearch-rresearchers.json--statusphdSearchThepaperoni searchcommand allows you to search for papers:$ paperoni search -h
usage: paperoni search [-h] [--author [VALUE [VALUE ...]]] [--cited]
                       [--collection VALUE] [--command VALUE] [--end VALUE]
                       [--group] [--institution [VALUE [VALUE ...]]]
                       [--key VALUE] [--keywords [VALUE [VALUE ...]]]
                       [--limit NUM] [--offset NUM] [--recent]
                       [--researchers VALUE] [--start VALUE]
                       [--status [VALUE [VALUE ...]]] [--symposium]
                       [--no-symposium] [--title [VALUE [VALUE ...]]]
                       [--venue VALUE] [--verbose]
                       [--words [VALUE [VALUE ...]]] [--workshop]
                       [--no-workshop] [--year NUM]

optional arguments:
  -h, --help            show this help message and exit
  --collection VALUE, -c VALUE
                        File containing the collection
  --command VALUE       Command to run on every paper
  --group               Group multiple versions of the same paper
  --key VALUE           Microsoft Cognitive API key
  --researchers VALUE, -r VALUE
                        Researchers file (JSON)
  --verbose, -v         Verbose output

search:
  --author [VALUE [VALUE ...]], -a [VALUE [VALUE ...]]
                        Search for an author
  --cited               Sort by most cited
  --end VALUE           End date (yyyy-mm-dd or yyyy)
  --institution [VALUE [VALUE ...]], -i [VALUE [VALUE ...]]
                        Search papers from institution
  --keywords [VALUE [VALUE ...]], -k [VALUE [VALUE ...]]
                        Search for keywords
  --limit NUM           Number of papers to fetch (default: 100)
  --offset NUM          Search offset
  --recent              Sort by most recent
  --start VALUE         Start date (yyyy-mm-dd or yyyy)
  --status [VALUE [VALUE ...]]
                        Researcher status(es) to filter for
  --symposium           List symposiums
  --no-symposium        Do not list symposiums
  --title [VALUE [VALUE ...]], -t [VALUE [VALUE ...]]
                        Search words in the title
  --venue VALUE         Search papers from a specific conference or journal
  --words [VALUE [VALUE ...]], -w [VALUE [VALUE ...]]
                        Search words in the title or abstract
  --workshop            List workshops
  --no-workshop         Do not list workshops
  --year NUM, -y NUM    YearThe interface will list each result interactively, allowing you to perform actions:lto show more information about the paper: abstract, affiliations, all linksbto print out a BibTeX entry for the paper (see alsopaperoni bibtex)pto save the PDF in the current directory, if a PDF is available (and doesn't require authentication or captchas)Generate BibTeXWithpaperoni bibtexyou can generate bibtex entries from a search or a collection. Each entry will have a reference name generated from the first author, year, longest word in the title and a small hash number.Generate HTMLWithpaperoni htmlyou can generate HTML from a search or a collection.Use--template my-template.htmlto use the specified file as a template. The publications will be inserted in the element with idpaperoni-papers, e.g.<div id="paperoni-papers">PAPERS GO HERE</div>. You can also specify a different id using the following syntax:--template my-template.html#mypapers.Use--template noneif you don't want to use a template at all an only want the raw HTML.Use--inject file.htmlto insert the papers into the elemnet with idpaperoni-papersdirectlyintofile.html.This will modify the file.Any previous contents of that div will be erased. For safety,paperoniwill create a backup file, with a.bkextension, unless you pass--no-backup.paperoni htmlincludesthe full search interface. You don't need to pass a collection if you want to search directly on the web.If you have a researchers file, you can pass it with-rand paperoni can generate bio links for any researchers in the set.You can see all the options withpaperoni html -h.CollectionsIt is possible to save papers into collections using:# Assuming you want your collection to be in my-collection.jsonpaperonicollect-cmy-collection.jsonThe options are the same assearch, but you can sort through the search results to add papers to the collection or reject them. Papers that were already added or rejected will be ignored, so the collection can be built incrementally by reusing the same search string and going through any new papers.paperoni search -c my-collection.jsonwill search for papers in the collection. The search algorithm may be slightly different since it is a purely local search.Researchers databaseFor more advanced uses you can create a researchers file that contains one or more people.The purpose ofpaperoni researcheris to properly identify authors, better than simply searching by name, because an individual may have several homonyms. Multiple authors can also be grouped so that you can search papers from all of them, so this can be useful to collect all of your organization's publications: simply register all of your researchers. You can even log their start/end dates, which will only collect publications from that time period.paperoni researcher -r researchers.json -a author namewill guide you interactively.Find ids: You will be asked whether certain papers are from the author or not, to weed out homonyms.Set a property: You can set arbitrary properties for the researcher. Note thatpaperoni htmlrecognizes thebioproperty. Erase a property by enteringnull.Add a role: You can optionally assign one or more "roles". A "role" is some arbitrary tag with optional start and end dates that can be assigned to a researcher.Then you can write for examplepaperoni collect -c org.json -r researchers.json --status xyzto collect papers from researchers when they had a given status. The-rflag is also compatible withpaperoni search.FAQI cannot find a paper.Paperoni usesMicrosoft Academicto find papers. First check if you can find the paper there. If it is indeed there, this is a bug with Paperoni and you should file an issue.If it isn't, the most likely reason is that the paper is too recent and has not yet been indexed. It can sometimes take a few weeks before a paper is indexed.The PDF download does not work.Try thelcommand, which will list all links pertaining to the paper, organized by type. Try opening them in your browser, it might work better.Can I manually enter a new paper into a collection?Assuming you mean a paper that is not indexed in the database, the answer, unfortunately, is no.Can I remove a paper from a collection?Yes, search for the paper(s) to remove, passing the collection using the-cargument, and use therinteractive command to remove it.$ paperoni search -c collection.json -t the paper title
================================================================================
Title: The paper title
Authors: Some Guy
Date: 2020-02-02
================================================================================
Enter a command (h or ? for help): b/p/[s]/r/q/l/h r
Removed 'The paper title' from the collection.You can use--command rto do this non-interactively.Programmatic APIThe API is very beta and unstable. It is liable to change arbitrarily.If you want to perform some custom operations like generating HTML exactly the way you want it, write some reference format other than BibTeX, or whatever else, here's some code to get you started. The following will search for papers by Alan Turing and will print out the titles and abstracts:importcoleo# You need these to wrap collection or researchers, if you want to provide# them outside of the command line.frompaperoni.ioimportPapersFile,ResearchersFile# There is also search(), the difference is that search() does not define# CLI arguments for collection and researchers but takes them as inputs# insteadfrompaperoni.commands.searchutilsimportsearch_extdefmain():papers=search_ext()forpaperinpapers:print(paper.title)print(paper.abstract)print("====")if__name__=="__main__":withcoleo.setvars(author="alan turing",# collection=PapersFile("alan.json"),# researchers=ResearchersFile("rsch.json"),):coleo.auto_cli(main,print_result=False)coleo.auto_cliwill expose all the search flags like--titleand whatnot that are defined insidesearch_ext, so you actually get all that for free.coleo.setvarslets you set any of the options programmatically, but some of them, likecollectionorresearchers, you will need to wrap yourself (see the commented lines).The API for the Paper object is kind of bad and in flux so I'm not going to document it right now, but if you dumppaper.datayou can see all the raw data and work from there.Check outcoleoif you want to define extra command line arguments inmain(), it's quite easy.Future versions ofpaperonimight break the API, so make sure to pin the version you're using.PluginsThe API is very beta and unstable. It is liable to change arbitrarily.You can add new commands to paperoni by registering them in thepaperoni.commandentry point. Command line options must be defined usingcoleo. If you are usingpoetry:pyproject.toml[tool.poetry.plugins."paperoni.command"]showprop="my_paperoni:showprop"my_paperoni/__init__.pyfromcoleoimportOption,default,tooledfrompaperoni.commands.searchutilsimportsearch@tooleddefshowprop():# Name of the property to display# [alias: -p]prop:Option&str=default("title")# This will add all the search optionspapers=search()forpaperinpapers:ifprop=="title":print(paper.title)elifprop=="venue":print(paper.venue)...Install the plugin:# If the plugin is accessible through pippipinstallmy_paperoni# If this is a local project:poetryinstallUse the plugin:paperonishowprop-pvenue-aalanturing--limit10Future versions ofpaperonimight break the API, so make sure to pin the version you're using.