aracnid-airtable 1.0.0__tar.gz

aracnid_airtable-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Romano
+
+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.

aracnid_airtable-1.0.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: aracnid-airtable
+Version: 1.0.0
+Summary: Airtable connector for the Aracnid integration framework
+License: MIT
+License-File: LICENSE
+Keywords: connector
+Author: Jason Romano
+Author-email: aracnid@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: aracnid-core (==1.0.0)
+Requires-Dist: pyairtable (>=3.1.1,<4.0.0)
+Project-URL: Repository, https://github.com/aracnid/aracnid-airtable
+Description-Content-Type: text/markdown
+
+# aracnid-airtable
+
+A Python Airtable connector implementation for the `aracnid-base` contract.
+
+## Overview
+
+`aracnid-airtable` provides an `AirtableConnector` implementation that follows the shared connector interface used across `i-*` connector modules. It wraps Airtable CRUD operations with consistent validation, normalization, and error handling semantics.
+
+## Installation
+
+Using Poetry:
+
+```bash
+poetry add aracnid-airtable
+```
+
+Using pip:
+
+```bash
+pip install aracnid-airtable
+```
+
+## Requirements
+
+- Python 3.12+
+- Airtable API key with access to the target base/table
+
+## Configuration
+
+Set your Airtable API key in the environment:
+
+```bash
+export AIRTABLE_API_KEY=your_api_key
+```
+
+## Quick Start
+
+```python
+from aracnid_airtable.connector import AirtableConnector
+
+connector = AirtableConnector(
+    base_id="appXXXXXXXXXXXXXX",
+    table_name="MyTable",
+)
+
+created = connector.create_one({"name": "example", "status": "active"})
+record_id = created["id"]
+
+one = connector.read_one(record_id)
+many = connector.read_many({"status": "active"})
+
+updated = connector.update_one(record_id, {"status": "inactive"})
+replaced = connector.replace_one(record_id, {"name": "replacement"})
+
+deleted = connector.delete_one(record_id, hard=True)
+```
+
+## API Notes
+
+- `read_one(record_id)` returns `None` when the record is not found.
+- `delete_one(record_id, hard=False)` raises `RuntimeError` because soft delete is not supported by this connector.
+- `delete_one(record_id, hard=True)` performs a hard delete and returns:
+  - `True` if deleted
+  - `False` if the record does not exist
+
+## Testing
+
+Run default tests (excluding external-service integration tests):
+
+```bash
+pytest -m "not integration" -q
+```
+
+Run integration tests (real Airtable):
+
+```bash
+pytest -m integration -q
+```
+
+### Integration test environment variables
+
+- `AIRTABLE_API_KEY`
+- `AIRTABLE_BASE_ID`
+- `AIRTABLE_TABLE_NAME`
+
+If these are not set, integration tests will skip.
+
+## Development
+
+Run all tests:
+
+```bash
+pytest -q
+```
+
+Run linting/type checks (if configured in your environment):
+
+```bash
+ruff check .
+pyright
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
+

aracnid_airtable-1.0.0/README.md

@@ -0,0 +1,105 @@
+# aracnid-airtable
+
+A Python Airtable connector implementation for the `aracnid-base` contract.
+
+## Overview
+
+`aracnid-airtable` provides an `AirtableConnector` implementation that follows the shared connector interface used across `i-*` connector modules. It wraps Airtable CRUD operations with consistent validation, normalization, and error handling semantics.
+
+## Installation
+
+Using Poetry:
+
+```bash
+poetry add aracnid-airtable
+```
+
+Using pip:
+
+```bash
+pip install aracnid-airtable
+```
+
+## Requirements
+
+- Python 3.12+
+- Airtable API key with access to the target base/table
+
+## Configuration
+
+Set your Airtable API key in the environment:
+
+```bash
+export AIRTABLE_API_KEY=your_api_key
+```
+
+## Quick Start
+
+```python
+from aracnid_airtable.connector import AirtableConnector
+
+connector = AirtableConnector(
+    base_id="appXXXXXXXXXXXXXX",
+    table_name="MyTable",
+)
+
+created = connector.create_one({"name": "example", "status": "active"})
+record_id = created["id"]
+
+one = connector.read_one(record_id)
+many = connector.read_many({"status": "active"})
+
+updated = connector.update_one(record_id, {"status": "inactive"})
+replaced = connector.replace_one(record_id, {"name": "replacement"})
+
+deleted = connector.delete_one(record_id, hard=True)
+```
+
+## API Notes
+
+- `read_one(record_id)` returns `None` when the record is not found.
+- `delete_one(record_id, hard=False)` raises `RuntimeError` because soft delete is not supported by this connector.
+- `delete_one(record_id, hard=True)` performs a hard delete and returns:
+  - `True` if deleted
+  - `False` if the record does not exist
+
+## Testing
+
+Run default tests (excluding external-service integration tests):
+
+```bash
+pytest -m "not integration" -q
+```
+
+Run integration tests (real Airtable):
+
+```bash
+pytest -m integration -q
+```
+
+### Integration test environment variables
+
+- `AIRTABLE_API_KEY`
+- `AIRTABLE_BASE_ID`
+- `AIRTABLE_TABLE_NAME`
+
+If these are not set, integration tests will skip.
+
+## Development
+
+Run all tests:
+
+```bash
+pytest -q
+```
+
+Run linting/type checks (if configured in your environment):
+
+```bash
+ruff check .
+pyright
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

aracnid_airtable-1.0.0/aracnid_airtable/__init__.py

@@ -0,0 +1,9 @@
+from .connector import AirtableConnector
+
+try:
+    from importlib.metadata import version as _version
+except ImportError:  # pragma: no cover
+    from importlib_metadata import version as _version  # type: ignore
+
+__all__ = ["__version__", "AirtableConnector"]
+__version__ = _version("aracnid-core")

aracnid_airtable-1.0.0/aracnid_airtable/connector.py

@@ -0,0 +1,284 @@
+"""A connector for Airtable using the pyairtable library.
+"""
+
+import os
+from typing import Any
+
+from pyairtable import Api
+from pyairtable.formulas import match
+from pyairtable.api.types import RecordDict
+
+from aracnid_core.base import BaseConnector
+
+
+class AirtableConnector(BaseConnector):
+    """A connector for Airtable using the pyairtable library.
+    """
+    @property
+    def capabilities(self) -> dict[str, bool]:
+        """Returns a mapping of capabilities.
+
+        Returns:
+            dict[str, bool]: Mapping of capabilities.
+        """
+        return {
+            "supports_filters": True,
+            "supports_partial_update": True,
+            "supports_replace_one": True,
+            "supports_soft_delete": False,
+            "supports_hard_delete": True,
+            "supports_transactions": False,
+        }
+
+
+    def __init__(self, base_id: str, table_name: str):
+        """Initialize the AirtableConnector.
+
+        Args:
+            base_id (str): The ID of the Airtable base.
+            table_name (str): The name of the Airtable table.
+
+        Raises:
+            ValueError: If base_id or table_name is not a non-empty string, or if AIRTABLE_API_KEY is not set.
+        """
+        if not isinstance(base_id, str) or not base_id.strip():
+            raise ValueError("base_id must be a non-empty string")
+        if not isinstance(table_name, str) or not table_name.strip():
+            raise ValueError("table_name must be a non-empty string")
+
+        api_key = os.getenv("AIRTABLE_API_KEY")
+        if not api_key or not api_key.strip():
+            raise ValueError("AIRTABLE_API_KEY environment variable is required.")
+
+        self.air_api_key = api_key.strip()
+        self.base_id = base_id.strip()
+        self.table_name = table_name.strip()
+
+        self.api = Api(self.air_api_key)
+        self.table = self.api.table(self.base_id, self.table_name)
+
+
+    def _normalize_record(self, rec: RecordDict | dict[str, Any]) -> dict[str, Any]:
+        """Normalize an Airtable record into a dictionary with standard keys.
+
+        Args:
+            rec (RecordDict | dict[str, Any]): The Airtable record to normalize.
+
+        Returns:
+            dict[str, Any]: The normalized record.
+        """
+        fields = rec.get("fields") or {}
+        return {
+            "id": rec.get("id"),
+            **fields,
+            "_created_time": rec.get("createdTime"),
+        }
+
+
+    def _as_runtime_error(self, exc: Exception, op: str) -> RuntimeError:
+        """Convert an exception into a RuntimeError with a standardized message.
+
+        Args:
+            exc (Exception): The original exception.
+            op (str): The operation being performed.
+
+        Returns:
+            RuntimeError: The converted runtime error.
+        """
+        return RuntimeError(f"{op} failed: {exc}")
+
+
+    def _is_not_found_error(self, exc: Exception) -> bool:
+        """Determine if an exception indicates a "not found" error.
+
+        Args:
+            exc (Exception): The exception to check.
+
+        Returns:
+            bool: True if the exception indicates a "not found" error, False otherwise.
+        """
+        msg = str(exc).lower()
+        return "404" in msg or "not found" in msg
+
+
+    def create_one(self, record: dict[str, Any]) -> dict[str, Any]:
+        """Create a new record in the Airtable table.
+
+        Args:
+            record (dict[str, Any]): The record to create.
+            
+        Returns:
+            dict[str, Any]: The created record.
+
+        Raises:
+            ValueError: If record is not a dict or is empty.
+        """
+        if not isinstance(record, dict):
+            raise ValueError("record must be a dict")
+        if not record:
+            raise ValueError("record must not be empty")
+
+        fields = dict(record)  # do not mutate caller input
+        try:
+            created = self.table.create(fields)
+        except Exception as exc:
+            raise self._as_runtime_error(exc, "create_one") from exc
+
+        return self._normalize_record(created)
+
+
+    def read_one(self, record_id: str) -> dict[str, Any] | None:
+        """Read a single record from the Airtable table by its ID.
+
+        Args:
+            record_id (str): The ID of the record to read.
+
+        Returns:
+            dict[str, Any] | None: The record if found, None otherwise.
+
+        Raises:
+            ValueError: If record_id is not a non-empty string.
+        """
+        if not isinstance(record_id, str) or not record_id.strip():
+            raise ValueError("record_id must be a non-empty string")
+
+        try:
+            rec = self.table.get(record_id.strip())
+        except Exception as exc:
+            if self._is_not_found_error(exc):
+                return None
+            raise self._as_runtime_error(exc, "read_one") from exc
+
+        return self._normalize_record(rec) if rec else None
+
+
+    def read_many(self, filters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        """Read multiple records from the Airtable table, optionally filtered by a dictionary of field values.
+
+        Args:
+            filters (dict[str, Any] | None): A dictionary of field values to filter records.
+
+        Returns:
+            list[dict[str, Any]]: A list of records matching the filters.
+
+        Raises:
+            ValueError: If filters is not a dict or None.
+        """
+        if filters is not None and not isinstance(filters, dict):
+            raise ValueError("filters must be a dict or None")
+
+        filter_obj: dict[str, Any] = dict(filters) if filters else {}
+
+        try:
+            recs = self.table.all(formula=match(filter_obj)) if filter_obj else self.table.all()
+        except Exception as exc:
+            raise self._as_runtime_error(exc, "read_many") from exc
+
+        return [self._normalize_record(rec) for rec in recs]
+
+
+    def update_one(self, record_id: str, changes: dict[str, Any]) -> dict[str, Any]:
+        """Update a single record in the Airtable table by its ID.
+        
+        Args:
+            record_id (str): The ID of the record to update.
+            changes (dict[str, Any]): A dictionary of field changes to apply.
+
+        Returns:
+            dict[str, Any]: The updated record.
+
+        Raises:
+            ValueError: If record_id is not a non-empty string or changes is not a non-empty dict.
+        """
+        if not isinstance(record_id, str) or not record_id.strip():
+            raise ValueError("record_id must be a non-empty string")
+        if not isinstance(changes, dict):
+            raise ValueError("changes must be a dict")
+        if not changes:
+            raise ValueError("changes must not be empty")
+
+        rid = record_id.strip()
+        fields = dict(changes)  # do not mutate caller input
+
+        try:
+            updated = self.table.update(rid, fields)
+        except Exception as exc:
+            if self._is_not_found_error(exc):
+                raise RuntimeError(f"update_one failed: record '{rid}' not found") from exc
+            raise self._as_runtime_error(exc, "update_one") from exc
+
+        if not updated:
+            raise RuntimeError(f"update_one failed: record '{rid}' not found")
+
+        return self._normalize_record(updated)
+
+
+    def replace_one(self, record_id: str, new_record: dict[str, Any]) -> dict[str, Any]:
+        """Replace a single record in the Airtable table by its ID.
+
+        Args:
+            record_id (str): The ID of the record to replace.
+            new_record (dict[str, Any]): A dictionary representing the new record.
+
+        Returns:
+            dict[str, Any]: The replaced record.
+
+        Raises:
+            ValueError: If record_id is not a non-empty string or new_record is not a non-empty dict.
+        """
+        if not isinstance(record_id, str) or not record_id.strip():
+            raise ValueError("record_id must be a non-empty string")
+        if not isinstance(new_record, dict):
+            raise ValueError("new_record must be a dict")
+        if not new_record:
+            raise ValueError("new_record must not be empty")
+
+        rid = record_id.strip()
+        fields = dict(new_record)  # do not mutate caller input
+
+        try:
+            replaced = self.table.update(rid, fields, replace=True)
+        except Exception as exc:
+            if self._is_not_found_error(exc):
+                raise RuntimeError(f"replace_one failed: record '{rid}' not found") from exc
+            raise self._as_runtime_error(exc, "replace_one") from exc
+
+        if not replaced:
+            raise RuntimeError(f"replace_one failed: record '{rid}' not found")
+
+        return self._normalize_record(replaced)
+
+
+    def delete_one(self, record_id: str, hard: bool = False) -> bool:
+        """Delete a single record from the Airtable table by its ID.
+
+        Args:
+            record_id (str): The ID of the record to delete.
+            hard (bool): Whether to perform a hard delete. Defaults to False.
+
+        Returns:
+            bool: True if the record was deleted, False if it was not found.
+
+        Raises:
+            ValueError: If record_id is not a non-empty string or hard is not a bool.
+            RuntimeError: If soft delete is requested (not supported).
+        """
+        if not isinstance(record_id, str) or not record_id.strip():
+            raise ValueError("record_id must be a non-empty string")
+        if not isinstance(hard, bool):
+            raise ValueError("hard must be a bool")
+
+        # Airtable connector supports hard delete only.
+        if not hard:
+            raise RuntimeError("delete_one failed: soft delete is not supported; pass hard=True")
+
+        rid = record_id.strip()
+        try:
+            result = self.table.delete(rid)
+        except Exception as exc:
+            if self._is_not_found_error(exc):
+                return False
+            raise self._as_runtime_error(exc, "delete_one") from exc
+
+        return bool((result or {}).get("deleted", False))
+    

aracnid_airtable-1.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[tool.poetry]
+name = "aracnid-airtable"
+version = "1.0.0"
+description = "Airtable connector for the Aracnid integration framework"
+authors = ["Jason Romano <aracnid@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+repository = "https://github.com/aracnid/aracnid-airtable"
+keywords = ["connector"]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+aracnid-core = "1.0.0"
+pyairtable = "^3.1.1"
+
+[tool.poetry.group.dev.dependencies]
+aracnid-core = { path = "../aracnid-core", develop = true }
+pytest = "^8.3.5"
+ruff = "^0.15.21"
+build = "^1.5.1"
+twine = "^6.2.0"
+pyright = "^1.1.411"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+addopts = "-p no:warnings"
+env_files = [".env"]
+log_cli = true
+log_cli_level = "DEBUG"
+markers = [
+  "contract: shared BaseConnector contract/conformance tests",
+  "integration: tests that call external services"
+]
+
+[tool.ruff]
+# Target your current version
+target-version = "py310"
+line-length = 88 
+
+[tool.ruff.lint]
+# E = pycodestyle (Errors), F = Pyflakes (Logic Bugs)
+# These are the "Pylint-like" essentials without the fluff.
+select = ["E", "F", "B"] 
+
+# Specifically ignore the stuff that usually annoys Pylint users
+ignore = [
+    "E501", # Ignore line length (let the formatter handle it)
+    #"D",    # Ignore all Docstring requirements
+    "ANN",  # Ignore missing type annotations (if you aren't ready for strict typing)
+]