struct-frame 0.0.25__tar.gz → 0.0.27__tar.gz

struct_frame-0.0.27/.github/copilot-instructions.md

@@ -0,0 +1,126 @@
+# struct-frame Repository
+struct-frame is a multi-language code generation framework that takes Protocol Buffer (.proto) files and generates serialization/deserialization code for C, TypeScript, and Python. It provides framing and parsing utilities for structured message communication.
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Prerequisites and Dependencies
+- Install Python dependencies:
+  - `python3 -m pip install proto-schema-parser structured-classes`
+- Install Node.js dependencies:
+  - `npm install` -- takes ~1 second
+- GCC is available for C compilation
+
+### Core Build Commands
+- **NEVER CANCEL**: All commands below complete in under 2 seconds unless specified
+- Generate code from proto files:
+  - `PYTHONPATH=src python3 src/main.py [proto_file] --build_c --build_ts --build_py --c_path gen/c --ts_path gen/ts --py_path gen/py`
+  - Takes ~0.1 seconds to complete
+- Compile TypeScript:
+  - `npx tsc --project tsconfig.json` -- takes ~2 seconds
+- Python module works via:
+  - `PYTHONPATH=src python3 -c "import struct_frame; struct_frame.main()"`
+
+### Known Working Components
+- **Python code generator**: FULLY FUNCTIONAL
+  - Reads .proto files and generates code for all three target languages
+  - CLI interface works correctly
+  - Code generation completes successfully
+  - Generated Python files can be imported and used
+- **TypeScript compilation**: PARTIALLY FUNCTIONAL
+  - TypeScript files compile without errors
+  - Generated code has runtime issues (missing method definitions in enum handling)
+  - Use with caution for actual execution
+- **C code generation**: GENERATES BUT HAS ISSUES
+  - Headers are generated but have compilation errors
+  - Conflicts between different API versions in generated macros
+  - Example code in examples/main.c is incompatible with generated headers
+
+### Running Tests and Validation
+- **No formal test suite exists** in the repository
+- Manual validation is required for all components (Python, TypeScript, and C)
+- Test Python code generation by running the main command and verifying output
+
+### Build Times and Timeouts
+- Python dependencies install: ~30 seconds (may fail due to network timeouts)
+- Code generation: ~0.1 seconds - NEVER CANCEL
+- npm install: ~1 second - NEVER CANCEL  
+- TypeScript compilation: ~2 seconds - NEVER CANCEL
+- All operations are very fast, no long builds
+
+## Validation Scenarios
+- **ALWAYS test Python code generation** after making changes to the core generator
+- **Test with the provided examples/myl_vehicle.proto file** as the reference example
+- **Validate that generated Python files import successfully**
+- **DO NOT rely on TypeScript or C compilation** for validation due to known runtime/compilation issues
+- Manually validate core functionality by generating code and checking output
+
+## Common Issues and Workarounds
+- **Python package build fails**: Network timeouts are common - use `PYTHONPATH=src` approach instead
+- **TypeScript runtime errors**: Generated code calls undefined methods like `.myl_vehicle_type()` - this is a code generation bug
+- **C compilation fails**: Generated headers have macro conflicts and syntax errors (C99 vs C++ style initialization)
+- **Example code is outdated**: examples/main.c and examples/index.ts examples don't match current generated code APIs
+
+## Repository Structure
+```
+/
+├── src/                      # Source code directory
+│   ├── main.py              # CLI entry point
+│   └── struct_frame/        # Python code generator (WORKING)
+│       ├── generate.py      # Main generation logic
+│       ├── c_gen.py         # C code generator  
+│       ├── ts_gen.py        # TypeScript code generator
+│       ├── py_gen.py        # Python code generator
+│       └── boilerplate/     # Template files for each language
+├── examples/                # Example files directory
+│   ├── myl_vehicle.proto    # Example proto file
+│   ├── index.ts             # TypeScript example (INCOMPATIBLE with generated code)
+│   └── main.c               # C example (INCOMPATIBLE with generated code)
+├── package.json             # Node.js dependencies
+├── tsconfig.json            # TypeScript configuration
+├── pyproject.toml           # Python package configuration
+└── gen/                     # Generated code output directory
+```
+
+## Critical Warnings
+- **DO NOT expect C or TypeScript examples to compile/run** - they are incompatible with current generator output
+- **DO NOT attempt Python package builds** - they fail due to network issues, use direct module execution
+- **ALWAYS use PYTHONPATH=src** when running Python components
+- **Generated code has API compatibility issues** between languages and with examples
+
+## Quick Start for New Developers
+1. Install dependencies: `python3 -m pip install proto-schema-parser structured-classes && npm install`
+2. Generate code: `PYTHONPATH=src python3 src/main.py examples/myl_vehicle.proto --build_py --py_path gen/py`  
+3. Validate: Check that generated files are created in gen/py directory
+4. For development: Always test Python generation, ignore C/TypeScript runtime errors
+
+## Common Tasks Reference
+
+### Repository Root Contents
+```
+.clang-format       # C formatting config
+.github/            # GitHub configuration including copilot-instructions.md
+.gitignore         # Git ignore rules
+DEVGUIDE.md        # Basic development guide (minimal)
+LICENSE            # MIT license
+README.md          # Basic setup instructions (minimal)
+TODO               # Single item: "Check if message id is repeated"
+examples/          # Example files directory
+├── index.ts       # TypeScript example (broken)
+├── main.c         # C example (broken) 
+└── myl_vehicle.proto  # Proto definition example
+package.json       # Node.js config
+package-lock.json  # Node.js lockfile
+pyproject.toml     # Python package config
+src/               # Source code directory
+tsconfig.json      # TypeScript config
+```
+
+### Example proto file content (examples/myl_vehicle.proto)
+Contains definitions for vehicle communication messages including position, pose, heartbeat with message IDs and field types.
+
+### Working Python Generation Command
+```bash
+PYTHONPATH=src python3 src/main.py examples/myl_vehicle.proto --build_py --py_path gen/py
+```

struct_frame-0.0.27/.gitignore

@@ -0,0 +1,12 @@
+ts_out
+node_modules
+.vscode
+main.exe
+dist
+generated/
+__pycache__/
+gen/
+# Generated output directories in root (legacy)
+c/
+py/
+ts/

struct_frame-0.0.27/DEVGUIDE.md

@@ -0,0 +1,37 @@
+
+### Installing
+``` py -m pip install --upgrade build twine```
+
+### Building
+Update version in pyproject.toml if needed
+```py -m build```
+
+### Uploading
+```py -m twine upload dist/*```
+
+```py -m build; py -m twine upload dist/*```
+
+
+### Running Locally
+Install dependencies
+```py -m pip install proto-schema-parser```
+
+Run module with example
+```python src/main.py examples/myl_vehicle.proto --build_c --build_ts --build_py --build_gql```
+
+The generated files will be placed in the `generated/` directory with subdirectories for each language (`c/`, `ts/`, `py/`, `gql/`). GraphQL schemas are written with a `.graphql` extension.
+
+### Testing Examples
+After generating code, you can test the examples:
+
+TypeScript:
+```bash
+npx tsc examples/index.ts --outDir generated/
+node generated/examples/index.js
+```
+
+C:
+```bash
+gcc examples/main.c -I generated/c -o main
+./main
+```

struct_frame-0.0.27/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: struct-frame
+Version: 0.0.27
+Summary: A framework for serializing data with headers
+Project-URL: Homepage, https://github.com/mylonics/struct-frame
+Project-URL: Issues, https://github.com/mylonics/struct-frame/issues
+Author-email: Rijesh Augustine <rijesh@mylonics.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: proto-schema-parser>=1.4.5
+Requires-Dist: structured-classes>=3.1.0
+Description-Content-Type: text/markdown
+
+
+# Struct Frame
+
+A framework for serializing data with headers
+
+## Quick Start
+
+### Python Usage
+```bash
+# Install dependencies
+pip install -e .
+
+# Generate code from proto file
+python src/main.py examples/myl_vehicle.proto --build_c --build_ts --build_py
+
+# Generated files will be in the generated/ directory
+```
+
+### TypeScript Example
+```bash
+# Install TypeScript dependencies
+npm i -D typescript typed-struct @types/node
+
+# Generate TypeScript code first
+python src/main.py examples/myl_vehicle.proto --build_ts
+
+# Compile and run the example
+npx tsc examples/index.ts --outDir generated/
+node generated/examples/index.js
+```
+
+### C Example
+```bash
+# Generate C code first  
+python src/main.py examples/myl_vehicle.proto --build_c
+
+# Compile the C example
+gcc examples/main.c -I generated/c -o main
+./main
+```
+
+## Project Structure
+
+- `src/` - Source code for the struct-frame library
+- `examples/` - Example usage and demo files
+- `generated/` - Generated output files (ignored by git)

struct_frame-0.0.27/README.md

@@ -0,0 +1,46 @@
+
+# Struct Frame
+
+A framework for serializing data with headers
+
+## Quick Start
+
+### Python Usage
+```bash
+# Install dependencies
+pip install -e .
+
+# Generate code from proto file
+python src/main.py examples/myl_vehicle.proto --build_c --build_ts --build_py
+
+# Generated files will be in the generated/ directory
+```
+
+### TypeScript Example
+```bash
+# Install TypeScript dependencies
+npm i -D typescript typed-struct @types/node
+
+# Generate TypeScript code first
+python src/main.py examples/myl_vehicle.proto --build_ts
+
+# Compile and run the example
+npx tsc examples/index.ts --outDir generated/
+node generated/examples/index.js
+```
+
+### C Example
+```bash
+# Generate C code first  
+python src/main.py examples/myl_vehicle.proto --build_c
+
+# Compile the C example
+gcc examples/main.c -I generated/c -o main
+./main
+```
+
+## Project Structure
+
+- `src/` - Source code for the struct-frame library
+- `examples/` - Example usage and demo files
+- `generated/` - Generated output files (ignored by git)

{struct_frame-0.0.25 → struct_frame-0.0.27/examples}/index.ts

@@ -1,6 +1,6 @@
-import * as mv from './gen/ts/myl_vehicle.sf';
-import { parse_char, parse_buffer } from './gen/ts/struct_frame_parser';
-import { struct_frame_buffer, buffer_parser_result_t, } from './gen/ts/struct_frame_types';
+import * as mv from '../generated/ts/myl_vehicle.sf';
+import { parse_char, parse_buffer } from '../generated/ts/struct_frame_parser';
+import { struct_frame_buffer, buffer_parser_result_t, } from '../generated/ts/struct_frame_types';
 import { type ExtractType } from 'typed-struct';
 
 let tx_buffer = new struct_frame_buffer(256)

{struct_frame-0.0.25 → struct_frame-0.0.27/examples}/main.c

@@ -1,7 +1,7 @@
 #include <stdio.h>
 
-#include "c/struct_frame_gen.h"
-#include "c/struct_frame_parser.h"
+#include "../generated/c/struct_frame_gen.h"
+#include "../generated/c/struct_frame_parser.h"
 
 // CREATE_DEFAULT_STRUCT_BUFFER(tx_buffer, 256);
 uint8_t tx_buffer_buffer[256];