oscilo 1.0.0__tar.gz

oscilo-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,61 @@
+name: Bug Report
+description: File a report to help us identify and fix a bug.
+title: "[BUG]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+
+  - type: textarea
+    id: description
+    attributes:
+      label: "Description"
+      placeholder: "A clear and concise description of what the bug is."
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: "Steps to Reproduce"
+      placeholder: |
+        1. Go to '...'
+        2. Click on '...'
+        3. Scroll down to '...'
+        4. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: "Expected Behavior"
+      placeholder: "A clear and concise description of what you expected to happen."
+    validations:
+      required: true
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: "Screenshots / Visuals"
+      placeholder: "Drag and drop screenshots or videos here to help explain your problem."
+    validations:
+      required: false
+
+  - type: input
+    id: environment
+    attributes:
+      label: "Environment"
+      placeholder: "e.g. OS: macOS, Browser: Chrome 120, Version: v1.2.3"
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: "Additional Context"
+      placeholder: "Add any other context, error logs, or thoughts here."
+    validations:
+      required: false

oscilo-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,49 @@
+name: Feature Request
+description: Suggest an idea or a new feature for this project.
+title: "[FEATURE]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have a great idea for this project? Tell us all about it!
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: "Problem Statement"
+      placeholder: "Is your feature request related to a problem? Please describe. (e.g., I'm always frustrated when...)"
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: "Proposed Solution"
+      placeholder: "A clear and concise description of what you want to happen and how it should work."
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: "Alternative Solutions"
+      placeholder: "A clear and concise description of any alternative solutions or features you've considered."
+    validations:
+      required: false
+
+  - type: textarea
+    id: mockups
+    attributes:
+      label: "Screenshots / Mockups"
+      placeholder: "Drag and drop visual examples, mockups, or diagrams to explain the request."
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: "Additional Context"
+      placeholder: "Add any other context or thoughts about the feature request here."
+    validations:
+      required: false

oscilo-1.0.0/.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Overview
+<!-- Provide a brief description of the overall changes in this PR. -->
+- 
+
+## Key Changes
+<!-- List the core updates and code modifications made in this PR. -->
+- [ ] 
+- [ ] 
+
+## Issue Link
+<!-- Link any related issues below. e.g., Closes #12 -->
+- Closes #
+
+## Screenshots / Videos (Optional)
+<!-- Attach any visual evidence, mockups, or demos if there are UI/UX changes. -->
+
+---
+
+## Checklist
+- [ ] My code follows the coding style and guidelines of this project.
+- [ ] I have performed a self-review of my own code.
+- [ ] I have verified and tested the changes successfully.
+- [ ] I have removed unnecessary debugging logs (e.g., console.log, print) and comments.

oscilo-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,94 @@
+name: Publish oscilo to PyPI
+on:
+  release:
+    types: [published]
+
+jobs:
+  # 1. Build the sdist first so it carries the setuptools-scm resolved version.
+  #    Wheels are then built from this sdist, so the C-extension build never needs
+  #    git access inside the cibuildwheel containers.
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools-scm needs full history + tags to resolve the version
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - name: Upload sdist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  # 2. Build the C-extension wheels from the sdist produced above. The sdist
+  #    already embeds the resolved version (PKG-INFO + _version.py), so no git
+  #    metadata is required inside the build containers.
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    needs: [build_sdist]
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+      - name: Set up QEMU
+        if: matrix.os == 'ubuntu-latest'
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: all
+
+      - name: Download sdist
+        uses: actions/download-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist
+
+      - name: Locate sdist
+        id: sdist
+        shell: bash
+        run: echo "path=$(ls dist/*.tar.gz)" >> "$GITHUB_OUTPUT"
+
+      - name: Build wheels via cibuildwheel
+        uses: pypa/cibuildwheel@v2.22.0
+        with:
+          package-dir: ${{ steps.sdist.outputs.path }}
+        env:
+          CIBW_BUILD: "cp311-* cp312-* cp313-*"
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux2014
+          CIBW_MANYLINUX_AARCH64_IMAGE: manylinux2014
+
+      - name: Upload wheels artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl
+
+  upload_pypi:
+    name: Upload to PyPI
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: release
+      url: https://pypi.org/p/oscilo
+
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          merge-multiple: true
+          path: dist
+
+      - name: Check dist
+        run: pipx run twine check dist/*
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

oscilo-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,44 @@
+name: Run Tests
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+    branches: [ develop, master ]
+
+jobs:
+  check-pr-checklist:
+    name: Verify PR Checklist
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check all checklist items are completed
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const body = context.payload.pull_request.body || '';
+            const unchecked = (body.match(/^- \[ \]/gm) || []).length;
+            if (unchecked > 0) {
+              core.setFailed(`${unchecked} checklist item(s) unchecked. Complete all items before merging.`);
+            }
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools-scm needs full history + tags to resolve the version
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with C extension
+        run: pip install -e .
+
+      - name: Run tests
+        run: python tests/test.py

oscilo-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+*.jsonl
+
+.vscode/
+
+build/
+
+*.pyd
+
+oscilo.egg-info/
+
+__pycache__/
+
+# setuptools-scm generated version file
+src/oscilo/_version.py

oscilo-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sdkurjnk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oscilo-1.0.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: oscilo
+Version: 1.0.0
+Summary: Zero-invasive Python variable-change tracker powered by a C-extension trace engine with automatic scope resolution and JSONL history output
+Author-email: sdkurjnk <sdkurjnk@naver.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sdkurjnk/oscilo/tree/master
+Keywords: logging,monitoring,c-extension
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# oscilo
+
+Zero-invasive variable-change tracker for Python. Register a variable once and `oscilo` records every change it undergoes — without touching your code.
+
+[![PyPI version](https://img.shields.io/pypi/v/oscilo)](https://pypi.org/project/oscilo/)
+[![Python](https://img.shields.io/pypi/pyversions/oscilo)](https://pypi.org/project/oscilo/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+**English** | [한국어](./README.ko.md)
+
+`oscilo` observes program execution in the background and captures how a variable evolves over time — reassignments, in-place mutations, and deletions — then writes the full history to a JSON Lines file when the program exits. The value comparison that runs on every line is delegated to a small C extension to keep the runtime overhead low.
+
+## Contents
+
+- [Motivation](#motivation)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Output format](#output-format)
+- [How it works](#how-it-works)
+- [Project layout](#project-layout)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Motivation
+
+Inspecting variable state during debugging usually means scattering `print` calls through the code:
+
+```python
+def solve(data):
+    result = []
+    for x in data:
+        result.append(x * 2)
+        print("result:", result)   # temporary, easy to forget to remove
+    return result
+```
+
+This clutters the source, is easy to leave behind, and does not scale to hot loops. Interactive debuggers avoid the clutter but interrupt execution, which is impractical when a loop runs thousands of times.
+
+`oscilo` takes a different approach: register a variable by name once, and its history is collected automatically.
+
+```python
+import oscilo
+
+def solve(data):
+    result = []
+    oscilo.register("result")   # every change to `result` from here on is recorded
+    for x in data:
+        result.append(x * 2)
+    return result
+```
+
+## Installation
+
+```bash
+pip install oscilo
+```
+
+`oscilo` ships a C extension. A prebuilt wheel is used when available; otherwise the extension is compiled locally, which requires a C compiler.
+
+<details>
+<summary>Building from source</summary>
+
+```bash
+pip install -e .                        # editable install (recommended for development)
+pip install .                           # standard install
+python setup.py build_ext --inplace     # build the C extension only
+```
+</details>
+
+**Requirements**
+
+- Python 3.11+
+- A C compiler (GCC / Clang / MSVC) when building from source
+
+## Quick start
+
+The public API is a single function, `oscilo.register()`, which takes the variable name as a string.
+
+```python
+import oscilo
+
+def run():
+    target = [100, 200]
+    oscilo.register("target")   # recorded as an "init" event
+
+    target.append(300)          # updated (in-place mutation)
+    target = "reassigned"       # updated (reassignment)
+    del target                  # deleted
+
+run()
+# On exit, the history is written to oscilo.jsonl
+```
+
+Calling `oscilo.register()` multiple times adds each variable to the same monitor, and all histories are merged into a single output file:
+
+```python
+import oscilo
+
+def run():
+    score = 10
+    items = ["potion", "shield"]
+
+    oscilo.register("score")
+    oscilo.register("items")
+
+    score += 55
+    items.append("sword")
+
+run()
+```
+
+Notes:
+
+- `register()` returns `None`; registration is its only effect.
+- Importing `oscilo` has no side effects — tracing starts only when `register()` is called.
+- If no change is ever recorded, no file is written.
+
+## Output format
+
+History is written as [JSON Lines](https://jsonlines.org/) (`oscilo.jsonl` by default). Each line represents a single change:
+
+```json
+{"name": "target", "var_id": 1, "data": [100, 200], "event": "init", "domain": "LOCAL", "line": 4, "func": "run", "call_id": 1, "parent_call_id": null, "call_depth": 1}
+{"name": "target", "var_id": 1, "data": [100, 200, 300], "event": "updated", "domain": "LOCAL", "line": 6, "func": "run", "call_id": 1, "parent_call_id": null, "call_depth": 1}
+{"name": "target", "var_id": 1, "data": "reassigned", "event": "updated", "domain": "LOCAL", "line": 7, "func": "run", "call_id": 1, "parent_call_id": null, "call_depth": 1}
+{"name": "target", "var_id": 1, "data": null, "event": "deleted", "domain": "LOCAL", "line": 8, "func": "run", "call_id": 1, "parent_call_id": null, "call_depth": 1}
+```
+
+| Field | Description |
+|-------|-------------|
+| `name` | The tracked variable name |
+| `var_id` | Identity of the tracked binding; records sharing a `var_id` refer to the same variable (matches `call_id` for locals; stays stable across frames for globals and closure variables) |
+| `data` | The value at the time of the change (`null` for `deleted`) |
+| `event` | `init`, `updated`, or `deleted` |
+| `domain` | Variable scope: `LOCAL` or `GLOBAL` (a closure/enclosing variable is reported as `LOCAL` from its owning frame's point of view and is identified by `var_id`) |
+| `line` | Source line where the change was detected |
+| `func` | Function in which the change occurred (`<module>` at module level) |
+| `call_id` | Unique id of the function call (frame) where the change occurred |
+| `parent_call_id` | `call_id` of the calling frame (`null` for a root call) |
+| `call_depth` | Call depth relative to the registration frame (root = `1`) |
+
+The `call_id` / `parent_call_id` / `call_depth` fields let a consumer reconstruct the call tree — i.e. which call each change happened in, and how the calls nest.
+
+The line-delimited format streams and parses efficiently for large histories.
+
+## How it works
+
+`oscilo` watches execution in Python and delegates value comparison to a C extension.
+
+1. The first `register()` call lazily creates a single monitor and installs a trace hook via `sys.settrace`.
+2. On each executed line, the C engine (`oscilo_engine`) determines whether a tracked variable changed, using a short-circuiting sequence:
+
+   ```
+   Variable no longer in scope?      → deleted
+   Reference identity changed?       → updated   (reassignment)
+   Immutable type (int/str/...)?     → unchanged (skip comparison)
+   Container size changed?           → updated
+   Otherwise, compare values         → updated / unchanged
+   ```
+
+3. When the process exits, an `atexit` hook flushes the in-memory history to disk in a single write. Records are buffered rather than written per change to avoid I/O overhead.
+
+Unchanged values produce no record, and immutable values are skipped entirely when their reference is unchanged — both are central to keeping the per-line cost low.
+
+## Project layout
+
+```
+src/oscilo/
+├── __init__.py          # public API (register) and single-instance management
+├── _core.py             # monitor implementation and atexit save logic
+├── CallContext.py       # lazy call-context tracking (call_id / parent_call_id / call_depth)
+├── FileWriter.py        # JSONL output
+├── HistoryBuffer.py     # in-memory history buffer
+├── ScopeResolver.py     # LEGB scope resolution (local/enclosing/global/builtin)
+├── TraceDispatcher.py   # sys.settrace event handling
+├── VariableTracker.py   # per-variable change detection and value snapshots
+└── oscilo_engine.c      # C extension for value comparison
+```
+
+## Testing
+
+```bash
+python tests/test.py
+```
+
+Tests are discovered from `tests/` (`test_*.py`). Component tests run in-process, while the end-to-end scenarios (registration and process lifecycle) spawn a separate interpreter process, since `atexit`-driven saving and `sys.settrace` behavior can only be verified across a full process lifetime.
+
+## Contributing
+
+Contributions are welcome — bug reports, feature ideas, and pull requests alike.
+
+- Open an issue using the bug report or feature request template.
+- Follow the checklist in `.github/pull_request_template.md` when submitting a PR.
+- Include tests with new features or fixes where practical.
+
+## License
+
+[MIT](./LICENSE) © 2026 [sdkurjnk](https://github.com/sdkurjnk)