auralogger 0.1.0__tar.gz

auralogger-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+ISC License
+
+Copyright (c) 2026, Bhanu Vardhan Reddy Nanavala
+
+Contact: nbhanuvardhanreddy@gmail.com
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

auralogger-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: auralogger
+Version: 0.1.0
+Summary: Open-Source Developer package repository for AuraLogger, a real-time logging and observability SDK and CLI for streaming, storing, searching, and filtering application logs—beautifully visualized and accessible anywhere in the world across terminal, web, and any screen.
+Author: Bhanu Vardhan Reddy Nanavala
+License-Expression: ISC
+Project-URL: Homepage, https://auralogger.com
+Project-URL: Documentation, https://auralogger.com/docs
+Keywords: auralogger,cli,logging
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: websocket-client>=1.6.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Dynamic: license-file
+
+# Auralogger for Python (SDK + CLI)
+
+ a real-time logging and observability SDK and CLI for streaming, storing, searching, and filtering application logs—beautifully visualized and accessible anywhere in the world across terminal, web, and any screen.
+
+---
+
+## Quick start
+
+Run CLI commands from the directory that contains your `.env` or `.env.local` (or wherever you export `AURALOGGER_`* in the shell or CI). The CLI loads `.env` files from the **current working directory** — `cd` into the app first.
+
+**Use a project virtualenv** (`python -m venv .venv`) so the CLI and library version match the repo you are in. Auralogger is **project-scoped** (credentials per app), not a global “install once and forget which folder you are in” tool.
+
+### 1) Install
+
+From PyPI:
+
+```bash
+pip install auralogger
+```
+
+```bash
+auralogger
+```
+
+### 2) Run `init` (credentials + server snippet)
+
+Get **private** credentials from [auralogger.com](https://auralogger.com), then run this in your app repo (where `.env` should live):
+
+```bash
+auralogger init
+```
+
+`auralogger init` walks you through anything missing, prints a **copy-paste block** for your `.env` (project token, user secret, session — each line skipped if already set), then prints a **small Python module** you can drop into your repo (for example `your_auralog_file.py`) with a ready-made `auralog(...)` helper .
+
+### 3) Sanity-check connectivity
+
+Before you sprinkle `auralog` everywhere, confirm the path works:
+
+```bash
+auralogger server-check
+```
+
+Optional: send a handful of test logs through the same path your app uses:
+
+```bash
+auralogger test-serverlog
+```
+
+If token or user secret is missing after `.env` is loaded, the CLI will prompt before running checks.
+
+### 4) Send logs from code
+
+Run `auralogger init` once and paste the printed module, or follow this shape: configure once (reads `AURALOGGER_PROJECT_TOKEN` and `AURALOGGER_USER_SECRET` from the environment), then call your helper.
+
+```python
+from your_auralog_file import auralog
+
+auralog(
+    "info",
+    "Request completed",
+    "api/orders#create",
+    {"order_id": "ord_123", "status": 201},
+)
+# expected: [info] Request completed @ api/orders#create {"order_id": "ord_123", "status": 201}
+
+auralog("warn", "Cache miss")
+# expected: [warn] Cache miss
+
+auralog("error", "Payment gateway timeout", data={"provider": "stripe"})
+# expected: [error] Payment gateway timeout {"provider": "stripe"}
+```
+
+**Important:** the logging helper reads `**os.environ` only** — it does not load `.env` files by itself. In Django, FastAPI, Celery, etc., load env in your normal startup path (or rely on your host injecting variables).
+
+### 5) Fetch logs in the terminal
+
+```bash
+auralogger get-logs -maxcount 20
+```
+
+Each run performs **one** HTTP request and prints the `logs` array from that response. Use `**-maxcount`** (capped at **100** in the CLI) and `**-skip`** to page manually across separate runs or a small script. Full filter grammar, every field, and examples are in **CLI commands (reference)** below.
+
+---
+
+## CLI commands (reference)
+
+Subcommands for the `auralogger` entrypoint, then `**get-logs`** filters (same grammar as the Node CLI). Environment variable spellings: `[user-docs/environment.md](user-docs/environment.md)`.
+
+### Invocation
+
+```bash
+auralogger <command> [arguments...]
+```
+
+Run `auralogger --help` to see all commands and options.
+
+### Commands (only `get-logs` takes extra filter tokens)
+
+
+| Command          | Arguments      | What it does                                                                                                                                                                                                                      |
+| ---------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init`           | —              | Prompts for missing `AURALOGGER_PROJECT_TOKEN` / `AURALOGGER_USER_SECRET`, prints copy-paste `.env` lines (token, user secret, session), then a **Python** server integration snippet with `sync_from_secret` and `auralog(...)`. |
+| `server-check`   | —              | One **server-side** test log over WebSocket; prompts for missing token or user secret if needed.                                                                                                                                  |
+| `test-serverlog` | —              | Calls `sync_from_secret`, sends **5** logs via `aura_log`, then closes the cached socket.                                                                                                                                         |
+| `get-logs`       | `[filters...]` | `POST` to project logs with token + user secret (env or prompt). If styles are not in env, the CLI resolves them for that run so terminal colors match the dashboard when possible.                                               |
+
+
+### `get-logs` filter grammar
+
+```text
+-<field> [--<operator>] <json-value>
+```
+
+- The token after the field name must be **valid JSON**.
+- `**maxcount`** and `**skip`**: value must be a JSON **number**.
+- **All other fields**: value must be a JSON **array**.
+
+**Paging:** one CLI invocation → one request → one page of logs. There is **no** automatic multi-page loop inside the CLI.
+
+#### Fields and operators
+
+
+| Field         | Allowed operators          | Default operator | Value shape                                                                                                                          |
+| ------------- | -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `type`        | `in`, `not-in`             | `in`             | JSON array of type strings                                                                                                           |
+| `message`     | `contains`, `not-contains` | `contains`       | JSON array of substrings                                                                                                             |
+| `location`    | `in`, `not-in`             | `in`             | JSON array of location strings                                                                                                       |
+| `time`        | `since`, `from-to`         | `since`          | JSON array (e.g. `["10m"]` for `since`; use `from-to` with a pair when supported)                                                    |
+| `order`       | `eq`                       | `eq`             | JSON array: `["newest-first"]` or `["oldest-first"]`                                                                                 |
+| `maxcount`    | `eq`                       | `eq`             | JSON number, clamped to `0..100`                                                                                                     |
+| `skip`        | `eq`                       | `eq`             | JSON number, floored, minimum `0`                                                                                                    |
+| `session`     | `eq`                       | `eq`             | JSON array of session strings. If `AURALOGGER_PROJECT_SESSION` is set and you omit `-session`, the CLI prepends this filter for you. |
+| `data.<path>` | `eq`                       | `eq`             | JSON array — filter on nested `data` using a dot path (e.g. `data.userId`)                                                           |
+
+
+If you omit `--<operator>`, the default operator for that field is used (for example `-type '["error"]'` is the same as `-type --in '["error"]'`).
+
+#### Examples
+
+```bash
+auralogger get-logs -type '["error","warn"]' -maxcount 50
+auralogger get-logs -message '["timeout"]' -skip 20 -maxcount 30
+auralogger get-logs -type --not-in '["info","debug"]' -time --since '["10m"]'
+auralogger get-logs -data.userId '["06431f39-55e2-4289-80c8-5d0340a8b66e"]'
+auralogger get-logs -order '["oldest-first"]' -maxcount 25
+```
+
+#### Common parse errors (filters)
+
+- `Expected 'get-logs'`
+- `Expected field at position N`
+- `Missing value for field '…'`
+- `Invalid JSON for field '…'`
+- `Field '…' expects a JSON array token`
+- `Field 'maxcount' expects a JSON number token` (and similarly for `skip`)
+- `Invalid op '…' for field '…'`
+- `Unknown filter field: …`
+
+---
+
+## Browser and frontends
+
+This package is for **Python on the server**. For React, Vue, Next, Vite, or any code bundled for the browser, use the `**auralogger-cli`** npm package and its **client** entry — **project token only** there, never `AURALOGGER_USER_SECRET` in frontend bundles.
+
+---
+
+## When something does not work
+
+- **Wrong directory** — Run the CLI from the folder that contains `.env`, or export variables in the shell.
+- **Logs never reach the dashboard** — Confirm `AURALOGGER_PROJECT_TOKEN` and `AURALOGGER_USER_SECRET` are set for the process (or passed explicitly in your configure step). Successful sends are quiet locally; problems may show as a one-time message on stderr.
+- `**get-logs` looks plain** — Optional style env vars are documented in `[user-docs/environment.md](user-docs/environment.md)`; the CLI can still resolve styling for a run when those are unset.
+
+---
+
+## Requirements
+
+Python **3.8+**.

auralogger-0.1.0/README.md

@@ -0,0 +1,177 @@
+# Auralogger for Python (SDK + CLI)
+
+ a real-time logging and observability SDK and CLI for streaming, storing, searching, and filtering application logs—beautifully visualized and accessible anywhere in the world across terminal, web, and any screen.
+
+---
+
+## Quick start
+
+Run CLI commands from the directory that contains your `.env` or `.env.local` (or wherever you export `AURALOGGER_`* in the shell or CI). The CLI loads `.env` files from the **current working directory** — `cd` into the app first.
+
+**Use a project virtualenv** (`python -m venv .venv`) so the CLI and library version match the repo you are in. Auralogger is **project-scoped** (credentials per app), not a global “install once and forget which folder you are in” tool.
+
+### 1) Install
+
+From PyPI:
+
+```bash
+pip install auralogger
+```
+
+```bash
+auralogger
+```
+
+### 2) Run `init` (credentials + server snippet)
+
+Get **private** credentials from [auralogger.com](https://auralogger.com), then run this in your app repo (where `.env` should live):
+
+```bash
+auralogger init
+```
+
+`auralogger init` walks you through anything missing, prints a **copy-paste block** for your `.env` (project token, user secret, session — each line skipped if already set), then prints a **small Python module** you can drop into your repo (for example `your_auralog_file.py`) with a ready-made `auralog(...)` helper .
+
+### 3) Sanity-check connectivity
+
+Before you sprinkle `auralog` everywhere, confirm the path works:
+
+```bash
+auralogger server-check
+```
+
+Optional: send a handful of test logs through the same path your app uses:
+
+```bash
+auralogger test-serverlog
+```
+
+If token or user secret is missing after `.env` is loaded, the CLI will prompt before running checks.
+
+### 4) Send logs from code
+
+Run `auralogger init` once and paste the printed module, or follow this shape: configure once (reads `AURALOGGER_PROJECT_TOKEN` and `AURALOGGER_USER_SECRET` from the environment), then call your helper.
+
+```python
+from your_auralog_file import auralog
+
+auralog(
+    "info",
+    "Request completed",
+    "api/orders#create",
+    {"order_id": "ord_123", "status": 201},
+)
+# expected: [info] Request completed @ api/orders#create {"order_id": "ord_123", "status": 201}
+
+auralog("warn", "Cache miss")
+# expected: [warn] Cache miss
+
+auralog("error", "Payment gateway timeout", data={"provider": "stripe"})
+# expected: [error] Payment gateway timeout {"provider": "stripe"}
+```
+
+**Important:** the logging helper reads `**os.environ` only** — it does not load `.env` files by itself. In Django, FastAPI, Celery, etc., load env in your normal startup path (or rely on your host injecting variables).
+
+### 5) Fetch logs in the terminal
+
+```bash
+auralogger get-logs -maxcount 20
+```
+
+Each run performs **one** HTTP request and prints the `logs` array from that response. Use `**-maxcount`** (capped at **100** in the CLI) and `**-skip`** to page manually across separate runs or a small script. Full filter grammar, every field, and examples are in **CLI commands (reference)** below.
+
+---
+
+## CLI commands (reference)
+
+Subcommands for the `auralogger` entrypoint, then `**get-logs`** filters (same grammar as the Node CLI). Environment variable spellings: `[user-docs/environment.md](user-docs/environment.md)`.
+
+### Invocation
+
+```bash
+auralogger <command> [arguments...]
+```
+
+Run `auralogger --help` to see all commands and options.
+
+### Commands (only `get-logs` takes extra filter tokens)
+
+
+| Command          | Arguments      | What it does                                                                                                                                                                                                                      |
+| ---------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init`           | —              | Prompts for missing `AURALOGGER_PROJECT_TOKEN` / `AURALOGGER_USER_SECRET`, prints copy-paste `.env` lines (token, user secret, session), then a **Python** server integration snippet with `sync_from_secret` and `auralog(...)`. |
+| `server-check`   | —              | One **server-side** test log over WebSocket; prompts for missing token or user secret if needed.                                                                                                                                  |
+| `test-serverlog` | —              | Calls `sync_from_secret`, sends **5** logs via `aura_log`, then closes the cached socket.                                                                                                                                         |
+| `get-logs`       | `[filters...]` | `POST` to project logs with token + user secret (env or prompt). If styles are not in env, the CLI resolves them for that run so terminal colors match the dashboard when possible.                                               |
+
+
+### `get-logs` filter grammar
+
+```text
+-<field> [--<operator>] <json-value>
+```
+
+- The token after the field name must be **valid JSON**.
+- `**maxcount`** and `**skip`**: value must be a JSON **number**.
+- **All other fields**: value must be a JSON **array**.
+
+**Paging:** one CLI invocation → one request → one page of logs. There is **no** automatic multi-page loop inside the CLI.
+
+#### Fields and operators
+
+
+| Field         | Allowed operators          | Default operator | Value shape                                                                                                                          |
+| ------------- | -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `type`        | `in`, `not-in`             | `in`             | JSON array of type strings                                                                                                           |
+| `message`     | `contains`, `not-contains` | `contains`       | JSON array of substrings                                                                                                             |
+| `location`    | `in`, `not-in`             | `in`             | JSON array of location strings                                                                                                       |
+| `time`        | `since`, `from-to`         | `since`          | JSON array (e.g. `["10m"]` for `since`; use `from-to` with a pair when supported)                                                    |
+| `order`       | `eq`                       | `eq`             | JSON array: `["newest-first"]` or `["oldest-first"]`                                                                                 |
+| `maxcount`    | `eq`                       | `eq`             | JSON number, clamped to `0..100`                                                                                                     |
+| `skip`        | `eq`                       | `eq`             | JSON number, floored, minimum `0`                                                                                                    |
+| `session`     | `eq`                       | `eq`             | JSON array of session strings. If `AURALOGGER_PROJECT_SESSION` is set and you omit `-session`, the CLI prepends this filter for you. |
+| `data.<path>` | `eq`                       | `eq`             | JSON array — filter on nested `data` using a dot path (e.g. `data.userId`)                                                           |
+
+
+If you omit `--<operator>`, the default operator for that field is used (for example `-type '["error"]'` is the same as `-type --in '["error"]'`).
+
+#### Examples
+
+```bash
+auralogger get-logs -type '["error","warn"]' -maxcount 50
+auralogger get-logs -message '["timeout"]' -skip 20 -maxcount 30
+auralogger get-logs -type --not-in '["info","debug"]' -time --since '["10m"]'
+auralogger get-logs -data.userId '["06431f39-55e2-4289-80c8-5d0340a8b66e"]'
+auralogger get-logs -order '["oldest-first"]' -maxcount 25
+```
+
+#### Common parse errors (filters)
+
+- `Expected 'get-logs'`
+- `Expected field at position N`
+- `Missing value for field '…'`
+- `Invalid JSON for field '…'`
+- `Field '…' expects a JSON array token`
+- `Field 'maxcount' expects a JSON number token` (and similarly for `skip`)
+- `Invalid op '…' for field '…'`
+- `Unknown filter field: …`
+
+---
+
+## Browser and frontends
+
+This package is for **Python on the server**. For React, Vue, Next, Vite, or any code bundled for the browser, use the `**auralogger-cli`** npm package and its **client** entry — **project token only** there, never `AURALOGGER_USER_SECRET` in frontend bundles.
+
+---
+
+## When something does not work
+
+- **Wrong directory** — Run the CLI from the folder that contains `.env`, or export variables in the shell.
+- **Logs never reach the dashboard** — Confirm `AURALOGGER_PROJECT_TOKEN` and `AURALOGGER_USER_SECRET` are set for the process (or passed explicitly in your configure step). Successful sends are quiet locally; problems may show as a one-time message on stderr.
+- `**get-logs` looks plain** — Optional style env vars are documented in `[user-docs/environment.md](user-docs/environment.md)`; the CLI can still resolve styling for a run when those are unset.
+
+---
+
+## Requirements
+
+Python **3.8+**.

auralogger-0.1.0/auralogger/__init__.py

@@ -0,0 +1,42 @@
+"""Public API barrel (mirrors node/src/index.ts)."""
+
+from auralogger.cli.commands.init import run_init
+from auralogger.cli.commands.server_check import run_server_check
+from auralogger.cli.commands.test_serverlog import run_test_serverlog
+from auralogger.cli.get_logs import run_get_logs
+from auralogger.cli.get_logs_filters import ApiLogFilter, normalize_and_validate_filters
+from auralogger.cli.log_styles import (
+    DEFAULT_LOG_STYLE_SPEC,
+    build_style_entries_from_api,
+    resolve_log_style_spec,
+    style_map_from_config_entries,
+)
+from auralogger.server.aura_log import auralogger, aura_log, close_aura_log_socket
+from auralogger.server.proj_auth import fetch_proj_auth_config, fetch_proj_auth_payload
+from auralogger.utils.backend_origin import build_proj_auth_url, build_project_logs_url
+from auralogger.utils.http_utils import parse_error_body
+from auralogger.utils.parser import ParsedFilter, ParsedGetLogsCommand, parse_command
+
+__all__ = [
+    "aura_log",
+    "close_aura_log_socket",
+    "auralogger",
+    "run_get_logs",
+    "normalize_and_validate_filters",
+    "ApiLogFilter",
+    "parse_error_body",
+    "run_init",
+    "run_server_check",
+    "run_test_serverlog",
+    "DEFAULT_LOG_STYLE_SPEC",
+    "build_style_entries_from_api",
+    "resolve_log_style_spec",
+    "style_map_from_config_entries",
+    "fetch_proj_auth_config",
+    "fetch_proj_auth_payload",
+    "build_proj_auth_url",
+    "build_project_logs_url",
+    "parse_command",
+    "ParsedFilter",
+    "ParsedGetLogsCommand",
+]

auralogger-0.1.0/auralogger/cli/__init__.py

@@ -0,0 +1,24 @@
+"""CLI package. Entrypoint: ``auralogger.cli.cli`` (``main``, ``print_usage``)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["main", "print_usage"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "main":
+        from auralogger.cli.cli import main
+
+        return main
+    if name == "print_usage":
+        from auralogger.cli.cli import print_usage
+
+        return print_usage
+    # Console scripts may target ``auralogger.cli:_entrypoint`` (older installs / metadata).
+    if name == "_entrypoint":
+        from auralogger.cli.cli import _entrypoint
+
+        return _entrypoint
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")