article-cli 1.0.0__py3-none-any.whl

article_cli/zotero.py

@@ -0,0 +1,359 @@
+"""
+Zotero bibliography synchronization module
+
+Handles fetching BibTeX entries from Zotero API with robust pagination,
+error handling, and rate limiting.
+"""
+
+import os
+import sys
+from typing import Optional, Tuple, List
+import time
+
+try:
+    import requests
+except ImportError:
+    print("Error: 'requests' library is required. Install with: pip install requests")
+    sys.exit(1)
+
+
+class Colors:
+    """ANSI color codes for terminal output"""
+
+    HEADER = "\033[95m"
+    OKBLUE = "\033[94m"
+    OKCYAN = "\033[96m"
+    OKGREEN = "\033[92m"
+    WARNING = "\033[93m"
+    FAIL = "\033[91m"
+    ENDC = "\033[0m"
+    BOLD = "\033[1m"
+    UNDERLINE = "\033[4m"
+
+
+def print_success(msg: str):
+    """Print success message in green"""
+    print(f"{Colors.OKGREEN}✓ {msg}{Colors.ENDC}")
+
+
+def print_error(msg: str):
+    """Print error message in red"""
+    print(f"{Colors.FAIL}✗ Error: {msg}{Colors.ENDC}", file=sys.stderr)
+
+
+def print_warning(msg: str):
+    """Print warning message in yellow"""
+    print(f"{Colors.WARNING}⚠ Warning: {msg}{Colors.ENDC}")
+
+
+def print_info(msg: str):
+    """Print info message in cyan"""
+    print(f"{Colors.OKCYAN}ℹ {msg}{Colors.ENDC}")
+
+
+class ZoteroBibTexUpdater:
+    """Handle Zotero BibTeX synchronization with robust error handling and rate limiting"""
+
+    def __init__(
+        self,
+        api_key: str,
+        user_id: Optional[str] = None,
+        group_id: Optional[str] = None,
+        output_file: str = "references.bib",
+    ):
+        self.api_key = api_key
+        self.user_id = user_id
+        self.group_id = group_id
+        self.output_file = output_file
+        self.base_url = "https://api.zotero.org"
+        self.limit = 100
+        self._group_name: Optional[str] = None
+
+        # Create session with persistent headers
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "Zotero-API-Version": "3",
+                "Authorization": f"Bearer {self.api_key}",
+                "User-Agent": "ArticleCLI/1.0",
+            }
+        )
+
+    def _build_url(self) -> str:
+        """Build the Zotero API URL based on user or group ID"""
+        if self.group_id:
+            return f"{self.base_url}/groups/{self.group_id}/items"
+        elif self.user_id:
+            return f"{self.base_url}/users/{self.user_id}/items"
+        else:
+            raise ValueError("Either user_id or group_id must be provided")
+
+    def _get_group_info(self) -> Optional[dict]:
+        """Get group information including name"""
+        if not self.group_id:
+            return None
+
+        try:
+            url = f"{self.base_url}/groups/{self.group_id}"
+            response = self.session.get(url, timeout=10)
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            print_warning(f"Could not fetch group info: {e}")
+            return None
+
+    def get_group_name(self) -> Optional[str]:
+        """Get the name of the Zotero group"""
+        if self._group_name is not None:
+            return self._group_name
+
+        if not self.group_id:
+            return None
+
+        group_info = self._get_group_info()
+        if group_info and "data" in group_info:
+            self._group_name = group_info["data"].get("name", "Unknown Group")
+            return self._group_name
+
+        return None
+
+    def _fetch_page(self, url: str, start: int = 0) -> Tuple[str, dict]:
+        """
+        Fetch a single page of results from Zotero API
+
+        Args:
+            url: Base API URL
+            start: Starting index for pagination
+
+        Returns:
+            Tuple of (response_content, headers_dict)
+        """
+        params = {"format": "bibtex", "start": start, "limit": self.limit}
+
+        try:
+            response = self.session.get(url, params=params, timeout=30)
+            response.raise_for_status()
+
+            # Check rate limiting
+            rate_limit_remaining = response.headers.get("X-RateLimit-Remaining")
+            if rate_limit_remaining and int(rate_limit_remaining) < 5:
+                rate_limit_reset = int(response.headers.get("X-RateLimit-Reset", 0))
+                wait_time = max(0, rate_limit_reset - time.time())
+                if wait_time > 0:
+                    print_warning(
+                        f"Rate limit low ({rate_limit_remaining} remaining). Waiting {wait_time:.1f}s..."
+                    )
+                    time.sleep(wait_time + 1)
+
+            return response.text, dict(response.headers)
+
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 429:
+                retry_after = int(e.response.headers.get("Retry-After", 60))
+                print_error(f"Rate limit exceeded. Retry after {retry_after}s")
+                raise
+            elif e.response.status_code == 403:
+                print_error("Access forbidden. Check your API key and permissions.")
+                raise
+            elif e.response.status_code == 404:
+                print_error("Resource not found. Check your user/group ID.")
+                raise
+            else:
+                print_error(f"HTTP error {e.response.status_code}: {e.response.reason}")
+                raise
+        except requests.exceptions.RequestException as e:
+            print_error(f"Network error: {str(e)}")
+            raise
+
+    def _count_bibtex_entries(self, content: str) -> int:
+        """Count the number of BibTeX entries in the content"""
+        return (
+            content.count("@article")
+            + content.count("@book")
+            + content.count("@inproceedings")
+            + content.count("@incollection")
+            + content.count("@misc")
+            + content.count("@phdthesis")
+            + content.count("@techreport")
+            + content.count("@mastersthesis")
+        )
+
+    def _filter_empty_entries(self, content: str) -> Tuple[str, int]:
+        """
+        Filter out empty or near-empty BibTeX entries
+
+        Args:
+            content: BibTeX content to filter
+
+        Returns:
+            Tuple of (filtered_content, num_removed)
+        """
+        import re
+
+        # Pattern to match BibTeX entries
+        entry_pattern = r"@\w+\{[^,]*,\s*\}"
+
+        # Find all empty entries (those with just the citation key and closing brace)
+        empty_entries = re.findall(entry_pattern, content)
+
+        if not empty_entries:
+            return content, 0
+
+        # Remove empty entries
+        filtered_content = content
+        for entry in empty_entries:
+            filtered_content = filtered_content.replace(entry, "")
+
+        # Clean up multiple blank lines
+        filtered_content = re.sub(r"\n\s*\n\s*\n+", "\n\n", filtered_content)
+
+        return filtered_content, len(empty_entries)
+
+    def _backup_existing_file(self):
+        """Create a backup of the existing BibTeX file"""
+        if os.path.exists(self.output_file):
+            backup_file = f"{self.output_file}.backup"
+            try:
+                with open(self.output_file, "r", encoding="utf-8") as src:
+                    with open(backup_file, "w", encoding="utf-8") as dst:
+                        dst.write(src.read())
+                print_info(f"Created backup: {backup_file}")
+            except Exception as e:
+                print_warning(f"Could not create backup: {e}")
+
+    def update(self, backup: bool = True) -> bool:
+        """
+        Fetch and update BibTeX file from Zotero with improved pagination
+
+        Args:
+            backup: Whether to create a backup of existing file
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            # Validate inputs
+            if not self.api_key:
+                print_error("Zotero API key is required")
+                return False
+
+            if not self.user_id and not self.group_id:
+                print_error("Either user_id or group_id must be provided")
+                return False
+
+            # Create backup if requested
+            if backup:
+                self._backup_existing_file()
+
+            # Build URL
+            base_url = self._build_url()
+
+            # Show what we're connecting to
+            if self.group_id:
+                group_name = self.get_group_name()
+                if group_name:
+                    print_info(
+                        f"Connecting to Zotero group: {group_name} (ID: {self.group_id})"
+                    )
+                else:
+                    print_info(f"Connecting to Zotero group ID: {self.group_id}")
+            elif self.user_id:
+                print_info(f"Connecting to Zotero user library (ID: {self.user_id})")
+
+            # First request to get total count
+            print_info("Fetching BibTeX entries from Zotero...")
+
+            try:
+                initial_content, initial_headers = self._fetch_page(base_url, start=0)
+            except Exception as e:
+                print_error(f"Failed to connect to Zotero: {e}")
+                return False
+
+            # Get total number of items from header
+            total_results = int(initial_headers.get("Total-Results", 0))
+
+            if total_results == 0:
+                print_warning("No items found in Zotero library")
+                return False
+
+            print_info(f"Found {total_results} total items in library")
+
+            # Collect all BibTeX content
+            all_bibtex_content: List[str] = []
+
+            # Add initial page
+            if initial_content.strip():
+                all_bibtex_content.append(initial_content)
+
+            # Calculate pages needed
+            pages_needed = (total_results + self.limit - 1) // self.limit
+            print_info(
+                f"Fetching {pages_needed} pages ({self.limit} items per page)..."
+            )
+
+            # Fetch remaining pages
+            for page in range(1, pages_needed):
+                start = page * self.limit
+                progress = ((page + 1) / pages_needed) * 100
+
+                print(
+                    f"  Progress: {progress:.0f}% ({start + self.limit if start + self.limit < total_results else total_results}/{total_results} items)",
+                    end="\r",
+                )
+
+                try:
+                    content, _ = self._fetch_page(base_url, start=start)
+                    if content.strip():
+                        all_bibtex_content.append(content)
+                except Exception as e:
+                    print_error(f"\nFailed to fetch page {page + 1}: {e}")
+                    return False
+
+            print()  # New line after progress
+
+            # Combine all content
+            combined_content = "\n\n".join(all_bibtex_content)
+
+            # Filter out empty entries
+            filtered_content, num_removed = self._filter_empty_entries(combined_content)
+            if num_removed > 0:
+                print_warning(
+                    f"Filtered out {num_removed} empty/incomplete entries from Zotero"
+                )
+
+            # Count total valid entries
+            total_entries = self._count_bibtex_entries(filtered_content)
+
+            if total_entries == 0:
+                print_warning("No valid BibTeX entries found after filtering")
+                return False
+
+            # Write to file
+            print_info(
+                f"Writing {total_entries} valid entries to {self.output_file}..."
+            )
+
+            try:
+                with open(self.output_file, "w", encoding="utf-8") as f:
+                    # Add header comment
+                    f.write(f"% BibTeX entries from Zotero\n")
+                    f.write(f"% Total entries: {total_entries}\n")
+                    if num_removed > 0:
+                        f.write(f"% Filtered out: {num_removed} empty entries\n")
+                    f.write(f"% Generated: {time.strftime('%Y-%m-%d %H:%M:%S')}\n\n")
+                    f.write(filtered_content)
+                    if not filtered_content.endswith("\n"):
+                        f.write("\n")
+
+                print_success(
+                    f"Successfully updated {self.output_file} with {total_entries} entries"
+                )
+                return True
+
+            except IOError as e:
+                print_error(f"Failed to write to {self.output_file}: {e}")
+                return False
+
+        except Exception as e:
+            print_error(f"Unexpected error during update: {e}")
+            return False

article_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: article-cli
+Version: 1.0.0
+Summary: CLI tool for managing LaTeX articles with git integration and Zotero bibliography
+Project-URL: Homepage, https://github.com/feelpp/article.cli
+Project-URL: Documentation, https://github.com/feelpp/article.cli#readme
+Project-URL: Repository, https://github.com/feelpp/article.cli.git
+Project-URL: Issues, https://github.com/feelpp/article.cli/issues
+Author-email: Christophe Prud'homme <prudhomm@cemosis.fr>
+License: MIT License
+        
+        Copyright (c) 2024 Christophe Prud'homme
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: academic,bibliography,git,latex,research,zotero
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: flake8>=6.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Article CLI
+
+[![CI](https://github.com/feelpp/article.cli/actions/workflows/ci.yml/badge.svg)](https://github.com/feelpp/article.cli/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/article-cli.svg)](https://badge.fury.io/py/article-cli)
+[![Python Support](https://img.shields.io/pypi/pyversions/article-cli.svg)](https://pypi.org/project/article-cli/)
+
+A command-line tool for managing LaTeX articles with git integration and Zotero bibliography synchronization.
+
+## Features
+
+- **Git Release Management**: Create, list, and delete releases with gitinfo2 support
+- **Zotero Integration**: Synchronize bibliography from Zotero with robust pagination and error handling
+- **LaTeX Build Management**: Clean build files and manage LaTeX compilation artifacts
+- **Git Hooks Setup**: Automated setup of git hooks for gitinfo2 integration
+- **Local Configuration**: Support for project-specific configuration files
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install article-cli
+```
+
+### From Source
+
+```bash
+git clone https://github.com/feelpp/article.cli.git
+cd article.cli
+pip install -e .
+```
+
+## Quick Start
+
+1. **Setup git hooks** (run once per repository):
+   ```bash
+   article-cli setup
+   ```
+
+2. **Configure Zotero credentials** (one-time setup):
+   ```bash
+   export ZOTERO_API_KEY="your_api_key_here"
+   export ZOTERO_GROUP_ID="your_group_id"  # or ZOTERO_USER_ID
+   ```
+
+3. **Update bibliography from Zotero**:
+   ```bash
+   article-cli update-bibtex
+   ```
+
+4. **Create a release**:
+   ```bash
+   article-cli create v1.0.0
+   ```
+
+## Configuration
+
+### Environment Variables
+
+- `ZOTERO_API_KEY`: Your Zotero API key (required for bibliography updates)
+- `ZOTERO_USER_ID`: Your Zotero user ID (alternative to group ID)
+- `ZOTERO_GROUP_ID`: Your Zotero group ID (alternative to user ID)
+
+### Local Configuration File
+
+Create a `.article-cli.toml` file in your project root for project-specific settings:
+
+```toml
+[zotero]
+api_key = "your_api_key_here"
+group_id = "6219333"
+# user_id = "your_user_id"  # alternative to group_id
+output_file = "references.bib"
+
+[git]
+auto_push = true
+default_branch = "main"
+
+[latex]
+clean_extensions = [".aux", ".bbl", ".blg", ".log", ".out", ".synctex.gz"]
+```
+
+## Usage
+
+### Git Release Management
+
+```bash
+# Create a new release
+article-cli create v1.2.3
+
+# List recent releases
+article-cli list --count 10
+
+# Delete a release
+article-cli delete v1.2.3
+```
+
+### Bibliography Management
+
+```bash
+# Update bibliography from Zotero
+article-cli update-bibtex
+
+# Specify custom output file
+article-cli update-bibtex --output my-refs.bib
+
+# Skip backup creation
+article-cli update-bibtex --no-backup
+```
+
+### Project Setup
+
+```bash
+# Setup git hooks for gitinfo2
+article-cli setup
+
+# Clean LaTeX build files
+article-cli clean
+```
+
+### Advanced Usage
+
+```bash
+# Override configuration via command line
+article-cli update-bibtex --api-key YOUR_KEY --group-id YOUR_GROUP
+
+# Specify custom configuration file
+article-cli --config custom-config.toml update-bibtex
+```
+
+## Version Format
+
+Release versions must follow the semantic versioning format:
+- `vX.Y.Z` for stable releases (e.g., `v1.2.3`)
+- `vX.Y.Z-pre.N` for pre-releases (e.g., `v1.2.3-pre.1`)
+
+## Requirements
+
+- Python 3.8+
+- Git repository with gitinfo2 package (for LaTeX integration)
+- Zotero account with API access (for bibliography features)
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Changelog
+
+### v1.0.0
+- Initial release
+- Git release management
+- Zotero bibliography synchronization
+- LaTeX build file cleanup
+- Configuration file support

article_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+article_cli/__init__.py,sha256=LBaDt3ml_owdcQghSIsChwgqmhuZ76O4aXTVq-rvxG0,521
+article_cli/__main__.py,sha256=tKzgx5NUMWBgIxJz23H7pSPF2G0xG6waivcNTmrb4eg,134
+article_cli/cli.py,sha256=cbAoPv3bfRgo7MQFRUJUFt_BYv39ucRvvyDdFam_SCw,10120
+article_cli/config.py,sha256=g4xPvzpHJk-Y0fPEXsgrPOdJ90b5zBpN5yiG3saF6ns,9152
+article_cli/git_manager.py,sha256=uJtzgjRmPpcXDuCBMdbf0BWpsvAtoCQtSxDSFB0836E,12017
+article_cli/zotero.py,sha256=GFbetgSvfLQS9U-EA2q9sb7GKgR3jTEOhPEDV1OLmKM,12439
+article_cli-1.0.0.dist-info/METADATA,sha256=gaBMHKioyy1N2nTpAnPXjZ-Ul2Wxm7wMB-RcC5a6Qhw,6537
+article_cli-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+article_cli-1.0.0.dist-info/entry_points.txt,sha256=TTD3ZO2r7w6Om13VFoFu_rW1LTmYzknhNsIep-uAvBg,53
+article_cli-1.0.0.dist-info/licenses/LICENSE,sha256=SjACEUOvqClPlozgN4K7uHFc39TDDikcH0YEot056l0,1077
+article_cli-1.0.0.dist-info/RECORD,,

article_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

article_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+article-cli = article_cli.cli:main

article_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Christophe Prud'homme
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.