bibdeskparser 0.1.0__tar.gz → 0.2.0__tar.gz

{bibdeskparser-0.1.0 → bibdeskparser-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: bibdeskparser
-Version: 0.1.0
+Version: 0.2.0
 Summary: Parser for Bibdesk database files
 Author: Michael Goerz
 Author-email: Michael Goerz <mail@michaelgoerz.net>
@@ -15,6 +15,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: bibtexparser==2.0.0b9
+Requires-Dist: click>=8
+Requires-Dist: tomli>=1.1.0 ; python_full_version < '3.11'
 Requires-Dist: pyobjc-framework-cocoa ; sys_platform == 'darwin' and extra == 'macos'
 Requires-Python: >=3.10
 Project-URL: Homepage, https://github.com/goerz/bibdeskparser
@@ -24,7 +26,7 @@ Description-Content-Type: text/markdown
 # BibDeskParser
 
 [![Source code on Github](https://img.shields.io/badge/goerz-bibdeskparser-blue.svg?logo=github)][Github]
-[![PyPI](https://img.shields.io/pypi/v/bibdeskparser.svg)](https://pypi.python.org/pypi/bibdeskparser)
+[![PyPI](https://img.shields.io/pypi/v/bibdeskparser)](https://pypi.python.org/pypi/bibdeskparser)
 [![Documentation](https://img.shields.io/badge/docs-gh--pages-blue.svg)][docs]
 [![Docs](https://github.com/goerz/bibdeskparser/actions/workflows/docs.yml/badge.svg?branch=master)](https://github.com/goerz/bibdeskparser/actions/workflows/docs.yml)
 [![Tests](https://github.com/goerz/bibdeskparser/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/goerz/bibdeskparser/actions/workflows/test.yml)
@@ -66,6 +68,16 @@ library directly in Python -- for batch edits, automation, or
 integration with other tools. It provides a simplified API on top
 of the [BibtexParser][] library.
 
+Making the bibliographic database accessible to AI coding agents is an
+explicit goal of the project: the [`bibdeskparser` command-line
+tool][cli] mirrors the public Python API, so any agent that can run
+shell commands can inspect and edit a BibDesk library, with no
+dedicated integration and no server to keep running. See [How to give
+an AI coding agent access to your library][howto-ai].
+
+[cli]: https://goerz.github.io/bibdeskparser/cli.html
+[howto-ai]: https://goerz.github.io/bibdeskparser/howto.html#how-to-give-an-ai-coding-agent-access-to-your-library
+
 
 ## Installation
 
@@ -75,12 +87,20 @@ To install the latest released version of BibDeskParser:
 pip install bibdeskparser
 ```
 
-or, if you use [uv](https://docs.astral.sh/uv/):
+If you use [uv](https://docs.astral.sh/uv/), add BibDeskParser as a
+dependency of your project with
 
 ```
 uv add bibdeskparser
 ```
 
+or install the `bibdeskparser` [command-line tool][cli] on your `PATH`,
+independently of any project, with
+
+```
+uv tool install bibdeskparser
+```
+
 
 To install the latest development version from [Github][]:
 
@@ -137,6 +157,14 @@ make develop
 
 to create a virtual environment with all development dependencies. Run `make help` for an overview of available targets, and see [CONTRIBUTING.md][] for full contributing guidelines.
 
+To put the `bibdeskparser` [command-line tool][cli] on your `PATH` as an *editable* install that links back to your working copy — so changes to the source take effect without reinstalling — run
+
+```
+make install
+```
+
+Use `make uninstall` to remove it again.
+
 [BibDesk]: https://bibdesk.sourceforge.io
 [BibTeX]: https://en.wikipedia.org/wiki/BibTeX
 [BibtexParser]: https://bibtexparser.readthedocs.io/en/main/

{bibdeskparser-0.1.0 → bibdeskparser-0.2.0}/README.md

@@ -1,7 +1,7 @@
 # BibDeskParser
 
 [![Source code on Github](https://img.shields.io/badge/goerz-bibdeskparser-blue.svg?logo=github)][Github]
-[![PyPI](https://img.shields.io/pypi/v/bibdeskparser.svg)](https://pypi.python.org/pypi/bibdeskparser)
+[![PyPI](https://img.shields.io/pypi/v/bibdeskparser)](https://pypi.python.org/pypi/bibdeskparser)
 [![Documentation](https://img.shields.io/badge/docs-gh--pages-blue.svg)][docs]
 [![Docs](https://github.com/goerz/bibdeskparser/actions/workflows/docs.yml/badge.svg?branch=master)](https://github.com/goerz/bibdeskparser/actions/workflows/docs.yml)
 [![Tests](https://github.com/goerz/bibdeskparser/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/goerz/bibdeskparser/actions/workflows/test.yml)
@@ -43,6 +43,16 @@ library directly in Python -- for batch edits, automation, or
 integration with other tools. It provides a simplified API on top
 of the [BibtexParser][] library.
 
+Making the bibliographic database accessible to AI coding agents is an
+explicit goal of the project: the [`bibdeskparser` command-line
+tool][cli] mirrors the public Python API, so any agent that can run
+shell commands can inspect and edit a BibDesk library, with no
+dedicated integration and no server to keep running. See [How to give
+an AI coding agent access to your library][howto-ai].
+
+[cli]: https://goerz.github.io/bibdeskparser/cli.html
+[howto-ai]: https://goerz.github.io/bibdeskparser/howto.html#how-to-give-an-ai-coding-agent-access-to-your-library
+
 
 ## Installation
 
@@ -52,12 +62,20 @@ To install the latest released version of BibDeskParser:
 pip install bibdeskparser
 ```
 
-or, if you use [uv](https://docs.astral.sh/uv/):
+If you use [uv](https://docs.astral.sh/uv/), add BibDeskParser as a
+dependency of your project with
 
 ```
 uv add bibdeskparser
 ```
 
+or install the `bibdeskparser` [command-line tool][cli] on your `PATH`,
+independently of any project, with
+
+```
+uv tool install bibdeskparser
+```
+
 
 To install the latest development version from [Github][]:
 
@@ -114,6 +132,14 @@ make develop
 
 to create a virtual environment with all development dependencies. Run `make help` for an overview of available targets, and see [CONTRIBUTING.md][] for full contributing guidelines.
 
+To put the `bibdeskparser` [command-line tool][cli] on your `PATH` as an *editable* install that links back to your working copy — so changes to the source take effect without reinstalling — run
+
+```
+make install
+```
+
+Use `make uninstall` to remove it again.
+
 [BibDesk]: https://bibdesk.sourceforge.io
 [BibTeX]: https://en.wikipedia.org/wiki/BibTeX
 [BibtexParser]: https://bibtexparser.readthedocs.io/en/main/

{bibdeskparser-0.1.0 → bibdeskparser-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "bibdeskparser"
-version = "0.1.0"
+version = "0.2.0"
 description = "Parser for Bibdesk database files"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -23,7 +23,14 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
 ]
-dependencies = ["bibtexparser==2.0.0b9"]
+dependencies = [
+    "bibtexparser==2.0.0b9",
+    "click>=8",
+    "tomli>=1.1.0; python_version < '3.11'",
+]
+
+[project.scripts]
+bibdeskparser = "bibdeskparser.cli:main"
 
 [project.optional-dependencies]
 macos = ["pyobjc-framework-Cocoa; sys_platform == 'darwin'"]

bibdeskparser-0.2.0/src/bibdeskparser/__init__.py

@@ -0,0 +1,40 @@
+"""Parser for [BibDesk](https://bibdesk.sourceforge.io) `.bib` files.
+
+This package builds on [bibtexparser](
+https://bibtexparser.readthedocs.io/en/main/) to read and write BibTeX
+databases as maintained by the BibDesk application.
+"""
+
+from importlib.metadata import version
+
+from . import config as _config
+from .entry import Entry
+from .library import Library, StaleFileError
+from .macros import MacroString, ValueString
+
+__version__ = version("bibdeskparser")
+
+# Load any bibdeskparser.toml from the current working directory or the
+# XDG location once, at import. Wrapped so that a malformed config file
+# can never prevent `import bibdeskparser`; it surfaces as a warning and
+# the built-in defaults are used instead. A `Library` re-applies the
+# configuration for its own directory when constructed.
+try:
+    _config.active.load()
+# pylint: disable-next=broad-except
+except Exception as _exc:  # pragma: no cover - config must not break import
+    import warnings as _warnings
+
+    _warnings.warn(f"failed to load bibdeskparser.toml: {_exc}", UserWarning)
+    del _warnings
+
+# All members whose name does not start with an underscore must be listed
+# either in __all__ or in __private__
+__all__ = [
+    "Library",
+    "Entry",
+    "ValueString",
+    "MacroString",
+    "StaleFileError",
+]
+__private__ = []

{bibdeskparser-0.1.0 → bibdeskparser-0.2.0}/src/bibdeskparser/bdskfile.py

@@ -52,7 +52,7 @@ class BibDeskFile:
       relative to the current working directory); defaults to the
       current working directory.
     * `must_exist`: whether to require `path` to point to an existing
-      file (raising {py:class}`FileNotFoundError` otherwise). With
+      file (raising {exc}`FileNotFoundError` otherwise). With
       `must_exist=False`, a nonexistent `path` yields a path-only
       attachment, without a bookmark and without any warning.
 
@@ -60,10 +60,10 @@ class BibDeskFile:
     `None` and the file exists, a bookmark is created automatically on
     macOS (requires `pyobjc-framework-Cocoa`). Where a bookmark cannot
     be created, the instance falls back to a path-only attachment with
-    a {py:class}`UserWarning` (BibDesk will generate a bookmark on its
+    a {exc}`UserWarning` (BibDesk will generate a bookmark on its
     next save).
 
-    Use {py:meth}`from_field_value` and {py:meth}`to_field_value` to
+    Use {meth}`from_field_value` and {meth}`to_field_value` to
     convert from and to the string value of a `bdsk-file-N` field:
 
     ```python
@@ -244,20 +244,20 @@ def bookmark_for_path(path: str) -> bytes:
     includingResourceValuesForKeys:nil relativeToURL:nil error:NULL]`
     via pyobjc, replicating exactly the Cocoa API BibDesk uses
     (`BDSKBookmarkLinkedFile.initWithURL:delegate:`). The resulting
-    bytes go into {py:attr}`BibDeskFile.bookmark`. The file must exist
+    bytes go into {attr}`BibDeskFile.bookmark`. The file must exist
     on disk.
 
     Requires macOS and `pyobjc-framework-Cocoa` (install
     `bibdeskparser[macos]`). For cross-platform code, use
-    {py:class}`BibDeskFile` directly; it falls back to a path-only
+    {class}`BibDeskFile` directly; it falls back to a path-only
     entry where bookmarks are unavailable (BibDesk auto-creates the
     bookmark on its next save).
 
     Raises:
 
-    * {py:class}`NotImplementedError`: on platforms other than macOS.
-    * {py:class}`ImportError`: if pyobjc is not installed.
-    * {py:class}`OSError`: if Cocoa fails to create the bookmark
+    * {exc}`NotImplementedError`: on platforms other than macOS.
+    * {exc}`ImportError`: if pyobjc is not installed.
+    * {exc}`OSError`: if Cocoa fails to create the bookmark
       (e.g., because the file does not exist).
     """
     if sys.platform != "darwin":