| Name | bibspire JSON |
| Version |
1.1.3
JSON |
| download |
| home_page | None |
| Summary | A tool to update .bib entries with INSPIRE-HEP citations |
| upload_time | 2025-08-27 20:33:06 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
bibliography
bibtex
inspire
hep
physics
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# BibSpire
A Python tool to update .bib file entries with INSPIRE-HEP citations while preserving reference keys.
[](https://github.com/lorenzennio/bibspire/actions)
[](https://python.org)
[](LICENSE)
[](https://codecov.io/gh/lorenzennio/bibspire)
## Overview
BibSpire reads a .bib file, searches each entry on inspire-hep.net, and replaces the entries with the official INSPIRE citations while keeping the same reference keys. This ensures your bibliography has the most accurate and complete citation information from INSPIRE-HEP.
## Features
- **Automatic INSPIRE Search**: Searches INSPIRE-HEP for each bibliography entry
- **Key Preservation**: Keeps original reference keys while updating content
- **Multiple Search Strategies**: Uses title, author, eprint, and DOI for matching
- **Robust Parsing**: Handles complex BibTeX formats with nested braces
- **Error Handling**: Gracefully handles missing entries and API errors
- **Rate Limiting**: Configurable delays between API requests
- **Code Quality**: Enforced with Ruff linting and formatting
- **Comprehensive Testing**: Full test suite with unit and integration tests
## Installation
### From PyPI (Recommended)
```bash
pip install bibspire
```
### From Source (Development)
```bash
# Clone the repository
git clone https://github.com/lorenzennio/bibspire.git
cd bibspire
# Install in development mode with dev dependencies
pip install -e ".[dev]"
```
### From Built Package
```bash
# Build and install
python -m build
pip install dist/bibspire-1.0.0-py3-none-any.whl
```
## Usage
### Command Line Interface
```bash
# Basic usage - update file in place
bibspire input.bib
# Save to different file
bibspire input.bib -o output.bib
# Verbose output
bibspire input.bib -v
# Custom delay between API requests
bibspire input.bib -d 2.0
# Show help
bibspire --help
```
### Run as Python Module
```bash
python -m bibspire input.bib -o output.bib -v
```
### Programmatic Usage
```python
from bibspire import BibSpire, BibParser
# Create BibSpire instance
bibspire = BibSpire(delay=1.0, verbose=True)
# Update a bibliography file
bibspire.update_bib_file("input.bib", "output.bib")
# Or work with entries directly
entries = BibParser.parse_bib_file("input.bib")
updated_entries = bibspire.update_entries(entries)
```
## Testing
The project includes a comprehensive test suite:
```bash
# Run fast unit and integration tests
pytest tests/ -v -m "not slow"
# Run all tests including slow real API tests
pytest tests/ -v
# Run only slow tests (real API calls)
pytest tests/ -v -m "slow"
# Run tests with coverage
pytest tests/ --cov=bibspire --cov-report=html
```
### Test Categories
- **Unit Tests** (`test_core.py`, `test_cli.py`): Fast tests with mocked dependencies
- **Integration Tests** (`test_integration.py`): Tests with mocked HTTP responses
- **Slow Tests** (`test_slow.py`): Real API calls to INSPIRE-HEP (marked as `slow`)
## Development
### Building and Testing
```bash
# Use Makefile targets
make help # Show all available targets
make all # Install deps, install pre-commit, run checks, and build
make check # Run linting, formatting, and fast tests
make ci # Run full CI checks with coverage
make pre-commit-install # Install pre-commit hooks
make pre-commit-run # Run pre-commit on all files
make test # Run fast tests only
make test-cov # Run fast tests with coverage
make lint # Run linting
make format # Format code
# Manual commands
pip install -e ".[dev]" # Install with dev dependencies
pytest tests/ -v # Run tests
pytest tests/ -v --cov=bibspire # Run tests with coverage
ruff check src/ tests/ # Run linting
ruff format src/ tests/ # Format code
python -m build # Build package
```
### Pre-commit Hooks
This project uses pre-commit hooks to ensure code quality. The hooks automatically run:
- Code linting and formatting with Ruff
- Trailing whitespace removal
- End-of-file fixes
- YAML and TOML validation
- Tests
To set up pre-commit hooks:
```bash
# Install and activate pre-commit hooks
make pre-commit-install
# Run pre-commit on all files manually
make pre-commit-run
```
Once installed, the hooks will run automatically on every commit. If any hook fails, the commit will be rejected until the issues are fixed.
### Publishing
#### Manual Publishing
```bash
# Install twine for uploading
pip install twine
# Check package integrity
twine check dist/*
# Upload to PyPI (requires account and authentication)
python -m twine upload dist/*
```
#### Automatic Publishing
The package is automatically published to PyPI when a new version tag is pushed:
```bash
git tag v1.0.1
git push origin v1.0.1
```
This triggers the release workflow which:
- Builds the package
- Checks package integrity
- Publishes to PyPI
- Creates a GitHub release
### Project Structure
```
bibspire/
├── .github/workflows/ # CI/CD workflows
├── src/bibspire/ # Main package
│ ├── __init__.py # Package exports
│ ├── __main__.py # Module entry point
│ ├── cli.py # Command-line interface
│ └── core.py # Core functionality
├── tests/ # Test suite
│ ├── conftest.py # Test fixtures
│ ├── test_core.py # Core functionality tests
│ ├── test_cli.py # CLI tests
│ ├── test_integration.py # Integration tests
│ └── test_slow.py # Slow API tests
├── pyproject.toml # Package configuration
├── Makefile # Development commands
└── README.md # This file
```
## Example
Given an input .bib file:
```bibtex
@article{mykey2023,
title = {Observation of a new particle in the search for the Standard Model Higgs boson},
author = {Aad, G. and others},
year = {2012}
}
```
BibSpire will search INSPIRE, find the official record, and replace it with:
```bibtex
@article{mykey2023,
author = {Aad, Georges and others},
collaboration = {ATLAS},
title = {{Observation of a new particle in the search for the Standard Model Higgs boson with the ATLAS detector at the LHC}},
eprint = {1207.7214},
archivePrefix = {arXiv},
primaryClass = {hep-ex},
doi = {10.1016/j.physletb.2012.08.020},
journal = {Phys. Lett. B},
volume = {716},
pages = {1--29},
year = {2012}
}
```
Note how the reference key `mykey2023` is preserved while all other fields are updated with official INSPIRE data.
## Dependencies
- Python ≥ 3.8
- requests ≥ 2.25.0
### Development Dependencies
- pytest ≥ 6.0.0
- pytest-mock ≥ 3.6.0
- responses ≥ 0.21.0
- ruff ≥ 0.1.0 (linting and formatting)
- build ≥ 0.8.0 (package building)
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for your changes
4. Run the test suite: `pytest tests/ -v`
5. Run linting: `make lint` or `ruff check src/ tests/`
6. Format code: `make format` or `ruff format src/ tests/`
7. Submit a pull request
### Code Quality
This project uses Ruff for linting and code formatting. The configuration includes:
- **Linting**: Enforces Python best practices, code style, and catches common errors
- **Formatting**: Consistent code style with 88-character line length
- **Import sorting**: Automatic import organization and cleanup
- **Type checking**: Basic type hint validation
Run `make check` to run all quality checks before submitting changes.
## Continuous Integration
This project uses GitHub Actions for automated testing and quality assurance:
### CI Workflow
- **Linting**: Ruff checks for code quality and style
- **Multi-Python Testing**: Tests run on Python 3.8-3.12
- **Coverage**: Code coverage reporting with Codecov integration
- **Integration Tests**: Slow tests run on main branch and when labeled
- **Package Building**: Validates package can be built locally
### Workflows
- `ci.yml`: Main CI pipeline for PRs and pushes
- `release.yml`: Automated publishing on version tags
### Quality Gates
All PRs must pass:
- Ruff linting (no violations)
- Code formatting check
- Test suite (35+ tests)
- Package build validation
To trigger slow integration tests, add the `run-slow-tests` label to your PR.
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Troubleshooting
### Command Not Found
If `bibspire` command is not found:
```bash
# Use full path or activate virtual environment
/path/to/venv/bin/bibspire input.bib
# Or run as module
python -m bibspire input.bib
```
### API Rate Limiting
If you encounter rate limiting:
```bash
# Increase delay between requests
bibspire input.bib -d 2.0
```
### Test Failures
If tests fail:
```bash
# Check dependencies
pip install -e ".[test]"
# Run specific test
pytest tests/test_core.py::TestBibEntry::test_init -v
```
Raw data
{
"_id": null,
"home_page": null,
"name": "bibspire",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "bibliography, bibtex, inspire, hep, physics",
"author": null,
"author_email": "Lorenz G\u00e4rtner <lorenz.gaertner@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c8/5c/e1478bc354987343a0929220315d5806925b7e137a3a790a5a8716b789d0/bibspire-1.1.3.tar.gz",
"platform": null,
"description": "# BibSpire\n\nA Python tool to update .bib file entries with INSPIRE-HEP citations while preserving reference keys.\n\n[](https://github.com/lorenzennio/bibspire/actions)\n[](https://python.org)\n[](LICENSE)\n[](https://codecov.io/gh/lorenzennio/bibspire)\n\n## Overview\n\nBibSpire reads a .bib file, searches each entry on inspire-hep.net, and replaces the entries with the official INSPIRE citations while keeping the same reference keys. This ensures your bibliography has the most accurate and complete citation information from INSPIRE-HEP.\n\n## Features\n\n- **Automatic INSPIRE Search**: Searches INSPIRE-HEP for each bibliography entry\n- **Key Preservation**: Keeps original reference keys while updating content\n- **Multiple Search Strategies**: Uses title, author, eprint, and DOI for matching\n- **Robust Parsing**: Handles complex BibTeX formats with nested braces\n- **Error Handling**: Gracefully handles missing entries and API errors\n- **Rate Limiting**: Configurable delays between API requests\n- **Code Quality**: Enforced with Ruff linting and formatting\n- **Comprehensive Testing**: Full test suite with unit and integration tests\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install bibspire\n```\n\n### From Source (Development)\n\n```bash\n# Clone the repository\ngit clone https://github.com/lorenzennio/bibspire.git\ncd bibspire\n\n# Install in development mode with dev dependencies\npip install -e \".[dev]\"\n```\n\n### From Built Package\n\n```bash\n# Build and install\npython -m build\npip install dist/bibspire-1.0.0-py3-none-any.whl\n```\n\n## Usage\n\n### Command Line Interface\n\n```bash\n# Basic usage - update file in place\nbibspire input.bib\n\n# Save to different file\nbibspire input.bib -o output.bib\n\n# Verbose output\nbibspire input.bib -v\n\n# Custom delay between API requests\nbibspire input.bib -d 2.0\n\n# Show help\nbibspire --help\n```\n\n### Run as Python Module\n\n```bash\npython -m bibspire input.bib -o output.bib -v\n```\n\n### Programmatic Usage\n\n```python\nfrom bibspire import BibSpire, BibParser\n\n# Create BibSpire instance\nbibspire = BibSpire(delay=1.0, verbose=True)\n\n# Update a bibliography file\nbibspire.update_bib_file(\"input.bib\", \"output.bib\")\n\n# Or work with entries directly\nentries = BibParser.parse_bib_file(\"input.bib\")\nupdated_entries = bibspire.update_entries(entries)\n```\n\n## Testing\n\nThe project includes a comprehensive test suite:\n\n```bash\n# Run fast unit and integration tests\npytest tests/ -v -m \"not slow\"\n\n# Run all tests including slow real API tests\npytest tests/ -v\n\n# Run only slow tests (real API calls)\npytest tests/ -v -m \"slow\"\n\n# Run tests with coverage\npytest tests/ --cov=bibspire --cov-report=html\n```\n\n### Test Categories\n\n- **Unit Tests** (`test_core.py`, `test_cli.py`): Fast tests with mocked dependencies\n- **Integration Tests** (`test_integration.py`): Tests with mocked HTTP responses\n- **Slow Tests** (`test_slow.py`): Real API calls to INSPIRE-HEP (marked as `slow`)\n\n## Development\n\n### Building and Testing\n\n```bash\n# Use Makefile targets\nmake help # Show all available targets\nmake all # Install deps, install pre-commit, run checks, and build\nmake check # Run linting, formatting, and fast tests\nmake ci # Run full CI checks with coverage\nmake pre-commit-install # Install pre-commit hooks\nmake pre-commit-run # Run pre-commit on all files\nmake test # Run fast tests only\nmake test-cov # Run fast tests with coverage\nmake lint # Run linting\nmake format # Format code\n\n# Manual commands\npip install -e \".[dev]\" # Install with dev dependencies\npytest tests/ -v # Run tests\npytest tests/ -v --cov=bibspire # Run tests with coverage\nruff check src/ tests/ # Run linting\nruff format src/ tests/ # Format code\npython -m build # Build package\n```\n\n### Pre-commit Hooks\n\nThis project uses pre-commit hooks to ensure code quality. The hooks automatically run:\n- Code linting and formatting with Ruff\n- Trailing whitespace removal\n- End-of-file fixes\n- YAML and TOML validation\n- Tests\n\nTo set up pre-commit hooks:\n\n```bash\n# Install and activate pre-commit hooks\nmake pre-commit-install\n\n# Run pre-commit on all files manually\nmake pre-commit-run\n```\n\nOnce installed, the hooks will run automatically on every commit. If any hook fails, the commit will be rejected until the issues are fixed.\n\n### Publishing\n\n#### Manual Publishing\n\n```bash\n# Install twine for uploading\npip install twine\n\n# Check package integrity\ntwine check dist/*\n\n# Upload to PyPI (requires account and authentication)\npython -m twine upload dist/*\n```\n\n#### Automatic Publishing\n\nThe package is automatically published to PyPI when a new version tag is pushed:\n\n```bash\ngit tag v1.0.1\ngit push origin v1.0.1\n```\n\nThis triggers the release workflow which:\n- Builds the package\n- Checks package integrity\n- Publishes to PyPI\n- Creates a GitHub release\n\n### Project Structure\n\n```\nbibspire/\n\u251c\u2500\u2500 .github/workflows/ # CI/CD workflows\n\u251c\u2500\u2500 src/bibspire/ # Main package\n\u2502 \u251c\u2500\u2500 __init__.py # Package exports\n\u2502 \u251c\u2500\u2500 __main__.py # Module entry point\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u2514\u2500\u2500 core.py # Core functionality\n\u251c\u2500\u2500 tests/ # Test suite\n\u2502 \u251c\u2500\u2500 conftest.py # Test fixtures\n\u2502 \u251c\u2500\u2500 test_core.py # Core functionality tests\n\u2502 \u251c\u2500\u2500 test_cli.py # CLI tests\n\u2502 \u251c\u2500\u2500 test_integration.py # Integration tests\n\u2502 \u2514\u2500\u2500 test_slow.py # Slow API tests\n\u251c\u2500\u2500 pyproject.toml # Package configuration\n\u251c\u2500\u2500 Makefile # Development commands\n\u2514\u2500\u2500 README.md # This file\n```\n\n## Example\n\nGiven an input .bib file:\n```bibtex\n@article{mykey2023,\n title = {Observation of a new particle in the search for the Standard Model Higgs boson},\n author = {Aad, G. and others},\n year = {2012}\n}\n```\n\nBibSpire will search INSPIRE, find the official record, and replace it with:\n```bibtex\n@article{mykey2023,\n author = {Aad, Georges and others},\n collaboration = {ATLAS},\n title = {{Observation of a new particle in the search for the Standard Model Higgs boson with the ATLAS detector at the LHC}},\n eprint = {1207.7214},\n archivePrefix = {arXiv},\n primaryClass = {hep-ex},\n doi = {10.1016/j.physletb.2012.08.020},\n journal = {Phys. Lett. B},\n volume = {716},\n pages = {1--29},\n year = {2012}\n}\n```\n\nNote how the reference key `mykey2023` is preserved while all other fields are updated with official INSPIRE data.\n\n## Dependencies\n\n- Python \u2265 3.8\n- requests \u2265 2.25.0\n\n### Development Dependencies\n\n- pytest \u2265 6.0.0\n- pytest-mock \u2265 3.6.0\n- responses \u2265 0.21.0\n- ruff \u2265 0.1.0 (linting and formatting)\n- build \u2265 0.8.0 (package building)\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for your changes\n4. Run the test suite: `pytest tests/ -v`\n5. Run linting: `make lint` or `ruff check src/ tests/`\n6. Format code: `make format` or `ruff format src/ tests/`\n7. Submit a pull request\n\n### Code Quality\n\nThis project uses Ruff for linting and code formatting. The configuration includes:\n\n- **Linting**: Enforces Python best practices, code style, and catches common errors\n- **Formatting**: Consistent code style with 88-character line length\n- **Import sorting**: Automatic import organization and cleanup\n- **Type checking**: Basic type hint validation\n\nRun `make check` to run all quality checks before submitting changes.\n\n## Continuous Integration\n\nThis project uses GitHub Actions for automated testing and quality assurance:\n\n### CI Workflow\n- **Linting**: Ruff checks for code quality and style\n- **Multi-Python Testing**: Tests run on Python 3.8-3.12\n- **Coverage**: Code coverage reporting with Codecov integration\n- **Integration Tests**: Slow tests run on main branch and when labeled\n- **Package Building**: Validates package can be built locally\n\n### Workflows\n- `ci.yml`: Main CI pipeline for PRs and pushes\n- `release.yml`: Automated publishing on version tags\n\n### Quality Gates\nAll PRs must pass:\n- Ruff linting (no violations)\n- Code formatting check\n- Test suite (35+ tests)\n- Package build validation\n\nTo trigger slow integration tests, add the `run-slow-tests` label to your PR.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Troubleshooting\n\n### Command Not Found\n\nIf `bibspire` command is not found:\n```bash\n# Use full path or activate virtual environment\n/path/to/venv/bin/bibspire input.bib\n\n# Or run as module\npython -m bibspire input.bib\n```\n\n### API Rate Limiting\n\nIf you encounter rate limiting:\n```bash\n# Increase delay between requests\nbibspire input.bib -d 2.0\n```\n\n### Test Failures\n\nIf tests fail:\n```bash\n# Check dependencies\npip install -e \".[test]\"\n\n# Run specific test\npytest tests/test_core.py::TestBibEntry::test_init -v\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool to update .bib entries with INSPIRE-HEP citations",
"version": "1.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/lorenzennio/bibspire/issues",
"Homepage": "https://github.com/lorenzennio/bibspire"
},
"split_keywords": [
"bibliography",
" bibtex",
" inspire",
" hep",
" physics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a053510429cafb66fe81c06979b32b1a4d1a33778b66bed6df0dfd8da6a42026",
"md5": "84cafc8d8bb3040e1f77e8f79c4359ac",
"sha256": "cc6785c1f0b521f10e0ff00a3cefe2c592fa5903e5d4494fadc23f8b9a32de9a"
},
"downloads": -1,
"filename": "bibspire-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "84cafc8d8bb3040e1f77e8f79c4359ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11099,
"upload_time": "2025-08-27T20:33:05",
"upload_time_iso_8601": "2025-08-27T20:33:05.488297Z",
"url": "https://files.pythonhosted.org/packages/a0/53/510429cafb66fe81c06979b32b1a4d1a33778b66bed6df0dfd8da6a42026/bibspire-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c85ce1478bc354987343a0929220315d5806925b7e137a3a790a5a8716b789d0",
"md5": "a3502e1d3a4838e5a81c035c745bb5fa",
"sha256": "5d358e6f6f76d8585c8f43476f05ea9b28807eb59018db12cfd553889baf4e95"
},
"downloads": -1,
"filename": "bibspire-1.1.3.tar.gz",
"has_sig": false,
"md5_digest": "a3502e1d3a4838e5a81c035c745bb5fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22511,
"upload_time": "2025-08-27T20:33:06",
"upload_time_iso_8601": "2025-08-27T20:33:06.218150Z",
"url": "https://files.pythonhosted.org/packages/c8/5c/e1478bc354987343a0929220315d5806925b7e137a3a790a5a8716b789d0/bibspire-1.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 20:33:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lorenzennio",
"github_project": "bibspire",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "bibspire"
}
