adsfolio 0.5.1__tar.gz

adsfolio-0.5.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Yoonsoo P. Bach
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

adsfolio-0.5.1/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: adsfolio
+Version: 0.5.1
+Summary: Research PDF management with ADS, Crossref, DataCite, and local references
+Author-email: "Yoonsoo P. Bach" <ysbach20766@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/ysBach/adsfolio
+Project-URL: Documentation, https://ysbach.github.io/adsfolio/docs/
+Project-URL: Repository, https://github.com/ysBach/adsfolio
+Project-URL: Issues, https://github.com/ysBach/adsfolio/issues
+Keywords: ads,scixplorer,astronomy,astrophysics,heliophysics,physics,life-sciences,space-biology,microgravity,materials-science,earth-science,atmospheric-science,oceanography,planetary-science,bibliography,scientific-literature
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Oceanography
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: click>=8.0
+Requires-Dist: platformdirs>=3.0
+Requires-Dist: tqdm>=4.66
+Requires-Dist: pypdf>=4.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: bibtexparser<2,>=1.4.3
+Requires-Dist: pyparsing>=3.0
+Provides-Extra: full
+Requires-Dist: pymupdf>=1.24; extra == "full"
+Requires-Dist: watchdog>=3.0; extra == "full"
+Requires-Dist: iso4>=0.0.2; extra == "full"
+Provides-Extra: gui
+Requires-Dist: PySide6>=6.6; extra == "gui"
+Requires-Dist: packaging>=23.2; extra == "gui"
+Dynamic: license-file
+
+# ADSfolio
+
+A desktop application and Python toolkit for organizing research PDFs with NASA
+ADS / SciXplorer, Crossref, and DataCite metadata. ADSfolio is an independent
+project, not an official ADS application.
+
+![ADSfolio logo](https://raw.githubusercontent.com/ysBach/adsfolio/main/docs/_static/adsfolio.png)
+
+## Start with the PDFs you already have
+
+Add your existing PDF folder. Identify papers in a batch, inspect their metadata,
+and preview useful filenames before you rename anything. You can keep your
+current folder structure. You do not need to import PDFs into managed storage.
+
+Identification checks saved results before online lookups. Lookup time depends on
+PDF text quality, cache coverage, provider limits, and your connection. No fixed
+speed claim applies to every collection. Start with one folder to check results.
+
+![ADSfolio library window](https://raw.githubusercontent.com/ysBach/adsfolio/main/docs/_static/app-overview.png)
+
+*Application screenshot with illustrative sample data. Version 0.5.0 shown.*
+
+[Website](https://ysbach.github.io/adsfolio/) · [First-library tutorial](https://ysbach.github.io/adsfolio/docs/getting-started.html) · [Application guide](https://ysbach.github.io/adsfolio/docs/gui.html)
+
+## Three everyday workflows
+
+- **Keep a BibTeX file for your paper.** Add the papers you cite to a NASA ADS
+  library, then choose **Tools → Export ADS Library…** to save a `.bib` file for
+  LaTeX or Overleaf. `adsfolio library watch` keeps that file current while you
+  write.
+- **Watch a folder and rename new papers.** Right-click a library and choose
+  **Watch Current Library** and **Automatically Identify & Rename**. Each new PDF
+  gets publication details and a filename from your Rename template.
+- **Make your CV from your publications.** **Tools → CV Generator…** builds your
+  publication list from NASA ADS in LaTeX, HTML, Markdown, plain text, or your
+  own template. You choose how to highlight your name and how each entry looks.
+
+[See the three workflows with screenshots and a short video](https://ysbach.github.io/adsfolio/docs/workflows.html).
+
+## Install the desktop app
+
+Download [ADSfolio 0.5.1](https://github.com/ysBach/adsfolio/releases/latest).
+macOS downloads include DMG installers and ZIP archives.
+Desktop downloads include Python and the application dependencies. You do not
+need a Python environment or an ADS token to browse your local library.
+
+| System | Download and open |
+| --- | --- |
+| macOS 15+, Apple Silicon | Open `adsfolio-macos-arm64.dmg`, drag `ADSfolio.app` to Applications, then open it. |
+| macOS 15+, Intel | Open `adsfolio-macos-x86_64.dmg`, drag `ADSfolio.app` to Applications, then open it. |
+| Windows x86-64 | Extract `adsfolio-windows-x86_64.zip`, then open `adsfolio.exe` inside the extracted folder. |
+| Linux x86-64 | Extract `adsfolio-linux-x86_64.tar.gz`, then run `adsfolio` inside the extracted folder. Requires glibc 2.39+ and system desktop libraries. |
+
+Keep the complete extracted folder together on Windows and Linux.
+See the [platform requirements](https://ysbach.github.io/adsfolio/docs/desktop.html) for details.
+
+### macOS with Homebrew
+
+```sh
+brew install --cask ysBach/adsfolio/adsfolio
+open -a ADSfolio
+```
+
+**Version 0.5.1 is unsigned and not notarized.** macOS can block opening even
+when Homebrew installation succeeds. After attempting to open ADSfolio, review
+**System Settings → Privacy & Security → Open Anyway** if macOS offers that
+option. Approve it only if you trust the release. Installation alone does not
+establish that the app can open. Windows can also show publisher warnings.
+
+### Start using your library
+
+![ADSfolio welcome page with three setup steps](https://raw.githubusercontent.com/ysBach/adsfolio/main/docs/_static/welcome.png)
+
+*Welcome page of a new installation. Version 0.5.0 shown.*
+
+[Watch the 28-second first-run video](https://ysbach.github.io/adsfolio/docs/getting-started.html#watch-the-first-run).
+
+1. Open ADSfolio. Choose **Add PDF Folder…** on the welcome page and select your
+   PDF folder. If it has subfolders, choose **Include Subfolders** or
+   **This Folder Only**.
+2. Select a PDF to inspect or edit its metadata. Double-click a row to open it
+   in your system PDF viewer.
+3. Choose **OK** in the **Identify** prompt to look up publication metadata.
+   The prompt also opens after adding a folder. Token setup opens if ADS needs it.
+   **Advanced options…** changes the provider order. Crossref and DataCite can
+   look up DOIs without an ADS token. Files keep their names and locations.
+4. Preview **Rename** before applying filename changes. Papers with sufficient
+   metadata can be renamed without an ADS bibcode. Use **File → Local References…**
+   for manual entries and BibTeX import/export, including references without PDFs.
+5. Press **Refresh** or **F5** after moving or deleting files outside ADSfolio.
+   This reconciles local files. Use the separate ADS refresh actions to update
+   remote metadata. Permanent cleanup remains a separate operation.
+
+See the [interactive application guide](https://ysbach.github.io/adsfolio/docs/gui.html) for watching folders,
+selection, metadata editing, notifications, and refresh options.
+
+### Updates and existing libraries
+
+Quit ADSfolio before replacing the app, or run `brew upgrade --cask adsfolio`.
+The catalog, metadata, and history live in your user data directory, outside the
+application bundle. Retain that directory when upgrading or uninstalling.
+
+Earlier settings and catalogs are copied into ADSfolio storage on first use.
+The source remains intact. Close the earlier application before migration and
+keep its data until you check the migrated library. Saved automatic watch and
+rename settings remain active, so review them before resuming library work.
+
+## CLI and Python
+
+ADSfolio also provides search, bibliography export, and scripted PDF workflows.
+See the [CLI and Python workflows](https://ysbach.github.io/adsfolio/docs/command-line-and-python.html),
+[CLI tutorials](https://ysbach.github.io/adsfolio/docs/cli-tutorials/index.html), and [API reference](https://ysbach.github.io/adsfolio/docs/api/index.html).
+Version 0.5.1 and later are on PyPI and need Python 3.10 or newer:
+
+```sh
+pip install adsfolio                # CLI and Python client
+pip install "adsfolio[full,gui]"    # also the desktop application (adsfolio-gui)
+```
+
+## License
+
+BSD-3-Clause

adsfolio-0.5.1/README.md

@@ -0,0 +1,122 @@
+# ADSfolio
+
+A desktop application and Python toolkit for organizing research PDFs with NASA
+ADS / SciXplorer, Crossref, and DataCite metadata. ADSfolio is an independent
+project, not an official ADS application.
+
+![ADSfolio logo](https://raw.githubusercontent.com/ysBach/adsfolio/main/docs/_static/adsfolio.png)
+
+## Start with the PDFs you already have
+
+Add your existing PDF folder. Identify papers in a batch, inspect their metadata,
+and preview useful filenames before you rename anything. You can keep your
+current folder structure. You do not need to import PDFs into managed storage.
+
+Identification checks saved results before online lookups. Lookup time depends on
+PDF text quality, cache coverage, provider limits, and your connection. No fixed
+speed claim applies to every collection. Start with one folder to check results.
+
+![ADSfolio library window](https://raw.githubusercontent.com/ysBach/adsfolio/main/docs/_static/app-overview.png)
+
+*Application screenshot with illustrative sample data. Version 0.5.0 shown.*
+
+[Website](https://ysbach.github.io/adsfolio/) · [First-library tutorial](https://ysbach.github.io/adsfolio/docs/getting-started.html) · [Application guide](https://ysbach.github.io/adsfolio/docs/gui.html)
+
+## Three everyday workflows
+
+- **Keep a BibTeX file for your paper.** Add the papers you cite to a NASA ADS
+  library, then choose **Tools → Export ADS Library…** to save a `.bib` file for
+  LaTeX or Overleaf. `adsfolio library watch` keeps that file current while you
+  write.
+- **Watch a folder and rename new papers.** Right-click a library and choose
+  **Watch Current Library** and **Automatically Identify & Rename**. Each new PDF
+  gets publication details and a filename from your Rename template.
+- **Make your CV from your publications.** **Tools → CV Generator…** builds your
+  publication list from NASA ADS in LaTeX, HTML, Markdown, plain text, or your
+  own template. You choose how to highlight your name and how each entry looks.
+
+[See the three workflows with screenshots and a short video](https://ysbach.github.io/adsfolio/docs/workflows.html).
+
+## Install the desktop app
+
+Download [ADSfolio 0.5.1](https://github.com/ysBach/adsfolio/releases/latest).
+macOS downloads include DMG installers and ZIP archives.
+Desktop downloads include Python and the application dependencies. You do not
+need a Python environment or an ADS token to browse your local library.
+
+| System | Download and open |
+| --- | --- |
+| macOS 15+, Apple Silicon | Open `adsfolio-macos-arm64.dmg`, drag `ADSfolio.app` to Applications, then open it. |
+| macOS 15+, Intel | Open `adsfolio-macos-x86_64.dmg`, drag `ADSfolio.app` to Applications, then open it. |
+| Windows x86-64 | Extract `adsfolio-windows-x86_64.zip`, then open `adsfolio.exe` inside the extracted folder. |
+| Linux x86-64 | Extract `adsfolio-linux-x86_64.tar.gz`, then run `adsfolio` inside the extracted folder. Requires glibc 2.39+ and system desktop libraries. |
+
+Keep the complete extracted folder together on Windows and Linux.
+See the [platform requirements](https://ysbach.github.io/adsfolio/docs/desktop.html) for details.
+
+### macOS with Homebrew
+
+```sh
+brew install --cask ysBach/adsfolio/adsfolio
+open -a ADSfolio
+```
+
+**Version 0.5.1 is unsigned and not notarized.** macOS can block opening even
+when Homebrew installation succeeds. After attempting to open ADSfolio, review
+**System Settings → Privacy & Security → Open Anyway** if macOS offers that
+option. Approve it only if you trust the release. Installation alone does not
+establish that the app can open. Windows can also show publisher warnings.
+
+### Start using your library
+
+![ADSfolio welcome page with three setup steps](https://raw.githubusercontent.com/ysBach/adsfolio/main/docs/_static/welcome.png)
+
+*Welcome page of a new installation. Version 0.5.0 shown.*
+
+[Watch the 28-second first-run video](https://ysbach.github.io/adsfolio/docs/getting-started.html#watch-the-first-run).
+
+1. Open ADSfolio. Choose **Add PDF Folder…** on the welcome page and select your
+   PDF folder. If it has subfolders, choose **Include Subfolders** or
+   **This Folder Only**.
+2. Select a PDF to inspect or edit its metadata. Double-click a row to open it
+   in your system PDF viewer.
+3. Choose **OK** in the **Identify** prompt to look up publication metadata.
+   The prompt also opens after adding a folder. Token setup opens if ADS needs it.
+   **Advanced options…** changes the provider order. Crossref and DataCite can
+   look up DOIs without an ADS token. Files keep their names and locations.
+4. Preview **Rename** before applying filename changes. Papers with sufficient
+   metadata can be renamed without an ADS bibcode. Use **File → Local References…**
+   for manual entries and BibTeX import/export, including references without PDFs.
+5. Press **Refresh** or **F5** after moving or deleting files outside ADSfolio.
+   This reconciles local files. Use the separate ADS refresh actions to update
+   remote metadata. Permanent cleanup remains a separate operation.
+
+See the [interactive application guide](https://ysbach.github.io/adsfolio/docs/gui.html) for watching folders,
+selection, metadata editing, notifications, and refresh options.
+
+### Updates and existing libraries
+
+Quit ADSfolio before replacing the app, or run `brew upgrade --cask adsfolio`.
+The catalog, metadata, and history live in your user data directory, outside the
+application bundle. Retain that directory when upgrading or uninstalling.
+
+Earlier settings and catalogs are copied into ADSfolio storage on first use.
+The source remains intact. Close the earlier application before migration and
+keep its data until you check the migrated library. Saved automatic watch and
+rename settings remain active, so review them before resuming library work.
+
+## CLI and Python
+
+ADSfolio also provides search, bibliography export, and scripted PDF workflows.
+See the [CLI and Python workflows](https://ysbach.github.io/adsfolio/docs/command-line-and-python.html),
+[CLI tutorials](https://ysbach.github.io/adsfolio/docs/cli-tutorials/index.html), and [API reference](https://ysbach.github.io/adsfolio/docs/api/index.html).
+Version 0.5.1 and later are on PyPI and need Python 3.10 or newer:
+
+```sh
+pip install adsfolio                # CLI and Python client
+pip install "adsfolio[full,gui]"    # also the desktop application (adsfolio-gui)
+```
+
+## License
+
+BSD-3-Clause

adsfolio-0.5.1/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "adsfolio"
+dynamic = ["version"]
+description = "Research PDF management with ADS, Crossref, DataCite, and local references"
+authors = [
+    {name = "Yoonsoo P. Bach", email = "ysbach20766@gmail.com"}
+]
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+readme = "README.md"
+keywords = [
+    "ads",
+    "scixplorer",
+    "astronomy",
+    "astrophysics",
+    "heliophysics",
+    "physics",
+    "life-sciences",
+    "space-biology",
+    "microgravity",
+    "materials-science",
+    "earth-science",
+    "atmospheric-science",
+    "oceanography",
+    "planetary-science",
+    "bibliography",
+    "scientific-literature",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Astronomy",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Scientific/Engineering :: Oceanography",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.28",
+    "click>=8.0",
+    "platformdirs>=3.0",
+    "tqdm>=4.66",
+    "pypdf>=4.0",
+    "pyyaml>=6.0",
+    "bibtexparser>=1.4.3,<2",
+    "pyparsing>=3.0",
+]
+
+[project.optional-dependencies]
+full = [
+    "pymupdf>=1.24",
+    "watchdog>=3.0",
+    "iso4>=0.0.2",
+]
+gui = ["PySide6>=6.6", "packaging>=23.2"]
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "pytest-qt>=4.2",
+    "isort>=5.13",
+    "ruff>=0.6",
+]
+desktop = ["pyinstaller>=6.16,<7"]
+docs = [
+    "sphinx>=7.4",
+    "myst-parser>=2.0",
+    "sphinx-click>=6.0",
+    "sphinx-rtd-theme>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ysBach/adsfolio"
+Documentation = "https://ysbach.github.io/adsfolio/docs/"
+Repository = "https://github.com/ysBach/adsfolio"
+Issues = "https://github.com/ysBach/adsfolio/issues"
+
+[project.scripts]
+adsfolio = "adsfolio.cli.commands:main"
+adsfolio-gui = "adsfolio.cli.commands:gui_command"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"adsfolio.gui" = ["assets/*"]
+
+[tool.setuptools.dynamic]
+version = {attr = "adsfolio.__version__"}
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.isort]
+profile = "black"
+known_third_party = ["packaging"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"

adsfolio-0.5.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

adsfolio-0.5.1/src/adsfolio/__init__.py

@@ -0,0 +1,16 @@
+"""ADSfolio research library tools and NASA ADS client."""
+
+from .client import ADSClient
+from .config import Config
+from .formatting import format_author_list_cv, format_title_latex
+from .journal_utils import format_journal
+
+__version__ = "0.5.1"
+__all__ = [
+    "ADSClient",
+    "Config",
+    "__version__",
+    "format_author_list_cv",
+    "format_journal",
+    "format_title_latex",
+]

adsfolio-0.5.1/src/adsfolio/api/__init__.py

@@ -0,0 +1,9 @@
+"""API module exports."""
+
+from .export import ExportAPI
+from .journals import JournalsAPI
+from .libraries import LibrariesAPI
+from .metrics import MetricsAPI
+from .search import SearchAPI
+
+__all__ = ["ExportAPI", "JournalsAPI", "LibrariesAPI", "MetricsAPI", "SearchAPI"]