Metadata-Version: 2.1
Name: hep-paper-manager
Version: 0.3.0
Summary: A command-line app helps add High Energy Physics (HEP) papers to a Notion database.
Home-page: https://github.com/Star9daisy/hep-paper-manager
License: MIT
Keywords: high-energy-physics,inspire-hep,notion,cli
Author: Star9daisy
Author-email: star9daisy@outlook.com
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: notion-database (>=1.1.0,<2.0.0)
Requires-Dist: pyfiglet (>=0.8.0,<0.9.0)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: requests (>=2.31.0,<3.0.0)
Requires-Dist: rich (>=13.4.1,<14.0.0)
Requires-Dist: typer[all] (>=0.9.0,<0.10.0)
Requires-Dist: typing-extensions (>=4.6.3,<5.0.0)
Project-URL: Repository, https://github.com/Star9daisy/hep-paper-manager
Description-Content-Type: text/markdown

# HEP Paper Manager (HPM)

![workflow](https://s2.loli.net/2024/08/13/8NGUdRiV7DFl5WH.png)

HPM is a command-line tool that helps adds literature from Inspire HEP to a
Notion database according to its arXiv ID.

It has features as following:
- Retrieve papers by arXiv ID.
- Customizable paper template.
- Interactive CLI for easy setup and usage.

## Installation
```
pip install hep-paper-manager
```

## Let's add a paper to a Notion database!
In this step-by-step guide, we will together add "[1511.05190] Jet image -- deep
learning edition"([link](https://inspirehep.net/literature/1405106)) to a Notion
database.

### Step 0: Create an integration in Notion
1. Open [My Integrations](https://www.notion.so/my-integrations).
2. Click `+ New integration`.
3. Enter a name for your integration.
4. Select your workspace.
4. Click `show` and `copy` the integration secret as your token.

Check the official guide for integrations
[here](https://developers.notion.com/docs/create-a-notion-integration).

![Create an integration](https://s2.loli.net/2024/08/13/zya7foBb9t4sdF1.gif)

### Step 1: Create a Notion database
A database is the place where we'll put all papers. Each item (or page)
represents a paper.

1. Follow the gif to create a database.

   ![create a database](https://s2.loli.net/2024/08/13/1juSdLEIJhN64KW.gif)

2. Add the following properties by clicking `+` on the right:

  | Property             | Type         |
  | -------------------- | ------------ |
  | Title                | Title        |
  | Authors              | Multi-select |
  | Date                 | Date         |
  | Published in         | Select       |
  | ArXiv ID             | Text         |
  | DOI                  | Text         |
  | Number of citations  | Number       |
  | Number of references | Number       |
  | Number of pages      | Number       |
  | Abstract             | Text         |
  | Bibtex               | Text         |
  | URL                  | URL          |

   ![Add properties](https://s2.loli.net/2024/08/13/bcNFe3rWhfd4P1A.gif)

After you finish it, open any page to check all properties, which should look
like this:

![An empty page](https://s2.loli.net/2024/08/13/A5ghwXqle6dDZma.png)

3. Connect to the integration.
   ![Connect to integration](https://s2.loli.net/2024/08/13/kBcjlYVtd1eOyLo.gif)

### Step 2: Set up `hpm`
1. Install `hep-paper-manager`.
   ```bash
   pip install hep-paper-manager
   ```

2. Initialize it to add the token.
   ```bash
   hpm init
   ```
   ![hpm init](https://imgur.com/uxBkbW6.gif)


### Step 3: Add the paper to the database
Usually, we search for papers on Inspire. The Inspire ID is the number in the
URL.
![inpsire](https://imgur.com/E3meDtH.gif)

In the command line, we use `hpm add` to add the paper to the database.
```bash
hpm add 1405106
```

Let's go back and check the database page. The paper is right there!
![database](https://imgur.com/r9bWdlm.png)

Of course, you can also add papers by Arxiv ID or DOI.
```bash
hpm add 1511.05190 --id-type arxiv
hpm add "10.1007/JHEP07(2016)069" --id-type doi
```
![other id](https://imgur.com/j4zi8ws.png)

You can now add more papers to your Notion database.

### Step 4: Update the paper
After a while, the paper may have newer information like citation number. You
can update the paper in the database by `hpm update`.
```bash
hpm update 1405106
```

Just like `hpm add`, you can also update papers by Arxiv ID or DOI.
```bash
hpm update 1511.05190 --id-type arxiv
hpm update "10.1007/JHEP07(2016)069" --id-type doi
```

Note, the columns in the database but not in the template will not be updated.
So you can add more columns to the database without worrying about losing
information.

## Engines
- `Inspire`: It fetches papers from the [Inspire HEP](https://inspirehep.net/).
   It serves the default engine for `hpm`. `InspirePaper` has the following
   properties:
   - date: str
   - citations: int
   - title: str
   - type: str
   - journal: str
   - authors: list[str]
   - link: str
   - abstract: str
   - bibtex: str
   - inspire_id: str
   - arxiv_id: str
   - doi: str


## Templates
Template saves the mapping from paper properties to Notion database properties.
You can adjust the properties within the template.

Below is the default template for `Inspire` engine which holds all properties
of `InspirePaper`:
- `paper.yml`
  ```yaml
  engine: Inspire
  database_id: <database_id>
  properties:
    date: Date
    citations: Citations
    title: Title
    type: Type
    journal: Journal
    authors: Authors
    link: Link
    abstract: Abstract
    bibtex: Bibtex
    inspire_id: Inspire ID
    arxiv_id: Arxiv ID
    doi: DOI
  ```
  These properties match the properties of the InpspirePaper class. You can
  modify the template to fit your needs.

  ! Remember the last three lines are necessary. You can't remove them.

## Updates
### v0.2.2
- Fix the error when `hpm add` some conference papers that may have no publication info.

### v0.2.1
- Fix the bug that `hpm add` only checks the first 100 pages in the database.
- Fix the checkmark style.

### v0.2.0
- Refactor the codebase by introducing `notion_database`.
- Add `hpm update` to update one paper in the database.
- Add `hpm info` to show the information of this app.

### v0.1.4
- Update print style.
- Add friendly error message when the `database_id` is not specified.
### v0.1.3
- Update `hpm add` to check if the paper already exists in the database.
- You can now create a database with more properties then the template.
### v0.1.2
- Update paper from Inspire engine to include url, bibtex, and source.
### v0.1.1
- Add `hpm init` for interactive setup.
- Add `hpm add` for adding a paper to a Notion database.
- Introduce the default `Inspire` engine and `paper.yml` template.

