bibdeskparser 0.1.0__tar.gz

bibdeskparser-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.3
+Name: bibdeskparser
+Version: 0.1.0
+Summary: Parser for Bibdesk database files
+Author: Michael Goerz
+Author-email: Michael Goerz <mail@michaelgoerz.net>
+License: MIT license
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+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: pyobjc-framework-cocoa ; sys_platform == 'darwin' and extra == 'macos'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/goerz/bibdeskparser
+Provides-Extra: macos
+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)
+[![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)
+[![Coverage](https://codecov.io/gh/goerz/bibdeskparser/branch/master/graph/badge.svg)](https://codecov.io/gh/goerz/bibdeskparser)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+BibDeskParser reads and writes [BibDesk][]
+`.bib` files exactly as BibDesk itself produces them: the header
+comment, linked files and URLs, `@string` macros, and static groups all
+round-trip byte-for-byte. The API centers on two classes: `Library`, a
+dict-like mapping of citation key to `Entry`, and `Entry`, a single
+bibliography record.
+
+Development of BibDeskParser happens on [Github][].
+
+You can read the full documentation [online][docs]. See the
+[page on BibDesk's `.bib` format][bibdesk-format] for details on how
+BibDesk's special `.bib` features are handled, and the
+[how-to guides][howto] for short recipes covering specific tasks.
+
+[docs]: https://goerz.github.io/bibdeskparser/
+[bibdesk-format]: https://goerz.github.io/bibdeskparser/bibdesk_format.html
+[howto]: https://goerz.github.io/bibdeskparser/howto.html
+
+## Introduction
+
+[BibDesk][] is a bibliography manager for macOS that stores
+its database library as a standard [BibTeX][] `.bib` file, but adds
+its own conventions on top of plain BibTeX -- tracking linked
+file attachments (macOS-specific), recording user-defined groups, custom
+support for `@string` macros and keyword fields, and more.
+
+These extended features are stored in custom fields of individual entries, and
+in comments in the `.bib` file. A generic BibTeX library like [BibtexParser][]
+is not aware of these BibDesk-specific features and thus provides no direct
+access to the stored data, and may even corrupt it on a round trip.
+BibDeskParser exists so you can read, script, and edit your BibDesk
+library directly in Python -- for batch edits, automation, or
+integration with other tools. It provides a simplified API on top
+of the [BibtexParser][] library.
+
+
+## Installation
+
+To install the latest released version of BibDeskParser:
+
+```
+pip install bibdeskparser
+```
+
+or, if you use [uv](https://docs.astral.sh/uv/):
+
+```
+uv add bibdeskparser
+```
+
+
+To install the latest development version from [Github][]:
+
+```
+pip install git+https://github.com/goerz/bibdeskparser.git@master#egg=bibdeskparser
+```
+
+
+## Usage
+
+```python
+>>> import tempfile
+>>> from pathlib import Path
+>>> from bibdeskparser import Entry, Library
+>>> tmpdir = tempfile.TemporaryDirectory()
+>>> bib_path = Path(tmpdir.name) / "references.bib"
+>>> bib = Library()
+>>> bib["Smith2020"] = Entry(
+...     "article",
+...     "Smith2020",
+...     fields={
+...         "title": "A Title",
+...         "author": "Smith, John and Doe, Jane",
+...         "journal": "J. Test",
+...         "year": "2020",
+...     },
+... )
+>>> bib.save(bib_path)
+
+>>> bib = Library(bib_path)
+>>> entry = bib["Smith2020"]
+>>> print(entry["title"])
+A Title
+>>> print(entry.author[0].last[0])  # 'Smith'
+Smith
+
+>>> entry["title"] = "A Better Title"
+>>> bib.groups["Favorites"] = ("Smith2020",)  # BibDesk static group
+>>> entry.groups
+('Favorites',)
+>>> bib.save()
+>>> tmpdir.cleanup()
+
+```
+
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/) to manage the development environment and [`make`](https://www.gnu.org/software/make/) as a task runner. After cloning the repository, run
+
+```
+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.
+
+[BibDesk]: https://bibdesk.sourceforge.io
+[BibTeX]: https://en.wikipedia.org/wiki/BibTeX
+[BibtexParser]: https://bibtexparser.readthedocs.io/en/main/
+[Github]: https://github.com/goerz/bibdeskparser
+[CONTRIBUTING.md]: https://github.com/goerz/bibdeskparser/blob/master/CONTRIBUTING.md

bibdeskparser-0.1.0/README.md

@@ -0,0 +1,121 @@
+# 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)
+[![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)
+[![Coverage](https://codecov.io/gh/goerz/bibdeskparser/branch/master/graph/badge.svg)](https://codecov.io/gh/goerz/bibdeskparser)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+BibDeskParser reads and writes [BibDesk][]
+`.bib` files exactly as BibDesk itself produces them: the header
+comment, linked files and URLs, `@string` macros, and static groups all
+round-trip byte-for-byte. The API centers on two classes: `Library`, a
+dict-like mapping of citation key to `Entry`, and `Entry`, a single
+bibliography record.
+
+Development of BibDeskParser happens on [Github][].
+
+You can read the full documentation [online][docs]. See the
+[page on BibDesk's `.bib` format][bibdesk-format] for details on how
+BibDesk's special `.bib` features are handled, and the
+[how-to guides][howto] for short recipes covering specific tasks.
+
+[docs]: https://goerz.github.io/bibdeskparser/
+[bibdesk-format]: https://goerz.github.io/bibdeskparser/bibdesk_format.html
+[howto]: https://goerz.github.io/bibdeskparser/howto.html
+
+## Introduction
+
+[BibDesk][] is a bibliography manager for macOS that stores
+its database library as a standard [BibTeX][] `.bib` file, but adds
+its own conventions on top of plain BibTeX -- tracking linked
+file attachments (macOS-specific), recording user-defined groups, custom
+support for `@string` macros and keyword fields, and more.
+
+These extended features are stored in custom fields of individual entries, and
+in comments in the `.bib` file. A generic BibTeX library like [BibtexParser][]
+is not aware of these BibDesk-specific features and thus provides no direct
+access to the stored data, and may even corrupt it on a round trip.
+BibDeskParser exists so you can read, script, and edit your BibDesk
+library directly in Python -- for batch edits, automation, or
+integration with other tools. It provides a simplified API on top
+of the [BibtexParser][] library.
+
+
+## Installation
+
+To install the latest released version of BibDeskParser:
+
+```
+pip install bibdeskparser
+```
+
+or, if you use [uv](https://docs.astral.sh/uv/):
+
+```
+uv add bibdeskparser
+```
+
+
+To install the latest development version from [Github][]:
+
+```
+pip install git+https://github.com/goerz/bibdeskparser.git@master#egg=bibdeskparser
+```
+
+
+## Usage
+
+```python
+>>> import tempfile
+>>> from pathlib import Path
+>>> from bibdeskparser import Entry, Library
+>>> tmpdir = tempfile.TemporaryDirectory()
+>>> bib_path = Path(tmpdir.name) / "references.bib"
+>>> bib = Library()
+>>> bib["Smith2020"] = Entry(
+...     "article",
+...     "Smith2020",
+...     fields={
+...         "title": "A Title",
+...         "author": "Smith, John and Doe, Jane",
+...         "journal": "J. Test",
+...         "year": "2020",
+...     },
+... )
+>>> bib.save(bib_path)
+
+>>> bib = Library(bib_path)
+>>> entry = bib["Smith2020"]
+>>> print(entry["title"])
+A Title
+>>> print(entry.author[0].last[0])  # 'Smith'
+Smith
+
+>>> entry["title"] = "A Better Title"
+>>> bib.groups["Favorites"] = ("Smith2020",)  # BibDesk static group
+>>> entry.groups
+('Favorites',)
+>>> bib.save()
+>>> tmpdir.cleanup()
+
+```
+
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/) to manage the development environment and [`make`](https://www.gnu.org/software/make/) as a task runner. After cloning the repository, run
+
+```
+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.
+
+[BibDesk]: https://bibdesk.sourceforge.io
+[BibTeX]: https://en.wikipedia.org/wiki/BibTeX
+[BibtexParser]: https://bibtexparser.readthedocs.io/en/main/
+[Github]: https://github.com/goerz/bibdeskparser
+[CONTRIBUTING.md]: https://github.com/goerz/bibdeskparser/blob/master/CONTRIBUTING.md

bibdeskparser-0.1.0/pyproject.toml

@@ -0,0 +1,149 @@
+[build-system]
+requires = ["uv_build>=0.9,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "bibdeskparser"
+version = "0.1.0"
+description = "Parser for Bibdesk database files"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT license" }
+authors = [
+    { name = "Michael Goerz", email = "mail@michaelgoerz.net" },
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = ["bibtexparser==2.0.0b9"]
+
+[project.optional-dependencies]
+macos = ["pyobjc-framework-Cocoa; sys_platform == 'darwin'"]
+
+[project.urls]
+Homepage = "https://github.com/goerz/bibdeskparser"
+
+[dependency-groups]
+dev = [
+    "pytest>=7",
+    "pytest-cov>=4",
+    "pytest-xdist>=3",
+    "packaging>=21",
+    "coverage>=7",
+    "coveralls>=3",
+    "ipdb>=0.13",
+    "ipython>=8",
+]
+docs = [
+    "sphinx>=7",
+    "sphinx_rtd_theme>=2",
+    "sphinx-copybutton>=0.5",
+    "sphinx-autobuild>=2024.2",
+    "myst-parser>=2",
+    "docs-versions-menu>=0.6",
+    "gitpython>=3",
+    "sphinx-autodoc2>=0.5",
+]
+lint = [
+    "black>=24",
+    "isort>=5",
+    "flake8>=6",
+    "flake8-pyproject>=1",
+    "pylint>=3",
+    "pre-commit>=3.5",
+]
+release = [
+    "click>=8",
+    "gitpython>=3",
+    "packaging>=21",
+    "pytest>=7",
+]
+
+[tool.black]
+line-length = 79
+
+[tool.isort]
+known_first_party = ["bibdeskparser"]
+force_single_line = false
+lines_after_imports = -1
+line_length = 79
+use_parentheses = true
+multi_line_output = 3
+include_trailing_comma = true
+skip_glob = ["src/*/__init__.py"]
+
+[tool.flake8]
+exclude = ["docs"]
+max-line-length = 79
+extend-ignore = [
+    # See https://github.com/PyCQA/pycodestyle/issues/373
+    "E203",
+    # don't care about "ambiguous variable names"
+    "E741",
+    # when I use lambdas, I know what I'm doing
+    "E731",
+]
+
+[tool.pytest.ini_options]
+# tests/Refs contains test data and standalone helper scripts, not tests
+addopts = "-ra --ignore=tests/Refs"
+
+[tool.coverage.run]
+relative_files = true
+source = ["bibdeskparser"]
+
+[tool.pylint."messages control"]
+disable = [
+    "invalid-name",
+    "unidiomatic-typecheck",
+    "consider-iterating-dictionary",
+    "consider-using-enumerate",
+    "too-many-lines",
+    "multiple-statements",
+    "wrong-spelling-in-comment",
+    "wrong-spelling-in-docstring",
+    "len-as-condition",
+    "import-error",
+    "too-many-function-args",
+    "assignment-from-none",
+    "too-many-instance-attributes",
+    "too-few-public-methods",
+    "too-many-public-methods",
+    "too-many-return-statements",
+    "too-many-branches",
+    "too-many-arguments",
+    "too-many-locals",
+    "too-many-statements",
+    "too-many-boolean-expressions",
+    "too-many-nested-blocks",
+    "exec-used",
+    "eval-used",
+    "using-constant-test",
+    "protected-access",
+    "global-statement",
+    "unused-argument",
+    "no-else-return",
+    "ungrouped-imports",
+    "unnecessary-lambda",
+]
+
+[tool.pylint.format]
+max-line-length = 79
+
+[tool.pylint.design]
+max-args = 10
+max-attributes = 15
+max-bool-expr = 10
+max-branches = 20
+max-locals = 30
+max-returns = 10
+max-statements = 200
+max-public-methods = 40

bibdeskparser-0.1.0/src/bibdeskparser/__init__.py

@@ -0,0 +1,23 @@
+"""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 .entry import Entry, Value
+from .library import Library, StaleFileError
+
+__version__ = version("bibdeskparser")
+
+# All members whose name does not start with an underscore must be listed
+# either in __all__ or in __private__
+__all__ = [
+    "Library",
+    "Entry",
+    "Value",
+    "StaleFileError",
+]
+__private__ = []