lokate 1.0.0__tar.gz

lokate-1.0.0/.gitignore

@@ -0,0 +1,153 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+**/__pycache__
+*.py[cod]
+*$py.class
+*.pyc
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# static files generated from Django application using `collectstatic`
+media
+export
+static_collected
+data
+
+*.token.temp
+*.fakts.yaml
+fakts.yaml
+# Local-source override for the integration stack (see tests/conftest.py)
+tests/integration/docker-compose.local.yml

lokate-1.0.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: lokate
+Version: 1.0.0
+Summary: The python client for lokate, the arkitekt backup of a phone's location timeline
+Author-email: jhnnsrs <jhnnsrs@gmail.com>
+Requires-Python: >=3.11
+Requires-Dist: aiohttp<4,>=3.9.5
+Requires-Dist: koil>=1.0.0
+Requires-Dist: rath>=4.1.1
+Requires-Dist: websockets>=15.0.1
+Description-Content-Type: text/markdown
+
+# lokate
+
+The python client for [lokate](https://github.com/arkitektio/lokate-server), the
+[Arkitekt](https://arkitekt.live) backup of a phone's location timeline: points,
+visits, trips and places, uploaded idempotently and restorable page by page.
+
+## Installation
+
+```sh
+pip install lokate
+```
+
+## Usage
+
+Every lokate operation is a method of the `Lokate` client, in a blocking and an
+`a`-prefixed async flavour. The server keys everything by the token's user and
+writes by its device (`client_device` claim).
+
+### In an arkitekt app
+
+The client is injected by annotation. Add the service to your app and ask for
+`lokate: Lokate`:
+
+```python
+from arkitekt import App, run
+from lokate import Lokate, lokate_service
+
+app = App("where-was-i", "0.1.0", services=[lokate_service])
+
+
+@app.action
+async def places_i_keep(lokate: Lokate) -> list[str]:
+    """The names of my places, from the server copy."""
+    names, cursor = [], None
+    while True:
+        page = await lokate.aget_changes(cursor=cursor)
+        names += [place.name for place in page.places]
+        cursor = page.next_cursor
+        if not page.has_more:
+            return names
+
+
+if __name__ == "__main__":
+    run(app)
+```
+
+### From a script
+
+```python
+from arkitekt import easy
+from lokate import lokate_service
+
+with easy("my-script", lokate_service) as lokate:
+    state = lokate.get_sync_state()
+    print(state.point_count, state.last_point_ts)
+```
+
+### Standalone
+
+Without arkitekt, build the client over a rath link of your own:
+
+```python
+import datetime
+from lokate import Lokate
+from lokate.api.schema import PointInput
+from lokate.rath import LokateRath
+
+lokate = Lokate(rath=LokateRath(link=...))
+
+with lokate:
+    result = lokate.upload_points([
+        PointInput(client_id="fix-1", ts=datetime.datetime.now(datetime.UTC), lat=48.2, lon=16.37),
+    ])
+    print(result.accepted, result.duplicates)
+```
+
+What the protocol guarantees:
+
+- **Every write can be retried.** `upload_points` counts points it already has as
+  `duplicates`. `replace_segments(from_=...)` and `merge_places` leave unchanged
+  rows alone.
+- **A point is keyed by `(device, client_id, ts)`.** Never send one `client_id`
+  with two different timestamps.
+- **Batches hold at most 1000 rows**, and so does a `get_changes` page.
+- **Leave defaulted arguments out** rather than passing `None`. For `set_retention`,
+  though, `days=None` is meaningful: it means keep forever.
+
+## Development
+
+The generated API (`lokate/api/schema.py`) comes from the checked-in
+`schema.graphql` and the documents in `graphql/`. The config comment in
+`graphql.config.yaml` has the command that refreshes the schema from a
+lokate-server checkout. Then regenerate with turms:
+
+```sh
+uvx --with 'graphql-core<3.3' --with-editable . --from <path to turms> turms gen
+```
+
+```sh
+uv run pytest -m "not integration"   # no server needed
+uv run pytest -m integration          # a real lokate + postgres/PostGIS via dokker
+```
+
+Until the server's first image is published, the integration suite needs a
+gitignored `tests/integration/docker-compose.local.yml` that builds
+`jhnnsrs/lokate` from a local lokate-server checkout.
+
+See [RELEASING.md](RELEASING.md) for how versions are cut.

lokate-1.0.0/README.md

@@ -0,0 +1,108 @@
+# lokate
+
+The python client for [lokate](https://github.com/arkitektio/lokate-server), the
+[Arkitekt](https://arkitekt.live) backup of a phone's location timeline: points,
+visits, trips and places, uploaded idempotently and restorable page by page.
+
+## Installation
+
+```sh
+pip install lokate
+```
+
+## Usage
+
+Every lokate operation is a method of the `Lokate` client, in a blocking and an
+`a`-prefixed async flavour. The server keys everything by the token's user and
+writes by its device (`client_device` claim).
+
+### In an arkitekt app
+
+The client is injected by annotation. Add the service to your app and ask for
+`lokate: Lokate`:
+
+```python
+from arkitekt import App, run
+from lokate import Lokate, lokate_service
+
+app = App("where-was-i", "0.1.0", services=[lokate_service])
+
+
+@app.action
+async def places_i_keep(lokate: Lokate) -> list[str]:
+    """The names of my places, from the server copy."""
+    names, cursor = [], None
+    while True:
+        page = await lokate.aget_changes(cursor=cursor)
+        names += [place.name for place in page.places]
+        cursor = page.next_cursor
+        if not page.has_more:
+            return names
+
+
+if __name__ == "__main__":
+    run(app)
+```
+
+### From a script
+
+```python
+from arkitekt import easy
+from lokate import lokate_service
+
+with easy("my-script", lokate_service) as lokate:
+    state = lokate.get_sync_state()
+    print(state.point_count, state.last_point_ts)
+```
+
+### Standalone
+
+Without arkitekt, build the client over a rath link of your own:
+
+```python
+import datetime
+from lokate import Lokate
+from lokate.api.schema import PointInput
+from lokate.rath import LokateRath
+
+lokate = Lokate(rath=LokateRath(link=...))
+
+with lokate:
+    result = lokate.upload_points([
+        PointInput(client_id="fix-1", ts=datetime.datetime.now(datetime.UTC), lat=48.2, lon=16.37),
+    ])
+    print(result.accepted, result.duplicates)
+```
+
+What the protocol guarantees:
+
+- **Every write can be retried.** `upload_points` counts points it already has as
+  `duplicates`. `replace_segments(from_=...)` and `merge_places` leave unchanged
+  rows alone.
+- **A point is keyed by `(device, client_id, ts)`.** Never send one `client_id`
+  with two different timestamps.
+- **Batches hold at most 1000 rows**, and so does a `get_changes` page.
+- **Leave defaulted arguments out** rather than passing `None`. For `set_retention`,
+  though, `days=None` is meaningful: it means keep forever.
+
+## Development
+
+The generated API (`lokate/api/schema.py`) comes from the checked-in
+`schema.graphql` and the documents in `graphql/`. The config comment in
+`graphql.config.yaml` has the command that refreshes the schema from a
+lokate-server checkout. Then regenerate with turms:
+
+```sh
+uvx --with 'graphql-core<3.3' --with-editable . --from <path to turms> turms gen
+```
+
+```sh
+uv run pytest -m "not integration"   # no server needed
+uv run pytest -m integration          # a real lokate + postgres/PostGIS via dokker
+```
+
+Until the server's first image is published, the integration suite needs a
+gitignored `tests/integration/docker-compose.local.yml` that builds
+`jhnnsrs/lokate` from a local lokate-server checkout.
+
+See [RELEASING.md](RELEASING.md) for how versions are cut.

lokate-1.0.0/lokate/__init__.py

@@ -0,0 +1,20 @@
+from .lokate import Lokate
+
+try:
+    from .arkitekt import lokate as lokate_service
+except ImportError as e:
+    # Only "rekuest is not installed" may pass silently. Anything else that fails
+    # to import here (a renamed query, a rekuest too old for what the module
+    # needs) is a bug, and hiding it makes this package's service vanish
+    # without a word. Whether it is installed is asked the plain way.
+    try:
+        import rekuest  # noqa: F401 -- presence is the question
+    except ImportError:
+        pass
+    else:
+        raise e
+
+__all__ = [
+    "Lokate",
+    "lokate_service",
+]

lokate-1.0.0/lokate/api/project.json

@@ -0,0 +1,120 @@
+{
+    "schema": "schema.graphql",
+    "documents": "graphql/**/**.graphql",
+    "extensions": {
+        "turms": {
+            "domain": null,
+            "out_dir": "lokate/api",
+            "dump_configuration": true,
+            "configuration_name": "project.json",
+            "dump_schema": true,
+            "schema_name": "schema.graphql",
+            "generated_name": "schema.py",
+            "documents": "graphql/**/**.graphql",
+            "verbose": false,
+            "exit_on_error": true,
+            "allow_introspection": true,
+            "object_bases": [
+                "pydantic.BaseModel"
+            ],
+            "interface_bases": null,
+            "always_resolve_interfaces": true,
+            "exclude_typenames": true,
+            "scalar_definitions": {
+                "uuid": "str",
+                "Callback": "str",
+                "Any": "typing.Any",
+                "JSON": "typing.Any",
+                "ID": "rath.scalars.ID",
+                "_Any": "typing.Any",
+                "ByteCount": "int"
+            },
+            "coercible_scalars": {},
+            "coercible_inputs": {},
+            "graphql_default_class": null,
+            "deprecated_class": null,
+            "document_field_metadata": true,
+            "unset_type_class": null,
+            "unset_instance": null,
+            "freeze": {
+                "enabled": true,
+                "types": [
+                    "input",
+                    "fragment",
+                    "object"
+                ],
+                "exclude": null,
+                "include": null,
+                "convert_list_to_tuple": true
+            },
+            "create_catchall": true,
+            "options": {
+                "enabled": true,
+                "extra": "forbid",
+                "populate_by_name": true,
+                "from_attributes": null,
+                "use_enum_values": true,
+                "validate_assignment": null,
+                "alias_mode": "split",
+                "types": [
+                    "input"
+                ],
+                "exclude": null,
+                "include": null
+            },
+            "skip_forwards": false,
+            "min_python_version": "3.10",
+            "type_annotation_style": "auto",
+            "external_modules": [],
+            "additional_bases": {},
+            "additional_config": {},
+            "force_plugin_order": true,
+            "omitted_document_rules": [],
+            "parsers": [],
+            "plugins": [
+                {
+                    "type": "turms.plugins.enums.EnumsPlugin"
+                },
+                {
+                    "type": "turms.plugins.inputs.InputsPlugin"
+                },
+                {
+                    "type": "turms.plugins.fragments.FragmentsPlugin"
+                },
+                {
+                    "type": "turms.plugins.operations.OperationsPlugin"
+                },
+                {
+                    "type": "turms.plugins.client.ClientPlugin",
+                    "client_class": "LokateApi",
+                    "global_kwargs": [
+                        {
+                            "key": "task",
+                            "type": "rath.task.TaskLike",
+                            "description": "The task this call is made for; the ambient one by default."
+                        }
+                    ],
+                    "reserved_from": [
+                        "lokate.lokate.Lokate"
+                    ],
+                    "coercible_scalars": {
+                        "ID": "rath.scalars.IDCoercible"
+                    },
+                    "expand_input_types": [
+                        "input"
+                    ]
+                }
+            ],
+            "processors": [],
+            "stylers": [
+                {
+                    "type": "turms.stylers.default.DefaultStyler"
+                },
+                {
+                    "type": "turms.stylers.appender.AppenderStyler",
+                    "append_fragment": ""
+                }
+            ]
+        }
+    }
+}