| Name | pysmartyaml JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Extended YAML format with custom directives for imports, environment variables, and more |
| upload_time | 2025-08-15 21:50:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
yaml
configuration
import
environment
template
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# SmartYAML
Extended YAML format with custom directives for imports, environment variables, conditional processing, and more. SmartYAML maintains full compatibility with standard YAML while providing powerful additional features.
## Features
SmartYAML extends standard YAML with powerful custom directives:
### Core Directives
- **!import(filename)** - Import content from text files
- **!import_yaml(filename)** - Import and merge YAML files
- **!env(VAR_NAME, default?)** - Access environment variables with optional defaults
- **!expand(text)** - Variable substitution using `{{key}}` syntax
### Template System
- **!template(template_name)** - Load external templates from template directory
- **__template** - Inline template inheritance and merging
- **__vars** - Variable definitions with inheritance support
### Conditional Processing
- **!include_if(condition, filename)** - Conditional file inclusion based on environment variables
- **!include_yaml_if(condition, filename)** - Conditional YAML inclusion
### Encoding
- **!base64(data)** - Base64 encoding of strings
- **!base64_decode(data)** - Base64 decoding of strings
### Metadata
- **Metadata fields** - `__field` prefixed fields for annotations (automatically removed)
## Installation
### From PyPI
```bash
pip install smartyaml
```
### From GitHub Repository
```bash
# Install latest from main branch
pip install git+https://github.com/apuigsech/smartyaml.git
# Install specific version/tag
pip install git+https://github.com/apuigsech/smartyaml.git@v0.1.0
# Clone and install for development
git clone https://github.com/apuigsech/smartyaml.git
cd smartyaml
pip install -e ".[dev]"
```
## Quick Start
```python
import smartyaml
# Basic loading
data = smartyaml.load("config.yaml")
# Load with template support
data = smartyaml.load("config.yaml", template_path="templates")
# Load with variables and full options
variables = {"environment": "production", "version": "2.0.0"}
data = smartyaml.load('config.yaml',
base_path='/custom/path',
template_path='/templates',
variables=variables,
max_file_size=5*1024*1024)
# Load from string content
yaml_content = """
__vars:
app: "MyApp"
database: !import_yaml db.yaml
password: !env(DB_PASSWORD)
name: !expand "{{app}}_database"
"""
data = smartyaml.loads(yaml_content)
```
## Real-World Example: AI Agent Configuration
```yaml
# agent.yaml - Customer support agent configuration
__vars:
agent_name: "ACME Customer Support"
company_name: "ACME Corp"
environment: !env(ENVIRONMENT, "development")
# Inherit from base agent template
__template:
<<: !template(agents/customer_support)
# Agent-specific customization
config:
name: !expand "{{agent_name}}"
welcome_message: !expand "Hello! Welcome to {{company_name}} support."
# Environment-specific features
debug_tools: !include_yaml_if(DEBUG, tools/debug.yaml)
production_monitoring: !include_yaml_if(PRODUCTION, monitoring/prod.yaml)
# Load external resources
knowledge_base: !import(knowledge/company_info.txt)
faq_data: !import_yaml(data/faq.yaml)
```
```yaml
# templates/agents/customer_support.yaml - Reusable template
__vars:
model: "gpt-4"
temperature: 0.7
max_tokens: 1000
voice_id: "default"
config:
llm:
model: !expand "{{model}}"
temperature: !expand "{{temperature}}"
max_tokens: !expand "{{max_tokens}}"
voice:
provider: "elevenlabs"
voice_id: !expand "{{voice_id}}"
conversation:
timeout: 300
max_turns: 50
```
**Loading:**
```python
import smartyaml
# Load with template inheritance
data = smartyaml.load("agent.yaml", template_path="templates")
# Override with production settings
prod_vars = {"environment": "production", "model": "gpt-4-turbo"}
data = smartyaml.load("agent.yaml",
template_path="templates",
variables=prod_vars)
```
**Result:** Deep merging with proper variable precedence - agent variables override template variables.
## Directive Reference
### 1. Text File Import: `!import(filename)`
Loads the entire content of a file as a string.
```yaml
# config.yaml
html_template: !import(template.html)
sql_query: !import(queries/select_users.sql)
```
### 2. YAML Import with Merge: `!import_yaml(filename)`
Loads YAML content from a file with optional local overrides.
```yaml
# Simple import
database: !import_yaml(database.yaml)
# Import with local overrides
database: !import_yaml(database.yaml)
password: production_pass # Overrides imported password
```
### 3. Environment Variables: `!env(VAR_NAME, default?)`
Reads values from environment variables with optional defaults.
```yaml
database_url: !env(DATABASE_URL, "postgresql://localhost/myapp")
debug_mode: !env(DEBUG, false)
port: !env(PORT, 8080)
```
### 4. Conditional Text Import: `!include_if(condition, filename)`
Includes a text file only if an environment variable condition is truthy.
```yaml
debug_config: !include_if(DEBUG_MODE, debug_settings.txt)
development_notes: !include_if(DEV_ENV, notes.md)
```
**Truthy values:** `1`, `true`, `yes`, `on`, `enabled` (case-insensitive)
### 5. Conditional YAML Import: `!include_yaml_if(condition, filename)`
Includes a YAML file only if an environment variable condition is truthy.
```yaml
debug: !include_yaml_if(DEBUG, debug.yaml)
database: !include_yaml_if(PRODUCTION, prod_db.yaml)
```
### 6. Template System
#### External Templates: `!template(template_name)`
Loads templates from a centralized template directory.
```yaml
# Loads from templates/postgres.yaml
database: !template(postgres)
# Loads from templates/redis.yaml
cache: !template(redis)
```
**Usage:** Pass `template_path` parameter to `smartyaml.load()`
#### Inline Templates: `__template`
Inherit from external templates with local customization.
```yaml
# agent.yaml
__vars:
agent_name: "Customer Support"
company: "ACME Corp"
__template:
<<: !template(agents/base)
# Document-level overrides
custom_prompt: !expand "You are {{agent_name}} for {{company}}"
```
```yaml
# templates/agents/base.yaml
__vars:
model: "gpt-4"
temperature: 0.7
config:
llm: !expand "{{model}}"
temperature: !expand "{{temperature}}"
prompt: !expand "{{custom_prompt}}"
```
**Features:**
- **Variable Inheritance**: Template variables available in main document
- **Override Support**: Document variables override template variables
- **Merge Semantics**: Uses YAML merge key (`<<:`) for composition
### 7. Base64 Encoding/Decoding
Encode strings to base64 or decode base64 strings.
```yaml
# Encoding
secret: !base64(my_secret_password) # -> bXlfc2VjcmV0X3Bhc3N3b3Jk
# Decoding
password: !base64_decode(bXlfc2VjcmV0X3Bhc3N3b3Jk) # -> my_secret_password
```
### 8. Variable Substitution: `!expand(text)`
Replaces `{{key}}` patterns with variable values from function parameters or `__vars` metadata.
```yaml
# Using __vars metadata
__vars:
app_name: "MyApp"
version: "1.0.0"
environment: "production"
title: !expand "{{app_name}} v{{version}}"
api_url: !expand "https://api-{{environment}}.example.com"
```
```python
# Using function variables (override __vars)
variables = {"app_name": "CustomApp", "version": "2.0.0"}
data = smartyaml.load("config.yaml", variables=variables)
```
**Variable Priority** (highest to lowest):
1. Function parameters (`smartyaml.load(file, variables={...})`)
2. Document `__vars` (main file)
3. Template `__vars` (from imported templates)
**Variable Inheritance:**
Variables from imported templates are available for expansion in the main document, enabling powerful template composition patterns.
### 9. Variable System: `__vars`
Define variables for template expansion with inheritance support.
```yaml
# Basic variables
__vars:
app_name: "MyApp"
version: "1.0.0"
debug: !env(DEBUG, false)
config:
name: !expand "{{app_name}}"
version: !expand "{{version}}"
debug_mode: !expand "{{debug}}"
```
**Variable Sources & Precedence:**
1. **Function variables** (highest): `smartyaml.load(file, variables={...})`
2. **Document variables** (medium): `__vars` in main file
3. **Template variables** (lowest): `__vars` from imported templates
**Variable Inheritance:**
```yaml
# main.yaml
__vars:
company: "ACME Corp" # Overrides template variable
__template:
<<: !template(base) # Inherits variables from templates/base.yaml
welcome: !expand "Welcome to {{company}}!" # Uses overridden value
```
### 10. Metadata Fields
Fields prefixed with `__` are automatically removed from the final result and serve as documentation/configuration.
```yaml
# Input
__version: "1.2.3" # Removed
__build_date: 2024-01-15 # Removed
app_name: "MyApp" # Kept
# Result: {"app_name": "MyApp"}
```
Metadata fields can contain SmartYAML directives:
```yaml
__vars: # Special metadata for variables
env: !env(ENVIRONMENT, "dev")
__template: # Template inheritance metadata
<<: !template(base_config)
__build_info: # Documentation metadata
date: !env(BUILD_DATE)
app_url: !expand "https://{{env}}.example.com"
```
**Special Metadata Fields:**
- `__vars`: Variable definitions
- `__template`: Template inheritance
- `__*`: Custom metadata (automatically removed)
## Complete Example
```yaml
# config.yaml - Comprehensive SmartYAML demonstration
# Variables and metadata for configuration
__vars:
app_name: "MyApplication"
environment: !env(ENVIRONMENT, "development")
version: !env(APP_VERSION, "1.0.0")
__build_info: # Documentation metadata (removed from final result)
date: !env(BUILD_DATE)
commit: !env(GIT_COMMIT, "unknown")
# Template inheritance with customization
__template:
<<: !template(apps/base_config)
# Application configuration with variable expansion
app:
name: !expand "{{app_name}}"
full_title: !expand "{{app_name}} v{{version}}"
environment: !expand "{{environment}}"
debug: !env(DEBUG, false)
api_url: !expand "https://api-{{environment}}.example.com"
# Database configuration using variables and imports
database: !import_yaml(config/database.yaml)
password: !env(DB_PASSWORD)
connection_string: !expand "postgresql://localhost/{{app_name}}_{{environment}}"
# Template-based configuration
cache: !template(redis)
# Conditional configuration based on environment
logging: !include_yaml_if(DEBUG, config/debug_logging.yaml)
# Large SQL queries from external files
queries:
get_users: !import(sql/users.sql)
analytics: !import(sql/analytics.sql)
# Secrets with encoding
secrets:
api_key: !base64_decode(YWJjZGVmZ2hpams=)
jwt_secret: !expand "{{app_name}}_secret_{{environment}}"
# Development-only settings
dev_tools: !include_if(DEVELOPMENT, dev_tools.txt)
# Service configuration with variable expansion
services:
api:
name: !expand "{{app_name}}-api"
image: !expand "{{app_name}}:{{version}}"
url: !expand "https://{{app_name}}-{{environment}}.example.com"
```
**Loading with templates and variables:**
```python
import smartyaml
# Load with template support
data = smartyaml.load("config.yaml", template_path="templates")
# Override variables via function parameters
custom_vars = {"environment": "production", "version": "2.0.0"}
data = smartyaml.load("config.yaml",
template_path="templates",
variables=custom_vars)
# Load string content
yaml_string = "app: !expand '{{name}}'"
data = smartyaml.loads(yaml_string, variables={"name": "MyApp"})
```
## Advanced Template Examples
### Template Inheritance Chain
```yaml
# templates/base/app.yaml - Base application template
__vars:
default_timeout: 30
log_level: "INFO"
__template:
application:
timeout: !expand "{{default_timeout}}"
logging:
level: !expand "{{log_level}}"
```
```yaml
# templates/environments/production.yaml - Production template
__vars:
log_level: "WARN"
replica_count: 3
__template:
<<: !template(base/app)
# Production-specific overrides
application:
replicas: !expand "{{replica_count}}"
security:
enabled: true
```
```yaml
# myapp.yaml - Final configuration
__vars:
app_name: "MyService"
default_timeout: 60 # Override base template
__template:
<<: !template(environments/production)
# Application-specific additions
app_config:
name: !expand "{{app_name}}"
custom_feature: true
```
**Result:** Deep merging with proper variable precedence - app variables override template variables.
### Multi-Template Composition
```yaml
# Service configuration combining multiple templates
__vars:
service_name: "UserAPI"
environment: "staging"
__template:
# Combine database, cache, and monitoring templates
database: !template(components/postgres)
cache: !template(components/redis)
monitoring: !template(components/prometheus)
# Service-specific configuration
service:
name: !expand "{{service_name}}"
environment: !expand "{{environment}}"
endpoints:
health: "/health"
metrics: "/metrics"
```
## Security Features
- **File Size Limits**: Default 10MB limit per file, configurable
- **Recursion Protection**: Default 10-level deep import limit
- **Path Security**: Directory traversal protection
- **Cycle Detection**: Prevents circular import chains
- **No Code Execution**: Safe YAML parsing only
- **Template Path Validation**: Prevents access to system directories
## Error Handling
SmartYAML provides specific exceptions with detailed context:
- `SmartYAMLError` - Base exception
- `SmartYAMLFileNotFoundError` - Referenced file not found
- `InvalidPathError` - Invalid or unsafe path access
- `EnvironmentVariableError` - Environment variable issues
- `TemplatePathError` - Template path configuration issues
- `Base64Error` - Base64 encoding/decoding failures
- `ResourceLimitError` - File size or resource limits exceeded
- `RecursionLimitError` - Import recursion or circular imports
- `ConstructorError` - Invalid arguments or constructor state
## Development
### Testing
```bash
python -m pytest
python -m pytest --cov=smartyaml
```
### Code Quality
```bash
black smartyaml/
isort smartyaml/
flake8 smartyaml/
mypy smartyaml/
```
### Building
```bash
python -m build
```
## Compatibility
- **Python**: 3.7+
- **YAML**: Full YAML 1.2 compatibility
- **Dependencies**: PyYAML 5.1+
SmartYAML files are valid YAML files - standard YAML parsers will treat custom directives as regular tagged values, making the format backward-compatible.
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions welcome! Please see CONTRIBUTING.md for guidelines.
Raw data
{
"_id": null,
"home_page": null,
"name": "pysmartyaml",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Albert Puigsech <albert@puigsech.com>",
"keywords": "yaml, configuration, import, environment, template",
"author": null,
"author_email": "Albert Puigsech <albert@puigsech.com>",
"download_url": "https://files.pythonhosted.org/packages/b9/4c/6442fca01562b9833aa2c7d5e79631104be603a4bba039e8ece5ea69a04d/pysmartyaml-0.1.0.tar.gz",
"platform": null,
"description": "# SmartYAML\n\nExtended YAML format with custom directives for imports, environment variables, conditional processing, and more. SmartYAML maintains full compatibility with standard YAML while providing powerful additional features.\n\n## Features\n\nSmartYAML extends standard YAML with powerful custom directives:\n\n### Core Directives\n- **!import(filename)** - Import content from text files\n- **!import_yaml(filename)** - Import and merge YAML files\n- **!env(VAR_NAME, default?)** - Access environment variables with optional defaults\n- **!expand(text)** - Variable substitution using `{{key}}` syntax\n\n### Template System\n- **!template(template_name)** - Load external templates from template directory\n- **__template** - Inline template inheritance and merging\n- **__vars** - Variable definitions with inheritance support\n\n### Conditional Processing\n- **!include_if(condition, filename)** - Conditional file inclusion based on environment variables\n- **!include_yaml_if(condition, filename)** - Conditional YAML inclusion\n\n### Encoding\n- **!base64(data)** - Base64 encoding of strings\n- **!base64_decode(data)** - Base64 decoding of strings\n\n### Metadata\n- **Metadata fields** - `__field` prefixed fields for annotations (automatically removed)\n\n## Installation\n\n### From PyPI\n\n```bash\npip install smartyaml\n```\n\n### From GitHub Repository\n\n```bash\n# Install latest from main branch\npip install git+https://github.com/apuigsech/smartyaml.git\n\n# Install specific version/tag\npip install git+https://github.com/apuigsech/smartyaml.git@v0.1.0\n\n# Clone and install for development\ngit clone https://github.com/apuigsech/smartyaml.git\ncd smartyaml\npip install -e \".[dev]\"\n```\n\n## Quick Start\n\n```python\nimport smartyaml\n\n# Basic loading\ndata = smartyaml.load(\"config.yaml\")\n\n# Load with template support\ndata = smartyaml.load(\"config.yaml\", template_path=\"templates\")\n\n# Load with variables and full options\nvariables = {\"environment\": \"production\", \"version\": \"2.0.0\"}\ndata = smartyaml.load('config.yaml',\n base_path='/custom/path',\n template_path='/templates',\n variables=variables,\n max_file_size=5*1024*1024)\n\n# Load from string content\nyaml_content = \"\"\"\n__vars:\n app: \"MyApp\"\n \ndatabase: !import_yaml db.yaml\n password: !env(DB_PASSWORD)\n name: !expand \"{{app}}_database\"\n\"\"\"\ndata = smartyaml.loads(yaml_content)\n```\n\n## Real-World Example: AI Agent Configuration\n\n```yaml\n# agent.yaml - Customer support agent configuration\n__vars:\n agent_name: \"ACME Customer Support\"\n company_name: \"ACME Corp\"\n environment: !env(ENVIRONMENT, \"development\")\n\n# Inherit from base agent template\n__template:\n <<: !template(agents/customer_support)\n\n# Agent-specific customization\nconfig:\n name: !expand \"{{agent_name}}\"\n welcome_message: !expand \"Hello! Welcome to {{company_name}} support.\"\n \n# Environment-specific features\ndebug_tools: !include_yaml_if(DEBUG, tools/debug.yaml)\nproduction_monitoring: !include_yaml_if(PRODUCTION, monitoring/prod.yaml)\n\n# Load external resources\nknowledge_base: !import(knowledge/company_info.txt)\nfaq_data: !import_yaml(data/faq.yaml)\n```\n\n```yaml\n# templates/agents/customer_support.yaml - Reusable template\n__vars:\n model: \"gpt-4\"\n temperature: 0.7\n max_tokens: 1000\n voice_id: \"default\"\n\nconfig:\n llm:\n model: !expand \"{{model}}\"\n temperature: !expand \"{{temperature}}\"\n max_tokens: !expand \"{{max_tokens}}\"\n \n voice:\n provider: \"elevenlabs\"\n voice_id: !expand \"{{voice_id}}\"\n \n conversation:\n timeout: 300\n max_turns: 50\n```\n\n**Loading:**\n```python\nimport smartyaml\n\n# Load with template inheritance\ndata = smartyaml.load(\"agent.yaml\", template_path=\"templates\")\n\n# Override with production settings\nprod_vars = {\"environment\": \"production\", \"model\": \"gpt-4-turbo\"}\ndata = smartyaml.load(\"agent.yaml\", \n template_path=\"templates\",\n variables=prod_vars)\n```\n\n**Result:** Deep merging with proper variable precedence - agent variables override template variables.\n\n## Directive Reference\n\n### 1. Text File Import: `!import(filename)`\n\nLoads the entire content of a file as a string.\n\n```yaml\n# config.yaml\nhtml_template: !import(template.html)\nsql_query: !import(queries/select_users.sql)\n```\n\n### 2. YAML Import with Merge: `!import_yaml(filename)`\n\nLoads YAML content from a file with optional local overrides.\n\n```yaml\n# Simple import\ndatabase: !import_yaml(database.yaml)\n\n# Import with local overrides\ndatabase: !import_yaml(database.yaml)\n password: production_pass # Overrides imported password\n```\n\n### 3. Environment Variables: `!env(VAR_NAME, default?)`\n\nReads values from environment variables with optional defaults.\n\n```yaml\ndatabase_url: !env(DATABASE_URL, \"postgresql://localhost/myapp\")\ndebug_mode: !env(DEBUG, false)\nport: !env(PORT, 8080)\n```\n\n### 4. Conditional Text Import: `!include_if(condition, filename)`\n\nIncludes a text file only if an environment variable condition is truthy.\n\n```yaml\ndebug_config: !include_if(DEBUG_MODE, debug_settings.txt)\ndevelopment_notes: !include_if(DEV_ENV, notes.md)\n```\n\n**Truthy values:** `1`, `true`, `yes`, `on`, `enabled` (case-insensitive)\n\n### 5. Conditional YAML Import: `!include_yaml_if(condition, filename)`\n\nIncludes a YAML file only if an environment variable condition is truthy.\n\n```yaml\ndebug: !include_yaml_if(DEBUG, debug.yaml)\ndatabase: !include_yaml_if(PRODUCTION, prod_db.yaml)\n```\n\n### 6. Template System\n\n#### External Templates: `!template(template_name)`\n\nLoads templates from a centralized template directory.\n\n```yaml\n# Loads from templates/postgres.yaml\ndatabase: !template(postgres)\n\n# Loads from templates/redis.yaml \ncache: !template(redis)\n```\n\n**Usage:** Pass `template_path` parameter to `smartyaml.load()`\n\n#### Inline Templates: `__template`\n\nInherit from external templates with local customization.\n\n```yaml\n# agent.yaml\n__vars:\n agent_name: \"Customer Support\"\n company: \"ACME Corp\"\n\n__template:\n <<: !template(agents/base)\n\n# Document-level overrides\ncustom_prompt: !expand \"You are {{agent_name}} for {{company}}\"\n```\n\n```yaml\n# templates/agents/base.yaml\n__vars:\n model: \"gpt-4\"\n temperature: 0.7\n\nconfig:\n llm: !expand \"{{model}}\"\n temperature: !expand \"{{temperature}}\"\n prompt: !expand \"{{custom_prompt}}\"\n```\n\n**Features:**\n- **Variable Inheritance**: Template variables available in main document\n- **Override Support**: Document variables override template variables\n- **Merge Semantics**: Uses YAML merge key (`<<:`) for composition\n\n### 7. Base64 Encoding/Decoding\n\nEncode strings to base64 or decode base64 strings.\n\n```yaml\n# Encoding\nsecret: !base64(my_secret_password) # -> bXlfc2VjcmV0X3Bhc3N3b3Jk\n\n# Decoding\npassword: !base64_decode(bXlfc2VjcmV0X3Bhc3N3b3Jk) # -> my_secret_password\n```\n\n### 8. Variable Substitution: `!expand(text)`\n\nReplaces `{{key}}` patterns with variable values from function parameters or `__vars` metadata.\n\n```yaml\n# Using __vars metadata\n__vars:\n app_name: \"MyApp\"\n version: \"1.0.0\"\n environment: \"production\"\n\ntitle: !expand \"{{app_name}} v{{version}}\"\napi_url: !expand \"https://api-{{environment}}.example.com\"\n```\n\n```python\n# Using function variables (override __vars)\nvariables = {\"app_name\": \"CustomApp\", \"version\": \"2.0.0\"}\ndata = smartyaml.load(\"config.yaml\", variables=variables)\n```\n\n**Variable Priority** (highest to lowest):\n1. Function parameters (`smartyaml.load(file, variables={...})`)\n2. Document `__vars` (main file)\n3. Template `__vars` (from imported templates)\n\n**Variable Inheritance:**\nVariables from imported templates are available for expansion in the main document, enabling powerful template composition patterns.\n\n### 9. Variable System: `__vars`\n\nDefine variables for template expansion with inheritance support.\n\n```yaml\n# Basic variables\n__vars:\n app_name: \"MyApp\"\n version: \"1.0.0\"\n debug: !env(DEBUG, false)\n\nconfig:\n name: !expand \"{{app_name}}\"\n version: !expand \"{{version}}\"\n debug_mode: !expand \"{{debug}}\"\n```\n\n**Variable Sources & Precedence:**\n1. **Function variables** (highest): `smartyaml.load(file, variables={...})`\n2. **Document variables** (medium): `__vars` in main file\n3. **Template variables** (lowest): `__vars` from imported templates\n\n**Variable Inheritance:**\n```yaml\n# main.yaml\n__vars:\n company: \"ACME Corp\" # Overrides template variable\n \n__template:\n <<: !template(base) # Inherits variables from templates/base.yaml\n \nwelcome: !expand \"Welcome to {{company}}!\" # Uses overridden value\n```\n\n### 10. Metadata Fields\n\nFields prefixed with `__` are automatically removed from the final result and serve as documentation/configuration.\n\n```yaml\n# Input\n__version: \"1.2.3\" # Removed\n__build_date: 2024-01-15 # Removed\napp_name: \"MyApp\" # Kept\n\n# Result: {\"app_name\": \"MyApp\"}\n```\n\nMetadata fields can contain SmartYAML directives:\n\n```yaml\n__vars: # Special metadata for variables\n env: !env(ENVIRONMENT, \"dev\")\n \n__template: # Template inheritance metadata\n <<: !template(base_config)\n \n__build_info: # Documentation metadata \n date: !env(BUILD_DATE)\n \napp_url: !expand \"https://{{env}}.example.com\"\n```\n\n**Special Metadata Fields:**\n- `__vars`: Variable definitions\n- `__template`: Template inheritance\n- `__*`: Custom metadata (automatically removed)\n\n## Complete Example\n\n```yaml\n# config.yaml - Comprehensive SmartYAML demonstration\n\n# Variables and metadata for configuration\n__vars:\n app_name: \"MyApplication\"\n environment: !env(ENVIRONMENT, \"development\")\n version: !env(APP_VERSION, \"1.0.0\")\n \n__build_info: # Documentation metadata (removed from final result)\n date: !env(BUILD_DATE)\n commit: !env(GIT_COMMIT, \"unknown\")\n\n# Template inheritance with customization\n__template:\n <<: !template(apps/base_config)\n\n# Application configuration with variable expansion\napp:\n name: !expand \"{{app_name}}\"\n full_title: !expand \"{{app_name}} v{{version}}\"\n environment: !expand \"{{environment}}\"\n debug: !env(DEBUG, false)\n api_url: !expand \"https://api-{{environment}}.example.com\"\n\n# Database configuration using variables and imports\ndatabase: !import_yaml(config/database.yaml)\n password: !env(DB_PASSWORD)\n connection_string: !expand \"postgresql://localhost/{{app_name}}_{{environment}}\"\n\n# Template-based configuration\ncache: !template(redis)\n\n# Conditional configuration based on environment\nlogging: !include_yaml_if(DEBUG, config/debug_logging.yaml)\n\n# Large SQL queries from external files\nqueries:\n get_users: !import(sql/users.sql)\n analytics: !import(sql/analytics.sql)\n\n# Secrets with encoding\nsecrets:\n api_key: !base64_decode(YWJjZGVmZ2hpams=)\n jwt_secret: !expand \"{{app_name}}_secret_{{environment}}\"\n\n# Development-only settings\ndev_tools: !include_if(DEVELOPMENT, dev_tools.txt)\n\n# Service configuration with variable expansion\nservices:\n api:\n name: !expand \"{{app_name}}-api\"\n image: !expand \"{{app_name}}:{{version}}\"\n url: !expand \"https://{{app_name}}-{{environment}}.example.com\"\n```\n\n**Loading with templates and variables:**\n\n```python\nimport smartyaml\n\n# Load with template support\ndata = smartyaml.load(\"config.yaml\", template_path=\"templates\")\n\n# Override variables via function parameters\ncustom_vars = {\"environment\": \"production\", \"version\": \"2.0.0\"}\ndata = smartyaml.load(\"config.yaml\", \n template_path=\"templates\",\n variables=custom_vars)\n\n# Load string content\nyaml_string = \"app: !expand '{{name}}'\"\ndata = smartyaml.loads(yaml_string, variables={\"name\": \"MyApp\"})\n```\n\n## Advanced Template Examples\n\n### Template Inheritance Chain\n\n```yaml\n# templates/base/app.yaml - Base application template\n__vars:\n default_timeout: 30\n log_level: \"INFO\"\n\n__template:\n application:\n timeout: !expand \"{{default_timeout}}\"\n logging:\n level: !expand \"{{log_level}}\"\n```\n\n```yaml\n# templates/environments/production.yaml - Production template\n__vars:\n log_level: \"WARN\"\n replica_count: 3\n\n__template:\n <<: !template(base/app)\n \n # Production-specific overrides\n application:\n replicas: !expand \"{{replica_count}}\"\n security:\n enabled: true\n```\n\n```yaml\n# myapp.yaml - Final configuration\n__vars:\n app_name: \"MyService\"\n default_timeout: 60 # Override base template\n\n__template:\n <<: !template(environments/production)\n\n# Application-specific additions\napp_config:\n name: !expand \"{{app_name}}\"\n custom_feature: true\n```\n\n**Result:** Deep merging with proper variable precedence - app variables override template variables.\n\n### Multi-Template Composition\n\n```yaml\n# Service configuration combining multiple templates\n__vars:\n service_name: \"UserAPI\"\n environment: \"staging\"\n\n__template:\n # Combine database, cache, and monitoring templates\n database: !template(components/postgres)\n cache: !template(components/redis)\n monitoring: !template(components/prometheus)\n \n# Service-specific configuration\nservice:\n name: !expand \"{{service_name}}\"\n environment: !expand \"{{environment}}\"\n endpoints:\n health: \"/health\"\n metrics: \"/metrics\"\n```\n\n## Security Features\n\n- **File Size Limits**: Default 10MB limit per file, configurable\n- **Recursion Protection**: Default 10-level deep import limit\n- **Path Security**: Directory traversal protection\n- **Cycle Detection**: Prevents circular import chains\n- **No Code Execution**: Safe YAML parsing only\n- **Template Path Validation**: Prevents access to system directories\n\n## Error Handling\n\nSmartYAML provides specific exceptions with detailed context:\n\n- `SmartYAMLError` - Base exception\n- `SmartYAMLFileNotFoundError` - Referenced file not found\n- `InvalidPathError` - Invalid or unsafe path access\n- `EnvironmentVariableError` - Environment variable issues\n- `TemplatePathError` - Template path configuration issues\n- `Base64Error` - Base64 encoding/decoding failures\n- `ResourceLimitError` - File size or resource limits exceeded\n- `RecursionLimitError` - Import recursion or circular imports\n- `ConstructorError` - Invalid arguments or constructor state\n\n## Development\n\n### Testing\n\n```bash\npython -m pytest\npython -m pytest --cov=smartyaml\n```\n\n### Code Quality\n\n```bash\nblack smartyaml/\nisort smartyaml/\nflake8 smartyaml/\nmypy smartyaml/\n```\n\n### Building\n\n```bash\npython -m build\n```\n\n## Compatibility\n\n- **Python**: 3.7+\n- **YAML**: Full YAML 1.2 compatibility\n- **Dependencies**: PyYAML 5.1+\n\nSmartYAML files are valid YAML files - standard YAML parsers will treat custom directives as regular tagged values, making the format backward-compatible.\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions welcome! Please see CONTRIBUTING.md for guidelines.\n",
"bugtrack_url": null,
"license": null,
"summary": "Extended YAML format with custom directives for imports, environment variables, and more",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/apuigsech/smartyaml/issues",
"Changelog": "https://github.com/apuigsech/smartyaml/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/apuigsech/smartyaml#readme",
"Homepage": "https://github.com/apuigsech/smartyaml",
"Source": "https://github.com/apuigsech/smartyaml"
},
"split_keywords": [
"yaml",
" configuration",
" import",
" environment",
" template"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "496cebc846d4dcd9fe5bdd201d8136e4d61cea69e8f165152ea99a5f0d6e958f",
"md5": "e85d886151e375779cbddb6fabd060ff",
"sha256": "8e791e38ed578aae1892f1fc2ebc6537d72ea8a4c6d103708a8ca9ee6d4768e2"
},
"downloads": -1,
"filename": "pysmartyaml-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e85d886151e375779cbddb6fabd060ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 79805,
"upload_time": "2025-08-15T21:50:28",
"upload_time_iso_8601": "2025-08-15T21:50:28.829491Z",
"url": "https://files.pythonhosted.org/packages/49/6c/ebc846d4dcd9fe5bdd201d8136e4d61cea69e8f165152ea99a5f0d6e958f/pysmartyaml-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b94c6442fca01562b9833aa2c7d5e79631104be603a4bba039e8ece5ea69a04d",
"md5": "027108d1b22f5bf1c2f057562d6c35ec",
"sha256": "f1de8963bf2b37228e2eb043db8cabec4df109af1d7fe0693fdf95902d55fbc8"
},
"downloads": -1,
"filename": "pysmartyaml-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "027108d1b22f5bf1c2f057562d6c35ec",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 77983,
"upload_time": "2025-08-15T21:50:30",
"upload_time_iso_8601": "2025-08-15T21:50:30.073421Z",
"url": "https://files.pythonhosted.org/packages/b9/4c/6442fca01562b9833aa2c7d5e79631104be603a4bba039e8ece5ea69a04d/pysmartyaml-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 21:50:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "apuigsech",
"github_project": "smartyaml",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pysmartyaml"
}
