jeff-contacts 0.1.2__tar.gz

jeff_contacts-0.1.2/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: jeff-contacts
+Version: 0.1.2
+Summary: CRM Markdown synchronisé depuis CardDAV (Baikal), publié en site statique Hugo.
+Keywords: crm,carddav,vcard,markdown,hugo,contacts
+Author: lduchosal
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.11
+Requires-Dist: requests>=2.28
+Requires-Dist: lxml>=5.0
+Requires-Dist: vobject>=0.9.8
+Requires-Dist: jinja2>=3.1
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="logo.svg" alt="jeff" width="128" height="128">
+</p>
+
+<h1 align="center">jeff</h1>
+
+<p align="center">Your contacts live in CardDAV. Your CRM lives in Markdown.</p>
+
+**jeff** syncs contacts from a Baikal CardDAV server into clean Markdown files with YAML frontmatter, then publishes a static HTML site. No database, no SaaS, no vendor lock-in — just files, Git, and a fast static site.
+
+## How it works
+
+```
+Baikal (CardDAV)  ──sync──>  Markdown + YAML  ──build──>  Hugo static site
+```
+
+1. **Fetch** contacts from your CardDAV server (incremental, ctag/etag-based)
+2. **Transform** vCards into Markdown files with structured YAML frontmatter
+3. **Publish** a fast, searchable static site with Hugo
+
+## Setup
+
+```sh
+pip install jeff-contacts
+```
+
+Create a `.jeff` file at the root of your project:
+
+```
+carddav_url=https://your-baikal.example.com/dav.php/addressbooks/user/default/
+carddav_username=user
+carddav_password=secret
+```
+
+```sh
+chmod 600 .jeff
+```
+
+## Usage
+
+```sh
+jeff sync           # incremental sync (only changed contacts)
+jeff sync --full    # force full re-sync
+jeff publish        # build static HTML site
+jeff --verbose sync # debug logging
+```
+
+`jeff sync` creates one Markdown file per contact in `content/contacts/`, extracts photos to `static/photos/`, and tracks sync state in `.sync-state.json`.
+
+`jeff publish` generates a static HTML site in `public/` with a contact index and individual profile pages.
+
+## License
+
+MIT

jeff_contacts-0.1.2/README.md

@@ -0,0 +1,54 @@
+<p align="center">
+  <img src="logo.svg" alt="jeff" width="128" height="128">
+</p>
+
+<h1 align="center">jeff</h1>
+
+<p align="center">Your contacts live in CardDAV. Your CRM lives in Markdown.</p>
+
+**jeff** syncs contacts from a Baikal CardDAV server into clean Markdown files with YAML frontmatter, then publishes a static HTML site. No database, no SaaS, no vendor lock-in — just files, Git, and a fast static site.
+
+## How it works
+
+```
+Baikal (CardDAV)  ──sync──>  Markdown + YAML  ──build──>  Hugo static site
+```
+
+1. **Fetch** contacts from your CardDAV server (incremental, ctag/etag-based)
+2. **Transform** vCards into Markdown files with structured YAML frontmatter
+3. **Publish** a fast, searchable static site with Hugo
+
+## Setup
+
+```sh
+pip install jeff-contacts
+```
+
+Create a `.jeff` file at the root of your project:
+
+```
+carddav_url=https://your-baikal.example.com/dav.php/addressbooks/user/default/
+carddav_username=user
+carddav_password=secret
+```
+
+```sh
+chmod 600 .jeff
+```
+
+## Usage
+
+```sh
+jeff sync           # incremental sync (only changed contacts)
+jeff sync --full    # force full re-sync
+jeff publish        # build static HTML site
+jeff --verbose sync # debug logging
+```
+
+`jeff sync` creates one Markdown file per contact in `content/contacts/`, extracts photos to `static/photos/`, and tracks sync state in `.sync-state.json`.
+
+`jeff publish` generates a static HTML site in `public/` with a contact index and individual profile pages.
+
+## License
+
+MIT

jeff_contacts-0.1.2/pyproject.toml

@@ -0,0 +1,215 @@
+[project]
+name = "jeff-contacts"
+version = "0.1.2"
+description = "CRM Markdown synchronisé depuis CardDAV (Baikal), publié en site statique Hugo."
+authors = [
+    { name = "lduchosal" },
+]
+requires-python = ">=3.11"
+readme = "README.md"
+keywords = [
+    "crm",
+    "carddav",
+    "vcard",
+    "markdown",
+    "hugo",
+    "contacts",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Office/Business",
+]
+dependencies = [
+    "requests>=2.28",
+    "lxml>=5.0",
+    "vobject>=0.9.8",
+    "jinja2>=3.1",
+    "click>=8.1",
+    "pyyaml>=6.0",
+]
+
+[project.license]
+text = "MIT"
+
+[project.scripts]
+jeff = "jeff.cli:cli"
+
+[dependency-groups]
+dev = [
+    "pdm>=2.26.0",
+    "pdm-bump>=0.9.0",
+    "pytest>=8.4",
+    "pytest-cov>=7.0",
+    "pytest-asyncio>=1.2.0",
+    "httpx>=0.24.0",
+    "black>=25.0",
+    "isort>=6.0",
+    "docformatter>=1.7",
+    "ruff>=0.13.0",
+    "flake8>=7.3",
+    "flake8-docstrings>=1.7.0",
+    "flake8-docstrings-complete>=1.3.0",
+    "mypy>=1.18",
+    "interrogate>=1.7.0",
+    "vulture>=2.14",
+    "refurb>=2.2.0",
+    "absolufy-imports>=0.3.1",
+]
+publish = [
+    "twine>=6.2.0",
+    "keyring>=25.7.0",
+]
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.scripts]
+test = "pytest tests/ -q --tb=short"
+test-quick = "pytest tests/ -q --tb=short -x"
+test-ci = "pytest tests/ -q --tb=short --cov=src/jeff --cov-report=xml --cov-report=term"
+test-unit = "pytest tests/unit/ -q --tb=short"
+test-integration = "pytest tests/integration/ -q --tb=short"
+test-cov = "pytest tests/ -q --tb=short --cov=src/jeff --cov-report=term-missing --cov-report=html"
+format = "black src/ tests/"
+isort = "isort src/ tests/"
+lint = "ruff check --fix src/ tests/"
+flake8 = "flake8 src/"
+typecheck = "mypy src/"
+interrogate = "interrogate src/"
+vulture = "vulture src/ tests/ vulture_whitelist.py"
+refurb = "refurb src/"
+clean = "rm -rf dist/ build/ .mypy_cache/ .pytest_cache/ htmlcov/ .coverage"
+install = "pdm install"
+install-dev = "pdm install -G dev"
+version-show = "python -c \"import jeff; print(jeff.__version__)\""
+version-patch = "pdm bump -v patch"
+version-minor = "pdm bump -v minor"
+version-major = "pdm bump -v major"
+
+[tool.pdm.scripts.docformatter]
+shell = "docformatter --recursive --in-place --wrap-summaries 88 --wrap-descriptions 88 --close-quotes-on-newline src/ tests/ || [ $? -eq 3 ]"
+
+[tool.pdm.scripts.absolufy]
+shell = "find src/ -name '*.py' -exec absolufy-imports {} +"
+
+[tool.pdm.scripts.check]
+composite = [
+    "isort",
+    "docformatter",
+    "format",
+    "typecheck",
+    "flake8",
+    "interrogate",
+    "refurb",
+    "lint",
+    "vulture",
+    "test-quick",
+]
+
+[tool.pdm-bump]
+version-files = [
+    "src/jeff/__init__.py:__version__",
+]
+
+[tool.black]
+line-length = 88
+target-version = [
+    "py311",
+]
+
+[tool.isort]
+profile = "black"
+src_paths = [
+    "src",
+    "tests",
+]
+line_length = 88
+multi_line_output = 3
+include_trailing_comma = true
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+strict_equality = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+python_files = [
+    "test_*.py",
+    "*_test.py",
+]
+python_classes = [
+    "Test*",
+]
+python_functions = [
+    "test_*",
+]
+markers = [
+    "slow: marks tests as slow",
+    "integration: marks integration tests",
+    "unit: marks unit tests",
+]
+
+[tool.coverage.run]
+source = [
+    "src/jeff",
+]
+omit = [
+    "tests/*",
+    "src/jeff/__main__.py",
+]
+
+[tool.coverage.report]
+fail_under = 75
+exclude_also = [
+    "def __repr__",
+    "if __name__ == .__main__.:",
+    "pragma: no cover",
+    "@(abc\\.)?abstractmethod",
+    "raise NotImplementedError",
+]
+
+[tool.vulture]
+min_confidence = 80
+paths = [
+    "src",
+    "tests",
+]
+
+[tool.interrogate]
+fail-under = 95
+ignore-init-method = true
+ignore-init-module = true
+exclude = [
+    "tests",
+    "docs",
+    "build",
+    "dist",
+]
+generate-badge = "."
+
+[tool.docformatter]
+recursive = true
+wrap-summaries = 88
+wrap-descriptions = 88
+close-quotes-on-newline = true

jeff_contacts-0.1.2/src/jeff/__init__.py

@@ -0,0 +1,3 @@
+"""Jeff — CRM Markdown synchronisé depuis CardDAV."""
+
+__version__ = "0.1.2"

jeff_contacts-0.1.2/src/jeff/carddav.py

@@ -0,0 +1,290 @@
+"""CardDAV client for Baikal.
+
+Minimal, no-bloat CardDAV client using ``requests`` + ``lxml``. Supports discovery,
+contact listing, batch fetch, and change detection via sync-token / ctag / etags.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import requests
+from lxml import etree
+
+from jeff.log import get_logger
+
+_log = get_logger("carddav")
+
+# XML namespaces used in CardDAV / WebDAV.
+DAV = "DAV:"
+CARDDAV = "urn:ietf:params:xml:ns:carddav"
+CS = "http://calendarserver.org/ns/"
+
+_NS = {"d": DAV, "card": CARDDAV, "cs": CS}
+
+
+@dataclass
+class Contact:
+    """A single contact fetched from the server."""
+
+    href: str
+    etag: str
+    vcard_raw: str
+
+
+@dataclass
+class SyncState:
+    """Persistent sync state stored on disk as JSON."""
+
+    sync_token: str | None = None
+    ctag: str | None = None
+    contacts: dict[str, dict[str, str]] = field(default_factory=dict)
+
+    def save(self, path: Path) -> None:
+        """Write state to a JSON file."""
+        data = {
+            "sync_token": self.sync_token,
+            "ctag": self.ctag,
+            "contacts": self.contacts,
+        }
+        path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    @classmethod
+    def load(cls, path: Path) -> SyncState:
+        """Load state from a JSON file, or return empty state."""
+        if not path.is_file():
+            return cls()
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return cls(
+            sync_token=data.get("sync_token"),
+            ctag=data.get("ctag"),
+            contacts=data.get("contacts", {}),
+        )
+
+
+@dataclass
+class CardDAVConfig:
+    """Connection parameters for a CardDAV server."""
+
+    url: str
+    username: str
+    password: str
+
+    @property
+    def base_url(self) -> str:
+        """Return the URL without a trailing slash."""
+        return self.url.rstrip("/")
+
+
+class CardDAVClient:
+    """Minimal CardDAV client for Baikal.
+
+    Talks to the server using raw WebDAV/CardDAV XML requests. No dependency on
+    vdirsyncer internals.
+    """
+
+    def __init__(self, config: CardDAVConfig) -> None:
+        """Initialize the CardDAV client."""
+        self._config = config
+        self._session = requests.Session()
+        self._session.auth = (config.username, config.password)
+        self._session.headers["Content-Type"] = "application/xml; charset=utf-8"
+
+    def discover_addressbooks(self) -> list[dict[str, str]]:
+        """Find all addressbooks for the authenticated user.
+
+        Returns a list of dicts with ``href`` and ``displayname`` keys.
+        """
+        body = (
+            '<?xml version="1.0" encoding="utf-8"?>'
+            '<d:propfind xmlns:d="DAV:">'
+            "<d:prop>"
+            "<d:resourcetype/>"
+            "<d:displayname/>"
+            "</d:prop>"
+            "</d:propfind>"
+        )
+        _log.debug("PROPFIND %s (discover addressbooks)", self._config.base_url)
+        resp = self._request("PROPFIND", self._config.base_url, body, depth="1")
+        tree = etree.fromstring(resp.content)
+        books: list[dict[str, str]] = []
+        for response in tree.findall("d:response", _NS):
+            restype = response.find(".//d:resourcetype/card:addressbook", _NS)
+            if restype is not None:
+                href = response.findtext("d:href", "", _NS)
+                name = response.findtext(".//d:displayname", "", _NS)
+                books.append({"href": href, "displayname": name})
+        return books
+
+    def get_ctag(self, addressbook_href: str) -> str | None:
+        """Fetch the CTag for an addressbook (collection-level change tag)."""
+        body = (
+            '<?xml version="1.0" encoding="utf-8"?>'
+            '<d:propfind xmlns:d="DAV:" xmlns:cs="http://calendarserver.org/ns/">'
+            "<d:prop>"
+            "<cs:getctag/>"
+            "</d:prop>"
+            "</d:propfind>"
+        )
+        url = self._absolute(addressbook_href)
+        resp = self._request("PROPFIND", url, body, depth="0")
+        tree = etree.fromstring(resp.content)
+        ctag: str | None = tree.findtext(".//cs:getctag", None, _NS)  # noqa: FURB184
+        return ctag
+
+    def list_contacts(self, addressbook_href: str) -> dict[str, str]:
+        """List all contact hrefs and their etags in an addressbook.
+
+        Returns a dict mapping ``href -> etag``.
+        """
+        body = (
+            '<?xml version="1.0" encoding="utf-8"?>'
+            '<d:propfind xmlns:d="DAV:">'
+            "<d:prop>"
+            "<d:getetag/>"
+            "<d:resourcetype/>"
+            "</d:prop>"
+            "</d:propfind>"
+        )
+        url = self._absolute(addressbook_href)
+        resp = self._request("PROPFIND", url, body, depth="1")
+        tree = etree.fromstring(resp.content)
+        contacts: dict[str, str] = {}
+        for response in tree.findall("d:response", _NS):
+            # Skip the addressbook itself (it has a resourcetype).
+            restype = response.find(".//d:resourcetype/card:addressbook", _NS)
+            if restype is not None:
+                continue
+            href = response.findtext("d:href", "", _NS)
+            etag = response.findtext(".//d:getetag", "", _NS).strip('"')
+            if href and href.endswith(".vcf"):
+                contacts[href] = etag
+        return contacts
+
+    def fetch_contacts(self, addressbook_href: str, hrefs: list[str]) -> list[Contact]:
+        """Fetch multiple contacts in a single request (multiget REPORT).
+
+        Returns a list of ``Contact`` objects with raw vCard data.
+        """
+        if not hrefs:
+            return []
+        _log.debug("Multiget %d contact(s)", len(hrefs))
+        href_xml = "".join(f"<d:href>{h}</d:href>" for h in hrefs)
+        body = (
+            '<?xml version="1.0" encoding="utf-8"?>'
+            '<card:addressbook-multiget xmlns:d="DAV:" '
+            'xmlns:card="urn:ietf:params:xml:ns:carddav">'
+            "<d:prop>"
+            "<d:getetag/>"
+            "<card:address-data/>"
+            "</d:prop>"
+            f"{href_xml}"
+            "</card:addressbook-multiget>"
+        )
+        url = self._absolute(addressbook_href)
+        resp = self._request("REPORT", url, body, depth="1")
+        tree = etree.fromstring(resp.content)
+        result: list[Contact] = []
+        for response in tree.findall("d:response", _NS):
+            href = response.findtext("d:href", "", _NS)
+            etag = response.findtext(".//d:getetag", "", _NS).strip('"')
+            vcard_raw = response.findtext(".//card:address-data", "", _NS)
+            if href and vcard_raw:
+                result.append(Contact(href=href, etag=etag, vcard_raw=vcard_raw))
+        return result
+
+    def fetch_all_contacts(self, addressbook_href: str) -> list[Contact]:
+        """Fetch all contacts in an addressbook."""
+        hrefs = list(self.list_contacts(addressbook_href).keys())
+        return self.fetch_contacts(addressbook_href, hrefs)
+
+    def sync(
+        self,
+        addressbook_href: str,
+        state: SyncState,
+    ) -> tuple[list[Contact], list[str], SyncState]:
+        """Incremental sync: fetch only changed contacts.
+
+        Returns ``(new_or_updated, deleted_hrefs, new_state)``. Uses ctag for
+        collection-level change detection, then diffs etags to find individual changes.
+        """
+        ctag = self.get_ctag(addressbook_href)
+        if ctag is not None and ctag == state.ctag:
+            _log.debug("CTag unchanged (%s), skipping sync", ctag)
+            return [], [], state
+        _log.debug("CTag changed: %s → %s", state.ctag, ctag)
+
+        current = self.list_contacts(addressbook_href)
+        old = state.contacts
+
+        # Find new or updated contacts.
+        changed_hrefs: list[str] = []
+        for href, etag in current.items():
+            old_etag = old.get(href, {}).get("etag")
+            if old_etag != etag:
+                changed_hrefs.append(href)
+
+        # Find deleted contacts.
+        deleted = [h for h in old if h not in current]
+
+        # Fetch changed contacts.
+        updated = self.fetch_contacts(addressbook_href, changed_hrefs)
+
+        # Build new state.
+        new_contacts: dict[str, dict[str, str]] = {}
+        for href, etag in current.items():
+            new_contacts[href] = {"etag": etag}
+
+        new_state = SyncState(
+            sync_token=state.sync_token,
+            ctag=ctag,
+            contacts=new_contacts,
+        )
+        return updated, deleted, new_state
+
+    def put_contact(self, href: str, vcard_raw: str, etag: str) -> str | None:
+        """Update a contact on the server via PUT.
+
+        Uses ``If-Match`` with the given etag for optimistic locking. Returns the new
+        etag on success, or None on conflict (412).
+        """
+        url = self._absolute(href)
+        _log.debug("PUT %s (If-Match: %s)", href, etag)
+        headers = {
+            "Content-Type": "text/vcard",
+            "If-Match": f'"{etag}"',
+        }
+        resp = self._session.put(url, data=vcard_raw.encode("utf-8"), headers=headers)
+        if resp.status_code == 412:
+            return None
+        resp.raise_for_status()
+        # Baikal returns the new etag in the ETag header.
+        new_etag = resp.headers.get("ETag", "").strip('"')
+        return new_etag or None
+
+    def _absolute(self, href: str) -> str:
+        """Resolve a relative href to an absolute URL."""
+        if href.startswith("http"):
+            return href
+        # Strip the path from the config URL, keep scheme+host.
+        from urllib.parse import urljoin
+
+        return urljoin(self._config.base_url + "/", href)
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        body: str,
+        depth: str = "0",
+    ) -> Any:
+        """Send a WebDAV request and return the response."""
+        headers = {"Depth": depth}
+        resp = self._session.request(
+            method, url, data=body.encode("utf-8"), headers=headers
+        )
+        resp.raise_for_status()
+        return resp