Python API

This reference is generated from the current checkout. The GUI guide and CLI reference describe user workflows; the modules below expose the corresponding Python interfaces. Explicit module lists avoid importing the executable adsfolio.cli.__main__ entry point during documentation discovery.

Client, configuration, and formatting

adsfolio	ADSfolio research library tools and NASA ADS client.
adsfolio.client	Base HTTP client for NASA ADS with rate limiting and caching.
adsfolio.config	Configuration and token management for NASA ADS.
adsfolio.data_migration	Read earlier application data without changing the source files.
adsfolio.user_profile	Global publication-profile settings for the current user.
adsfolio.pubcache	Persistent user-level cache for the user's ADS publication universe.
adsfolio.citations	Plain-text citation domain models, validation, and rendering.
adsfolio.formatting
adsfolio.journal_utils	Resolve and format journal names from ADS bibstems.
adsfolio.library_sync	Qt-free local selection and ADS library synchronization helpers.

ADS services and BibTeX

ADSfolio implements its own Python client using requests to call the official NASA ADS API at https://api.adsabs.harvard.edu/v1. The ADS team’s API documentation and examples cover search, export, metrics, libraries, and journals. That repository documents the service. It is not an installed client dependency.

adsfolio.api	API module exports.
adsfolio.api.search	Search API wrapper for ADS.
adsfolio.api.export	Export API wrapper for ADS.
adsfolio.api.libraries	Libraries API wrapper for ADS.
adsfolio.api.metrics	Metrics API wrapper for ADS.
adsfolio.api.journals	Journals API wrapper for ADS.
adsfolio.bibtex	BibTeX utilities module.
adsfolio.bibtex.parser	BibTeX parsing utilities.
adsfolio.bibtex.formatter	Journal name formatting utilities.
adsfolio.bibtex.io	File I/O utilities for bibcode and BibTeX files.
adsfolio.bibtex.sanitize	Repair malformed field values in ADS BibTeX exports.
adsfolio.references	Local references with optional ADS identities and PDF attachments.
adsfolio.citekeys	Citation keys for BibTeX export, for papers inside and outside ADS.

Publication lists and CLI

adsfolio.cli	CLI package with lazy access to the Click command group.
adsfolio.cli.commands	CLI command definitions and entry point for adsfolio.
adsfolio.reference_cli	Import external references and export local bibliographies from the CLI.
adsfolio.cv	Public API for CV publication list generation.
adsfolio.cv.config	Configuration loading for adsfolio cv.
adsfolio.cv.config_starter	Starter cv.yaml payload helpers for adsfolio cv init.
adsfolio.cv.query	ADS query + classification helpers for adsfolio cv.
adsfolio.cv.renderer	Render ADS publication docs into LaTeX or Markdown CV fragments.
adsfolio.cv.template	User-defined CV templates for LaTeX, HTML, Markdown, or plain text.
adsfolio.cv.render_factory	Renderer factory and style previews for adsfolio cv.
adsfolio.cv.render_legend	Legend and section-label helpers for CV renderers.
adsfolio.cv.cli	Click command group for adsfolio cv.

PDF catalog and processing

adsfolio.pdf	PDF tooling for ADS metadata identification and organization.
adsfolio.pdf.sidecar	Sidecar JSON management for PDF identification metadata.
adsfolio.pdf.catalog	Central local catalog for PDF attachments and observed file locations.
adsfolio.pdf.registry	Root-scoped views over the central PDF catalog.
adsfolio.pdf.search	Match library search text against catalog records.
adsfolio.pdf.cli	Click command group for PDF identification and organization.
adsfolio.pdf.cli_common	Shared helpers for pdf CLI commands.
adsfolio.pdf.cli_upgrade	Upgrade-specific CLI command for adsfolio pdf.
adsfolio.pdf.arxiv	Derive arXiv identifiers from PDF file and ADS metadata records.
adsfolio.pdf.files	Enumerate PDF files in a library directory.
adsfolio.pdf.identifier	PDF-to-ADS record identification utilities.
adsfolio.pdf.reference_lookup	Match bibliographic reference hints against the current PDF's identity.
adsfolio.pdf.identity	Verify that a PDF is the paper that metadata claims it is.
adsfolio.pdf.document_identity_evidence	Corroborate PDF identity evidence from mutual DocInfo, text, and provider matches.
adsfolio.pdf.identity_repair	Reversible repair of PDFs that are attached to the wrong paper.
adsfolio.pdf.doi_providers	Metadata provider abstractions for DOI lookup.
adsfolio.pdf.readiness	Metadata readiness verification for catalog records.
adsfolio.pdf.identify	Cached PDF identification workflow.
adsfolio.pdf.identify_settings	Canonical settings shared by PDF Identify interfaces.
adsfolio.pdf.recheck_worker	Run one library's automatic identifier recheck in a separate process.
adsfolio.pdf.rename_preview	Build a rename preview in a separate process for the desktop app.
adsfolio.pdf.rename_settings	Canonical settings shared by PDF Rename interfaces.
adsfolio.pdf.renamer	Template-based PDF renaming engine.
adsfolio.pdf.watcher	PDF filesystem watcher with polling and optional watchdog backends.
adsfolio.pdf.watch_session	Pure Python watch session state machine and immutable event types.
adsfolio.pdf.tracked_move	Filesystem moves kept consistent with the PDF catalog.
adsfolio.pdf.prefetch	Publication prefetch helpers to reduce first-run ADS query volume.
adsfolio.pdf.obsidian	Obsidian-friendly Markdown note generation for tracked PDFs.
adsfolio.pdf.annotations	Annotation extraction and porting helpers for PDF upgrades.
adsfolio.pdf.annotation_merge	Move annotations between PDF editions of the same paper into a new copy.
adsfolio.pdf.annotation_matching	Find annotation locations locally for explicit review.
adsfolio.pdf.upgrade	arXiv-to-published PDF upgrade workflow.
adsfolio.pdf.upgrade_utils	Utility models and helpers for arXiv upgrade workflow.

Desktop GUI

These modules require the gui extra (PySide6). Importing them does not launch a window. See App GUI guide for operation and Building the desktop app for standalone bundle setup.

adsfolio.gui	PySide6 desktop application for browsing local ADS PDF libraries.
adsfolio.gui.app	Application entry point for the ADSfolio desktop GUI.
adsfolio.gui.about	Show application information and the latest release check.
adsfolio.gui.updates	Check GitHub for stable desktop releases without blocking the window.
adsfolio.gui.update_dialog	Show available releases, their changes, and the install path for this copy.
adsfolio.gui.welcome	First-run guide shown while no library folder has been added.
adsfolio.gui.cv_dialog	Build a CV publication list in any text format from your ADS records.
adsfolio.gui.export_dialog	One window that exports library papers as BibTeX, citation text, or a list.
adsfolio.gui.search_completion	Suggest field names and values while the user types a search query.
adsfolio.gui.config	Persistent configuration for the adsfolio desktop application.
adsfolio.gui.library	Qt-free data definitions for the PDF library table.
adsfolio.gui.icons	Small stroke icons rendered as vectors using each widget's Qt palette.
adsfolio.gui.models	Qt models for the paged PDF library table.
adsfolio.gui.main_window	Main three-pane desktop window for the adsfolio PDF library.
adsfolio.gui.detail_pane	Editable, reorderable metadata detail pane for a selected PDF.
adsfolio.gui.annotation_merge	Interactive review dialog for moving annotations between PDF editions.
adsfolio.gui.merge_cleanup	Offer reversible original-file cleanup after a verified PDF merge.
adsfolio.gui.edition_merge	Choose PDF editions using shared identifiers and explicit user review.
adsfolio.gui.dialogs	Dialogs for identify and rename operations.
adsfolio.gui.appearance	Table and metadata-pane appearance preferences.
adsfolio.gui.citation_styles	Dialog for editing and managing custom citation styles.
adsfolio.gui.ads_library_dialog	Dialogs for selecting and populating an ADS library.
adsfolio.gui.ads_library_export_dialog	Dialog for exporting a complete ADS library.
adsfolio.gui.references_dialog	Add local references and export them without an ADS lookup.
adsfolio.gui.ads_library_jobs	Thread-owned one-shot jobs for ADS library operations.
adsfolio.gui.jobs	Qt subprocess helpers for running the existing adsfolio CLI.
adsfolio.gui.refresh_job	Run a local library refresh without blocking the GUI.
adsfolio.gui.token_dialog	Desktop token setup using the existing per-user configuration.
adsfolio.gui.notifications	Compact non-modal notifications for the desktop GUI.
adsfolio.gui.osint	Operating-system integration for opening and revealing library files.
adsfolio.gui.watch	Thread-owned PDF watch workers and their GUI-thread controller.