pypyconfig/doc/README.md

# Modern PyPy Configuration System

## Overview
This project provides a modern Python implementation of PyPy's configuration system. It features a flexible, type-safe configuration management system with support for:
- Hierarchical configuration structures
- Type validation for configuration values
- Dependency management between options
- Command-line interface generation
- Configuration suggestions and requirements

## Project Structure
```
modern_pypy/
├── config/               # Configuration system core
│   ├── __init__.py
│   ├── config.py         # Main configuration classes
│   ├── pairtype.py       # Metaclass utilities
│   ├── parse.py          # Configuration parsing
│   ├── support.py         # Support utilities
│   ├── translationoption.py  # Translation options
│   └── test/             # Unit tests
├── pypyconfig/           # PyPy-specific configuration
│   ├── __init__.py
│   ├── makerestdoc.py    # Documentation generator
│   ├── pypyoption.py     # PyPy option definitions
│   └── test/             # Unit tests
├── tests/                # Comprehensive test suite
└── doc/                  # Documentation
    └── README.md         # This file
```

## Key Features

### Configuration Classes
```python
from config.config import Config, OptionDescription, BoolOption

# Define configuration structure
descr = OptionDescription("app", "Application Configuration", [
    BoolOption("debug", "Enable debug mode", default=False),
    IntOption("port", "Server port", default=8000)
])

# Create configuration instance
config = Config(descr)
config.debug = True
print(config.debug)  # Output: True
```

### Option Types
- `BoolOption`: Boolean values with automatic negation flags
- `IntOption`: Integer values with validation
- `FloatOption`: Floating-point numbers
- `StrOption`: String values
- `ChoiceOption`: Enumerated values with dependencies
- `ArbitraryOption`: Any Python object

### Command-Line Interface
```python
from config.config import to_optparse

# Generate command-line parser
parser = to_optparse(config)
parser.parse_args()  # Handles --debug, --no-debug, --port, etc.
```

### Advanced Features
- **Dependencies**: Options can require or suggest other options
- **Validation**: Type and value validation for all options
- **Configuration Groups**: Hierarchical organization of options
- **Freezing**: Prevent modification of configuration after setup

## Installation
```bash
git clone https://github.com/your-repo/modern_pypy.git
cd modern_pypy
pip install -e .
```

## Usage Examples

### Basic Configuration
```python
from config.config import Config, OptionDescription, StrOption

descr = OptionDescription("db", "Database Configuration", [
    StrOption("host", "Database host", default="localhost"),
    IntOption("port", "Database port", default=5432)
])

db_config = Config(descr)
db_config.host = "db.example.com"
```

### Option Dependencies
```python
descr = OptionDescription("features", "Feature Flags", [
    BoolOption("analytics", "Enable analytics", default=False,
               requires=[("logging.level", "debug")]),
    ChoiceOption("logging.level", "Log level", 
                 values=["debug", "info", "warning"],
                 default="info")
])

features = Config(descr)
features.analytics = True  # Automatically sets logging.level to "debug"
```

## Contributing
Contributions are welcome! Please follow these steps:
1. Fork the repository
2. Create a new branch (`git checkout -b feature/your-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin feature/your-feature`)
5. Open a pull request

## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.