karma365 0.2.0__tar.gz

karma365-0.2.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: karma365
+Version: 0.2.0
+Summary: Add to your KARMA 365 library from Python. Your data stays on your phone.
+License: MIT
+Project-URL: Homepage, https://github.com/ayushkotadiya5499/karma365-sdk
+Project-URL: Bug Tracker, https://github.com/ayushkotadiya5499/karma365-sdk/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.25
+
+# KARMA 365 SDK for Python
+
+Add to your KARMA 365 library from Python: results, plots, videos, notes and tasks.
+
+Your data stays on your phone. This SDK has no database and no cloud. It talks to the
+app over your own Wi-Fi, hotspot or USB, and everything on the way is encrypted.
+
+## Before you start
+
+1. Open KARMA 365 on your phone.
+2. Go to Settings, AI MCP, and turn on **Allow PC connection**.
+3. Copy the token, and put it in an environment variable:
+
+```bash
+export KARMA365_TOKEN="your token"          # macOS, Linux
+setx KARMA365_TOKEN "your token"            # Windows, then open a new terminal
+```
+
+**Keep the token out of your code, and off GitHub.** Whoever holds it, on the same
+network as your phone, can read and change everything that is not PIN-locked. If it
+leaks, make a new one in the app. The old one stops working at once.
+
+The phone must be on, with the app unlocked, on the same network as this PC.
+
+## Is it connected?
+
+```bash
+python -m karma365 status
+```
+
+```python
+status = await karma.status()
+print(status.connected, status.reason, status.message, status.hint)
+```
+
+`connected` is true only after your phone has answered with your token's key, so
+another device cannot pass as your phone. The answer is true for that moment; if the
+Wi-Fi goes later, the next call says so.
+
+In the app, Settings, AI MCP shows the last connection, and a file being received.
+
+## Use it
+
+With `await`:
+
+```python
+import asyncio
+from karma365 import AsyncKarmaClient
+
+async def main():
+    async with AsyncKarmaClient() as karma:
+        topic = await karma.find_minor_id("Machine Learning")
+        await karma.add_image(topic, "outputs/confusion_matrix.png", caption="Accuracy 96.4%")
+        await karma.create_task("Train ResNet-50", priority="high")
+
+asyncio.run(main())
+```
+
+Without `await`, for scripts and notebooks. It works inside Jupyter too:
+
+```python
+from karma365 import KarmaClient
+
+karma = KarmaClient()
+karma.create_task("Train ResNet-50", priority="high")
+```
+
+## Large files
+
+```python
+await karma.add_video(
+    "Machine Learning", "lecture_8gb.mp4", title="Lecture 1",
+    on_progress=lambda sent, total: print(f"{sent * 100 // total}%"),
+)
+```
+
+- Any size. The limit is your phone's free space, which is checked before anything is sent.
+- The file goes in encrypted pieces, so it never fills your memory.
+- **If it stops, run the same call again.** Only the missing pieces are sent.
+- Nothing appears in the app until the whole file has arrived.
+- On the phone, a notification keeps it going while the screen is off. Android can
+  still close the app, Oppo phones especially. Open it again and repeat the call.
+
+`await` does not itself make a file faster. It keeps your program free, and lets
+several pieces travel at once. The speed comes from your Wi-Fi and your phone. Measure
+yours, using a test file that is deleted afterwards:
+
+```bash
+python -m karma365 speedtest 100
+```
+
+This needs a minor topic to exist, which the test file passes through.
+
+## Locked items
+
+The phone checks every PIN, and allows 6 wrong tries before a short wait.
+
+```python
+import getpass
+await karma.unlock(getpass.getpass("PIN: "))   # kept in memory until lock() or close()
+await karma.list_resources("Private", pin=my_pin)   # or for one call
+```
+
+Do not write the PIN in your code. Without it, locked rows say only that they are
+locked, and `is_locked` is true on them. The PIN can only be set or changed in the app.
+
+## Errors
+
+Every error says what happened and what to do, and has a `code` that never changes.
+
+```python
+from karma365 import KarmaError, PhoneNotFoundError
+
+try:
+    await karma.add_video("ML", "lecture.mp4")
+except PhoneNotFoundError as e:
+    print(e.hint)
+except KarmaError as e:
+    print(e.code, e.message, e.details)
+```
+
+| Code | Meaning |
+|---|---|
+| `TOKEN_MISSING`, `TOKEN_REJECTED` | No token, or the phone did not accept it |
+| `CLOCK_OUT_OF_SYNC` | This PC's clock and the phone's are too far apart |
+| `PHONE_NOT_FOUND` | No answer. App closed, Allow PC off, or another network |
+| `NOT_YOUR_PHONE` | Something answered, but could not prove it is your phone |
+| `APP_LOCKED` | Unlock the app on your phone |
+| `CONNECTION_LOST`, `PHONE_TIMEOUT` | Lost during a call. A change may have happened, so check before repeating it |
+| `APP_UPDATE_NEEDED` | The app on your phone is too old for this |
+| `PIN_REQUIRED`, `PIN_WRONG`, `PIN_LOCKED_OUT`, `PARENT_LOCKED` | About locks |
+| `NOT_FOUND`, `AMBIGUOUS_NAME`, `INVALID_INPUT` | About what you passed |
+| `FILE_NOT_FOUND`, `FILE_NOT_ALLOWED`, `FILE_CHANGED` | About the file on this PC |
+| `PHONE_STORAGE_FULL`, `UPLOAD_INTERRUPTED` | About sending a file |
+| `PHONE_ERROR` | Unexpected. Set `KARMA365_DEBUG=1` to see more |
+
+Reads, and pieces of a file, are tried again by themselves. A create or a delete is
+not, because the first try may have worked. A wrong PIN is never tried again, so a
+script cannot use up your tries.
+
+## Deleting locked items
+
+Something locked is never deleted, not even with the PIN. Neither is something under a
+lock, or something holding a locked item. Remove the lock first, then delete. Until then
+the call fails with `PARENT_LOCKED`.
+
+## Names and IDs
+
+Anything that changes something needs an ID, or a whole name that fits only one item.
+Part of a name works only in `find_id()` and `search()`, so a short word can never
+delete the wrong thing.
+
+## Methods
+
+**Connection:** `status`, `is_connected`, `unlock`, `lock`, `close`
+
+**Finding:** `find_id`, `find_minor_id`, `find_major_id`, `get_info`, `search`
+
+**Topics:** `create_major`, `create_minor`, `list_majors`, `list_minors`, `get_major`,
+`get_minor`, `change_name`, `change_minor_name`, `change_major_name`, `change_color`,
+`change_minor_color`, `change_major_color`, `change_dp`, `change_difficulty`,
+`transfer_minor_to`, `transfer_to`, `pin`, `unpin`, `star`, `unstar`, `delete`, `clean_empty`
+
+**Resources:** `add_image`, `add_video`, `add_audio`, `add_pdf`, `add_youtube`, `add_link`,
+`add_code`, `add_note`, `append_note`, `list_resources`, `view_all`, `get_resource`,
+`change_description`, `mark_done`, `unmark_done`
+
+**Tasks:** `create_task`, `list_tasks`, `get_task`, `change_priority`, `mark_done`,
+`unmark_done`, `delete`, `clear_completed_tasks`
+
+**Stats:** `get_stats`
+
+## Settings
+
+| Variable | Use |
+|---|---|
+| `KARMA365_TOKEN` | Your token |
+| `KARMA365_PHONE_URL` | The phone's address, if it is not found by itself |
+| `KARMA365_DEBUG` | Set to 1 to add the technical cause to errors. Never shows your token or PIN |

karma365-0.2.0/README.md

@@ -0,0 +1,179 @@
+# KARMA 365 SDK for Python
+
+Add to your KARMA 365 library from Python: results, plots, videos, notes and tasks.
+
+Your data stays on your phone. This SDK has no database and no cloud. It talks to the
+app over your own Wi-Fi, hotspot or USB, and everything on the way is encrypted.
+
+## Before you start
+
+1. Open KARMA 365 on your phone.
+2. Go to Settings, AI MCP, and turn on **Allow PC connection**.
+3. Copy the token, and put it in an environment variable:
+
+```bash
+export KARMA365_TOKEN="your token"          # macOS, Linux
+setx KARMA365_TOKEN "your token"            # Windows, then open a new terminal
+```
+
+**Keep the token out of your code, and off GitHub.** Whoever holds it, on the same
+network as your phone, can read and change everything that is not PIN-locked. If it
+leaks, make a new one in the app. The old one stops working at once.
+
+The phone must be on, with the app unlocked, on the same network as this PC.
+
+## Is it connected?
+
+```bash
+python -m karma365 status
+```
+
+```python
+status = await karma.status()
+print(status.connected, status.reason, status.message, status.hint)
+```
+
+`connected` is true only after your phone has answered with your token's key, so
+another device cannot pass as your phone. The answer is true for that moment; if the
+Wi-Fi goes later, the next call says so.
+
+In the app, Settings, AI MCP shows the last connection, and a file being received.
+
+## Use it
+
+With `await`:
+
+```python
+import asyncio
+from karma365 import AsyncKarmaClient
+
+async def main():
+    async with AsyncKarmaClient() as karma:
+        topic = await karma.find_minor_id("Machine Learning")
+        await karma.add_image(topic, "outputs/confusion_matrix.png", caption="Accuracy 96.4%")
+        await karma.create_task("Train ResNet-50", priority="high")
+
+asyncio.run(main())
+```
+
+Without `await`, for scripts and notebooks. It works inside Jupyter too:
+
+```python
+from karma365 import KarmaClient
+
+karma = KarmaClient()
+karma.create_task("Train ResNet-50", priority="high")
+```
+
+## Large files
+
+```python
+await karma.add_video(
+    "Machine Learning", "lecture_8gb.mp4", title="Lecture 1",
+    on_progress=lambda sent, total: print(f"{sent * 100 // total}%"),
+)
+```
+
+- Any size. The limit is your phone's free space, which is checked before anything is sent.
+- The file goes in encrypted pieces, so it never fills your memory.
+- **If it stops, run the same call again.** Only the missing pieces are sent.
+- Nothing appears in the app until the whole file has arrived.
+- On the phone, a notification keeps it going while the screen is off. Android can
+  still close the app, Oppo phones especially. Open it again and repeat the call.
+
+`await` does not itself make a file faster. It keeps your program free, and lets
+several pieces travel at once. The speed comes from your Wi-Fi and your phone. Measure
+yours, using a test file that is deleted afterwards:
+
+```bash
+python -m karma365 speedtest 100
+```
+
+This needs a minor topic to exist, which the test file passes through.
+
+## Locked items
+
+The phone checks every PIN, and allows 6 wrong tries before a short wait.
+
+```python
+import getpass
+await karma.unlock(getpass.getpass("PIN: "))   # kept in memory until lock() or close()
+await karma.list_resources("Private", pin=my_pin)   # or for one call
+```
+
+Do not write the PIN in your code. Without it, locked rows say only that they are
+locked, and `is_locked` is true on them. The PIN can only be set or changed in the app.
+
+## Errors
+
+Every error says what happened and what to do, and has a `code` that never changes.
+
+```python
+from karma365 import KarmaError, PhoneNotFoundError
+
+try:
+    await karma.add_video("ML", "lecture.mp4")
+except PhoneNotFoundError as e:
+    print(e.hint)
+except KarmaError as e:
+    print(e.code, e.message, e.details)
+```
+
+| Code | Meaning |
+|---|---|
+| `TOKEN_MISSING`, `TOKEN_REJECTED` | No token, or the phone did not accept it |
+| `CLOCK_OUT_OF_SYNC` | This PC's clock and the phone's are too far apart |
+| `PHONE_NOT_FOUND` | No answer. App closed, Allow PC off, or another network |
+| `NOT_YOUR_PHONE` | Something answered, but could not prove it is your phone |
+| `APP_LOCKED` | Unlock the app on your phone |
+| `CONNECTION_LOST`, `PHONE_TIMEOUT` | Lost during a call. A change may have happened, so check before repeating it |
+| `APP_UPDATE_NEEDED` | The app on your phone is too old for this |
+| `PIN_REQUIRED`, `PIN_WRONG`, `PIN_LOCKED_OUT`, `PARENT_LOCKED` | About locks |
+| `NOT_FOUND`, `AMBIGUOUS_NAME`, `INVALID_INPUT` | About what you passed |
+| `FILE_NOT_FOUND`, `FILE_NOT_ALLOWED`, `FILE_CHANGED` | About the file on this PC |
+| `PHONE_STORAGE_FULL`, `UPLOAD_INTERRUPTED` | About sending a file |
+| `PHONE_ERROR` | Unexpected. Set `KARMA365_DEBUG=1` to see more |
+
+Reads, and pieces of a file, are tried again by themselves. A create or a delete is
+not, because the first try may have worked. A wrong PIN is never tried again, so a
+script cannot use up your tries.
+
+## Deleting locked items
+
+Something locked is never deleted, not even with the PIN. Neither is something under a
+lock, or something holding a locked item. Remove the lock first, then delete. Until then
+the call fails with `PARENT_LOCKED`.
+
+## Names and IDs
+
+Anything that changes something needs an ID, or a whole name that fits only one item.
+Part of a name works only in `find_id()` and `search()`, so a short word can never
+delete the wrong thing.
+
+## Methods
+
+**Connection:** `status`, `is_connected`, `unlock`, `lock`, `close`
+
+**Finding:** `find_id`, `find_minor_id`, `find_major_id`, `get_info`, `search`
+
+**Topics:** `create_major`, `create_minor`, `list_majors`, `list_minors`, `get_major`,
+`get_minor`, `change_name`, `change_minor_name`, `change_major_name`, `change_color`,
+`change_minor_color`, `change_major_color`, `change_dp`, `change_difficulty`,
+`transfer_minor_to`, `transfer_to`, `pin`, `unpin`, `star`, `unstar`, `delete`, `clean_empty`
+
+**Resources:** `add_image`, `add_video`, `add_audio`, `add_pdf`, `add_youtube`, `add_link`,
+`add_code`, `add_note`, `append_note`, `list_resources`, `view_all`, `get_resource`,
+`change_description`, `mark_done`, `unmark_done`
+
+**Tasks:** `create_task`, `list_tasks`, `get_task`, `change_priority`, `mark_done`,
+`unmark_done`, `delete`, `clear_completed_tasks`
+
+**Stats:** `get_stats`
+
+## Settings
+
+| Variable | Use |
+|---|---|
+| `KARMA365_TOKEN` | Your token |
+| `KARMA365_PHONE_URL` | The phone's address, if it is not found by itself |
+| `KARMA365_DEBUG` | Set to 1 to add the technical cause to errors. Never shows your token or PIN |

karma365-0.2.0/karma365/__init__.py

@@ -0,0 +1,56 @@
+"""KARMA 365 SDK for Python. Your data stays on your phone; this talks to it."""
+
+from .client import AsyncKarmaClient, KarmaClient
+from .errors import (
+    AmbiguousNameError,
+    AppLockedError,
+    AppUpdateNeededError,
+    ConnectionLostError,
+    FileProblemError,
+    InvalidInputError,
+    KarmaError,
+    NotFoundError,
+    NotYourPhoneError,
+    ParentLockedError,
+    PhoneError,
+    PhoneNotFoundError,
+    PhoneStorageFullError,
+    PinLockedOutError,
+    PinRequiredError,
+    PinWrongError,
+    TokenError,
+    UploadInterruptedError,
+)
+from .link import Status
+from .models import InfoResult, MajorTopic, Resource, Task, Topic, WorkspaceStats
+
+__version__ = "0.2.0"
+__all__ = [
+    "AsyncKarmaClient",
+    "KarmaClient",
+    "Status",
+    "MajorTopic",
+    "Topic",
+    "Resource",
+    "Task",
+    "WorkspaceStats",
+    "InfoResult",
+    "KarmaError",
+    "TokenError",
+    "PhoneNotFoundError",
+    "NotYourPhoneError",
+    "AppLockedError",
+    "ConnectionLostError",
+    "AppUpdateNeededError",
+    "PinRequiredError",
+    "PinWrongError",
+    "PinLockedOutError",
+    "ParentLockedError",
+    "NotFoundError",
+    "AmbiguousNameError",
+    "InvalidInputError",
+    "FileProblemError",
+    "PhoneStorageFullError",
+    "UploadInterruptedError",
+    "PhoneError",
+]

karma365-0.2.0/karma365/__main__.py

@@ -0,0 +1,76 @@
+"""`python -m karma365 status` and `python -m karma365 speedtest`."""
+
+import asyncio
+import os
+import sys
+import tempfile
+import time
+
+from .client import AsyncKarmaClient
+from .errors import KarmaError
+from .upload import cancel_file, send_file
+
+
+async def status() -> int:
+    async with AsyncKarmaClient() as karma:
+        result = await karma.status()
+    if result.connected:
+        print(f"Connected to your phone at {result.phone_url} ({result.latency_ms} ms)")
+        return 0
+    print(f"Not connected: {result.message}")
+    if result.hint:
+        print(f"What to do: {result.hint}")
+    print(f"Code: {result.reason}")
+    return 1
+
+
+async def speedtest(megabytes: int) -> int:
+    """Sends a throwaway file over the real path and measures it. Wi-Fi, the phone's
+    decrypting and its storage all count, so this is the speed you will really get."""
+    async with AsyncKarmaClient() as karma:
+        minors = await karma.list_minors()
+        if not minors:
+            print("Create a minor topic first. The test needs one, and leaves nothing in it.")
+            return 1
+        handle, path = tempfile.mkstemp(suffix=".bin", prefix="karma_speedtest_")
+        try:
+            with os.fdopen(handle, "wb") as file:
+                for _ in range(megabytes):
+                    file.write(os.urandom(1024 * 1024))
+
+            def progress(sent: int, total: int) -> None:
+                print(f"\r{sent * 100 // total}%", end="", flush=True)
+
+            started = time.perf_counter()
+            resource_id = await send_file(
+                karma._link,
+                path=path,
+                file_type="video",
+                topic_id=minors[0].id,
+                title="KARMA 365 speed test",
+                on_progress=progress,
+            )
+            seconds = time.perf_counter() - started
+            await karma.delete(resource_id)
+            print(f"\n{megabytes} MB in {seconds:.1f} s: {megabytes / seconds:.1f} MB/s")
+            return 0
+        finally:
+            os.unlink(path)
+
+
+def main() -> int:
+    command = sys.argv[1] if len(sys.argv) > 1 else "status"
+    try:
+        if command == "status":
+            return asyncio.run(status())
+        if command == "speedtest":
+            return asyncio.run(speedtest(int(sys.argv[2]) if len(sys.argv) > 2 else 100))
+    except KarmaError as error:
+        print(error)
+        return 1
+    print("Usage: python -m karma365 status\n       python -m karma365 speedtest [MB]")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())