python-mod 1.0.0

A macro library for including a Python module in Rust. At this point, very imcomplete.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Rust procedural macro library called `python-mod` that enables embedding Python code (specifically Rython, a limited subset of Python) directly into Rust projects. The library provides macros that compile Python modules to Rust at compile time.

## Architecture

- **Core Library**: `src/lib.rs` - Contains the main procedural macros `python_module!` and `python_module_nostd!`
- **Module Loading**: Python modules are loaded from either `src/{module_name}.py` or `src/{module_name}/__init__.py`
- **Python AST Processing**: Uses the `python-ast` crate to parse Python code and generate Rust TokenStreams
- **Compilation**: The macro generates Rust modules at compile time that can be used like native Rust modules

## Key Dependencies

- `python-ast`: Core dependency for parsing Python and generating Rust code
- `quote`: For Rust code generation and token manipulation
- `proc-macro2`: For advanced procedural macro functionality
- `proc-macro-error`: For better error handling in macros
- `path_macro`: For path manipulation utilities

## Development Commands

### Build
```bash
cargo build        # Standard build
cargo check        # Fast compilation check without artifacts
```

### Testing
```bash
cargo test                     # Run all tests (23 tests total)
cargo test --test lib_tests    # Run core library tests
cargo test --test documentation_tests  # Run documentation validation tests
cargo test --test edge_case_tests      # Run edge case and boundary tests
cargo test -- --nocapture     # Run tests with output
```

#### Test Structure
- **lib_tests.rs**: Core functionality, file operations, path handling
- **documentation_tests.rs**: Example validation and syntax verification  
- **edge_case_tests.rs**: Boundary conditions and error scenarios
- **Test Python modules**: Located in `src/` for testing different module patterns

### Common Issues
- Uses nightly Rust features (`#![feature(proc_macro_span)]`)
- Requires nightly toolchain for development
- Runtime testing is limited due to missing `stdpython` dependency in the ecosystem
- Full integration tests require the broader Rython/PyO3 runtime environment

## Macro Usage

The library exports two main macros:

1. `python_module!(module_name)` - Imports Python module with standard library
2. `python_module_nostd!(module_name)` - Imports Python module without standard library

Python modules should be placed in:
- `src/{module_name}.py` for single-file modules
- `src/{module_name}/__init__.py` for package modules

## Code Generation Flow

1. Macro receives module name and optional Rust preamble code
2. `load_module()` function locates and reads the Python file
3. `python-ast` parses Python code into AST
4. AST is converted to Rust TokenStream via `to_rust()`
5. Generated code is wrapped in a Rust module declaration

## Documentation

- **README.md**: Comprehensive user documentation with examples, API reference, and usage patterns
- **CLAUDE.md**: Development guidance for Claude Code instances
- **tests/README.md**: Test suite documentation and structure
- All major functionality is documented with practical examples

## Notes for Future Development

- The project is marked as "very incomplete" in the description
- Rython is described as a "very limited subset of Python"
- The library is designed to grow as Rython capabilities expand
- Error handling uses the `proc-macro-error` crate for better user experience
- Comprehensive test suite (23+ tests) ensures stability during development
- Well-documented API with multiple usage examples in README