gramps-web-api-client 0.1__tar.gz

gramps-web-api-client-0.1/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__
+
+# setuptools
+/dist
+/src/*.egg-info
+
+# mypy
+.mypy_cache/
+
+# IntelliJ/PyCharm
+*.iml
+.idea
+
+# Miscelaneous
+/build
+/target
+.DS_Store

gramps-web-api-client-0.1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.1
+Name: gramps-web-api-client
+Version: 0.1
+Summary: A simple Python client to interact with Gramps Web API
+Author-email: "David M. Straub" <straub@protonmail.com>
+License: MIT
+Project-URL: homepage, https://github.com/DavidMStraub/gramps-web-api-client
+Project-URL: repository, https://github.com/DavidMStraub/gramps-web-api-client
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+
+# Gramps Web API Client
+
+
+A simple Python client based on `requests` for interacting with a [Gramps Web API](https://github.com/gramps-project/gramps-webapi/) server.
+
+## Warning
+
+This is an experimental project for advanced users. The goal is to allow powerful batch operations on Gramps objects via the API. But only use it if you know what you are doing &ndash; you can easily break your Gramps database with this tool!
+
+## Quick start
+
+First, instantiate the API instance:
+
+```python
+from gramps_web_api_client import API
+
+api = API(
+    host="https://my-gramps-web-instance.com",
+    basic_auth("my_user", "my_password")
+)
+```
+
+Methods currently implemented:
+
+
+| Method  | description |
+| ------------- | ------------- |
+| `api.iter_people()`  | Generator iterating over people  |
+| `api.iter_events()`  | Generator iterating over events  |
+| `api.iter_places()`  | Generator iterating over places  |
+| `api.get_person(handle)`  | Get a single person by handle  |
+| `api.get_event(handle)`  | Get a single event by handle  |
+| `api.get_place(handle)`  | Get a single place by handle  |
+| `api.update_person(handle, data)`  | Update a single person  |
+| `api.update_event(handle, data)`  | Update a single event  |
+| `api.update_place(handle, data)`  | Update a single place |
+| `api.create_person(data)`  | Create a new person  |
+| `api.create_event(data)`  | Create a new evebt  |
+| `api.create_place(data)`  | GCreateet a new place  |
+
+
+In all cases, `data` are dictionaries for JSON objects following the Gramps Web API conventions.
+
+## Examples
+
+Removing all citations from an existing person:
+
+```python
+api.update_person("somehandle", {"citation_list": []})
+```
+
+In this example, all other properties of the person (except citations) will remain the same.
+
+Creating a new place:
+
+```python
+api.create_place({
+    "name": {
+        "_class": "PlaceName",
+        "value": "Gotham City"
+    }
+})
+```
+
+Iterating over people and adding a citation if a condition is satisfied:
+
+```python
+for person in api.iter_people():
+    try:
+        surname = person["primary_name"]["surname_list"][0]["surname"]
+    except (KeyError, IndexError):
+        continue
+    if surname == "Garner":
+        api.update_person(
+            person["handle"],
+            {"citation_list": person["citation_list"] + ["some_citation_handle"]}
+        )    
+```

gramps-web-api-client-0.1/README.md

@@ -0,0 +1,78 @@
+# Gramps Web API Client
+
+
+A simple Python client based on `requests` for interacting with a [Gramps Web API](https://github.com/gramps-project/gramps-webapi/) server.
+
+## Warning
+
+This is an experimental project for advanced users. The goal is to allow powerful batch operations on Gramps objects via the API. But only use it if you know what you are doing – you can easily break your Gramps database with this tool!
+
+## Quick start
+
+First, instantiate the API instance:
+
+```python
+from gramps_web_api_client import API
+
+api = API(
+    host="https://my-gramps-web-instance.com",
+    basic_auth("my_user", "my_password")
+)
+```
+
+Methods currently implemented:
+
+
+| Method  | description |
+| ------------- | ------------- |
+| `api.iter_people()`  | Generator iterating over people  |
+| `api.iter_events()`  | Generator iterating over events  |
+| `api.iter_places()`  | Generator iterating over places  |
+| `api.get_person(handle)`  | Get a single person by handle  |
+| `api.get_event(handle)`  | Get a single event by handle  |
+| `api.get_place(handle)`  | Get a single place by handle  |
+| `api.update_person(handle, data)`  | Update a single person  |
+| `api.update_event(handle, data)`  | Update a single event  |
+| `api.update_place(handle, data)`  | Update a single place |
+| `api.create_person(data)`  | Create a new person  |
+| `api.create_event(data)`  | Create a new evebt  |
+| `api.create_place(data)`  | GCreateet a new place  |
+
+
+In all cases, `data` are dictionaries for JSON objects following the Gramps Web API conventions.
+
+## Examples
+
+Removing all citations from an existing person:
+
+```python
+api.update_person("somehandle", {"citation_list": []})
+```
+
+In this example, all other properties of the person (except citations) will remain the same.
+
+Creating a new place:
+
+```python
+api.create_place({
+    "name": {
+        "_class": "PlaceName",
+        "value": "Gotham City"
+    }
+})
+```
+
+Iterating over people and adding a citation if a condition is satisfied:
+
+```python
+for person in api.iter_people():
+    try:
+        surname = person["primary_name"]["surname_list"][0]["surname"]
+    except (KeyError, IndexError):
+        continue
+    if surname == "Garner":
+        api.update_person(
+            person["handle"],
+            {"citation_list": person["citation_list"] + ["some_citation_handle"]}
+        )    
+```

gramps-web-api-client-0.1/mypy.cfg

@@ -0,0 +1,2 @@
+[mypy]
+strict = true

gramps-web-api-client-0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "gramps-web-api-client"
+description = "A simple Python client to interact with Gramps Web API"
+authors = [
+  { name = "David M. Straub", email = "straub@protonmail.com" },
+]
+license = { text = "MIT" }
+readme = "README.md"
+dynamic = ["version"]
+dependencies = [
+  "requests>=2.31.0"
+]
+
+[project.urls]
+homepage = "https://github.com/DavidMStraub/gramps-web-api-client"
+repository = "https://github.com/DavidMStraub/gramps-web-api-client"
+
+[build-system]
+requires = ["setuptools>=61.0", "setuptools_scm[toml]>=6.2"]
+build-backend = "setuptools.build_meta"
+
+[tool.isort]
+profile = "black"
+
+[tool.setuptools_scm]
+# NOTE: Using a version file avoids some overhead
+#
+# This file is explicitly ignored by version control.
+write_to = "src/gramps_web_api_client/_version.py"

gramps-web-api-client-0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gramps-web-api-client-0.1/setup.py

@@ -0,0 +1,4 @@
+# Compatibility shim: Loads the real config from pyproject.toml
+from setuptools import setup
+
+setup()

gramps-web-api-client-0.1/src/gramps_web_api_client/.gitignore

@@ -0,0 +1,2 @@
+# Generated by setuptools_scm, should be ignored by VCS
+/_version.py

gramps-web-api-client-0.1/src/gramps_web_api_client/__init__.py

@@ -0,0 +1,17 @@
+__version__: str | None
+__version_tuple__: tuple | None
+
+try:
+    # This file is auto-generated, and could be missing.
+    # Tell mypy to ignore it
+    from ._version import __version__, __version_tuple__  # type: ignore
+except ImportError:
+    __version__ = None
+    __version_tuple__ = None
+
+__all__ = (
+    "__version__",
+    "__version_tuple__",
+)
+
+from .api import API

gramps-web-api-client-0.1/src/gramps_web_api_client/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.1'
+__version_tuple__ = version_tuple = (0, 1)

gramps-web-api-client-0.1/src/gramps_web_api_client/api.py

@@ -0,0 +1,165 @@
+"""A simple Gramps Web API Client."""
+
+from typing import Optional, Tuple
+from urllib.parse import urlencode
+
+import requests
+
+API_PREFIX = "/api"
+ENDPOINT_TOKEN = "/token/"
+ENDPOINT_PEOPLE = "/people/"
+ENDPOINT_EVENTS = "/events/"
+ENDPOINT_PLACES = "/places/"
+PAGE_SIZE = 200
+
+
+class API:
+    """API."""
+
+    def __init__(
+        self,
+        host: str = "http://127.0.0.1:5555",
+        basic_auth: Optional[Tuple[str, str]] = None,
+    ):
+        """Inititalize self."""
+        self.host = host.rstrip("/")
+        if basic_auth:
+            self.user, self.password = basic_auth
+        else:
+            raise ValueError("basic_auth is required")
+        self._access_token = ""
+        self._refresh_token = ""
+
+    def _endpoint_url(self, endpoint: str):
+        """Build a full URL for the given endpoint."""
+        return f"{self.host}{API_PREFIX}{endpoint}"
+
+    def _fetch_tokens(self):
+        """Fetch tokens."""
+        res = requests.post(
+            self._endpoint_url(ENDPOINT_TOKEN),
+            json={"username": self.user, "password": self.password},
+        )
+        res.raise_for_status()
+        data = res.json()
+        self._access_token = data["access_token"]
+        self._refresh_token = data["refresh_token"]
+
+    @property
+    def _auth_header(self):
+        """return the auth header."""
+        return {"Authorization": f"Bearer {self._access_token}"}
+
+    def _get(self, endpoint: str):
+        """Get data from a protected URL."""
+        if not self._access_token:
+            self._fetch_tokens()
+        url = self._endpoint_url(endpoint)
+        res = requests.get(url, headers=self._auth_header)
+        res.raise_for_status()
+        data = res.json()
+        return data
+
+    def _put(self, endpoint: str, data):
+        """Put data to a protected URL."""
+        if not self._access_token:
+            self._fetch_tokens()
+        url = self._endpoint_url(endpoint)
+        res = requests.put(url, headers=self._auth_header, json=data)
+        res.raise_for_status()
+        data = res.json()
+        return data
+
+    def _post(self, endpoint: str, data):
+        """Post data to a protected URL."""
+        if not self._access_token:
+            self._fetch_tokens()
+        url = self._endpoint_url(endpoint)
+        res = requests.post(url, headers=self._auth_header, json=data)
+        res.raise_for_status()
+        data = res.json()
+        return data
+
+    def _get_object(self, object_endpoint: str, handle: str):
+        """Get a single object."""
+        if not handle:
+            raise ValueError("handle is required")
+        endpoint = f"{object_endpoint}{handle}"
+        return self._get(endpoint)
+
+    def _put_object(self, object_endpoint: str, handle: str, data):
+        """Put a single object."""
+        if not handle:
+            raise ValueError("handle is required")
+        endpoint = f"{object_endpoint}{handle}"
+        return self._put(endpoint, data)
+
+    def _iter_objects(self, object_endpoint: str, **kwargs):
+        """Iterate over objects."""
+        page = 1
+        while True:
+            endpoint = f"{object_endpoint}?pagesize={PAGE_SIZE}&page={page}"
+            for key, value in kwargs.items():
+                if not isinstance(value, str):
+                    value = urlencode(value)
+                endpoint += f"&{key}={value}"
+            data = self._get(endpoint)
+            if not len(data):
+                break
+            for obj in data:
+                yield obj
+            page += 1
+
+    def _update_object(self, object_endpoint: str, handle: str, data):
+        """Update an object."""
+        old_data = self._get_object(object_endpoint, handle)
+        new_data = {**old_data, **data}
+        return self._put_object(object_endpoint, handle, new_data)
+
+    def get_person(self, handle: str):
+        """Get a single person."""
+        return self._get_object(ENDPOINT_PEOPLE, handle)
+
+    def get_event(self, handle: str):
+        """Get a single event."""
+        return self._get_object(ENDPOINT_EVENTS, handle)
+
+    def get_place(self, handle: str):
+        """Get a single place."""
+        return self._get_object(ENDPOINT_PLACES, handle)
+
+    def iter_people(self, **kwargs):
+        """Iterate over people."""
+        return self._iter_objects(ENDPOINT_PEOPLE, **kwargs)
+
+    def iter_events(self, **kwargs):
+        """Iterate over events."""
+        return self._iter_objects(ENDPOINT_EVENTS, **kwargs)
+
+    def iter_places(self, **kwargs):
+        """Iterate over places."""
+        return self._iter_objects(ENDPOINT_PLACES, **kwargs)
+
+    def update_person(self, handle: str, data):
+        """Update a person."""
+        return self._update_object(ENDPOINT_PEOPLE, handle, data)
+
+    def update_event(self, handle: str, data):
+        """Update an event."""
+        return self._update_object(ENDPOINT_EVENTS, handle, data)
+
+    def update_place(self, handle: str, data):
+        """Update a place."""
+        return self._update_object(ENDPOINT_PLACES, handle, data)
+
+    def create_person(self, data):
+        """Create a person."""
+        return self._post(ENDPOINT_PEOPLE, data)
+
+    def create_event(self, data):
+        """Create ab event."""
+        return self._post(ENDPOINT_EVENTS, data)
+
+    def create_place(self, data):
+        """Create a place."""
+        return self._post(ENDPOINT_PLACES, data)

gramps-web-api-client-0.1/src/gramps_web_api_client.egg-info/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.1
+Name: gramps-web-api-client
+Version: 0.1
+Summary: A simple Python client to interact with Gramps Web API
+Author-email: "David M. Straub" <straub@protonmail.com>
+License: MIT
+Project-URL: homepage, https://github.com/DavidMStraub/gramps-web-api-client
+Project-URL: repository, https://github.com/DavidMStraub/gramps-web-api-client
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+
+# Gramps Web API Client
+
+
+A simple Python client based on `requests` for interacting with a [Gramps Web API](https://github.com/gramps-project/gramps-webapi/) server.
+
+## Warning
+
+This is an experimental project for advanced users. The goal is to allow powerful batch operations on Gramps objects via the API. But only use it if you know what you are doing &ndash; you can easily break your Gramps database with this tool!
+
+## Quick start
+
+First, instantiate the API instance:
+
+```python
+from gramps_web_api_client import API
+
+api = API(
+    host="https://my-gramps-web-instance.com",
+    basic_auth("my_user", "my_password")
+)
+```
+
+Methods currently implemented:
+
+
+| Method  | description |
+| ------------- | ------------- |
+| `api.iter_people()`  | Generator iterating over people  |
+| `api.iter_events()`  | Generator iterating over events  |
+| `api.iter_places()`  | Generator iterating over places  |
+| `api.get_person(handle)`  | Get a single person by handle  |
+| `api.get_event(handle)`  | Get a single event by handle  |
+| `api.get_place(handle)`  | Get a single place by handle  |
+| `api.update_person(handle, data)`  | Update a single person  |
+| `api.update_event(handle, data)`  | Update a single event  |
+| `api.update_place(handle, data)`  | Update a single place |
+| `api.create_person(data)`  | Create a new person  |
+| `api.create_event(data)`  | Create a new evebt  |
+| `api.create_place(data)`  | GCreateet a new place  |
+
+
+In all cases, `data` are dictionaries for JSON objects following the Gramps Web API conventions.
+
+## Examples
+
+Removing all citations from an existing person:
+
+```python
+api.update_person("somehandle", {"citation_list": []})
+```
+
+In this example, all other properties of the person (except citations) will remain the same.
+
+Creating a new place:
+
+```python
+api.create_place({
+    "name": {
+        "_class": "PlaceName",
+        "value": "Gotham City"
+    }
+})
+```
+
+Iterating over people and adding a citation if a condition is satisfied:
+
+```python
+for person in api.iter_people():
+    try:
+        surname = person["primary_name"]["surname_list"][0]["surname"]
+    except (KeyError, IndexError):
+        continue
+    if surname == "Garner":
+        api.update_person(
+            person["handle"],
+            {"citation_list": person["citation_list"] + ["some_citation_handle"]}
+        )    
+```

gramps-web-api-client-0.1/src/gramps_web_api_client.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+.gitignore
+README.md
+mypy.cfg
+pyproject.toml
+setup.py
+src/gramps_web_api_client/.gitignore
+src/gramps_web_api_client/__init__.py
+src/gramps_web_api_client/_version.py
+src/gramps_web_api_client/api.py
+src/gramps_web_api_client.egg-info/PKG-INFO
+src/gramps_web_api_client.egg-info/SOURCES.txt
+src/gramps_web_api_client.egg-info/dependency_links.txt
+src/gramps_web_api_client.egg-info/requires.txt
+src/gramps_web_api_client.egg-info/top_level.txt
+tests/gramps_web_api_client/test_todo.py

gramps-web-api-client-0.1/src/gramps_web_api_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gramps-web-api-client-0.1/src/gramps_web_api_client.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.31.0

gramps-web-api-client-0.1/src/gramps_web_api_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+gramps_web_api_client

gramps-web-api-client-0.1/tests/gramps_web_api_client/test_todo.py

@@ -0,0 +1,2 @@
+def test_todo():
+    raise NotImplementedError("TODO: Implement tests")